omp-conductor 0.10.0 → 0.13.0

package/src/verbs/protocol.ts

@@ -293,9 +293,10 @@ export const VERB_SPECS: Readonly<Record<VerbName, VerbSpec>> = {
     mutating: false,
     allowedRoles: ["worker", "orchestrator"],
     description:
-      "Read one pull request's live state: is it open, is its head still the sha you pushed, and are " +
-      "its checks green. This is the daemon's own merge-gate verdict, not a summary of it. A poll, not " +
-      "a watcher — call it again after waiting. A worker may omit prUrl and gets its own run's.",
+      "Read one pull request's live state and current head: is it open and are its checks green. " +
+      "Optionally compare that head with one the caller already observed. This is the daemon's own " +
+      "merge-gate verdict, not a summary of it. A poll, not a watcher — call it again after waiting. " +
+      "A worker may omit prUrl and gets its own run's.",
     args: {
       prUrl: {
         type: "string",
@@ -304,10 +305,10 @@ export const VERB_SPECS: Readonly<Record<VerbName, VerbSpec>> = {
       },
       headSha: {
         type: "string",
-        required: true,
+        required: false,
         description:
-          "The head you believe is on the branch — the sha conductor_push returned. If the branch has " +
-          "moved, the answer names both shas.",
+          "Optional: an expected head to compare against; omit it to read the current head. If the " +
+          "branch has moved, the answer names both shas.",
       },
     },
     roleRefusalText: (role) => `conductor_pr_status is not open to a ${role} session.`,

package/src/verbs/server.ts

@@ -42,6 +42,8 @@ import { randomUUID } from "node:crypto";
 import { createServer, type Server, type Socket } from "node:net";
 
 import { resolvePolicy, resolveReleaseGrants } from "../config.ts";
+import { chainEntriesFromDiff, chainViolations } from "../chain-check.ts";
+import type { readBaseChain as readBaseChainType } from "../gitops.ts";
 import { releaseRefusal } from "../release-policy.ts";
 import { LIVE_STATES } from "../store.ts";
 import type {
@@ -181,6 +183,12 @@ export interface VerbDeps {
   pausedAt: () => number | undefined;
   log: (message: string) => void;
   now: () => number;
+  /**
+   * Read-only access to the ordered-migration-chain guard. A read seam, kept
+   * off `VerbActions` (the mutation surface) on purpose: `prMergeVerb` consults
+   * whether the merge would fork the chain, it never changes it (#227).
+   */
+  chain: { readBaseChain: typeof readBaseChainType };
 }
 
 /**
@@ -257,6 +265,10 @@ export interface ReleaseFacts {
   openPrs: number;
   /** Queue depth, or `undefined` when the tracker could not be read. */
   queueDepth: number | undefined;
+  /** Newest observed verdict for the released routed repository. */
+  baseCheck?: RunRecord["baseCheck"];
+  /** Evidence attached to a newest red verdict. */
+  redBase?: string;
 }
 
 export function releaseRequirementRefusal(
@@ -278,6 +290,19 @@ export function releaseRequirementRefusal(
         return `policy.release.requires includes queue-drained and ${facts.queueDepth} issue(s) are still queued`;
       }
     }
+    if (requirement === "base-branch-green") {
+      if (facts.baseCheck === "green") continue;
+      if (facts.baseCheck === "pending") {
+        return "policy.release.requires includes base-branch-green and the newest merge's base workflows are still pending";
+      }
+      if (facts.baseCheck === "red" || facts.baseCheck === "red-preexisting") {
+        return (
+          "policy.release.requires includes base-branch-green and the newest observed base branch is red" +
+          (facts.redBase === undefined ? "" : `: ${facts.redBase}`)
+        );
+      }
+      return "policy.release.requires includes base-branch-green and no green base-branch verdict is available; refusing rather than assuming the base is healthy";
+    }
     if (requirement === "epic-children-closed") {
       return "policy.release.requires includes epic-children-closed, which nothing in a release request names an epic for. The daemon cannot settle it, so it refuses: take the requirement off this project's policy, or cut this release by hand.";
     }
@@ -415,19 +440,32 @@ async function decide(deps: VerbDeps, channel: VerbChannel, raw: unknown): Promi
     }
   }
 
