omp-conductor 0.20.0 → 0.20.2

package/src/daemon/review.ts

@@ -62,15 +62,15 @@ export async function dispatchReviewRevisions(d: Deps, pool?: WorkerPool): Promi
       );
       break;
     }
-    // A capped/failed run has no pushed-green settle sweep keeping its row
-    // honest (#795 review round 1): nothing transitions a `failed` / `killed`
-    // row when its PR merges or closes, so a PR that changed after the verb
-    // recorded the round would otherwise be claimed and a worker resumed
-    // against a dead PR. The settled-green origin keeps its own interlock
-    // (the settle sweep flips the row and the claim below refuses it), so
-    // only terminal-origin rounds re-read the reviewed PR fact here: the
-    // round dispatches only while the PR is still open at the exact reviewed
-    // head.
+    // A capped/failed/stopped run has no pushed-green settle sweep keeping its
+    // row honest (#795 review round 1, #1101): nothing transitions a `failed`
+    // / `killed` / `stopped` row when its PR merges or closes, so a PR that
+    // changed after the verb recorded the round would otherwise be claimed and
+    // a worker resumed against a dead PR. The settled-green origin keeps its
+    // own interlock (the settle sweep flips the row and the claim below
+    // refuses it), so every other revisable origin re-reads the reviewed PR
+    // fact here: the round dispatches only while the PR is still open at the
+    // exact reviewed head.
     //
     // The skip decision is decisive-fact only (review round 2): a definitively
     // missing PR (`GhPrMissingError` — a corroborated 404, #779), a PR that
@@ -86,7 +86,7 @@ export async function dispatchReviewRevisions(d: Deps, pool?: WorkerPool): Promi
     // #1047's launch decision rests on are only readable here.
     const originRun = d.store.getRun(revision.runId);
     const origin = originRun?.state;
