Repair: an agent for a stopped or failed run that fixes the cause and carries the run on #222

Closed
opened 2026-10-19 18:54:00 -04:00 by cmoriarty · 1 comment
Owner

Symptom

When a run fails or is stopped there are two moves: redo the step, or start the run over. A failure whose cause is outside the step has no remedy in Braid. Run 88 finished its work and failed at git.pr.merge because another run's pull request had merged into the base in the meantime (#221 is the graph fix for that case). Nothing in Braid could resolve the conflict and carry the run on; the merge had to be fixed outside it. Braid has a full coding agent for exactly this kind of problem, but it only talks to a step that is running.

The next failure will be a different one, so the fix should not be one more special case in the graph.

Wanted

A Repair agent: one per run, active whenever the run is stopped or failed.

  • Appears by itself. When a run is stopped or failed, the message box talks to Repair. No switch, no setting.
  • Acts like the normal agent. Full access to the run's worktree, shell and tools by default, so it can do whatever the situation needs. (A setting to limit it can come later.)
  • Drives the run through the engine. A Braid tool, in the style of the app tool, that appends the same events the Resume, Redo and Accept buttons do: read the graph and each step's state, resume the run, redo a step, and mark a failed step done by hand. It goes through the engine's own paths, so checkpoints, attempt counts and the rules of those verbs apply.
  • Cannot answer a gate. It may resume a run, which then waits at the next gate for a person as usual. It has no tool to approve, reject or answer one.
  • One conversation per run. It remembers what it tried and can say what it changed.
  • Its own backend setting, like the planning setting: by default the run's own backend, or another one chosen in Settings. Repair on the Free profile is allowed to be chosen but is not recommended until #201 is closed.
  • Its server is short-lived. A failed run's opencode server is stopped when the run is reaped, so Repair starts one when the person talks to it and stops it afterwards. It takes a free slot and does not hold one.
  • Only for stopped or failed runs. Not for succeeded or archived runs.
  • Shown on the steps it touched. A marker like the attempts badge on each step Repair redid or marked done, linking to its conversation, and one entry for the Repair session in the run spine. A step Repair marked done by hand reads differently from one that ran.

The hazard to design first

A retry of a scripted step rolls the worktree back to the step's entry checkpoint (an agent step that continues is the exception). If Repair merges the base into the branch, pushes, and then resumes at git.pr.merge, the rollback can undo Repair's commits. Repair must end its work with a checkpoint that becomes the baseline for the next attempt, or its resume must skip the rollback; either way there needs to be a test for exactly this scenario.

Not in this issue

The live-run "Ask" mode and the stuck-run nudge are a separate issue that builds on this one.

## Symptom When a run fails or is stopped there are two moves: redo the step, or start the run over. A failure whose cause is outside the step has no remedy in Braid. Run 88 finished its work and failed at `git.pr.merge` because another run's pull request had merged into the base in the meantime (#221 is the graph fix for that case). Nothing in Braid could resolve the conflict and carry the run on; the merge had to be fixed outside it. Braid has a full coding agent for exactly this kind of problem, but it only talks to a step that is running. The next failure will be a different one, so the fix should not be one more special case in the graph. ## Wanted A **Repair** agent: one per run, active whenever the run is stopped or failed. - **Appears by itself.** When a run is stopped or failed, the message box talks to Repair. No switch, no setting. - **Acts like the normal agent.** Full access to the run's worktree, shell and tools by default, so it can do whatever the situation needs. (A setting to limit it can come later.) - **Drives the run through the engine.** A Braid tool, in the style of the `app` tool, that appends the same events the Resume, Redo and Accept buttons do: read the graph and each step's state, resume the run, redo a step, and mark a failed step done by hand. It goes through the engine's own paths, so checkpoints, attempt counts and the rules of those verbs apply. - **Cannot answer a gate.** It may resume a run, which then waits at the next gate for a person as usual. It has no tool to approve, reject or answer one. - **One conversation per run.** It remembers what it tried and can say what it changed. - **Its own backend setting**, like the planning setting: by default the run's own backend, or another one chosen in Settings. Repair on the Free profile is allowed to be chosen but is not recommended until #201 is closed. - **Its server is short-lived.** A failed run's opencode server is stopped when the run is reaped, so Repair starts one when the person talks to it and stops it afterwards. It takes a free slot and does not hold one. - **Only for stopped or failed runs.** Not for succeeded or archived runs. - **Shown on the steps it touched.** A marker like the attempts badge on each step Repair redid or marked done, linking to its conversation, and one entry for the Repair session in the run spine. A step Repair marked done by hand reads differently from one that ran. ## The hazard to design first A retry of a scripted step rolls the worktree back to the step's entry checkpoint (an agent step that continues is the exception). If Repair merges the base into the branch, pushes, and then resumes at `git.pr.merge`, the rollback can undo Repair's commits. Repair must end its work with a checkpoint that becomes the baseline for the next attempt, or its resume must skip the rollback; either way there needs to be a test for exactly this scenario. ## Not in this issue The live-run "Ask" mode and the stuck-run nudge are a separate issue that builds on this one.
Author
Owner