-  // 4. Stop always wins, and is re-read here rather than remembered. Reads are
-  //    exempt: a run finishing its report during a `hold` still has to be able
-  //    to say what it saw, and refusing that would only make it guess. A run
-  //    admitted *before* the pause may finish its in-flight mutations — pause
-  //    stops new claims, not the work already running (#174) — so only a call
-  //    whose run started at or after the pause (or an orchestrator's call, with
-  //    no run row at all) is refused.
-  const stopped = spec.mutating ? deps.fleetStop() : undefined;
+  // 4. Stop always wins for work-starting mutations, and is re-read here
+  //    rather than remembered. Reads are exempt. A run admitted before the
+  //    pause may finish its own mutations (#174). Orchestrator completion
+  //    verbs resolve their target run inside the handler, where they can prove
+  //    that run also predates the pause (#251). Release remains available:
+  //    its authority, grant, and runs-settled gates still fail closed below.
+  const orchestratorCompletion =
+    channel.kind === "orchestrator" &&
+    (verb === "conductor_pr_merge" ||
+      verb === "conductor_pr_update_branch" ||
+      verb === "conductor_pr_update" ||
+      verb === "conductor_label");
+  const stopped =
+    spec.mutating && verb !== "conductor_release" && !orchestratorCompletion
+      ? deps.fleetStop()
+      : undefined;
   if (stopped !== undefined) {
     const at = deps.pausedAt();
     const admittedBeforePause = run !== undefined && at !== undefined && run.startedAt < at;
     if (!admittedBeforePause) {
-      return refuse("fleet-paused", `refused: ${stopped}. The pause stops new claims and new mutations; a run admitted before the pause may finish.`);
+      return refuse(
+        "fleet-paused",
+        `refused: ${stopped}. The pause refuses new claims and work-starting mutations. ` +
+          "Completion verbs for runs admitted before the pause (conductor_pr_merge, conductor_pr_update_branch, " +
+          "conductor_pr_update, conductor_label) and conductor_release remain available.",
+      );
     }
   }
 