-    if (origin === "failed" || origin === "killed") {
+    if (origin === "failed" || origin === "killed" || origin === "stopped") {
       let prState: PrState | undefined;
       try {
         prState = await d.tracker.prState(revision.prUrl);
@@ -161,7 +161,7 @@ export async function dispatchReviewRevisions(d: Deps, pool?: WorkerPool): Promi
     if (!d.store.claimRunForReview(revision.runId)) {
       d.store.settleReviewRevision(revision.id, "skipped", Date.now());
       log(
-        `#${revision.issue} review round ${revision.round} skipped: run ${revision.runId} is no longer pushed-green`,
+        `#${revision.issue} review round ${revision.round} skipped: run ${revision.runId} is ${origin ?? "gone"} — no longer reclaimable for review`,
       );
       continue;
     }

package/src/daemon/runtime.ts

@@ -33,7 +33,7 @@ import { reconcileOrphanedRuns } from "../settlement.ts";
 import { dbPath, openStore, utcDay } from "../store.ts";
 import { checkTelegramFreshness } from "../telegram-freshness.ts";
 import { GraphqlBreaker, makeTracker } from "../tracker/github.ts";
-import { RELEASE_SHAPES, type ProjectConfig, type ResolvedGrants, type RunRecord } from "../types.ts";
+import { RELEASE_SHAPES, type Escalation, type ProjectConfig, type ResolvedGrants, type RunRecord } from "../types.ts";
 import { runCommand } from "../upgrade-verify.ts";
 import { inspectSurfaces } from "../upgrade.ts";
 import { sharedUsageSource } from "../usage.ts";
@@ -203,6 +203,54 @@ export async function runDispatchLoop(o: DispatchLoopOptions): Promise<void> {
   }
 }
 
+/** What the daemon knows about its tier-1 orchestrator at diversion time. */
+export interface Tier1DiversionFacts {
+  /** The project's configured tier-1 transport is the external orchestrator
+   *  session: issue comments are the *configured* destination, not a
+   *  fallback. */
+  external: boolean;
+  /** Why the daemon-owned orchestrator session failed to start, when it did. */
+  startError?: string;
+  /** Whether the daemon-owned orchestrator session is alive right now
+   *  (`OrchestratorHandle.alive()` — event-driven, false once the session
+   *  exited). */
+  alive: boolean;
+  /** Whether the daemon-owned orchestrator session is mid-turn right now
+   *  (`OrchestratorHandle.busy()`). */
+  busy: boolean;
+}
+
+/**
+ * The one-line record of a tier-1 escalation that landed on the issue-comment
+ * fallback instead of the orchestrator injection (#1068).
+ *
+ * "while the orchestrator was down" is reserved for what it actually means —
+ * a session that failed to start or one that has exited. The #1062 shape was
+ * neither: the orchestrator was mid-tick, its session did not take the
+ * injection, and a reader of "diverted … while the orchestrator was down"
+ * went looking for a dead session that did not exist. When the session is
+ * alive the line says where the escalation was delivered and why it was not
+ * injected; when the project runs an external orchestrator the comments *are*
+ * the configured transport and the line says so instead of calling it a
+ * diversion.
+ */
+export function tier1DiversionLine(e: Escalation, facts: Tier1DiversionFacts): string {
+  const ref = escalationIssueRef(e.issue);
+  if (facts.external) {
+    return `orchestrator: tier-1 escalation on ${ref} posted as an issue comment (external orchestrator — the configured tier-1 transport)`;
+  }
+  if (facts.startError !== undefined || !facts.alive) {
+    return (
+      `orchestrator: tier-1 escalation on ${ref} diverted to issue comments while the orchestrator was down` +
+      (facts.startError !== undefined ? ` (start failed: ${facts.startError})` : " (session exited)")
+    );
+  }
+  return (
+    `orchestrator: tier-1 escalation on ${ref} posted as an issue comment — the orchestrator session ` +
+    `is alive but did not take the injection${facts.busy ? " (mid-turn)" : ""}`
+  );
+}
+
 export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
   // A `--once` tick is still a dispatcher: it settles rows, projects labels,
   // admits and launches workers, so it must hold the same exclusive daemon/
@@ -391,8 +439,12 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
         // the outage diverted (#288).
         store.bumpOrchestratorDiverted(project.name, 1);
         projectLog(
-          `orchestrator: tier-1 escalation on ${escalationIssueRef(e.issue)} diverted to issue comments ` +
-            `while the orchestrator was down`,
+          tier1DiversionLine(e, {
+            external: project.escalation.orchestrator === "external",
+            startError: orchestratorStartError,
+            alive: orchestrator?.alive() ?? false,
+            busy: orchestrator?.busy() ?? false,
+          }),
         );
       },
     );

package/src/daemon/settle-pass.ts

@@ -16,6 +16,7 @@
  */
 import { infraLogSignature, infraSignatureVersion } from "../failure-class.ts";
 import { errText, log, safeEscalate } from "../log.ts";
+import { GhPrMissingError } from "../tracker/github.ts";
 import type { BaseHealth, RunRecord, SettlementFlag, WorkflowRun } from "../types.ts";
 import { cleanupRetainedWorktree, mirrorPathFor, type RetainedWorktreeCleanup } from "../worktree.ts";
 import { githubRepo, type Deps, type RetainedCleanupCursor } from "./deps.ts";
@@ -393,8 +394,24 @@ export async function cleanupRetainedRuns(
         terminal = issue === "closed";
       }
     } catch (err) {
-      log(`#${run.issue} retained cleanup deferred: tracker state failed (${errText(err)})`);
-      continue;
+      // The tracker throws exactly one classified error: `GhPrMissingError`,
+      // an individual REST 404 it corroborated with a same-repository
+      // pulls-list read, so the claimed PR definitively does not exist
+      // (#779). That is a fact, not "could not tell": retrying can never
+      // conjure the PR, so the missing PR is terminal and the retained row
+      // settles in this same pass like a closed one (#1065). The row's
+      // phantom URL is cleared with the settlement so a repeat pass neither
+      // asks GitHub about it again nor logs about it again. Everything else —
+      // a rate limit, a 5xx, a lost network — keeps the deferred retry below,
+      // unchanged.
+      if (err instanceof GhPrMissingError) {
+        store.updateRun(run.id, { prUrl: null });
+        log(`#${run.issue} retained cleanup settled: PR ${run.prUrl} does not exist`);
+        terminal = true;
+      } else {
+        log(`#${run.issue} retained cleanup deferred: tracker state failed (${errText(err)})`);
+        continue;
+      }
     }
     if (!terminal) continue;
 

