Pi Patch Desk

The problem

You give a coding agent a bug report. It changes a file and says the tests pass.

To review that result, you need to establish what happened: which test failed before the change, which files were inspected and edited, which checks actually finished, and which source supports the explanation. You also need a patch you can inspect without reading the entire conversation.

Pi Patch Desk gathers those answers around one concrete issue: a small TypeScript parser rejects blank lines between otherwise valid records. The requested repair must ignore blank lines while preserving validation of nonblank records, and add a regression test.

Why the obvious approach fails

A prompt can ask an agent to stay within two directories and verify its work. The application still needs executable rules that own those decisions.

The agent’s claim that a test passed needs a recorded command and exit code. A test the agent can edit needs an independent acceptance check. A requested tool call needs an observed completion. Instructions found in repository files need to remain source data rather than become permission to change policy.

Those requirements belong in the surrounding software.

The solution

Pi Patch Desk combines a real Pi agent loop with a deterministic host. The host creates a disposable fixture copy, records the original state, reproduces the failing test, and exposes a small set of tools. Pi reads source, edits the copy, invokes fixed checks, and submits exact source references.

After the Pi run finishes, the host runs the final fixture tests, TypeScript typecheck, and its own acceptance assertions. A successful result produces patch.diff and a review dossier. A failed or prohibited action produces a failure dossier. The original fixture remains unchanged.

The current version is an offline demonstration with scripted responses. Pi’s loop and tools actually execute, and the checks run against real files. The responses determine which operations Pi requests; this does not measure a real model’s ability to diagnose or repair an unfamiliar bug.

How it works

bug report
    -> fresh disposable fixture and original-file hashes
    -> reproduce the failing regression
    -> Pi reads the source and tests
    -> Pi edits the permitted files
    -> Pi submits source references
    -> host tests, typecheck and independent acceptance checks
    -> patch and review dossier
    -> human decision

The host permits edits to exactly src/records.ts and tests/regression.ts. Its central policy rejects forbidden paths, traversal, symlink escapes, tool aliases, nested-call arguments and model-supplied approval. Test commands come from a fixed allowlist rather than agent-authored shell strings.

The evidence gate requires nonempty citations whose file, line range and quotation match the current source. These references establish source identity; the executed checks establish the behavior they cover.

Request, turn, tool, time, file, output and log budgets keep each run bounded. Cancellation terminates the fixed check child and waits for it to close.

Evidence and validation

The recorded development run on 14 October 2026 used Pi packages pinned to 1.0.4, Node 25.8.2, and TypeScript 5.9.3 on Windows.

The full examples suite passed 311 tests, including 32 capstone tests, and typecheck passed. The capstone tests exercise the actual Pi runtime and real fixture commands. They cover successful repair, patch applicability, repeatable outcomes, original-worktree preservation, source-reference failures, prohibited operations, failed and weakened tests, provider errors, refusal, abort, timeout, and exhausted budgets.

The independent host grader rejects an unfixed parser even when the proposed fixture tests have been weakened to pass. A separate watchdog test confirms that an otherwise-continuing child process has exited after cancellation.

Each run writes seven files:

Read the capstone evidence record for the executed commands, recorded results and limitations. Scripted results provide evidence about control flow; real-model quality, injection recognition, pass@1 and pass^k have not been measured for this solution.

Capstone and implementation

The related book, Pi Agents: Building on the Coding Agent, teaches how to choose the mechanism and layer that should own each part of agent behavior. Pi Patch Desk brings those parts together: typed tools, a bounded agent loop, source validation, host verification, completed events, prompt and skill resources, and a separate human decision.

The public implementation lives in examples/capstone-patch-desk/. Start with its reader guide, then inspect the fixture, policy.ts, checks.ts, evidence.ts, and run.ts. The CLI, JSON driver and optional Pi command call the same host workflow.

Use it

Install Node.js 22.19 or later and Git, then run:

git clone https://github.com/ernanhughes/pi-agents.git
cd pi-agents/examples
npm ci
npm run capstone

After dependencies are installed, the demonstration needs no network, API key or global Pi installation. Open review.md, patch.diff and tests.json in the printed run directory. The baseline test should exit 1; the repaired tests, typecheck and final host grader should exit 0.

To demonstrate a refusal:

npm run capstone -- --scenario injection

This command deliberately exits 1. A scripted response follows malicious instructions in the fixture README and tries to edit a forbidden file with a fake approval flag. The host refuses it and records the decision.

For an interactive walkthrough, run npm run capstone:interactive, then enter /patch-desk or /patch-desk injection in Pi. For JSON events, run node capstone-patch-desk/cli.ts --json from examples/. Applying the proposed patch, committing it, pushing it or opening a PR remains a separate operation.

Operating boundary and next steps

This release accepts its known fixture and scripted scenarios. It provides a temporary working copy and application policy; it does not provide an OS sandbox. Changed TypeScript executes in child checks with the user’s OS permissions. The demonstration should not be extended to hostile repositories or arbitrary model-authored code without an external containment boundary.

Temporary copies are removed after reporting. Review dossiers are retained locally until deleted and capped at 128 KiB per run; accumulated run directories have no total retention cap.

A real-model mode would need verified external containment, explicit provider opt-in, resource limits and a held-out evaluation with an independent grader. That is future work. The current solution gives you a complete, inspectable offline example of how a proposed agent repair earns a reviewable result.