@nickysagan/issue-orchestrator 0.1.2 → 0.2.0

package/bin/supervisor.mjs

@@ -6,12 +6,19 @@ import { access, realpath } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { createManagedContainerClient, resolveContainerId as resolveOwnContainerId } from "../src/managedContainer.mjs";
+import { describeEnforcementTransition } from "../src/enforcementNotice.mjs";
 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 +27,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";
@@ -39,6 +52,38 @@ export async function isAgentSetupReady({ accessImpl = access } = {}) {
   }
 }
 
+// Admission control for new launches. The pinned `github-issue` skill refuses
+// to isolate issue work when the primary worktree is dirty, so claiming an
+// issue in that state only produces a worker that exits before opening a PR.
+// This runs the same predicate that guard runs — `git status --porcelain` —
+// before anything is claimed.
+//
+// The primary worktree is resolved explicitly rather than assumed to be the
+// caller's cwd: `git worktree list --porcelain` always reports it first, so a
+// supervisor started from inside a linked worktree still inspects the tree
+// isolation will actually branch from.
+//
+// Read-only by construction: it never stashes, resets, cleans, checks out, or
+// commits, and it fails closed — an unreadable result is not a clean one.
+export async function checkPrimaryWorktree({ exec }) {
+  try {
+    const { stdout: worktrees } = await exec("git", ["worktree", "list", "--porcelain"]);
+    const primary = String(worktrees).split("\n")
+      .find((line) => line.startsWith("worktree "))?.slice("worktree ".length).trim();
+    if (!primary) throw new Error("could not resolve the primary worktree");
+    const { stdout: status } = await exec("git", ["-C", primary, "status", "--porcelain"]);
+    const pending = String(status).split("\n").filter((line) => line.trim() !== "");
+    if (pending.length === 0) return { clean: true, reason: "clean", detail: "" };
+    return {
+      clean: false,
+      reason: "dirty",
+      detail: `${pending.length} pending change${pending.length === 1 ? "" : "s"} in ${primary}`,
+    };
+  } catch (err) {
+    return { clean: false, reason: "unreadable", detail: err.message };
+  }
+}
+
 export async function acquireSupervisorOwnership(repo, {
   createServer = createNetServer,
 } = {}) {
@@ -126,6 +171,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 +188,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 || [];
@@ -161,9 +220,13 @@ export function createGitHub({ exec, repo }) {
 
   const claim = (n) => setIssueLabels(n, { add: [RUNNING], remove: [READY] });
   // A launch that fails before any work exists reverts to the queue. This is
-  // the only path that removes `agent-running`, which is otherwise durable
-  // until Phase 7 cleanup.
+  // the only path that returns the issue to `agent-ready`; every other removal
+  // of `agent-running` goes through `release` below.
   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 +244,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 +267,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 +296,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 +305,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 +318,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 +339,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 +389,170 @@ 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 whenever the PR declares any, so a PR on
+// `agent/<other>-*` that closes a different issue never maps to the branch
+// number. The conventional branch prefix applies only to PRs that declare no
+// closing reference at all. Two or more applicable PRs are reported as
+// ambiguous rather than resolved to the first match: the caller must not act.
+export function implementationPrForIssue(prs, number) {
+  const prefix = `agent/${number}-`;
+  const applies = (pr) => (Array.isArray(pr.closingIssuesReferences) && pr.closingIssuesReferences.length > 0
+    ? pr.closingIssuesReferences.some((ref) => ref?.number === number)
+    : typeof pr.headRefName === "string" && pr.headRefName.startsWith(prefix));
+  const matches = (prs || []).filter(applies);
+  if (matches.length > 1) return { pr: null, ambiguous: true };
+  return { pr: matches[0] || null, ambiguous: false };
+}
+
+// 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,
+  checkPrimaryClean = async () => ({ clean: true, reason: "clean", detail: "" }),
+  implementationSlots = IMPLEMENTATION_SLOTS,
+  log,
+  logs = NO_WORKER_LOGS,
+  runningIssues,
+}) {
+  await tmux.ensureSession();
+  const running = runningIssues !== undefined ? runningIssues : await gh.listRunningIssues();
+  // A supervisor restarted into an `orchestrator` session left by the managed
+  // review release inherits live `review-N`/`repair-N` windows this route never
+  // opens. They are read before any mutation, alongside the implementation
+  // windows, so an inspection failure aborts the poll rather than running with
+  // unknown capacity.
+  const liveIssues = await tmux.listWorkerIssues();
+  const liveReview = await tmux.listReviewIssues();
+  const liveRepair = await tmux.listRepairIssues();
+  const prs = await gh.listOpenPrs();
+  // A legacy repair worker is a full `ccode` run sharing the implementation
+  // slots, exactly as it did before the rollback; a legacy reviewer had its own
+  // reserved slot and still consumes none.
+  let liveCount = liveIssues.size + liveRepair.size;
+
+  // Legacy windows are drained, never killed and never re-created: each may
+  // hold a worktree, a pushed branch, a draft PR and labels mid-transition, and
+  // the logic that knew how to finish or unwind that was removed with the
+  // managed review route. They exit on their own; until then they are visible
+  // here so nothing is launched over them and the supervisor cannot call itself
+  // idle. This line is the operator's only notice, so it names each one.
+  const legacyWindows = [
+    ...[...liveReview].sort((a, b) => a - b).map((n) => `review-${n}`),
+    ...[...liveRepair].sort((a, b) => a - b).map((n) => `repair-${n}`),
+  ];
+  if (legacyWindows.length > 0) {
+    log(`Legacy managed-review windows still live: ${legacyWindows.join(", ")}`
+      + " — draining; not managed, not restarted, and never killed by this supervisor");
+  }
+
+  for (const issue of running) {
+    try {
+      // Releasing the claim, or acting on a PR a legacy worker is still
+      // editing, is the race this reconciliation exists to avoid. Defer the
+      // whole issue; once its legacy window exits, the next poll reconciles it
+      // by the ordinary rules.
+      if (liveReview.has(issue.number) || liveRepair.has(issue.number)) {
+        log(`#${issue.number} has a live legacy window — deferring reconciliation to a later poll`);
+        continue;
+      }
+      const { pr, ambiguous } = implementationPrForIssue(prs, issue.number);
+      if (ambiguous) {
+        log(`#${issue.number}: multiple open PRs claim this issue — leaving worker and claim untouched`);
+        continue;
+      }
+      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: liveReview.size,
+      repairLive: liveRepair.size,
+      started: 0, reviewsStarted: 0, repairsStarted: 0,
+    };
+  }
+
+  // Admission control. Isolation refuses a dirty primary worktree, so claiming
+  // an issue here would only burn a label transition on a worker that exits
+  // before opening a PR — which the next poll then misreports as vanished.
+  // Reconciliation above has already run, so live work keeps its slot, its
+  // claim and its lease; only new launches pause, and only for this poll.
+  if (ready.length > 0) {
+    const primary = await checkPrimaryClean();
+    if (!primary.clean) {
+      log(`Primary worktree ${primary.reason} (${primary.detail})`
+        + " — no issue claimed, worker launches paused this poll");
+      return {
+        done: false, implLive: liveCount, reviewLive: liveReview.size,
+        repairLive: liveRepair.size,
+        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` drops the Sentinel lease and stops the supervisor, so a live
+    // legacy worker of either kind must hold it false.
+    done: ready.length === 0 && liveCount === 0 && liveReview.size === 0,
+    implLive: liveCount,
+    reviewLive: liveReview.size,
+    repairLive: liveRepair.size,
+    started,
+    reviewsStarted: 0,
+    repairsStarted: 0,
+  };
 }
 
 // ---- one poll cycle ---------------------------------------------------------
@@ -305,6 +567,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 +577,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 +639,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 +746,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 +767,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 +795,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 +890,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,15 +949,50 @@ export async function main({
   bootstrapLabels = bootstrapRepoLabels,
   resolveContainerId: resolveContainer = resolveOwnContainerId,
   createLeaseClient = createConfiguredLease,
-  runPoll = runOnce,
+  runPoll = runImplementationOnlyOnce,
   checkSetupReady = isAgentSetupReady,
+  checkPrimaryClean = () => checkPrimaryWorktree({ exec }),
   sleepImpl = sleep,
   log = (message) => console.log(formatLogLine(message)),
+  stdout = process.stdout,
 } = {}) {
   const repo = await resolve(exec);
   const releaseOwnership = await acquireOwnership(repo);
   const lease = createLeaseClient();
   let containerId;
+  // Docker freezes this process rather than restarting it, so the last observed
+  // enforcement state survives the pause in memory — nothing needs persisting.
+  let enforcementState = "running";
+
+  // Resolves only once the line has actually left the process. Workers run under
+  // `tmux … | tee`, where stdout is a pipe and `console.log` does not block, so
+  // an unflushed pause message could lose the race against Docker.
+  function logFlush(message) {
+    return new Promise((resolve, reject) => {
+      stdout.write(`${formatLogLine(message)}\n`, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  // Announce a transition, flush it, then acknowledge — in that order. The
+  // acknowledgment lets Sentinel pause this very container, so an unflushed
+  // message would race Docker and could be lost. A failed acknowledgment is
+  // visible but not fatal: Sentinel pauses anyway once its timeout elapses, so
+  // failing here would cost availability without adding enforcement.
+  //
+  // The parameter default covers a client that predates the enforcement field;
+  // the current one always parses and returns it.
+  async function notifyEnforcement(enforcement = { state: "running" }) {
+    const transition = describeEnforcementTransition(enforcementState, enforcement);
+    enforcementState = transition.state;
+    if (transition.message) await logFlush(transition.message);
+    if (!transition.acknowledge) return;
+    try {
+      await lease.acknowledge(containerId);
+    } catch (err) {
+      log(`pause acknowledgment failed: ${err.message}`);
+    }
+  }
+
   try {
     // One helper for the whole run: the launcher that reserves an attempt and
     // the poll that later reads it must agree on where the logs live.
@@ -556,8 +1022,9 @@ export async function main({
     // silently running unenforced.
     try {
       containerId = await resolveContainer();
-      const { status } = await lease.register(containerId);
+      const { status, enforcement } = await lease.register(containerId);
       log(`Managed container lease ${status} for ${containerId}`);
+      await notifyEnforcement(enforcement);
     } catch (err) {
       throw new Error(`managed-container registration failed: ${err.message}`);
     }
@@ -569,7 +1036,8 @@ export async function main({
     for (let firstPoll = true; ; firstPoll = false) {
       if (!firstPoll) {
         try {
-          await lease.register(containerId);
+          const { enforcement } = await lease.register(containerId);
+          await notifyEnforcement(enforcement);
         } catch (err) {
           log(`lease heartbeat failed: ${err.message}`);
         }
@@ -579,7 +1047,7 @@ export async function main({
         const token = await mint(repo);
         const gh = createGitHub({ exec: authExec(token), repo });
         result = await runPoll({
-          gh, tmux, checkSetupReady,
+          gh, tmux, checkSetupReady, checkPrimaryClean,
           implementationSlots: IMPLEMENTATION_SLOTS,
           reviewerSlots: REVIEWER_SLOTS,
           log, logs,