@nickysagan/issue-orchestrator 0.1.2 → 0.1.3

package/README.md

@@ -6,18 +6,21 @@ subscription-authenticated `ccode` implementation workers alive — each in its
 tmux window running:
 
 ```bash
-ccode --print --permission-mode auto --model claude-opus-4-8 "/github-issue <number>"
+ccode --print --permission-mode auto --model claude-opus-5 "/github-issue <number>"
 ```
 
+The full model name pins implementation workers to Opus 5 rather than the
+Claude Code default or the moving `opus` alias. Non-interactive print mode
+skips the workspace-trust prompt, and each process exits — closing its tmux
+window — once its command finishes.
+
 Usage limits are enforced by
 [Usage Sentinel](https://github.com/Sadotu/usage-sentinel), which pauses this
 orchestrator's entire Docker container — supervisor and workers together — rather
-than this repository stopping workers itself. The full model name pins issue
-workers to Opus 4.8 instead of the Claude Code default or the moving `opus`
-alias.
+than this repository stopping workers itself.
 
-A finished PR is not merged automatically. It first passes through the managed
-review gate below, which uses a third, separately reserved worker slot.
+A finished implementation PR is marked ready for the repository owner. The
+supervisor does not review, repair, approve, or merge it automatically.
 
 ## Orchestrator
 
@@ -44,37 +47,24 @@ issue-orchestrator
 ```
 
 The shared [`agent-devcontainer`](https://github.com/Sadotu/agent-devcontainer)
-also exposes that command through the literal alias:
-
-```bash
-start work
-```
-
-The supervisor resolves the `origin` of that current working directory,
-checks GitHub App authentication, registers its own container with Sentinel, and
-starts autonomous workers itself:
-
-```bash
-ccode --print --permission-mode auto --model claude-opus-4-8 "/github-issue <number>"
-```
+also exposes that command through the literal alias `start work`.
 
-Non-interactive print mode skips the workspace-trust prompt, and each process
-exits after its command finishes. A supervisor that cannot resolve its container
-ID or register its lease exits nonzero rather than run unenforced. Do not start
-Claude separately.
+The supervisor resolves the `origin` of that working directory, checks GitHub App
+authentication, registers its own container with Sentinel, and starts the
+autonomous workers itself. Do not start Claude separately. A supervisor that
+cannot resolve its container ID or register its lease exits nonzero rather than
+run unenforced.
 
 Only one supervisor per repository per Linux network namespace may run at a
-time. A second invocation in the same namespace for the same resolved
-`owner/repo` exits nonzero with an `already running` error before
-authentication, the container lease, tmux, or worker startup. Ownership is held by a
-kernel-owned Linux abstract Unix socket, so it is released on normal exit and
-automatically when the supervisor process dies. Devcontainers normally have
-distinct network namespaces and therefore independent guards; containers that
-share a network namespace also share this guard.
-
-Neither the image build nor devcontainer startup launches the supervisor or
-an LLM. Work begins only when a user explicitly runs `issue-orchestrator` or
-its `start work` alias.
+time; a second invocation for the same resolved `owner/repo` exits nonzero with
+`already running` before authentication, the lease, tmux, or worker startup.
+Ownership is a kernel-owned Linux abstract Unix socket, released on normal exit
+and automatically when the process dies. Devcontainers normally have distinct
+network namespaces and therefore independent guards; containers sharing a
+namespace share this guard.
+
+Neither the image build nor devcontainer startup launches the supervisor or an
+LLM. Work begins only when a user runs `issue-orchestrator` or `start work`.
 
 ### Repository-checkout usage
 
@@ -87,226 +77,100 @@ tmux attach -t orchestrator   # watch the workers directly
 ### How it works
 
 - **Claim** — the lowest-numbered `agent-ready` issue has its label swapped
-  `agent-ready` → `agent-running`, then a tmux window `issue-<n>` opens running
-  this autonomous command:
-
-  ```bash
-  ccode --print --permission-mode auto --model claude-opus-4-8 "/github-issue <n>"
-  ```
-
-  Non-interactive print mode skips the workspace-trust prompt; the process exits
-  and its tmux window closes after the command finishes.
-- **Complete** — a worker finishes by leaving its PR in draft and putting
-  `agent-review` on the issue. Reaching any phase label is what marks
-  implementation done: the supervisor closes the tmux window and frees the slot,
-  and `agent-running` stays. An already-closed window is treated as closed; a
-  failure at any later step is logged and retried by the next poll.
-- **Vanished** — if a worker window disappears before the issue reaches a phase
-  label, the workflow died. There is no repair worker, so the supervisor fails
-  closed: it comments on the issue — including the vanished worker's log path
-  and the tail of its output — and sets `agent-blocked`. The issue is never
-  restarted automatically, because its draft PR or worktree may still exist.
-- **Worker logs** — every launch `tee`s the window's combined output to
-  `<git-common-dir>/issue-orchestrator/logs/<issue|review>-<n>.<attempt>.log`,
-  keeping the latest three attempts. Surfaced tails are scrubbed of secrets. A
-  run that reaches its end stamps a final `[orchestrator <ISO>] ... finished ...`
-  line into its log, so a tail can be placed in time without the file's mtime.
-- **Active-container lease** — at startup the supervisor resolves its own exact
-  64-character Docker container ID (from `/proc/self/mountinfo`; the short
-  `hostname` form is not accepted) and registers it with
-  `PUT /managed-containers/<id>` on Sentinel. Registration is a lease, not an
-  admission decision: Sentinel never allows or denies a start. Every later poll
-  re-PUTs the same ID as its heartbeat, well inside the five-minute lease; a
-  clean exit `DELETE`s it as best-effort cleanup, and an abrupt exit is handled
-  by Sentinel's lease expiry. A failed heartbeat is logged and retried on the
-  next poll. The supervisor keeps a local guard of two implementation workers
-  plus one reviewer.
-- **Usage enforcement lives in Sentinel** — when Claude Code's five-hour or
-  weekly window reaches 95%, Sentinel `docker pause`s every registered container,
-  freezing this supervisor and every worker process in place, and unpauses only
-  after a fresh valid reading puts both windows below 95%. This repository reads
-  no usage telemetry, applies no thresholds, calls no Docker API, and never kills
-  a worker because of usage.
-- **Stop** — the supervisor exits when nothing is queued, no worker or reviewer
-  window is live, and every managed issue rests in `agent-blocked` or
-  `user-merge-review`. Merge and post-merge cleanup monitoring are not yet
-  implemented.
+  `agent-ready` → `agent-running`, then a tmux window `issue-<n>` opens.
+- **Complete** — Phase 6 marks the implementation PR ready for the owner. The
+  next poll closes any remaining worker window, removes `agent-running` from
+  the issue, and frees the slot.
+- **Vanished** — if a worker disappears while its PR is still draft or absent,
+  the claim is released and the draft/worktree is preserved. It is not
+  restarted automatically.
+- **Worker logs** — every implementation launch writes combined output to
+  `<git-common-dir>/issue-orchestrator/logs/issue-<n>.<attempt>.log`, keeping
+  the latest three attempts and scrubbing secrets from surfaced tails.
+- **Usage enforcement** — Usage Sentinel owns pause/unpause thresholds. This
+  repository reads no usage telemetry and never kills a worker for usage.
+- **Stop** — the supervisor exits when nothing is queued and no implementation
+  window is live.
 
 Live container pause/unpause check:
 [docs/smoke-checks/README.md](docs/smoke-checks/README.md).
 
-## Managed review gate
-
-A managed PR receives an independent automated review and then either stops with
-documented blockers or becomes ready for the owner. The supervisor never
-approves and never merges.
-
-### Labels
-
-At startup — after the repository is resolved and the GitHub App auth check
-passes, and before the first poll — the supervisor creates any of these labels
-that the repository is missing. Labels that already exist are never renamed,
-recoloured, or re-described, and no GitHub mutation ever happens at image-build
-time (the build has neither a target repository nor runtime credentials).
+## Implementation-only handoff
 
-| Label | Colour | Meaning |
-|---|---|---|
-| `agent-ready` | `0e8a16` | Ready for issue-orchestrator claim |
-| `agent-running` | `1d76db` | Managed by issue-orchestrator |
-| `agent-review` | `5319e7` | Waiting for or undergoing automated review |
-| `agent-blocked` | `d73a4a` | Automated workflow blocked; findings posted |
-| `user-merge-review` | `fbca04` | Automated review passed; waiting for owner review and merge |
+`agent-running` remains the active ownership marker: it is applied when an
+issue is claimed and removed only after the implementation PR is ready for the
+owner, or when a vanished/failed launch is safely released. Existing review
+labels are left untouched in repositories, but the supervisor does not create a
+reviewer or repair worker and does not transition issues through them.
 
-`agent-running` is the durable ownership marker: it is applied at claim and
-stays until post-merge cleanup (not yet implemented). Exactly one phase label —
-`agent-review`, `agent-blocked`, or `user-merge-review` — is active alongside
-it. Issue labels are canonical and the PR mirrors them; every poll repairs a
-mismatch, issuing an edit only when the sets actually differ.
-
-A PR with no linked `agent-running` issue is ignored entirely — manual
-`/github-issue` PRs and unrelated `agent/*` branches are never touched. More
-than one PR closing an issue, a branch that disagrees with its closing
-reference, or an `agent-review` issue with no PR all fail closed: an actionable
-comment plus `agent-blocked`.
-
-### Capacity
-
-Two reserved implementation slots plus one reviewer slot that is never borrowed
-for implementation. The pools are separate tmux window namespaces — `issue-<n>`
-and `review-<n>` — each counting only its own live windows. The oldest eligible
-`agent-review` PR gets a fresh reviewer window running:
-
-```bash
-ccode --print --permission-mode auto --model claude-opus-4-8 "/review-pr <pr>"
-```
-
-The reviewer slot frees as soon as that window exits. Waiting on CI holds no
-slot, because it is pure label state with no window.
-
-### Review marker
-
-The reviewer (`Sadotu/agent-skills`, `review-pr`) records each pass in one
-immutable PR comment carrying a single-line marker:
-
-```
-<!-- review-pr:v1 {"fingerprint":"<64-hex>","head":"<40-hex>","base":"<40-hex>","issueUpdatedAt":"<ISO>","prUpdatedAt":"<ISO>","issue":41,"pr":72,"pass":1,"verdict":"PASS"} -->
-```
+Manual and managed `/github-issue` runs both finish by marking the PR ready.
+Human review and merge begin there. The supervisor exposes no approve or merge
+operation.
 
-The reviewer is the producer and owns this format; this repository only consumes
-it. Verdicts are exactly `PASS` and `BLOCKING`.
-
-A marker is applied only when all three hold:
-
-- **Authorship** — the comment has `viewerDidAuthor: true`, so the same GitHub
-  App identity the supervisor authenticates as wrote it. Every fingerprint input
-  is public, so without this check any commenter could forge a `PASS`.
-- **Identity** — its `issue` and `pr` are the managed pair being gated.
-- **Freshness** — its `fingerprint` equals the live fingerprint,
-  `sha256(head 0x1e base 0x1e issue-body 0x1e pr-body)`. Bodies decide
-  freshness, not `updatedAt`: a new comment or a label edit moves the timestamps
-  while reviewing the same content, whereas any real change to the head, the
-  base, the issue text, or the PR text invalidates the pass. `issueUpdatedAt`
-  and `prUpdatedAt` are recorded for audit only.
-
-Comparing against live state rather than a snapshot captured at launch needs no
-persistence, so the same content is handled once even across a supervisor
-restart or a crash between the comment and the label transition. A marker that
-fails any check is discarded silently: nothing is posted, nothing transitions,
-and the PR simply queues a fresh pass. Parsing fails closed on an unsupported
-tag, malformed JSON, or a missing or ill-typed field. A trusted, applicable
-marker carrying an unsupported *verdict* is the one case that is not discarded —
-it blocks, so a contract break surfaces instead of looping.
-
-### Transitions
-
-**`BLOCKING`** — the PR is kept or returned to draft and `agent-review` becomes
-`agent-blocked` on issue and PR. The reviewer's findings stand alone in its own
-comment; the supervisor adds nothing and stops. There is no automatic repair.
-
-**`PASS`** — the PR is marked ready for review first, so repositories whose CI
-triggers on `ready_for_review` start their checks. Checks are read on the
-following poll, never in the same one that opened the PR:
-
-| Checks | Outcome |
-|---|---|
-| None configured | Green → `user-merge-review` |
-| All complete and successful, neutral, or skipped | Green → `user-merge-review` |
-| Any still running | Keep `agent-review`; reviewer slot stays free |
-| Any failed | Return to draft, `agent-blocked`, post the failing check names and URLs |
-| Data unreadable | Transition nothing; retry next poll |
-
-Every check GitHub reports is treated as required. "No checks configured" and
-"could not read the checks" are deliberately distinct: only the former counts as
-green.
-
-### GitHub authentication
+## GitHub authentication
 
 `gh` does not auto-consume the GitHub App credential, so the supervisor mints a
-short-lived App installation token (via `gh-app-token.sh`, overridable with
+short-lived installation token (via `gh-app-token.sh`, overridable with
 `GH_APP_TOKEN_SCRIPT`) and injects it as `GH_TOKEN` for every `gh` call,
-re-minting each poll. At startup it runs an authenticated `gh repo view` smoke
-check and exits with a clear message if the App is not authenticated — rather
-than churning on unauthenticated calls every poll.
+re-minting each poll. At startup an authenticated `gh repo view` smoke check
+exits with a clear message if the App is not authenticated, rather than churning
+on unauthenticated calls every poll.
 
 ### Configuration
 
-The local concurrency guard is fixed at two implementation slots plus one
-reviewer slot. Two knobs are environment-tunable:
+The local concurrency guard is fixed at two implementation slots. Two knobs
+are environment-tunable:
 
 | Var | Default | Meaning |
 |-----|---------|---------|
 | `SENTINEL_URL` | `http://usage-sentinel:4317` | Usage Sentinel base URL for the managed-container lease, on the shared container network; set this explicitly (for example, `http://host.docker.internal:4317`) only when Sentinel is exposed on the host |
 | `POLL_MS` | `60000` | Poll interval |
 
-Labels are created at startup — see the managed review gate below.
+Labels are created at startup — see the managed review gate above.
 
 ## Repo contents
 
 | Path | Purpose |
 |------|---------|
 | `agents.toml` / `agents.lock` | [dotagents](https://github.com/Sadotu/agent-skills) manifest — declares which skills are installed and pins their source commits |
-| `.agents/skills/` | Installed skills (`github-issue`, `setup`) — managed artifacts, restored from the manifest, not committed |
+| `.agents/skills/` | Installed skills (`address-review`, `github-issue`, `review-pr`, `setup`) — managed artifacts, restored from the manifest, not committed |
 | `.claude/skills` | Symlink to `.agents/skills` so Claude Code picks the skills up |
 | `CLAUDE.md` | Agent instructions and gotchas for working in this repo |
 
 ## Skills
 
-- **`github-issue`** — runs a GitHub issue end to end: select issue, open a
-  draft PR immediately, self-resolve design decisions (logged to the PR),
-  implement in an isolated worktree, verify against the issue, mark ready.
+- **`github-issue`** — runs an issue end to end, opens a draft PR, implements
+  in an isolated worktree, verifies the result, and marks the PR ready for the
+  owner.
 - **`setup`** — connects the repo to the `container-coding-agent` GitHub App
   and verifies `git`/`gh` authenticate as the App.
 
-Both are sourced from [`Sadotu/agent-skills`](https://github.com/Sadotu/agent-skills).
+The standalone `review-pr` and `address-review` skills remain installed for
+manual use, but the production supervisor route does not invoke them.
 
 ## Releasing
 
-`package.json` holds the version, and merging the bump is the whole release.
-Bump it in a normal pull request; when that lands on `main`,
-`.github/workflows/publish.yml` sees a version the registry does not carry,
-runs the tests, publishes, and pushes the matching `v<version>` tag. A merge
-that does not bump the version finds its version already published and exits
-without releasing anything.
+`package.json` holds the version, and merging the bump is the whole release. Bump
+it in a normal pull request; when that lands on `main`,
+`.github/workflows/publish.yml` sees a version the registry does not carry, runs
+the tests, publishes, and pushes the matching `v<version>` tag. A merge without a
+bump finds its version already published and exits without releasing. Pushing a
+`v*` tag by hand takes the same path, with one extra guard: the tag must equal
+`v<version>` or the run fails. A published version cannot be republished; bump
+and merge again.
 
 Publishing goes to npmjs via
-[trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm
-token is stored anywhere: npm exchanges the workflow's OIDC identity for a
-short-lived credential. Tagging is a second job, so the job holding an npm
-credential cannot write to this repository and the job that can push a tag
-holds no npm credential. A published version cannot be republished; bump and
-merge again.
-
-Pushing a `v*` tag by hand still works and takes the same path, with one extra
-guard: the tag must equal `v<version>` or the run fails.
-
-Trusted publishing can only be configured on a package that already exists, so
-`0.1.0` was published by hand (`npm login && npm publish`) to bootstrap it.
-Every later release goes through the workflow.
-
-Package visibility is set on the package, not inherited from this private
-repository, and the setting appears only once a version exists. So after the
-**first** release, set it once under **Sadotu → Packages →
-issue-orchestrator → Package settings**.
+[trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token
+is stored anywhere — npm exchanges the workflow's OIDC identity for a short-lived
+credential. Tagging is a separate job, so the job holding an npm credential
+cannot write to this repository and the job that can push a tag holds no npm
+credential.
+
+Two one-time bootstraps, both because they need a package that already exists:
+`0.1.0` was published by hand (`npm login && npm publish`) to enable trusted
+publishing, and package visibility — set on the package, not inherited from this
+private repository — must be set once after the first release under **Sadotu →
+Packages → issue-orchestrator → Package settings**.
 
 ## Development environment
 

package/bin/supervisor.mjs

@@ -9,9 +9,15 @@ import { createManagedContainerClient, resolveContainerId as resolveOwnContainer
 import { BLOCKED, MERGE_REVIEW, READY, REVIEW, RUNNING, phaseOf } from "../src/labels.mjs";
 import { ensureLabels } from "../src/labels.mjs";
 import { selectApplicableMarker } from "../src/reviewMarker.mjs";
+import {
+  formatRepairAttemptComment, formatRepairBudgetComment, formatRepairFailureComment,
+  formatInvalidRepairHistoryComment, hasInvalidRepairHistoryComment,
+  hasRepairBudgetComment, hasRepairFailure,
+} from "../src/repairMarker.mjs";
+import { exactPhase, planRepair } from "../src/repairGate.mjs";
 import { createWorkerLogs } from "../src/workerLogs.mjs";
 import {
-  applyReviewPlan, classifyChecks, failClosed, mirrorLabels, planVerdict, resolveManagedPrs,
+  applyReviewPlan, classifyChecks, failClosed, mirrorLabels, planVerdict, resolveManagedPrs, setPhase,
 } from "../src/reviewGate.mjs";
 
 const run = promisify(execFile);
@@ -20,11 +26,17 @@ const run = promisify(execFile);
 // Fixed defaults per the issue's simplicity constraints. Only the Sentinel URL
 // and the poll interval are environment-tunable.
 //
-// Two reserved implementation slots plus one reviewer slot that is never
-// borrowed for implementation. The pools are separate counters over separate
-// tmux window namespaces, so an orphan in one role can never eat the other's.
+// Two shared implementation/repair slots plus one reviewer slot that is never
+// borrowed. Issue and repair windows share one counter; review windows remain
+// independent.
 const IMPLEMENTATION_SLOTS = 2;
 const REVIEWER_SLOTS = 1;
+// A reviewer that exits without gating its PR is relaunched, because the usual
+// cause is transient. It is not relaunched forever: after this many launches
+// the issue fails closed, rather than burning a `ccode` run and the single
+// reviewer slot every poll on a reviewer that cannot start.
+const REVIEWER_ATTEMPTS = 3;
+const REPAIR_ATTEMPTS = 2;
 const POLL_MS = Number(process.env.POLL_MS || 60000);
 const TOKEN_SCRIPT = process.env.GH_APP_TOKEN_SCRIPT || "/opt/agent-devcontainer/gh-app-token.sh";
 const SESSION = "orchestrator";
@@ -126,6 +138,14 @@ export function createGitHub({ exec, repo }) {
       .sort((a, b) => a.number - b.number);
   }
 
+  async function getIssue(number) {
+    const { stdout } = await exec("gh", [
+      "issue", "view", String(number), ...R, "--json", "number,labels,updatedAt,body",
+    ]);
+    const issue = JSON.parse(stdout || "null");
+    return issue && { ...issue, labels: names(issue.labels) };
+  }
+
   // One call per poll carries everything the review gate needs: the marker
   // fingerprint inputs (SHAs and body), mirror labels, and the check rollup.
   async function listOpenPrs() {
@@ -135,6 +155,12 @@ export function createGitHub({ exec, repo }) {
     return JSON.parse(stdout || "[]").map((pr) => ({ ...pr, labels: names(pr.labels) }));
   }
 
+  async function getPr(number) {
+    const { stdout } = await exec("gh", ["pr", "view", String(number), ...R, "--json", PR_FIELDS]);
+    const pr = JSON.parse(stdout || "null");
+    return pr && { ...pr, labels: names(pr.labels) };
+  }
+
   async function listPrComments(number) {
     const { stdout } = await exec("gh", ["pr", "view", String(number), ...R, "--json", "comments"]);
     return JSON.parse(stdout || "{}").comments || [];
@@ -164,6 +190,10 @@ export function createGitHub({ exec, repo }) {
   // the only path that removes `agent-running`, which is otherwise durable
   // until Phase 7 cleanup.
   const restore = (n) => setIssueLabels(n, { add: [READY], remove: [RUNNING] });
+  // Implementation-only completion releases the active claim after the PR is
+  // ready for the repository owner. The label itself remains the queue's
+  // durable "worker owns this issue" marker while work is in progress.
+  const release = (n) => setIssueLabels(n, { remove: [RUNNING] });
 
   const markPrReady = (n) => exec("gh", ["pr", "ready", String(n), ...R]);
   const markPrDraft = (n) => exec("gh", ["pr", "ready", String(n), ...R, "--undo"]);
@@ -181,8 +211,8 @@ export function createGitHub({ exec, repo }) {
 
   // Deliberately no approve and no merge: the supervisor never does either.
   return {
-    listReadyIssues, listRunningIssues, listOpenPrs, listPrComments,
-    claim, restore, setIssueLabels, setPrLabels, markPrReady, markPrDraft,
+    listReadyIssues, listRunningIssues, getIssue, listOpenPrs, getPr, listPrComments,
+    claim, restore, release, setIssueLabels, setPrLabels, markPrReady, markPrDraft,
     commentIssue, commentPr, listLabels, createLabel,
   };
 }
@@ -204,6 +234,14 @@ export function createTmux({ exec, session = SESSION, logs = NO_WORKER_LOGS }) {
     return n;
   }
 
+  function reviewFingerprint(value) {
+    const fingerprint = String(value ?? "");
+    if (!/^[0-9a-f]{64}$/.test(fingerprint)) {
+      throw new Error(`invalid review fingerprint: ${value}`);
+    }
+    return fingerprint;
+  }
+
   // tmux passes its command to /bin/sh, which then invokes interactive bash so
   // the subscription-authenticated `ccode` alias is available. Quote every
   // model-derived or recorded value before it crosses either shell boundary.
@@ -225,7 +263,7 @@ export function createTmux({ exec, session = SESSION, logs = NO_WORKER_LOGS }) {
     const set = new Set();
     for (const line of stdout.split("\n")) {
       const m = line.trim().match(pattern);
-      if (m) set.add(Number(m[1]));
+      if (m && Number(m[1]) > 0) set.add(Number(m[1]));
     }
     return set;
   }
@@ -234,6 +272,7 @@ export function createTmux({ exec, session = SESSION, logs = NO_WORKER_LOGS }) {
   // Reviewer windows are a separate namespace so the reserved reviewer slot can
   // never be consumed by — or borrowed for — implementation.
   const listReviewIssues = () => listWindows("review");
+  const listRepairIssues = () => listWindows("repair");
 
   // Callers validate their numbers before calling this, so an invalid number
   // still throws synchronously rather than rejecting a returned promise.
@@ -246,13 +285,18 @@ export function createTmux({ exec, session = SESSION, logs = NO_WORKER_LOGS }) {
   // finish instant — the supervisor learns of it up to a poll later, while
   // `tee` may still hold the file open. `date` matches `formatLogLine`'s ISO
   // 8601 UTC shape, so both kinds of orchestrator line read alike.
-  async function newWindow(role, number, name, command, completion) {
-    const path = await logs.prepare(role, number);
-    const cmd = `bash -ic ${shellQuote(command)}${path
-      ? ` 2>&1 | tee ${shellQuote(path)}`
-        + `; printf '[orchestrator %s] %s\\n' "$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)"`
-        + ` ${shellQuote(completion)} >> ${shellQuote(path)}`
-      : ""}`;
+  async function newWindow(role, number, name, command, completion, options = {}) {
+    const path = options.pathReserved ? options.path : await logs.prepare(role, number);
+    if (!path) {
+      return exec("tmux", ["new-window", "-t", session, "-n", name, `bash -ic ${shellQuote(command)}`]);
+    }
+    const pipeline = `bash -ic ${shellQuote(command)} 2>&1 | tee ${shellQuote(path)}`;
+    const status = options.preserveExitStatus ? `; status=\${PIPESTATUS[0]}` : "";
+    const stamp = options.preserveExitStatus
+      ? `; printf '[orchestrator %s] %s (exit status %s)\\n' "$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)" ${shellQuote(completion)} "$status" >> ${shellQuote(path)}; exit "$status"`
+      : `; printf '[orchestrator %s] %s\\n' "$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)" ${shellQuote(completion)} >> ${shellQuote(path)}`;
+    const script = `${pipeline}${status}${stamp}`;
+    const cmd = options.preserveExitStatus ? `bash -c ${shellQuote(script)}` : script;
     return exec("tmux", ["new-window", "-t", session, "-n", name, cmd]);
   }
 
@@ -262,20 +306,42 @@ export function createTmux({ exec, session = SESSION, logs = NO_WORKER_LOGS }) {
     // window command via a non-interactive shell that never sources .bashrc,
     // so the alias would silently fail to resolve without `bash -ic`, which
     // forces alias expansion regardless of login/interactive invocation.
-    const command = `ccode --print --permission-mode auto --model claude-opus-4-8 "/github-issue ${n}"`;
+    const command = `ccode --print --permission-mode auto --model claude-opus-5 "/github-issue ${n}"`;
     // No PR to name: the worker opens one mid-run, long after this launch.
     return newWindow("issue", n, `issue-${n}`, command, `Worker finished for #${n}`);
   }
 
   // The reviewer is a read-only pass over an existing PR; the window is named
   // for the issue so capacity accounting lines up with the managed issue set.
+  //
+  // `review-pr` reviews a linked *pair* and takes the issue first, then the PR
+  // — the order its SKILL.md and both consumer specs document, which is the
+  // reverse of the order its own snapshot/publish helper scripts take. The
+  // reviewer runs under `--print`, so a missing argument cannot be asked for:
+  // it would simply never resolve its inputs and never publish a pass.
   function openReviewer(number, prNumber) {
     const i = issueNumber(number);
     const p = issueNumber(prNumber);
-    const command = `ccode --print --permission-mode auto --model claude-opus-4-8 "/review-pr ${p}"`;
+    const command = `ccode --print --permission-mode auto --model claude-opus-5 "/review-pr ${i} ${p}"`;
     return newWindow("review", i, `review-${i}`, command, `Reviewer finished for #${i} (PR #${p})`);
   }
 
+  function openRepair(number, prNumber, fingerprint, reservedPath) {
+    const i = issueNumber(number);
+    const p = issueNumber(prNumber);
+    const f = reviewFingerprint(fingerprint);
+    if (reservedPath === undefined) {
+      throw new Error("reserved repair log path must be provided explicitly");
+    }
+    const command = `ccode --print --permission-mode auto --model claude-opus-5 "/address-review ${i} ${p} ${f}"`;
+
+    return newWindow("repair", i, `repair-${i}`, command, `Repair finished for #${i} (PR #${p})`, {
+      pathReserved: true, path: reservedPath, preserveExitStatus: true,
+    });
+  }
+
+  const prepareRepair = (number) => logs.prepare("repair", issueNumber(number));
+
   // Suppress ONLY a confirmed "window absent" failure (idempotent close). Any
   // other tmux failure (e.g. server down) propagates so the caller does not
   // wrongly free the slot for a window that may still be alive.
@@ -290,7 +356,105 @@ export function createTmux({ exec, session = SESSION, logs = NO_WORKER_LOGS }) {
     }
   }
 
-  return { ensureSession, listWorkerIssues, listReviewIssues, openWorker, openReviewer, closeWorker };
+  return {
+    ensureSession, listWorkerIssues, listReviewIssues, listRepairIssues,
+    openWorker, openReviewer, prepareRepair, openRepair, closeWorker,
+  };
+}
+
+// Map open PRs to the implementation issue they close. GitHub's parsed closing
+// linkage is authoritative; the conventional branch prefix is a fallback.
+export function implementationPrForIssue(prs, number) {
+  const prefix = `agent/${number}-`;
+  const closesIssue = (pr) => Array.isArray(pr.closingIssuesReferences)
+    && pr.closingIssuesReferences.some((ref) => ref?.number === number);
+  const matchesBranch = (pr) => typeof pr.headRefName === "string"
+    && pr.headRefName.startsWith(prefix);
+  return (prs || []).find((pr) => closesIssue(pr) || matchesBranch(pr)) || null;
+}
+
+// Production poll route after the managed-review rollback. It deliberately
+// knows only queue, implementation worker and owner-ready PR states. Review,
+// repair, approval and merge remain outside the supervisor.
+export async function runImplementationOnlyOnce({
+  gh, tmux,
+  checkSetupReady = async () => true,
+  implementationSlots = IMPLEMENTATION_SLOTS,
+  log,
+  logs = NO_WORKER_LOGS,
+  runningIssues,
+}) {
+  await tmux.ensureSession();
+  const running = runningIssues !== undefined ? runningIssues : await gh.listRunningIssues();
+  const liveIssues = await tmux.listWorkerIssues();
+  const prs = await gh.listOpenPrs();
+  let liveCount = liveIssues.size;
+
+  for (const issue of running) {
+    try {
+      const pr = implementationPrForIssue(prs, issue.number);
+      if (pr && pr.isDraft === false) {
+        if (liveIssues.has(issue.number)) {
+          await tmux.closeWorker(issue.number);
+          liveIssues.delete(issue.number);
+          liveCount -= 1;
+        }
+        await gh.release(issue.number);
+        log(`Completed #${issue.number} (PR ready for owner) — agent-running released`);
+      } else if (!liveIssues.has(issue.number)) {
+        const diagnostics = await logs.diagnostics("issue", issue.number);
+        const detail = diagnostics
+          ? `; log: ${diagnostics.path}\n${diagnostics.tail}`
+          : "";
+        await gh.release(issue.number);
+        log(`Worker for #${issue.number} vanished; PR still draft (${pr ? pr.url : "no PR"}) — released, not restarted${detail}`);
+      }
+    } catch (err) {
+      log(`reconcile error for #${issue.number} (leaving for next poll): ${err.message}`);
+    }
+  }
+
+  const ready = await gh.listReadyIssues();
+  if (ready.length > 0 && !await checkSetupReady()) {
+    log("Agent setup incomplete — pausing worker launches");
+    return {
+      done: false, implLive: liveCount, reviewLive: 0,
+      started: 0, reviewsStarted: 0, repairsStarted: 0,
+    };
+  }
+
+  let started = 0;
+  for (const number of ready) {
+    if (liveCount >= implementationSlots) break;
+    let claimed = false;
+    try {
+      await gh.claim(number);
+      claimed = true;
+      await tmux.openWorker(number);
+      liveCount += 1;
+      started += 1;
+      log(`Started worker for #${number}`);
+    } catch (err) {
+      const cleanup = [];
+      if (claimed) {
+        try {
+          await gh.restore(number);
+        } catch (cleanupError) {
+          cleanup.push(`restore: ${cleanupError.message}`);
+        }
+      }
+      log(`failed to start #${number} (leaving for next poll): ${err.message}${cleanup.length ? `; cleanup failed: ${cleanup.join(", ")}` : ""}`);
+    }
+  }
+
+  return {
+    done: ready.length === 0 && liveCount === 0,
+    implLive: liveCount,
+    reviewLive: 0,
+    started,
+    reviewsStarted: 0,
+    repairsStarted: 0,
+  };
 }
 
 // ---- one poll cycle ---------------------------------------------------------
@@ -305,6 +469,7 @@ export async function runOnce({
   checkSetupReady = async () => true,
   implementationSlots = IMPLEMENTATION_SLOTS,
   reviewerSlots = REVIEWER_SLOTS,
+  reviewerAttempts = REVIEWER_ATTEMPTS,
   log,
   logs = NO_WORKER_LOGS,
   runningIssues,
@@ -314,15 +479,21 @@ export async function runOnce({
   const running = runningIssues !== undefined ? runningIssues : await gh.listRunningIssues();
   const liveImpl = await tmux.listWorkerIssues();
   const liveReview = await tmux.listReviewIssues();
+  const liveRepair = await tmux.listRepairIssues();
   const prs = await gh.listOpenPrs();
 
-  let implLive = liveImpl.size;
+  let implLive = liveImpl.size + liveRepair.size;
   let reviewLive = liveReview.size;
 
   // Phase state as this poll last knew it, updated in place by each transition
   // so the exit condition below reflects the work just done.
   const phases = new Map(running.map((issue) => [issue.number, phaseOf(issue.labels)]));
   const { managed, problems } = resolveManagedPrs(running, prs);
+  const commentsByPr = new Map();
+  const prComments = async (number) => {
+    if (!commentsByPr.has(number)) commentsByPr.set(number, gh.listPrComments(number));
+    return commentsByPr.get(number);
+  };
 
   // --- linkage ambiguity fails closed ---------------------------------------
   for (const problem of problems) {
@@ -370,15 +541,89 @@ export async function runOnce({
     }
   }
 
+  // --- blocked repair reconciliation and eligibility ------------------------
+  // First reconcile durable reservations and collect complete candidates.
+  // Launching happens only after every managed item has been inspected.
+  const eligibleRepairs = [];
+  const liveRepairPairs = new Set();
+  const reconciledRepairPairs = new Set();
+  for (const { issue, pr } of managed) {
+    try {
+      if (![BLOCKED, REVIEW].includes(phases.get(issue.number))) continue;
+      const comments = await prComments(pr.number);
+      const identity = { issue: issue.number, pr: pr.number };
+      const plan = planRepair({
+        issue, pr, comments, phase: phases.get(issue.number),
+        liveRepair: liveRepair.has(issue.number), maxAttempts: REPAIR_ATTEMPTS,
+      });
+      if (plan.action === "invalid-history") {
+        log(`#${issue.number}: invalid repair history — leaving blocked for manual intervention`);
+        const sourceFingerprint = plan.latestReview?.fingerprint;
+        if (sourceFingerprint && !hasInvalidRepairHistoryComment(comments, identity, sourceFingerprint)) {
+          await gh.commentPr(pr.number, formatInvalidRepairHistoryComment({ ...identity, sourceFingerprint }));
+        }
+        continue;
+      }
+      if (plan.action === "live") {
+        liveRepairPairs.add(issue.number);
+        continue;
+      }
+      if (plan.action === "review") {
+        await setPhase({ gh, issue, pr, phase: REVIEW });
+        phases.set(issue.number, REVIEW);
+        reconciledRepairPairs.add(issue.number);
+        continue;
+      }
+      if (plan.action === "failed") {
+        const { reservation } = plan;
+        await setPhase({ gh, issue, pr, phase: BLOCKED });
+        phases.set(issue.number, BLOCKED);
+        reconciledRepairPairs.add(issue.number);
+        if (!hasRepairFailure(comments, identity, reservation.attempt, reservation.sourceFingerprint)) {
+          const diagnostics = await logs.diagnostics("repair", issue.number);
+          const correlated = reservation.log && diagnostics?.path === reservation.log ? diagnostics : null;
+          const exitMatch = String(correlated?.tail ?? "").match(/exit status\s+(\d+)/i);
+          await gh.commentPr(pr.number, formatRepairFailureComment({
+            ...identity,
+            attempt: reservation.attempt,
+            sourceFingerprint: reservation.sourceFingerprint,
+            logUrl: correlated?.path ?? null,
+            exitCode: exitMatch ? Number(exitMatch[1]) : "unavailable",
+          }));
+        }
+        continue;
+      }
+      if (plan.action === "budget") {
+        if (!hasRepairBudgetComment(comments, identity, plan.marker.fingerprint)) {
+          await gh.commentPr(pr.number, formatRepairBudgetComment({
+            ...identity,
+            maxAttempts: REPAIR_ATTEMPTS,
+            sourceFingerprint: plan.marker.fingerprint,
+            blockingReviewUrls: plan.history.blockingPasses.map(({ url }) => url),
+          }));
+        }
+        continue;
+      }
+      if (plan.action !== "eligible") continue;
+      eligibleRepairs.push({
+        issue, pr, attempt: plan.attempt, sourceFingerprint: plan.sourceFingerprint,
+        blockingCreatedAt: plan.blockingCreatedAt,
+      });
+    } catch (err) {
+      log(`repair reconciliation error for #${issue.number} (leaving for next poll): ${err.message}`);
+    }
+  }
+
   // --- review reconciliation -------------------------------------------------
   const needsReview = [];
   for (const { issue, pr } of managed) {
     try {
+      if (liveRepairPairs.has(issue.number) || reconciledRepairPairs.has(issue.number)) continue;
       await mirrorLabels({ gh, issue, pr });
       if (phases.get(issue.number) !== REVIEW) continue;
 
       const checkedAt = now();
-      const comments = await gh.listPrComments(pr.number);
+      const comments = await prComments(pr.number);
       const marker = selectApplicableMarker(comments, {
         issue: issue.number, pr: pr.number,
         head: pr.headRefOid, base: pr.baseRefOid,
@@ -403,10 +648,10 @@ export async function runOnce({
   }
 
   const ready = await gh.listReadyIssues();
-  const wantsLaunch = ready.length > 0 || needsReview.length > 0;
+  const wantsLaunch = ready.length > 0 || needsReview.length > 0 || eligibleRepairs.length > 0;
   if (wantsLaunch && !await checkSetupReady()) {
     log("Agent setup incomplete — pausing worker and reviewer launches");
-    return { done: false, implLive, reviewLive, started: 0, reviewsStarted: 0 };
+    return { done: false, implLive, reviewLive, started: 0, reviewsStarted: 0, repairsStarted: 0 };
   }
 
   // --- reviewer launches (oldest PR first) -----------------------------------
@@ -424,6 +669,23 @@ export async function runOnce({
       // eventually displace it and the relaunch itself explains nothing.
       const diagnostics = await logs.diagnostics("review", issue.number);
       if (diagnostics) {
+        // The reviewer log's attempt number is the durable launch count, so a
+        // reviewer that never gates its PR is bounded instead of relaunched
+        // every poll forever. A missing count (no log at all, or a helper that
+        // reports none) keeps the unbounded behaviour: logs are best effort and
+        // must never be what blocks an issue.
+        if (Number.isInteger(diagnostics.attempt) && diagnostics.attempt >= reviewerAttempts) {
+          await failClosed({
+            gh, issue, pr, log,
+            message: `The reviewer for #${issue.number} exited without gating PR #${pr.number}`
+              + ` after ${diagnostics.attempt} attempts. Its linked PR is ${pr.url}.`
+              + `\n\nReviewer log: \`${diagnostics.path}\`\n\n\`\`\`\n${diagnostics.tail}\n\`\`\``,
+          });
+          phases.set(issue.number, BLOCKED);
+          // The slot is deliberately not consumed: another PR can use it in
+          // this same poll.
+          continue;
+        }
         log(`A previous reviewer for #${issue.number} (${pr.url}) left ${diagnostics.path}:\n${diagnostics.tail}`);
       }
       await tmux.openReviewer(issue.number, pr.number);
@@ -435,6 +697,76 @@ export async function runOnce({
     }
   }
 
+  // --- repair launches (oldest blocking review first) -----------------------
+  eligibleRepairs.sort((a, b) =>
+    String(a.blockingCreatedAt ?? "").localeCompare(String(b.blockingCreatedAt ?? ""))
+      || a.issue.number - b.issue.number);
+  let repairsStarted = 0;
+  for (const repair of eligibleRepairs) {
+    if (implLive >= implementationSlots) break;
+    const { issue, pr, attempt, sourceFingerprint } = repair;
+    let currentIssue;
+    let currentPr;
+    try {
+      currentIssue = await gh.getIssue(issue.number);
+      currentPr = await gh.getPr(pr.number);
+      const comments = await gh.listPrComments(pr.number);
+      const freshPlan = planRepair({
+        issue: currentIssue, pr: currentPr, comments, phase: BLOCKED,
+        liveRepair: false, maxAttempts: REPAIR_ATTEMPTS,
+      });
+      if (freshPlan.action === "invalid-history") {
+        const identity = { issue: issue.number, pr: pr.number };
+        const fingerprint = freshPlan.latestReview?.fingerprint;
+        if (fingerprint && !hasInvalidRepairHistoryComment(comments, identity, fingerprint)) {
+          await gh.commentPr(pr.number, formatInvalidRepairHistoryComment({ ...identity, sourceFingerprint: fingerprint }));
+        }
+        log(`#${issue.number}: repair history became invalid during launch revalidation`);
+        continue;
+      }
+      const linked = currentPr?.closingIssuesReferences?.some(({ number }) => number === issue.number);
+      const valid = currentIssue?.number === issue.number && currentPr?.number === pr.number && linked
+        && freshPlan.action === "eligible" && freshPlan.attempt === attempt
+        && freshPlan.sourceFingerprint === sourceFingerprint;
+      if (!valid) {
+        if (freshPlan.action === "review"
+          && ["stale-review-snapshot", "reserved-head-changed"].includes(freshPlan.reason)
+          && currentIssue && currentPr
+          && exactPhase(currentIssue.labels, BLOCKED) && exactPhase(currentPr.labels, BLOCKED)) {
+          await setPhase({ gh, issue: currentIssue, pr: currentPr, phase: REVIEW });
+          phases.set(issue.number, REVIEW);
+        }
+        continue;
+      }
+    } catch (err) {
+      log(`failed to revalidate repair for #${issue.number} (leaving for next poll): ${err.message}`);
+      continue;
+    }
+    const logPath = await tmux.prepareRepair(issue.number);
+    try {
+      await gh.commentPr(pr.number, formatRepairAttemptComment({
+        issue: issue.number,
+        pr: pr.number,
+        attempt,
+        maxAttempts: REPAIR_ATTEMPTS,
+        sourceFingerprint,
+        head: currentPr.headRefOid,
+        log: logPath,
+      }));
+    } catch (err) {
+      log(`failed to reserve repair for #${issue.number} (leaving for next poll): ${err.message}`);
+      continue;
+    }
+    try {
+      await tmux.openRepair(issue.number, pr.number, sourceFingerprint, logPath);
+      implLive += 1;
+      repairsStarted += 1;
+      log(`Started repair ${attempt} for #${issue.number} (PR #${pr.number})`);
+    } catch (err) {
+      log(`failed to start repair for #${issue.number} (reservation remains for reconciliation): ${err.message}`);
+    }
+  }
+
   // --- implementation launches ----------------------------------------------
   let started = 0;
   for (const n of ready) {
@@ -460,8 +792,9 @@ export async function runOnce({
   // nothing is queued or live. Merge and cleanup monitoring belong to later
   // groups.
   const settled = [...phases.values()].every((phase) => phase === BLOCKED || phase === MERGE_REVIEW);
-  const done = ready.length === 0 && implLive === 0 && reviewLive === 0 && settled;
-  return { done, implLive, reviewLive, started, reviewsStarted };
+  const done = ready.length === 0 && eligibleRepairs.length === 0
+    && implLive === 0 && reviewLive === 0 && settled;
+  return { done, implLive, reviewLive, started, reviewsStarted, repairsStarted };
 }
 
 // ---- real-environment wiring ------------------------------------------------
@@ -518,7 +851,7 @@ export async function main({
   bootstrapLabels = bootstrapRepoLabels,
   resolveContainerId: resolveContainer = resolveOwnContainerId,
   createLeaseClient = createConfiguredLease,
-  runPoll = runOnce,
+  runPoll = runImplementationOnlyOnce,
   checkSetupReady = isAgentSetupReady,
   sleepImpl = sleep,
   log = (message) => console.log(formatLogLine(message)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nickysagan/issue-orchestrator",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A small, supervised GitHub issue queue that keeps autonomous coding workers alive.",
   "license": "MIT",
   "repository": {

package/src/repairGate.mjs

@@ -0,0 +1,57 @@
+import { BLOCKED, PHASE_LABELS, REVIEW, RUNNING } from "./labels.mjs";
+import { selectApplicableMarker } from "./reviewMarker.mjs";
+import {
+  selectLatestTrustedReview, selectLatestTrustedReviewContext,
+  selectRepairHistory, selectRepairReservation,
+} from "./repairMarker.mjs";
+
+export function exactPhase(labels, phase) {
+  const set = new Set(labels || []);
+  return set.has(RUNNING) && set.has(phase)
+    && PHASE_LABELS.filter((label) => set.has(label)).length === 1;
+}
+
+export function planRepair({ issue, pr, comments, phase, liveRepair, maxAttempts }) {
+  if (![BLOCKED, REVIEW].includes(phase)) return { action: "skip" };
+  if (!liveRepair && exactPhase(issue.labels, REVIEW) && exactPhase(pr.labels, REVIEW)) return { action: "skip" };
+
+  const identity = { issue: issue.number, pr: pr.number };
+  const history = selectRepairHistory(comments, identity);
+  const latestReview = selectLatestTrustedReview(comments, identity);
+  const latestContext = selectLatestTrustedReviewContext(comments, identity);
+  if (!history.valid) return { action: "invalid-history", history, latestReview };
+  const reservation = latestReview?.verdict === "BLOCKING"
+    ? selectRepairReservation(comments, identity, latestReview.fingerprint)
+    : null;
+  if (reservation) {
+    if (liveRepair) return { action: "live", reservation };
+    if (reservation.head !== pr.headRefOid) {
+      return { action: "review", reason: "reserved-head-changed", reservation };
+    }
+    return { action: "failed", reservation };
+  }
+  if (phase !== BLOCKED || !exactPhase(issue.labels, BLOCKED) || !exactPhase(pr.labels, BLOCKED)) {
+    return { action: "skip" };
+  }
+  const marker = selectApplicableMarker(comments, {
+    ...identity, head: pr.headRefOid, base: pr.baseRefOid,
+    issueBody: issue.body, prBody: pr.body,
+  });
+  const applicable = marker && latestReview
+    && marker.fingerprint === latestReview.fingerprint && marker.pass === latestReview.pass;
+  if (!applicable || marker.verdict !== "BLOCKING") {
+    return latestReview?.verdict === "BLOCKING"
+      ? { action: "review", reason: "stale-review-snapshot" }
+      : { action: "skip" };
+  }
+  if (!pr.isDraft) return { action: "skip" };
+  if (history.attempts.length >= maxAttempts) {
+    return { action: "budget", marker, history };
+  }
+  return {
+    action: "eligible", marker, history,
+    attempt: history.attempts.length + 1,
+    sourceFingerprint: marker.fingerprint,
+    blockingCreatedAt: latestContext?.createdAt,
+  };
+}

package/src/repairMarker.mjs

@@ -0,0 +1,248 @@
+import { parseReviewMarkers } from "./reviewMarker.mjs";
+
+export const REPAIR_MARKER_TAG = "issue-orchestrator:repair-attempt v1";
+
+const ATTEMPT_PATTERN = /^<!-- issue-orchestrator:repair-attempt v1 (\{.*\}) -->$/m;
+const ATTEMPT_FIELDS = ["issue", "pr", "attempt", "sourceFingerprint", "head", "log"];
+const FAILURE_FIELDS = ["issue", "pr", "attempt", "sourceFingerprint"];
+const BUDGET_FIELDS = ["issue", "pr", "sourceFingerprint"];
+const INVALID_HISTORY_FIELDS = ["issue", "pr", "sourceFingerprint"];
+const FAILURE_PATTERN = /^<!-- issue-orchestrator:repair-failure v1 (\{.*\}) -->$/m;
+const BUDGET_PATTERN = /^<!-- issue-orchestrator:repair-budget-exhausted v1 (\{.*\}) -->$/m;
+const INVALID_HISTORY_PATTERN = /^<!-- issue-orchestrator:repair-history-invalid v1 (\{.*\}) -->$/m;
+
+function positiveInteger(value) {
+  return Number.isInteger(value) && value > 0;
+}
+
+function validIdentity(value) {
+  return value && positiveInteger(value.issue) && positiveInteger(value.pr);
+}
+
+const fingerprint = (value) => typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+const commit = (value) => typeof value === "string" && /^[0-9a-f]{40}$/.test(value);
+
+function exactPayload(value, fields) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).length === fields.length
+    && fields.every((field) => Object.hasOwn(value, field));
+}
+
+function attemptPayload(value) {
+  if (!exactPayload(value, ATTEMPT_FIELDS)) return null;
+  if (!positiveInteger(value.issue) || !positiveInteger(value.pr) || !positiveInteger(value.attempt)) return null;
+  if (!fingerprint(value.sourceFingerprint) || !commit(value.head)) return null;
+  if (value.log !== null && (typeof value.log !== "string" || value.log.length === 0)) return null;
+  return Object.fromEntries(ATTEMPT_FIELDS.map((field) => [field, value[field]]));
+}
+
+export function parseRepairAttempt(body) {
+  const match = ATTEMPT_PATTERN.exec(String(body ?? ""));
+  if (!match) return null;
+  try {
+    return attemptPayload(JSON.parse(match[1]));
+  } catch {
+    return null;
+  }
+}
+
+function trustedAttempt(comment, identity) {
+  if (comment?.viewerDidAuthor !== true) return null;
+  const marker = parseRepairAttempt(comment.body);
+  if (!marker || marker.issue !== identity.issue || marker.pr !== identity.pr) return null;
+  return marker;
+}
+
+export function selectRepairReservation(comments, identity, sourceFingerprint) {
+  if (!validIdentity(identity) || typeof sourceFingerprint !== "string" || sourceFingerprint.length === 0) return null;
+  let found = null;
+  for (const comment of comments || []) {
+    const marker = trustedAttempt(comment, identity);
+    if (marker?.sourceFingerprint === sourceFingerprint) found = marker;
+  }
+  return found;
+}
+
+function trustedReviews(comment, identity) {
+  if (comment?.viewerDidAuthor !== true) return [];
+  return parseReviewMarkers(comment.body).filter((marker) => (
+    marker.issue === identity.issue && marker.pr === identity.pr
+  ));
+}
+
+export function selectLatestTrustedReview(comments, identity) {
+  if (!validIdentity(identity)) return null;
+  let found = null;
+  for (const comment of comments || []) {
+    for (const marker of trustedReviews(comment, identity)) found = marker;
+  }
+  return found;
+}
+
+export function selectLatestTrustedReviewContext(comments, identity) {
+  if (!validIdentity(identity)) return null;
+  let found = null;
+  for (const comment of comments || []) {
+    for (const marker of trustedReviews(comment, identity)) {
+      found = { marker, createdAt: comment.createdAt, url: comment.url };
+    }
+  }
+  return found;
+}
+
+export function selectRepairHistory(comments, identity) {
+  if (!validIdentity(identity)) return { valid: false, attempts: [], blockingPasses: [] };
+  const all = Array.from(comments || []);
+  let start = 0;
+  for (let index = 0; index < all.length; index += 1) {
+    if (trustedReviews(all[index], identity).some(({ verdict }) => verdict === "PASS")) start = index + 1;
+  }
+
+  const attempts = [];
+  const blockingPasses = [];
+  const blockingSources = new Set();
+  const attemptedSources = new Set();
+  let valid = true;
+  for (const comment of all.slice(start)) {
+    for (const marker of trustedReviews(comment, identity)) {
+      if (marker.verdict === "BLOCKING") {
+        blockingPasses.push({ fingerprint: marker.fingerprint, pass: marker.pass, url: comment.url });
+        blockingSources.add(`${marker.fingerprint}\0${marker.head}`);
+      }
+    }
+    const marker = trustedAttempt(comment, identity);
+    if (!marker) continue;
+    if (!blockingSources.has(`${marker.sourceFingerprint}\0${marker.head}`)) continue;
+    if (attemptedSources.has(marker.sourceFingerprint)) {
+      valid = false;
+      continue;
+    }
+    if (marker.attempt !== attempts.length + 1) {
+      valid = false;
+      continue;
+    }
+    attempts.push(marker);
+    attemptedSources.add(marker.sourceFingerprint);
+  }
+  return { valid, attempts, blockingPasses };
+}
+
+function hasTrustedMarker(comments, identity, pattern, fields, validPayload, matches) {
+  for (const comment of comments || []) {
+    if (comment?.viewerDidAuthor !== true) continue;
+    const match = pattern.exec(String(comment.body ?? ""));
+    if (!match) continue;
+    try {
+      const marker = JSON.parse(match[1]);
+      if (exactPayload(marker, fields) && validPayload(marker)
+        && marker.issue === identity.issue && marker.pr === identity.pr
+        && matches(marker)) return true;
+    } catch {
+      // Malformed comments are untrusted state, never durable evidence.
+    }
+  }
+  return false;
+}
+
+export function hasRepairFailure(comments, identity, attempt, sourceFingerprint) {
+  if (!validIdentity(identity) || !positiveInteger(attempt) || !fingerprint(sourceFingerprint)) return false;
+  return hasTrustedMarker(
+    comments, identity, FAILURE_PATTERN, FAILURE_FIELDS,
+    (marker) => positiveInteger(marker.issue) && positiveInteger(marker.pr)
+      && positiveInteger(marker.attempt) && fingerprint(marker.sourceFingerprint),
+    (marker) => marker.attempt === attempt && marker.sourceFingerprint === sourceFingerprint,
+  );
+}
+
+export function hasRepairBudgetComment(comments, identity, sourceFingerprint) {
+  if (!validIdentity(identity) || !fingerprint(sourceFingerprint)) return false;
+  return hasTrustedMarker(
+    comments, identity, BUDGET_PATTERN, BUDGET_FIELDS,
+    (marker) => positiveInteger(marker.issue) && positiveInteger(marker.pr)
+      && fingerprint(marker.sourceFingerprint),
+    (marker) => marker.sourceFingerprint === sourceFingerprint,
+  );
+}
+
+export function hasInvalidRepairHistoryComment(comments, identity, sourceFingerprint) {
+  if (!validIdentity(identity) || !fingerprint(sourceFingerprint)) return false;
+  return hasTrustedMarker(
+    comments, identity, INVALID_HISTORY_PATTERN, INVALID_HISTORY_FIELDS,
+    (marker) => positiveInteger(marker.issue) && positiveInteger(marker.pr)
+      && fingerprint(marker.sourceFingerprint),
+    (marker) => marker.sourceFingerprint === sourceFingerprint,
+  );
+}
+
+function requireCommentInput(input, { attempt = false } = {}) {
+  if (!validIdentity(input)) throw new TypeError("issue and pr must be positive integers");
+  if (!fingerprint(input.sourceFingerprint)) {
+    throw new TypeError("sourceFingerprint must be 64 lowercase hex characters");
+  }
+  if (attempt && !positiveInteger(input.attempt)) throw new TypeError("attempt must be a positive integer");
+}
+
+function hidden(tag, payload) {
+  return `<!-- ${tag} ${JSON.stringify(payload)} -->`;
+}
+
+export function formatRepairAttemptComment(input) {
+  requireCommentInput(input, { attempt: true });
+  if (!commit(input.head)) throw new TypeError("head must be 40 hex characters");
+  if (input.log !== undefined && input.log !== null
+    && (typeof input.log !== "string" || input.log.length === 0)) {
+    throw new TypeError("log must be a nonempty string or null");
+  }
+  if (!positiveInteger(input.maxAttempts)) throw new TypeError("maxAttempts must be a positive integer");
+  const marker = {
+    issue: input.issue, pr: input.pr, attempt: input.attempt,
+    sourceFingerprint: input.sourceFingerprint, head: input.head,
+    log: input.log ?? null,
+  };
+  return [
+    `Automatic repair attempt ${input.attempt} of ${input.maxAttempts} reserved for review source \`${input.sourceFingerprint}\`.`,
+    "",
+    hidden(REPAIR_MARKER_TAG, marker),
+  ].join("\n");
+}
+
+export function formatRepairFailureComment(input) {
+  requireCommentInput(input, { attempt: true });
+  const details = [];
+  if (input.exitCode !== undefined) details.push(`Exit code ${input.exitCode}.`);
+  if (typeof input.logUrl === "string" && input.logUrl.length > 0) details.push(`Logs: ${input.logUrl}`);
+  else details.push("Log location unavailable.");
+  return [
+    `Automatic repair attempt ${input.attempt} failed for review source \`${input.sourceFingerprint}\`.`,
+    ...details,
+    "",
+    hidden("issue-orchestrator:repair-failure v1", {
+      issue: input.issue, pr: input.pr, attempt: input.attempt, sourceFingerprint: input.sourceFingerprint,
+    }),
+  ].join("\n");
+}
+
+export function formatRepairBudgetComment(input) {
+  requireCommentInput(input);
+  if (!positiveInteger(input.maxAttempts)) throw new TypeError("maxAttempts must be a positive integer");
+  const urls = Array.from(input.blockingReviewUrls || []).filter((url) => typeof url === "string" && url.length > 0);
+  return [
+    `${input.maxAttempts} automatic repair attempts have been exhausted for review source \`${input.sourceFingerprint}\`.`,
+    ...(urls.length > 0 ? ["", "Blocking review passes:", ...urls.map((url) => `- ${url}`)] : []),
+    "",
+    hidden("issue-orchestrator:repair-budget-exhausted v1", {
+      issue: input.issue, pr: input.pr, sourceFingerprint: input.sourceFingerprint,
+    }),
+  ].join("\n");
+}
+
+export function formatInvalidRepairHistoryComment(input) {
+  requireCommentInput(input);
+  return [
+    `Invalid automatic repair history detected for review source \`${input.sourceFingerprint}\`. Manual intervention is required.`,
+    "",
+    hidden("issue-orchestrator:repair-history-invalid v1", {
+      issue: input.issue, pr: input.pr, sourceFingerprint: input.sourceFingerprint,
+    }),
+  ].join("\n");
+}

package/src/reviewGate.mjs

@@ -1,4 +1,4 @@
-import { BLOCKED, MANAGED_LABELS, MERGE_REVIEW, REVIEW, phaseOf } from "./labels.mjs";
+import { BLOCKED, MANAGED_LABELS, MERGE_REVIEW, PHASE_LABELS, REVIEW, phaseOf } from "./labels.mjs";
 
 const BRANCH_PREFIX = /^agent\/(\d+)-/;
 
@@ -189,12 +189,21 @@ export function planLabelMirror(issueLabels, prLabels) {
 
 // Swap the issue's phase label and mirror it onto the PR. `agent-running` is
 // never removed here — it is durable until Phase 7.
-async function setPhase({ gh, issue, pr, phase }) {
-  const current = phaseOf(issue.labels);
-  if (current === phase) return;
-  const delta = { add: [phase], remove: current ? [current] : [] };
-  await gh.setIssueLabels(issue.number, delta);
-  if (pr) await gh.setPrLabels(pr.number, delta);
+export async function setPhase({ gh, issue, pr, phase }) {
+  const deltaFor = (labels) => {
+    const current = new Set(labels || []);
+    return {
+      add: current.has(phase) ? [] : [phase],
+      remove: PHASE_LABELS.filter((label) => label !== phase && current.has(label)),
+    };
+  };
+  const issueDelta = deltaFor(issue.labels);
+  if (issueDelta.add.length || issueDelta.remove.length) await gh.setIssueLabels(issue.number, issueDelta);
+  if (pr) {
+    if (!Array.isArray(pr.labels)) throw new Error("PR labels must be provided");
+    const prDelta = deltaFor(pr.labels);
+    if (prDelta.add.length || prDelta.remove.length) await gh.setPrLabels(pr.number, prDelta);
+  }
 }
 
 export async function mirrorLabels({ gh, issue, pr }) {

package/src/workerLogs.mjs

@@ -1,9 +1,8 @@
 // Durable per-attempt worker logs.
 //
-// A tmux worker's output lives and dies with its pane, so a window that
-// vanishes takes the only evidence of why with it. Every launch reserves a
-// file here and streams its combined output into it, which lets the supervisor
-// surface a bounded, redacted tail when it later notices the worker is gone.
+// A tmux worker's pane output disappears with its window. Every launch reserves
+// a file here and streams its combined output into it, preserving evidence the
+// supervisor can surface as a bounded, redacted tail after the worker is gone.
 //
 // Everything is best effort: a log that cannot be written must never cost a
 // worker, so every operation degrades to `null` rather than throwing.
@@ -26,7 +25,7 @@ export const TAIL_CHARS = 4000;
 // Roles are an allowlist, not a passthrough: a later repair worker adds one
 // string here and needs no other change, while no caller-supplied value can
 // ever reach the path.
-export const WORKER_ROLES = new Set(["issue", "review"]);
+export const WORKER_ROLES = new Set(["issue", "review", "repair"]);
 
 const REDACTIONS = [
   // Whole PEM blocks first, before any inner rule can fragment them. The body
@@ -154,9 +153,10 @@ export function createWorkerLogs({
     return join(dir, `${id.role}-${id.number}.${attempt}.log`);
   }
 
-  // The newest recorded attempt for a worker, with its tail already bounded and
-  // redacted. `null` when there is nothing to show — including on any read
-  // failure, because diagnostics must never break the poll that surfaces them.
+  // The newest recorded attempt for a worker, with its attempt number and its
+  // tail already bounded and redacted. `null` when there is nothing to show —
+  // including on any read failure, because diagnostics must never break the
+  // poll that surfaces them.
   async function diagnostics(role, number) {
     const id = identity(role, number);
     if (!id) return null;
@@ -164,8 +164,12 @@ export function createWorkerLogs({
       const dir = await logDir();
       const attempts = await existingAttempts(dir, id.role, id.number);
       if (attempts.length === 0) return null;
-      const path = join(dir, attempts.at(-1).name);
-      return { path, tail: boundedTail(await readFile(path, "utf8")) };
+      const newest = attempts.at(-1);
+      const path = join(dir, newest.name);
+      // The attempt number is this worker's durable launch count: retention
+      // prunes the *oldest* files while `prepare` numbers from the highest
+      // surviving one, so it keeps rising past `KEEP_ATTEMPTS`.
+      return { path, attempt: newest.attempt, tail: boundedTail(await readFile(path, "utf8")) };
     } catch {
       return null;
     }