@@ -591,7 +629,7 @@ async function prCreateVerb(
  * How far back to look is the recent-history cutoff `status` already uses: a
  * pull request older than that is not one an orchestrator is mid-flight on.
  */
-const PR_LOOKUP_WINDOW_MS = 30 * 24 * 60 * 60_000;
+export const PR_LOOKUP_WINDOW_MS = 30 * 24 * 60 * 60_000;
 
 function runForPr(deps: VerbDeps, project: string, prUrl: string): RunRecord | undefined {
   return deps.store
@@ -599,6 +637,31 @@ function runForPr(deps: VerbDeps, project: string, prUrl: string): RunRecord | u
     .find((candidate) => candidate.prUrl === prUrl);
 }
 
+/** Refuse an orchestrator completion mutation that cannot prove a pre-pause run. */
+function orchestratorPauseRefusal(
+  deps: VerbDeps,
+  channel: VerbChannel,
+  target: RunRecord | undefined,
+  refuse: Refuse,
+): Verdict | undefined {
+  if (channel.kind !== "orchestrator") return undefined;
+  const stopped = deps.fleetStop();
+  if (stopped === undefined) return undefined;
+  const at = deps.pausedAt();
+  if (target !== undefined && at !== undefined && target.startedAt < at) return undefined;
+  const why =
+    target === undefined
+      ? "this issue has no recorded run admitted before it."
+      : at === undefined
+        ? "the pause timestamp cannot prove when this run started."
+        : "this run started after it.";
+  return refuse(
+    "fleet-paused",
+    `refused: ${stopped}. Under pause, this verb applies only to runs admitted before the pause; ${why}`,
+    target?.issue,
+  );
+}
+
 async function prUpdateBranchVerb(
   deps: VerbDeps,
   project: ProjectConfig,
@@ -630,6 +693,9 @@ async function prUpdateBranchVerb(
     }
   }
 
+  const paused = orchestratorPauseRefusal(deps, channel, target, refuse);
+  if (paused !== undefined) return paused;
+
   let state: PrState | undefined;
   try {
     state = await deps.tracker.prState(prUrl);
@@ -683,6 +749,9 @@ async function prMergeVerb(
     return refuse("pr-not-this-run", `refused: ${prUrl} is not a pull request any run in ${project.name} opened.`);
   }
 
+  const paused = orchestratorPauseRefusal(deps, channel, target, refuse);
+  if (paused !== undefined) return paused;
+
   // Taken before any network call, so two concurrent callers contend here
   // rather than both spending a `gh` round trip and racing at the merge.
   const holderId = randomUUID();
@@ -728,6 +797,47 @@ async function prMergeVerb(
       );
     }
 
+    const repoTarget = Object.values(project.routing.repos).find((r) => r.name === target.repo);
+    const chainDir = repoTarget?.migrations?.dir;
+    if (chainDir !== undefined && repoTarget !== undefined) {
+      // Checked against the base tip at merge time, not against a stale advisory:
+      // the author hit two merged PRs leaving main with two Alembic heads (#227).
+      const diff = await deps.tracker.prDiff(prUrl).catch(() => undefined);
+      if (diff === undefined) {
+        return refuse(
+          "chain-unreadable",
+          `refused: the diff of ${prUrl} could not be read, so the migration chain in ${chainDir} cannot be verified. Failing closed: a wrong merge here is a silent production schema drift (#227).`,
+          target.issue,
+        );
+      }
+      const { added, changed, deleted } = chainEntriesFromDiff(diff.files, chainDir);
+      if (added.length + changed.length + deleted.length > 0) {
+        if (diff.truncated) {
+          return refuse(
+            "chain-unreadable",
+            `refused: the diff of ${prUrl} was truncated and it touches ${chainDir} — the chain cannot be verified from a partial diff.`,
+            target.issue,
+          );
+        }
+        const base = await deps.chain.readBaseChain(project, repoTarget, chainDir);
+        if (!base.ok) {
+          return refuse(
+            "chain-unreadable",
+            `refused: could not read ${chainDir} at the tip of ${repoTarget.defaultBranch} (${base.stderr}).`,
+            target.issue,
+          );
+        }
+        const violations = chainViolations({ base: base.entries, added, changed, deleted });
+        if (violations.length > 0) {
+          return refuse(
+            "chain-conflict",
+            `refused: merging ${prUrl} would corrupt the ordered migration chain in ${chainDir} — ${violations.join("; ")}. Rebase onto the current tip, regenerate the migration, and call again.`,
+            target.issue,
+          );
+        }
+      }
+    }
+
     const outcome = await deps.actions.mergePr(prUrl, headSha);
     if (!outcome.ok) {
       return refuse("action-failed", `refused: gh could not merge:\n${outcome.stderr}`, target.issue);
@@ -765,6 +875,14 @@ async function labelVerb(
     );
   }
 
+  const paused = orchestratorPauseRefusal(
+    deps,
+    channel,
+    deps.store.latestRun(project.name, ref.issue),
+    refuse,
+  );
+  if (paused !== undefined) return paused;
+
   const label = String(args["label"]);
   const vocabulary = labelVocabulary(project);
   if (vocabulary.lifecycle.includes(label)) {
@@ -859,10 +977,19 @@ async function releaseVerb(
       queueDepth = undefined;
     }
   }
+  const wantsBase = policy.release.requires.includes("base-branch-green");
+  const latestBase = wantsBase
+    ? deps.store.latestBaseChecks(project.name, 0).find((run) => run.repo === repoName)
+    : undefined;
+  const redBase = latestBase?.settlementFlags?.find(
+    (flag) => flag.kind === "base-branch-red",
+  )?.detail;
   const unmet = releaseRequirementRefusal(policy.release.requires, {
     unsettledRuns: active.length,
     openPrs: active.filter((r) => r.prUrl !== undefined).length,
     queueDepth,
+    ...(latestBase?.baseCheck === undefined ? {} : { baseCheck: latestBase.baseCheck }),
+    ...(redBase === undefined ? {} : { redBase }),
   });
   if (unmet !== undefined) return refuse("release-not-granted", `refused: ${unmet}`);
 
@@ -942,10 +1069,11 @@ async function prStatusVerb(
     issue = target.issue;
   }
 
-  const headSha = String(args["headSha"]);
+  const askedHead = args["headSha"];
+  const expectedHead = typeof askedHead === "string" ? askedHead : undefined;
   let verification: PrVerification | undefined;
   try {
-    verification = await deps.tracker.verifyPr(prUrl, headSha);
+    verification = await deps.tracker.verifyPr(prUrl, expectedHead);
   } catch (err) {
     verification = undefined;
     deps.log(`verb pr_status could not read ${prUrl}: ${err instanceof Error ? err.message : String(err)}`);
@@ -958,7 +1086,7 @@ async function prStatusVerb(
       issue,
     );
   }
-  return allow(`${prUrl} at ${headSha}: ${verification.status} — ${verification.reason}`, undefined, issue);
+  return allow(`${prUrl} at ${verification.headSha}: ${verification.status} — ${verification.reason}`, undefined, issue);
 }
 
 /**
@@ -1005,6 +1133,9 @@ async function prUpdateVerb(
     if (target === undefined) {
       return refuse("pr-not-this-run", `refused: ${asked} is not a pull request any run in ${project.name} opened.`);
     }
+
+    const paused = orchestratorPauseRefusal(deps, channel, target, refuse);
+    if (paused !== undefined) return paused;
     prUrl = asked;
     issue = target.issue;
   }

package/src/worker.ts

@@ -11,6 +11,7 @@
  */
 
 import { createSession, disposeSession } from "./omp.ts";