Shipped on main (098c8af), archived as 2026-10-19-repair-agent.

  • Repair is one conversation per run, available while a run is stopped or failed. The message box talks to it by itself (Send only), and a Repair button opens its conversation.
  • It works in the run's worktree with an implementation agent's access, and drives the run through a repair tool: status, resume, redo, accept. Each goes through the route the buttons use, with Repair as the actor. It has no action for a gate.
  • A repair survives the retry. Before one of Repair's verbs takes effect, Braid snapshots the worktree, and the rollback restores that snapshot when it is newer than the step's entry checkpoint. The operator's own Resume after a repair keeps it too.
  • Short-lived server. The first message starts the run's own opencode server in its slot, it stops after a quiet period (Settings), and on resume it simply becomes the run's server.
  • Settings: a Repair backend (the main backend by default, or another saved profile) and the quiet period. The Free profile is refused for now, also when the run's own backend is Free, until the agent-shell isolation work is done.
  • Marked in the console: a repaired or by hand marker on the steps it touched, and a spine entry for each session.

Verified by unit tests, 358 browser specs, a live test against opencode 2.0.30, and a simulated run (repair-carries-a-failed-run-on) in which a failed run is repaired and merges. The simulated run found that opencode refuses a prompt id not starting msg_; the route now normalises it.

Not in this change: asking a question of a live run without interrupting it, and a nudge for a stuck run (braid#223). Repair's text appears as each part settles rather than streaming. Its "cannot answer a gate" rule is enforced by the tool and its instructions, not by the API, so it is as strong as the agent shell's isolation (braid#201, braid#203).

Shipped on main (098c8af), archived as `2026-10-19-repair-agent`. - **Repair** is one conversation per run, available while a run is stopped or failed. The message box talks to it by itself (Send only), and a **Repair** button opens its conversation. - It works in the run's worktree with an implementation agent's access, and drives the run through a `repair` tool: `status`, `resume`, `redo`, `accept`. Each goes through the route the buttons use, with Repair as the actor. It has no action for a gate. - **A repair survives the retry.** Before one of Repair's verbs takes effect, Braid snapshots the worktree, and the rollback restores that snapshot when it is newer than the step's entry checkpoint. The operator's own Resume after a repair keeps it too. - **Short-lived server.** The first message starts the run's own opencode server in its slot, it stops after a quiet period (Settings), and on resume it simply becomes the run's server. - **Settings:** a Repair backend (the main backend by default, or another saved profile) and the quiet period. The Free profile is refused for now, also when the run's own backend is Free, until the agent-shell isolation work is done. - **Marked in the console:** a `repaired` or `by hand` marker on the steps it touched, and a spine entry for each session. Verified by unit tests, 358 browser specs, a live test against opencode 2.0.30, and a simulated run (`repair-carries-a-failed-run-on`) in which a failed run is repaired and merges. The simulated run found that opencode refuses a prompt id not starting `msg_`; the route now normalises it. Not in this change: asking a question of a live run without interrupting it, and a nudge for a stuck run (braid#223). Repair's text appears as each part settles rather than streaming. Its "cannot answer a gate" rule is enforced by the tool and its instructions, not by the API, so it is as strong as the agent shell's isolation (braid#201, braid#203).
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
cmoriarty/braid#222
No description provided.