RepoRescue — Verified Code Rescue

Paste broken Python code or a reviewed allow-listed public Python GitHub repository. RepoRescue explains it, generates a minimal repair, runs before-and-after verification, and reports exactly what the evidence proves.

RepoRescue is not another “maybe try this” coding chatbot. Its differentiator is a verification protocol:

understand intent → reproduce failure → generate minimal fix → run the same case again → grade the evidence

The product serves beginners through one low-friction entry point while keeping repository reproduction as the advanced mode:

Direct file/notebook upload is a planned mode, not a current backend capability.

On a deployed service, users do not install or start Docker and do not confirm an isolation mode in chat. They submit the code or an allowed repository URL; the backend worker owns isolation and execution. The Docker setup commands below are for administrators and local developers, not the hosted user flow. If the worker is unavailable, execution fails closed instead of running code on the host.

Why it is different

• Generated repair, not a checklist: the agent produces the candidate code.

• Before/after proof: a fix is “verified” only when the original fails and the repaired version passes the same stated case.

• Beginner-first result: users see the cause, change, and outcome before technical logs.

• Scoped claims: snippet execution, repository tests, official demos, and paper metrics are different evidence levels.

• Portable core: the same MCP tools can power XFYun Agent, OpenClaw, Codex, or another agent shell.

Related MCP server: ProofScope

Backend repair architecture

reviewed allow-listed public Python GitHub URL + issue
        │
        ▼
commit-pinned temporary checkout
        │
        ▼
Docker/managed verifier ── records failing command, exit code and logs
        │
        ├── OpenAI Repair Agent (server-managed, API key path)
        │
        └── Host Repair Agent (prepare + submit proposal, no model API key in backend)
        │
        ▼
safe patch application ── blocks traversal, test edits, new files and Git metadata
        │
        ▼
same-command verifier ── retries up to the configured attempt limit
        │
        ▼
repair.patch + evidence.json + report.md

Interview demo — one command, no model API key or Docker

From PowerShell in the repository root:

.\demo.ps1

On Windows, demo.cmd can also be double-clicked.

The script creates or reuses .venv, installs the project, and runs a seeded broken calculator through the real orchestration path. The original test exits 1, the Repair Agent changes calculator.py, the exact same command exits 0, and a timestamped evidence bundle is written under artifacts/.

This deterministic demo is intentionally limited to the bundled trusted project, so the repair run itself needs neither Docker, network access nor model credentials. A first-time setup may still need package access to install the Python dependencies. Reviewed allow-listed public Python GitHub repositories use one of the isolated paths below.

Quick start: hosted Node MCP

The hosted launcher uses a fresh child-process CPython WebAssembly worker for bounded snippet execution. It runs the original and candidate in two separate workers sequentially, so a 256 MB hosted instance does not keep two Pyodide runtimes resident at once. The revisions still share no interpreter state, and each worker retains the same hard wall-clock, V8 heap, protocol, and output limits. Because the wall-clock limit applies independently to both workers, the MCP client timeout must allow two worker budgets plus cold-start overhead (about 12 seconds plus overhead with the 6000 ms default). Node never executes repository code in its own hosted container. The platform toolset can instead dispatch a bound request to this repository's trusted GitHub Actions workflow, where the Python v0.4 backend uses Docker isolation.

npm install
npm test
npm run benchmark
node .\stdio-server.mjs
node .\platform-entry.mjs

For compatibility the default Node launcher keeps the legacy four-tool surface, but reproduce_python_project never clones or executes repository code there. Set REPO_RESCUE_NODE_TOOLSET=snippet for snippet-only hosting. The dedicated repo-rescue-mcp-platform bin is the competition entrypoint: it unconditionally fixes the reviewed toolset, control repository, workflow, protected ref, two-repository allow-list, rates, timeouts, and snippet budget in code. Discovery then contains exactly rescue_python_snippet, start_prepare_github_repair, get_repair_job, and start_verify_github_patch, while direct calls to hidden legacy tools fail closed.

XFYun Agent repair through an authenticated HTTP gateway

The current integration candidate uses four XFYun personal HTTP plugins. A single-replica Node gateway on Railway hosts the reviewed platform stdio worker; the long, untrusted repository run executes on an Ubuntu GitHub runner. Two real autonomous repository repairs passed backend artifact audits on 2026-09-10, but the model's final transcription altered hashes or patch text. The new delivery candidate returns a signed, read-only receipt with original artifact downloads. Its platform validation and publication are still pending. See deployment evidence, original artifact delivery, and the current integration checklist.

XFYun model → authenticated HTTP plugin → Node platform worker → GitHub workflow_dispatch
             → pinned workflow checkout → fixed verifier Docker image
             → Python v0.4 prepare/verify → bound artifact ZIP