package/src/daemon/supervision.ts

@@ -14,12 +14,15 @@
  * pass into the dispatch path's import graph, for two functions whose subject —
  * "make the orchestrator look at this now" — is already this module's.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { stateDir } from "../config.ts";
+import { stallSilenceMs } from "../failure-class.ts";
 import { resolvePaneHaltPath, stopConductorPane } from "../fleet.ts";
 import { errText, log, safeEscalate } from "../log.ts";
 import { STALL_MARKER_FILE, readTickRequestReason, requestImmediateTick, resolveTickConfigCwd } from "../orchestrator-tick.ts";
+import { LIVE_STATES } from "../store.ts";
+import { wakeDispatch } from "../wake.ts";
 import { NO_ISSUE, type Deps, type StallGate } from "./deps.ts";
 import { markPaged } from "./integrity.ts";
 
@@ -436,3 +439,143 @@ export function wakeOrchestratorForBlockedRun(
     );
   }
 }
+
+
+// ----------------------------------------------------------------- worker progress
+
+/**
+ * Watching live workers for silence, and settling a run that stopped making
+ * progress (#1086).
+ *
+ * The only bounds a worker's own session enforces are the turn ceiling and the
+ * wall clock — neither fires until the whole budget is gone, so a session that
+ * hangs at minute 44 keeps its slot for another 46 minutes and then dies as a
+ * `wall-clock-cap-*` verdict that reads like an oversized slice about work that
+ * may already be merged. The signal that separates "thinking" from "gone" is
+ * already on disk: a live session writes its transcript continuously, so the
+ * file's own mtime is when the worker was last demonstrably alive.
+ *
+ * Deliberately transcript-only: the row's turn counter rides in the evidence,
+ * but it is never the trigger — one turn can legitimately run for minutes on a
+ * slow provider, and this fleet has measured 1.5 min/turn.
+ *
+ * A stall whose PR is already pushed and green settles `pushed-green` — the
+ * exact state any delivered run holds — so the settle sweep owns the merge and
+ * no continuation is charged for work that landed (#1086). Every other stall
+ * settles `killed` over the observed facts; the classifier turns those into
+ * `progress-stall`, whose recovery splits on artifacts exactly as the caps do.
+ */
+export async function watchWorkerProgress(
+  d: Pick<Deps, "project" | "caps" | "store" | "tracker" | "workerControls" | "escalate">,
+  now = Date.now(),
+): Promise<void> {
+  const thresholdMs = stallSilenceMs(d.caps);
+  // A paused worker banks its wall clock and goes quiet on purpose (#938):
+  // silence under pause is the pause working, never a hang.
+  const pausedIssues = new Set(
+    d.workerControls
+      .snapshot(d.project.name)
+      .filter((w) => w.phase === "pausing" || w.phase === "paused")
+      .map((w) => w.issue),
+  );
+  for (const run of d.store.liveRuns(d.project.name)) {
+    if (pausedIssues.has(run.issue)) continue;
+    if (run.sessionFile === undefined) continue;
+    let wroteAt: number;
+    try {
+      wroteAt = Math.trunc(statSync(run.sessionFile).mtimeMs);
+    } catch {
+      // No transcript yet (claimed, session opening) or none readable: nothing
+      // to observe, which is never evidence of a stall.
+      continue;
+    }
+    // Record before judging: `status` renders this instant as the run's
+    // silence interval whether or not the threshold fires (#1086).
+    if (run.lastProgressAt !== wroteAt) {
+      d.store.updateRun(run.id, { lastProgressAt: wroteAt });
+    }
+    const silentMs = now - wroteAt;
+    if (silentMs < thresholdMs) continue;
+
+    // Re-read before settling: the session can finish between the stat above
+    // and here, and a terminal row must never be re-settled over.
+    const current = d.store.getRun(run.id);
+    if (current === undefined || !LIVE_STATES.includes(current.state)) continue;
+    const minutes = Math.round(silentMs / 60_000);
+    const silent =
+      minutes < 60 ? `${minutes}m` : `${Math.floor(minutes / 60)}h${minutes % 60 === 0 ? "" : `${minutes % 60}m`}`;
+    const why = `transcript silent ${silent} at turn ${current.turns}/${current.maxTurns}`;
+    log(`#${current.issue} ${why} — settling (silence window ${Math.round(thresholdMs / 60_000)}m)`);
+
+    // Best-effort abort through the run-control surface, so a session that can
+    // still answer exits through its own settlement path. One that cannot is
+    // exactly the case this pass exists for: the row settles below regardless,
+    // and the re-read guard keeps whichever writer lands second out.
+    try {
+      void d.workerControls.stop(d.project.name, current.issue, `progress stall: ${why}`).catch(() => {});
+    } catch {
+      // No live control for this run — the settle below is the only writer.
+    }
+
+    // Work that already landed is delivered work — but only verified green
+    // counts: landing `pushed-green` puts the row exactly where any delivered
+    // run sits, under the settle sweep's merge watch, with nothing charged.
+    let deliveredGreen = false;
+    if (current.prUrl !== undefined && current.headSha !== undefined) {
+      try {
+        deliveredGreen = (await d.tracker.verifyPr(current.prUrl, current.headSha))?.status === "green";
+      } catch {
+        deliveredGreen = false;
+      }
+    }
+    if (deliveredGreen) {
+      d.store.updateRun(current.id, { state: "pushed-green", endedAt: now });
+      log(`#${current.issue} stalled but ${current.prUrl} was already green — settled as delivered`);
+      await safeEscalate(d, {
+        tier: 1,
+        project: d.project.name,
+        issue: current.issue,
+        runId: current.id,
+        summary: `#${current.issue} went silent (${why}) with its PR already green — settled as delivered`,
+        detail: [
+          current.prUrl ?? "(no PR URL)",
+          `Branch ${current.branch} at ${current.headSha}.`,
+          `Session: ${current.sessionFile ?? "(no transcript)"}`,
+          "",
+          "The worker never reported, so there is no settlement narrative — the PR's diff is the record.",
+          "The slot is released; the settle sweep watches the merge from here.",
+        ].join("\n"),
+      });
+      await wakeDispatchLogged(d.project.name);
+      continue;
+    }
+
+    d.store.updateRun(current.id, {
+      state: "killed",
+      endedAt: now,
+      lastError: `progress-stall: ${why}`,
+    });
+    await safeEscalate(d, {
+      tier: 1,
+      project: d.project.name,
+      issue: current.issue,
+      runId: current.id,
+      summary: `[progress-stall] #${current.issue} attempt ${current.attempt}: ${why}`,
+      detail: [
+        `${current.prUrl === undefined ? "No PR" : `PR ${current.prUrl} not verified green`} — the classifier decides continue vs escalate from what attempt ${current.attempt} left.`,
+        `Branch ${current.branch}; worktree ${current.worktree === "" ? "(none)" : current.worktree}.`,
+        `Session: ${current.sessionFile ?? "(no transcript)"}`,
+      ].join("\n"),
+    });
+    await wakeDispatchLogged(d.project.name);
+  }
+}
+
+/** Best-effort dispatch wake once a stall settle freed its slot (#1086). */
+async function wakeDispatchLogged(projectName: string): Promise<void> {
+  try {
+    log(`dispatch wake after stall settle: ${await wakeDispatch(projectName)}`);
+  } catch (err) {
+    log(`dispatch wake after stall settle failed: ${errText(err)}`);
+  }
+}