+import type { ReleaseBlockContext } from "./release-policy.ts";
 import type { Caps, ReleaseShape, ResolvedGrants, RunState } from "./types.ts";
 
 /** Structured evidence fields from the worker's final report. */
@@ -25,6 +26,11 @@ const STATE_LINE_PATTERN = /^state:\s*\S+\s*$/im;
 /** `{{KEY}}` placeholders in a brief template. */
 const PLACEHOLDER_PATTERN = /\{\{([A-Za-z0-9_]+)\}\}/g;
 
+function scheduleWallClock(callback: () => void, delayMs: number): () => void {
+  const timer = setTimeout(callback, delayMs);
+  return () => clearTimeout(timer);
+}
+
 /**
  * Which ceiling stopped a run. Only ever set alongside `state: "killed"`: the
  * turn counter caught a loop, or the wall clock caught a session that was stuck
@@ -32,6 +38,27 @@ const PLACEHOLDER_PATTERN = /\{\{([A-Za-z0-9_]+)\}\}/g;
  */
 export type KilledBy = "turns" | "wallclock";
 
+export type WorkerPausePhase = "running" | "pausing" | "paused";
+
+export interface WorkerPauseControl {
+  phase(): WorkerPausePhase;
+  /** Cooperative park; resolves when the harness is idle. Rejects when the
+   * run is settling, cap-killed, or already pausing/paused. */
+  pause(): Promise<void>;
+  /** Returns a parked session to work with a continuation prompt. Throws
+   * when the phase is not `paused`. */
+  resume(): void;
+  /** Terminally ends this run for an operator-supplied reason. The run is
+   * recorded as an administrative kill and cannot be resumed. */
+  stop(reason: string): void;
+}
+
+/** What a resumed session is told. One literal so tests can pin it. */
+export const RESUME_PROMPT =
+  "The operator paused this session and has now resumed it. Continue exactly where you left off: " +
+  "re-check the outcome of your last action before repeating it, then keep working your original " +
+  "brief to the same report contract.";
+
 export interface WorkerOpts {
   brief: string;
   cwd: string;
@@ -55,7 +82,7 @@ export interface WorkerOpts {
    */
   releaseGrants?: ResolvedGrants;
   /** Durable audit sink for rejected release/deploy calls. */
-  onReleaseBlocked?: (shape: ReleaseShape) => void;
+  onReleaseBlocked?: (shape: ReleaseShape, context: ReleaseBlockContext) => void;
   /** The child's pid, the instant it exists. See {@link VerbListener.bindPid}. */
   onSpawn?: (pid: number) => void;
   /** Control socket for that child, beside the run's own session directory. */
@@ -87,15 +114,21 @@ export interface WorkerOpts {
    * would be a path that fails to open rather than an absence.
    */
   onSessionFile?: (path: string) => void;
+  /**
+   * Installs the run's operator pause controller the moment the session
+   * exists; absent = no pause surface (tests, one-shot callers).
+   */
+  onPauseControl?: (control: WorkerPauseControl) => void;
 }
 
 /**
- * The one collaborator worth injecting: starting a session is the only thing
- * `runWorker` does that needs a real harness. Defaulted, so production callers
- * never pass it and a test can hand over a fake without a live peer dependency.
+ * Session creation plus the clock seam needed to prove wall-clock behavior
+ * without sleeping. Production callers use the defaults.
  */
 export interface RunWorkerDeps {
   createSession: typeof createSession;
+  now?: () => number;
+  schedule?: (callback: () => void, delayMs: number) => () => void;
 }
 
 export interface WorkerResult {
@@ -106,6 +139,8 @@ export interface WorkerResult {
   spendUsd: number;
   report: string;
   killedBy?: KilledBy;
+  /** Present only when an operator terminally stopped this run. */
+  stoppedReason?: string;
   /**
    * Transcript the session actually opened, absent if it opened none. Recorded
    * per run because it is the only readable evidence left once the worktree is
@@ -203,6 +238,8 @@ export async function runWorker(
 ): Promise<WorkerResult> {
   const { workerWallClockMs } = o.caps;
   const maxTurns = o.maxTurns ?? (() => o.caps.workerMaxTurns);
+  const now = deps.now ?? Date.now;
+  const schedule = deps.schedule ?? scheduleWallClock;
 
   const session = await deps.createSession({
     cwd: o.cwd,
@@ -249,31 +286,127 @@ export async function runWorker(
   // merged (#217).
   let claim: { prUrl: string; headSha: string } | undefined;
   let killedBy: KilledBy | undefined;
-  // Bun's global timer handle; cleared on every exit path below.
-  let timer: Timer | undefined;
+  let stoppedReason: string | undefined;
+  // Canceler for the armed wall clock; invoked on every exit path below.
+  let cancelWallClock: (() => void) | undefined;
+  let wallClockRemainingMs = workerWallClockMs;
+  let wallClockArmedAt = now();
+  let pausePhase: WorkerPausePhase = "running";
+  let resumeWaiter: PromiseWithResolvers<string> | undefined;
+  // A terminal agent_end or cap has settled the run.
+  let done = false;
   // Resolved by the first terminal `agent_end`, and by every cap kill. Only
   // ever awaited when the harness has already said it is not finished.
   const { promise: settled, resolve: settle } = Promise.withResolvers<void>();
+  // Resolves whenever a pause request must interrupt the existing
+  // non-terminal agent_end wait. Re-armed after its resume prompt is consumed.
+  let pauseRequested = Promise.withResolvers<void>();
   // Set by a non-terminal `agent_end`: the harness will resume this session.
   let resuming = false;
 
   const clearWallClock = () => {
-    if (timer === undefined) return;
-    clearTimeout(timer);
-    timer = undefined;
+    if (cancelWallClock === undefined) return;
+    cancelWallClock();
+    cancelWallClock = undefined;
+  };
+
+  const armWallClock = () => {
+    wallClockArmedAt = now();
+    cancelWallClock = schedule(() => kill("wallclock"), wallClockRemainingMs);
   };
 
   const kill = (by: KilledBy) => {
-    if (killedBy !== undefined) return;
+    if (killedBy !== undefined || stoppedReason !== undefined) return;
     killedBy = by;
     o.onKilled?.(by);
     clearWallClock();
     session.abort();
     // An aborted session may never reach a terminal `agent_end`. The cap is the
     // outcome now, so nothing may still be waiting for one.
+    done = true;
     settle();
   };
 
+  const takeResumePrompt = async (): Promise<string | undefined> => {
+    const waiter = resumeWaiter;
+    if (waiter === undefined) return undefined;
+    const prompt = await Promise.race([
+      waiter.promise,
+      settled.then(() => undefined),
+    ]);
+    if (resumeWaiter === waiter) {
+      resumeWaiter = undefined;
+      pauseRequested = Promise.withResolvers<void>();
+    }
+    return killedBy !== undefined || stoppedReason !== undefined || done ? undefined : prompt;
+  };
+
+  o.onPauseControl?.({
+    phase: () => pausePhase,
+    pause: async () => {
+      if (killedBy !== undefined || done) {
+        throw new Error("the run is settling; nothing left to pause");
+      }
+      if (pausePhase !== "running") throw new Error(`the worker is already ${pausePhase}`);
+      if (resumeWaiter !== undefined) {
+        throw new Error("the worker resume is still starting");
+      }
+      pausePhase = "pausing";
+      resumeWaiter = Promise.withResolvers<string>();
+      pauseRequested.resolve();
+      // Bank the remaining wall clock before the abort: a slow drain must not
+      // be cap-killed mid-park (#238 acceptance 3).
+      wallClockRemainingMs = Math.max(
+        1_000,
+        wallClockRemainingMs - (now() - wallClockArmedAt),
+      );
+      clearWallClock();
+      try {
+        await session.park();
+      } catch (err) {
+        pausePhase = "running";
+        if (killedBy !== undefined || done) {
+          resumeWaiter = undefined;
+          throw err;
+        }
+        // The abort may already have unwound prompt() even though park itself
+        // failed. Wake that path with the same defensive continuation rather
+        // than leaving the worker hung on an orphaned waiter.
+        armWallClock();
+        resumeWaiter?.resolve(RESUME_PROMPT);
+        throw err;
+      }
+      if (killedBy !== undefined || done) {
+        pausePhase = "running";
+        resumeWaiter = undefined;
+        throw new Error("the run settled while pausing");
+      }
+      pausePhase = "paused";
+    },
+    resume: () => {
+      if (pausePhase !== "paused") {
+        throw new Error(
+          pausePhase === "pausing"
+            ? "still pausing — wait until it reports paused"
+            : "the worker is not paused",
+        );
+      }
+      pausePhase = "running";
+      armWallClock();
+      resumeWaiter?.resolve(RESUME_PROMPT);
+    },
+    stop: (reason) => {
+      if (killedBy !== undefined || done) {
+        throw new Error("the run is settling; nothing left to stop");
+      }
+      stoppedReason = reason;
+      clearWallClock();
+      done = true;
+      settle();
+      session.abort();
+    },
+  });
+
   session.on("turn_start", () => {
     // The documented watchdog signal, and the honest one: `turn_start` fires
     // exactly once per turn, whereas one turn can emit several assistant
@@ -326,6 +459,8 @@ export async function runWorker(
     // all — is a finished run.
     const isTerminal = field(event, "isTerminal");
     if (shouldComplete(typeof isTerminal === "boolean" ? { isTerminal } : {})) {
+      if (pausePhase !== "running") return;
+      done = true;
       settle();
       return;
     }
@@ -336,17 +471,36 @@ export async function runWorker(
   // callback does not drop the handle itself: every exit runs `clearWallClock()`
   // exactly once instead, and clearing an already-fired handle is a documented
   // no-op — cheaper than assuming a fired timer holds nothing.
-  timer = setTimeout(() => kill("wallclock"), workerWallClockMs);
+  armWallClock();
 
   try {
-    await session.prompt(o.brief);
-    // `prompt()` returning is not the end of the run once the harness has
-    // announced a resume: finishing here would hand back a truncated report as
-    // the final result. Wait for the terminal `agent_end`, or for a cap.
-    if (resuming && killedBy === undefined) await settled;
+    let next: string | undefined = o.brief;
+    while (next !== undefined) {
+      try {
+        await session.prompt(next);
+      } catch (cause) {
+        // Our own abort surfaces here on some paths: a cap kill (existing
+        // behavior) or an operator park (new). Anything else is a real failure.
+        if (killedBy === undefined && stoppedReason === undefined && resumeWaiter === undefined) throw cause;
+      }
+      next = undefined;
+      if (killedBy !== undefined) break;
+      if (resumeWaiter === undefined && resuming && !done) {
+        // A non-terminal agent_end ordinarily waits for the harness to finish
+        // later. A pause request must wake that wait so resume can prompt the
+        // same session instead of hanging behind the old settlement promise.
+        await Promise.race([settled, pauseRequested.promise]);
+      }
+      if (killedBy !== undefined) break;
+      if (resumeWaiter !== undefined) {
+        next = await takeResumePrompt();
+        if (next === undefined) break;
+        continue;
+      }
+    }
   } catch (cause) {
     // Our own abort surfaces here on some paths; that is a kill, not a crash.
-    if (killedBy === undefined) {
+    if (killedBy === undefined && stoppedReason === undefined) {
       const detail = cause instanceof Error ? cause.message : String(cause);
       return withSessionFacts({
         state: "failed",
@@ -356,6 +510,7 @@ export async function runWorker(
       });
     }
   } finally {
+    done = true;
     // Runs on every exit, including the early return above: a live timer keeps
     // the dispatcher process alive long after the run it was guarding.
     clearWallClock();
@@ -366,6 +521,17 @@ export async function runWorker(
     }
   }
 
+  if (stoppedReason !== undefined) {
+    return withSessionFacts({
+      state: "stopped",
+      turns,
+      spendUsd,
+      report,
+      stoppedReason,
+      ...(claim === undefined ? {} : { prUrl: claim.prUrl, headSha: claim.headSha }),
+    });
+  }
+
   if (killedBy !== undefined) {
     // The PR and head are facts the session already established, so they
     // survive the kill. Without them `shouldContinueAfterTurnsCap` sees no

package/src/worktree.ts

@@ -317,6 +317,11 @@ async function ensureMirrorUnlocked(repo: RepoTarget, mirrorRoot: string): Promi
     throw err;
   }
   await configureMirror(mirrorPath);
+  // `clone --mirror` writes upstream heads under `refs/heads/*`; the safe
+  // normal-clone refspec above uses `refs/remotes/origin/*`. Populate that
+  // namespace before returning so first-use callers see the same fresh mirror
+  // shape as every later refresh.
+  await refreshMirror(mirrorPath);
   return mirrorPath;
 }