XFYun model ← rescue_poll HTTP plugin ← result.json + repair.patch + evidence.json + report.md

Generic self-hosting can configure the standard launcher with administrator-owned values; none of them is accepted as a tool argument:

REPO_RESCUE_NODE_TOOLSET=platform
REPO_RESCUE_GITHUB_TOKEN=<fine-grained token>
REPO_RESCUE_ACTIONS_REPOSITORY=wenjieding327/repo-rescue-mcp
REPO_RESCUE_ACTIONS_WORKFLOW=repo-rescue-actions-bridge.yml
REPO_RESCUE_ACTIONS_REF=<protected branch containing the reviewed workflow>
REPO_RESCUE_ALLOWED_REPOS=wenjieding327/repo-rescue-canary,wenjieding327/repo-rescue-mcp

For the current candidate, deploy http-sse-server.mjs using Dockerfile.railway, inject separate gateway and repository credentials in Railway, and configure the four XFYun plugins with Service/Header authentication. XFYun receives only the dedicated gateway credential; the GitHub credential stays in Railway. Inputs use JSON Body, not Query. HTTP 200 and is_error=false are transport results, never repair verdicts. See the exact plugin mapping and acceptance gates.

The earlier XFYun-hosted MCP alternative is retained for recovery, not claimed operational: command npx, arguments -y https://github.com/wenjieding327/repo-rescue-mcp/releases/download/v0.4.1-xfyun.1/repo-rescue-mcp-platform-0.4.1-xfyun.1.tgz. npm run pack:xfyun and npm run verify:xfyun still audit and execute the single-bin archive locally. Local package success does not prove XFYun runner startup. Do not rebind or retransmit credentials merely to retry this historical alternative.

The fine-grained token is restricted to the one bridge repository with Actions read/write; RepoRescue does not need Contents, Workflows, Administration, or a model API key on that token. The Node and workflow allow-lists must be identical. The trusted workflow has its own fixed allow-list, builds repo-rescue-python:3.11, clears GITHUB_TOKEN/GH_TOKEN for the controller step, and never adds a credential to the untrusted Docker container.

Dispatch payloads are gzip+base64 but are not trusted: both sides enforce 55,000 encoded and expanded bytes, at most three replacements, and 12,000 characters per replacement. Active work defaults to one job (matching the workflow's global single concurrency), three starts per minute, and twelve starts per hour. Every start receives a private in-process job_id; the separate 256-bit request_id appears in the public Actions run/artifact only as a correlation nonce and is never accepted as authorization. A timed-out dispatch POST is discovered by that exact nonce and is never implicitly re-dispatched. Verification additionally requires the still-live private preparation_job_id, an exact repository/commit/baseline match, and one-time consumption of that preparation capability; an idempotent retry of the same verify call returns its already-started verify job. Polling checks workflow/run/ref/head SHA, request ID, payload SHA, artifact ID/digest, ZIP layout, patch SHA, and evidence fields. A successful verify returns the real bounded patch, evidence JSON, and report text under job.result.github_actions.artifact_contents.

This competition bridge remains intentionally limited to reviewed public Python repositories. Do not put credentials, private source, personal data, or secrets in the issue text or proposed patch: workflow inputs and one-day artifacts live in the team's GitHub Actions control repository. The hosted process keeps job capabilities in memory; if that process restarts, an already-running GitHub job may finish but the old job_id is no longer pollable. The Agent must start a fresh prepare chain rather than reuse an orphaned commit/baseline. A commercial service should persist job mappings in a database and use a GitHub App installation token.

Release operators can run node scripts/live_actions_bridge_smoke.mjs after setting the reviewed environment variables and a process-only REPO_RESCUE_GITHUB_TOKEN. The smoke performs a real prepare→verify chain against the team canary and exits non-zero unless the Docker baseline fails, the same pytest command passes after one source-only replacement, all three evidence texts are returned, and their hashes agree. Set REPO_RESCUE_ACTIONS_EXPECTED_HEAD_SHA to the frozen 40-character bridge commit for an additional release-ref assertion. Never put the token on the command line or in a tracked .env file.

rescue_python_snippet

Supply original code and the AI-generated candidate. Optional cases provide stdin and expected stdout. Without expected output, RepoRescue can prove only that the candidate ran; it will not label the change a verified fix.

{
  "original_code": "numbers = [1, 2, 3]\nprint(numbers[3])",
  "candidate_code": "numbers = [1, 2, 3]\nprint(numbers[-1])",
  "test_cases": [
    {"name": "last item", "stdin": "", "expected_stdout": "3"}
  ]
}

The response records the original IndexError, the repaired output, case-level status, and a scoped S2/L1_SNIPPET_EXECUTION result. It never claims a whole project or paper was reproduced from this snippet run.

npm run benchmark exercises fourteen deterministic success and rejection cases, including index, type, syntax, zero-division, missing-key, runaway-loop, unsafe-import, incorrect-candidate, already-passing, over-limit, missing-oracle, deterministic-random, serializer-corruption and private-runtime-escape inputs. This benchmarks the execution/verdict backend; it does not measure how often an LLM generates the correct candidate repair.

Full repository Repair Agent

The Python backend provides repository inspection, container-backed reproduction, repository repair orchestration, verification and artifact output:

py -3.11 -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev,agent]"
.venv\Scripts\python -m pytest
docker build -f sandbox/Dockerfile.python311 -t repo-rescue-python:3.11 .