package/src/daemon/tick.ts

@@ -42,13 +42,13 @@ import { writeAdmissionAck } from "./ack.ts";
 import { dispatchAdmissions, summarizeDispatch, summarizeHeldPass, type WorkerPool } from "./admission-pass.ts";
 import { NO_ISSUE, PACKAGE_SRC_DIR, UNROUTABLE_TEXT, type Deps } from "./deps.ts";
 import { handleIssue } from "./dispatch.ts";
-import { cancelDrain, consumeDrain } from "./drain.ts";
+import { consumeDrain, markDrained } from "./drain.ts";
 import { dispatchToSpecGrooming } from "./groom-pass.ts";
 import { INTEGRITY_SAMPLE, checkIntegrity, markPaged, packageManifest } from "./integrity.ts";
 import { reconcilePanes } from "./panes.ts";
 import { applyAdjudicationDispositions, dispatchReviewAdjudications, dispatchReviewRevisions } from "./review.ts";
 import { cleanupRetainedRuns, watchBaseHealth, watchMergedBase } from "./settle-pass.ts";
-import { wakeOrchestratorForMetConditions, watchOrchestrator } from "./supervision.ts";
+import { wakeOrchestratorForMetConditions, watchOrchestrator, watchWorkerProgress } from "./supervision.ts";
 
 /**
  * Record what this host has installed, once per dispatch pass (#919).
@@ -388,6 +388,16 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
   // failure happened. A pause silences claiming, not the operator's right to
   // know their supervising session stopped reading its queue.
   await watchOrchestrator(d);
+  // The worker-side sibling, and above the pause gate with it: a stalled run
+  // holds its slot on a parked fleet exactly as hard as on a busy one, and the
+  // #1086 incident was an upgrade drain blocked for 26 minutes by one silent
+  // session. Paused workers are skipped inside the pass — their silence is
+  // the pause working (#938) — so this gate costs nothing there.
+  try {
+    await watchWorkerProgress(d);
+  } catch (err) {
+    log(`worker-progress sweep failed: ${errText(err)}`);
+  }
   // The down incident is reconciled the same place and for the same reason: a
   // session that has actually died is as much the operator's concern as one
   // that is wedged, and restarting it is the daemon's restart either way. This
@@ -584,11 +594,16 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
   // the same admission boundary — settlement above it, nothing claimed below —
   // but the intent is durable (it survives orchestrator loss) and bounded (the
   // record carries an absolute deadline, so a crash can never strand
-  // admission). Three shapes, three behaviours:
+  // admission). Reaching an empty active set SUCCEEDS the drain; it does not
+  // end it (#1078): the release window the drain exists to create opens at
+  // that moment and holds claims down until the deadline — exactly the quiet
+  // interval a tick-driven orchestrator needs to cut a release, which the old
+  // eight-second auto-clear destroyed before any tick could use it. Four
+  // shapes, four behaviours:
   //   - fresh drain with live runs → a held pass, exactly like a pause;
-  //   - fresh drain with nothing left to wait for → the drain is satisfied
-  //     and clears itself, so a completed drain never needs a second operator
-  //     action and this pass proceeds normally;
+  //   - fresh drain whose active set just reached zero → the opening is marked
+  //     on the record once and logged once, and this pass admits nothing;
+  //   - fresh drain already marked drained → the same held pass, silent;
   //   - malformed record → fails closed for THIS pass (it might be a fresh
   //     fence we cannot read), and the same consume removed it, so it can
   //     never become an unbounded permanent drain.
@@ -596,15 +611,17 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
   if (drain.kind === "active") {
     // Completion is the ACTIVE set, not the live-worker set: pushed-pending
     // and pushed-green PRs still make the `runs-settled` release gate fail, so
-    // a drain that cleared while one remained would admit work on top of a
-    // batch the releases still see as unfinished (#776 review #2).
-    if (d.store.activeRuns(d.project.name).length === 0) {
-      cancelDrain(d.project.name);
-      log("project drain completed: no active runs remain — drain cleared");
-    } else {
-      d.store.recordDispatch(d.project.name, summarizeHeldPass(settled));
-      return;
+    // a window declared open over a remaining run would admit work on top of
+    // a batch the releases still see as unfinished (#776 review #2).
+    if (d.store.activeRuns(d.project.name).length === 0 && drain.drain.drainedAt === undefined) {
+      markDrained(d.project.name);
+      log(
+        `project drain: fleet drained — release window open until ${drain.drain.expiresAt}` +
+          " (claims stay paused; admission resumes at the deadline or on drain cancel)",
+      );
     }
+    d.store.recordDispatch(d.project.name, summarizeHeldPass(settled));
+    return;
   } else if (drain.kind === "error") {
     log(`project drain record invalid (${drain.problem}) — removed; this pass admits nothing`);
     d.store.recordDispatch(d.project.name, summarizeHeldPass(settled));

package/src/daemon/views.ts

@@ -23,6 +23,7 @@ import { availabilityState, type AvailabilityState } from "../availability.ts";
 import { configPath, findProject, loadConfig, resolveCaps, resolveReleaseGrants, resolveReview, stateDir } from "../config.ts";
 import { digestScheduleState, type DigestScheduleState } from "../digest-schedule.ts";
 import { SPEND_SAMPLE_ROWS, SPEND_SAMPLE_RUNS } from "../doctor.ts";
+import { EFFECTIVE_BUDGET_SAMPLE_RUNS, observeTurnBudget, type ObservedTurnBudget } from "../failure-class.ts";
 import type { CodeGraphHealth } from "../graph-health.ts";
 import { isPaused, pauseProvenance, setPaused } from "../pause.ts";
 import { branchName, route } from "../routing.ts";
@@ -189,6 +190,11 @@ export interface StatusSnapshot {
    */
   reporting?: ReportingSummary;
   caps: Caps;