$env:OPENAI_API_KEY="your-api-key"
$env:REPO_RESCUE_ALLOWED_REPOS="owner/broken-repository"
.venv\Scripts\repo-rescue repair `
  https://github.com/owner/broken-repository `
  --issue "describe the observed failure" `
  --artifacts .\artifacts

The repair command uses the OpenAI Responses API. REPO_RESCUE_OPENAI_MODEL selects the model and defaults to gpt-5.6-terra. The repository must be public and explicitly allow-listed; arbitrary shell commands are never accepted.

To expose the same workflow as MCP, run .venv\Scripts\repo-rescue-mcp. The Streamable HTTP endpoint defaults to http://localhost:8000/mcp; set REPO_RESCUE_TRANSPORT=stdio for a command-based host or REPO_RESCUE_TRANSPORT=sse for a legacy SSE client. Direct SSE uses the verified root /sse and /messages/ routes. If a public URL needs a path prefix, add it in a reverse proxy rather than setting a FastMCP runtime mount path.

The root Dockerfile packages the MCP API and trusted interview Demo; it does not embed a Docker daemon. Run full repository repair from a host/worker that can reach the separately built repo-rescue-python:3.11 verifier image. Do not expose a privileged Docker socket to anonymous callers.

Automatic test discovery

The trusted pytest worker extends default discovery to test.py, tests.py (including src/tests.py), and *_tests.py, alongside pytest's default names. It does not supply a manually selected file path or replace testpaths. An explicit python_files setting or -o python_files=... override remains authoritative, including an empty setting or an explicit copy of the defaults. A valid tox.ini is a pytest signal only if it contains a [pytest] section; tox commands are never executed automatically. Damaged or unreadable tox configurations retain pytest verification instead of a compile-only fallback.

Results record pytest_discovery_policy=project-config-or-extended-defaults-v1. The same policy is used before and after patching. A zero-test run still fails verification, and the additional test filenames are protected against repair edits. This supports conventional Python layouts, not arbitrary test frameworks or arbitrary unreviewed repositories. See pytest's official documentation on configuration and test discovery.

API-key-free host-agent repair

An agent platform such as XFYun can use its own model as the Repair Agent, so the user and RepoRescue repair backend do not need a separate model API key. The private platform administrator still supplies the least-privilege GitHub Actions credential described above:

prepare_github_repair(repo_url)
  → pinned commit + real baseline + baseline_sha256 + bounded untrusted source/config context
host model generates complete-file replacements
verify_github_patch(repo_url, expected_commit, expected_baseline_sha256, changes)
  → fresh checkout + baseline hash match + protected patch + same-command re-verification

Agent platforms with short tool-call deadlines should use the asynchronous equivalents:

start_prepare_github_repair(repo_url) → job_id
get_repair_job(job_id, wait_seconds<=20) → preparation result
host model generates complete-file replacements
start_verify_github_patch(...) → job_id
get_repair_job(job_id, wait_seconds<=20) → verified result

The actual wire shape is start.job.job_id, followed by poll.job.terminal/status/result; preparation lives at job.result.preparation and the final verdict at job.result.repair.verified_repair. The hosted Node platform variant adds a required preparation_job_id to its verify tool and consumes that capability once; the direct Python MCP signature remains unchanged. A job status of succeeded means only that the backend operation returned—not that a repair was verified. Jobs use unguessable lookup IDs, bounded queues/rates, and finite in-memory TTLs.

The in-memory job store is deliberately a single-instance competition/demo design: run exactly one application process and one replica so a start and its polls reach the same store. Jobs do not survive restart or rolling deployment. A commercial multi-worker or multi-replica service must move the queue and results to Redis or a database, authenticate callers, enforce per-tenant rate limits, and terminate TLS at a gateway.

This path still requires an isolated execution backend. Local untrusted repositories use Docker. A managed host may use REPO_RESCUE_EXECUTION_BACKEND=direct only when the whole service already runs inside a disposable, resource-limited container and the repository is explicitly allow-listed. If dependency installation prevents the baseline pytest run, a later passing suite is reported as repair_tests_passed_uncompared, not verified_repair, because the original test coverage could not be measured.

Repository tools

inspect_github_project

Read-only inspection of a public repository. Returns the exact commit, bounded file tree, Python manifests, dependency declarations, version hints, risks, entry points, and suggested verification commands. The execution allow-list is checked before any reproduction or repair run, not before read-only inspection.

reproduce_python_project

Runs a fixed verification scope for an explicitly allow-listed Python repository and returns the actual command, install/execution exit codes, duration, bounded logs, backend, and evidence boundary.

repair_github_project

Runs the full repository loop: commit-pinned clone, Docker baseline, bounded Repair Agent proposal, protected source replacement, identical-command verification, retry, and durable evidence artifacts. It never pushes or opens a pull request.

prepare_github_repair + verify_github_patch

Runs the same evidence protocol with the surrounding agent host as the Repair Agent. Preparation is never called a success. The second tool checks both the 40-character commit and preparation baseline hash, applies only bounded replacements to existing allowed files, reruns dependency analysis and installation, and reports a repair only when the exact verifier command passes. A repair may change versions of existing dependency names; adding a new distribution requires explicit administrator approval through REPO_RESCUE_ALLOWED_ADDITIONAL_DEPENDENCIES.

start_prepare_github_repair + start_verify_github_patch + get_repair_job

Runs the same preparation and verification operations through a bounded background queue for agent platforms that disconnect long synchronous calls. Polling never restarts an operation. Only the terminal job result—and ultimately verified_repair=true—can support a repair claim.

run_interview_demo

Runs the deterministic end-to-end demonstration through MCP without Docker or an API key. This is the safest live interview entry point.

get_repair_artifact

Returns bounded chunks of repair.patch, report.md, or evidence.json using a generated run ID instead of exposing server filesystem paths.

windows_environment_probe

Returns a copy-paste PowerShell probe. It never claims to read a user's computer automatically and does not change the machine.

Evidence levels

• S1: snippet executed.

• S2: original snippet failed and repaired snippet passed the same case.

• P1: repository and commit inspected; no execution claim.

• P2: dependencies resolved.

• P3: named repository test scope executed with recorded exit code.

• P4: documented official demo reproduced.

• P5: paper metric reproduced under a stated dataset, configuration, seed, and hardware boundary.

The archived competition deployment has evidence for S2 on safe Python snippets and P3 for the named Click core smoke scope. The source tree also has a deterministic 14/14 snippet backend benchmark and a host-agent path that needs no separate model API key. The private platform administrator still configures a least-privilege GitHub Actions credential. These source capabilities must be redeployed and retested on the public Agent before they are described as live. None of them claims P4 or P5.

Verified Code Rescue Skill

skills/verified-code-rescue/SKILL.md packages the distinctive orchestration protocol for agent hosts. It routes snippets, files, and repositories; requires before/after evidence; grades the claim scope; and produces a beginner-readable answer before technical details.

This Skill is intentionally not a generic coding prompt. Its reusable value is the truth-preserving rescue workflow.

Safety boundary

• Snippet rescue limits source size and case count, permits only a small safe standard-library import set, rejects filesystem/process/network capabilities, and applies a deterministic execution budget.

• Repository execution remains allow-listed and constrained.

• Model output can replace only exact paths from the initial bounded source/config inventory; test trees and their helpers, conftest.py, pytest discovery/execution settings, path aliases, traversal, symlinks and Git metadata are rejected. New dependency distribution names are denied by default, pytest plugin autoload is disabled, and a trusted parent controller parses worker-produced JUnit evidence before accepting a pytest result.

• A repair is verified only when the pinned original fails and the modified checkout passes the exact same recorded command.

• Repository execution is isolated as untrusted code, but semantic pytest evidence assumes an administrator-allow-listed test harness is not deliberately designed to spoof pytest internals; production exposure to hostile repositories requires a stronger verifier trust boundary.

• The service does not read a user's computer, accept arbitrary shell commands, or execute private repositories.

• Public production should move untrusted repositories to gVisor or Firecracker, authenticate and rate-limit callers, scan archives, restrict outbound installation traffic, and expire stored source and logs.

Portfolio summary

Built a backend Repair Agent that accepts a reviewed allow-listed public Python GitHub repository, creates a commit-pinned isolated checkout, reproduces a real failure, generates and safely applies a bounded source repair, reruns the exact same verifier, and emits a patch plus machine-readable and human-readable evidence. Exposed the loop through CLI and MCP while preventing test tampering and unverified success claims.

Roadmap

• File and notebook upload with focused test generation.

• Broader dependency-conflict and lockfile strategies beyond existing manifest replacement.

• Web job dashboard and downloadable artifact bundle.

• Official-demo (P4) benchmark cases beyond the bundled interview fixture.

• Optional GitHub Issue/PR output after explicit user confirmation.