+  /** #1063: the turn count the wall-clock ceiling actually buys at this
+   *  project's observed per-turn latency, with the sample it was derived
+   *  from. Absent when no qualifying completed run exists — never derived
+   *  from the configured constants, whose ratio is a constant. */
+  workerTurnBudgetObserved?: ObservedTurnBudget;
   /**
    * The effective per-shape release grants. On the snapshot rather than re-read
    * by each renderer because #122 began with a grant nobody had looked at in
@@ -552,6 +558,17 @@ export function statusSnapshotFromStore(
       const observed = store.installSurfaces();
       return observed === undefined ? {} : { installSurfaces: observed };
     })(),
+    // #1063, the same read-not-probe discipline as the spend judgement above:
+    // derived from completed-run rows on this read, never probed at render
+    // time. The renderer decides whether the figure is materially lower.
+    ...(() => {
+      const budget = observeTurnBudget(
+        store.recentLatencySamples(p.name, EFFECTIVE_BUDGET_SAMPLE_RUNS),
+        caps,
+        p.workerModel,
+      );
+      return budget === undefined ? {} : { workerTurnBudgetObserved: budget };
+    })(),
     ...(dispatch === undefined ? {} : { dispatch }),
     ...(planUsage === undefined ? {} : { planUsage }),
     // Written by the tracker's hooks rather than polled, so the renderer does

package/src/daemon.ts

@@ -34,7 +34,7 @@ export type {
 export { completionLastError, exhaustedSessionReason, verbDeps } from "./daemon/deps.ts";
 
 export type { CreateDrainOptions, DrainProblem, DrainRecord, DrainVerdict } from "./daemon/drain.ts";
-export { cancelDrain, consumeDrain, createDrain, drainPath, readDrain } from "./daemon/drain.ts";
+export { cancelDrain, consumeDrain, createDrain, drainPath, markDrained, readDrain } from "./daemon/drain.ts";
 
 export type { AdmissionAckRecord } from "./daemon/ack.ts";
 export { admissionAckPath, daemonGeneration, readAdmissionAck, wakeDaemon, writeAdmissionAck } from "./daemon/ack.ts";
@@ -52,6 +52,7 @@ export {
   wakeOrchestratorForBlockedRun,
   wakeOrchestratorForMetConditions,
   watchOrchestrator,
+  watchWorkerProgress,
 } from "./daemon/supervision.ts";
 
 export { reconcilePanes } from "./daemon/panes.ts";
@@ -113,8 +114,8 @@ export { daemonHttpResponse, turnLimitResponse, workerControlResponse } from "./
 
 export { mineIntakeSignals, runDbSnapshotCadence, tick, upgradeVerifyDepsFor } from "./daemon/tick.ts";
 
-export type { DispatchLoopOptions, DispatchPace } from "./daemon/runtime.ts";
-export { createDispatchPace, orchestratorStandingOrders, runDaemon, runDispatchLoop } from "./daemon/runtime.ts";
+export type { DispatchLoopOptions, DispatchPace, Tier1DiversionFacts } from "./daemon/runtime.ts";
+export { createDispatchPace, orchestratorStandingOrders, runDaemon, runDispatchLoop, tier1DiversionLine } from "./daemon/runtime.ts";
 
 // ------------------------------------------------------------------- pause
 // The sentinel itself lives in `pause.ts` (#938): this module imports

package/src/decisions.ts

@@ -45,26 +45,35 @@ const NPM_SPEC = /^(@[^/@\s]+\/)?[^@\s]+@[^\s]+$/;
 const GREEN_CHECK_STATES: Record<string, true> = { success: true, neutral: true };
 
 /**
- * The run states a review revision may start from (#795) — the single
+ * The run states a review revision may start from (#795, #1101) — the single
  * definition shared by `conductor_pr_review` and the `pr-review-ready` watch,
  * so the verb's gate and the condition can never name different sets.
  *
  * A revision round resumes the exact run whose row owns the PR, so the
- * revisable states are exactly the terminal runs that pushed one: a settled
- * `pushed-green` row, or a `failed` / `killed` row — a run that capped or
- * failed *after* pushing a green PR. The PR is the durable artefact, the
- * exact-head green verification is the gate on "green at the reviewed SHA",
- * and a terminal row proves no worker is in flight, so findings are returned
+ * revisable states are exactly the terminal runs that own the named PR: a
+ * settled `pushed-green` row, a `failed` / `killed` row — a run that capped or
+ * failed *after* pushing a green PR — and, since #1101, a `stopped` row that
+ * pushed one. Ownership is not carried by the state alone: selection runs
+ * through `runsForProjectPr`, so only a row that itself recorded the reviewed
+ * PR can ever reach this gate. The PR is the durable artefact, the exact-head
+ * green verification is the gate on "green at the reviewed SHA", and a
+ * terminal row proves no worker is in flight, so findings are returned
  * without the close-PR → unblock → continuation dance.
  *
+ * A `stopped` row has no settle sweep keeping it honest (nothing transitions a
+ * stopped row when its PR merges or closes), so like `failed` / `killed` its
+ * rounds re-read PR-open and green-at-head decisively before the claim — the
+ * dispatch pass refuses to wake a worker against a dead or moved PR.
+ *
  * Closed on purpose: a live row (`running` / `claimed`) is already doing its
  * own work, a `pushed-pending` PR is not green yet, and a `blocked` /
- * `orphaned` / `stopped` / `merged` row is not work returned for revision.
+ * `orphaned` / `merged` row is not work returned for revision.
  */
 export const REVISABLE_RUN_STATES: Record<string, true> = {
   "pushed-green": true,
   failed: true,
   killed: true,
+  stopped: true,
 };
 
 /**
@@ -92,8 +101,10 @@ export const PR_LOOKUP_WINDOW_MS = 30 * 24 * 60 * 60_000;
  * `running`, and a watch keyed only to checks woke the orchestrator before
  * `conductor_pr_review` was actionable), `pushed-pending` checks are still
  * settling, `blocked` may resume, `orphaned` is reconciled back to live at
- * startup, and `merged` means the PR lifecycle is over. When every row is
- * `stopped`, the newest one answers and the predicate fails closed.
+ * startup, and `merged` means the PR lifecycle is over. When every row of the
+ * history is `stopped`, the newest one answers — and since #1101 it answers
+ * `ready` when it owns the named PR: stopping a worker that had already pushed
+ * must leave the PR reviewable rather than stranded.
  *
  * `no-owner` and `not-revisable` both fail closed: a review can never act, so
  * a watch must not wake, even when the checks are green.