@coreplane/switchboard 1.235.0 → 1.236.0

package/dist/assets/src/core/ship/coordinator.ts

@@ -51,6 +51,29 @@ export interface ShipCaps {
  *  burning an attach and a model turn on a doomed round. */
 export const SHIP_ROUND_RESERVE_MS = 3 * MIN;
 
+/** What a round-0 coding child must leave on the pipeline's clock: two review
+ *  rounds (a review and, after a fix, its re-review) and one merge poll — the
+ *  loop the pipeline exists to run. The coding child's budget is clipped to
+ *  the remaining wall clock MINUS this reserve (never under the two minutes a
+ *  spawn accepts), so a child that uses its whole directive still hands the
+ *  pipeline a clock that holds the review; without the clip a 40-minute
+ *  pipeline hands 39 minutes to the child and caps out with the pull request
+ *  shipped and unreviewed. */
+export const SHIP_LOOP_RESERVE_MS = 2 * SHIP_ROUND_RESERVE_MS + 5 * MIN;
+
+/** What a findings child (the fix after a review asked for changes) must leave
+ *  on the clock: the re-review and one merge poll — one round's reserve and
+ *  five minutes. Never the whole loop's: by the time a fix round runs, the
+ *  first review has already happened, and holding two rounds back from a late
+ *  fix would cap a pipeline that still has the time. */
+export const SHIP_FIX_RESERVE_MS = SHIP_ROUND_RESERVE_MS + 5 * MIN;
+
+/** The floor `validateShip` holds `ship.maxMinutes` to: the loop's reserve
+ *  plus one round's — under it no coding child can both work and leave the
+ *  review its time, so the config is refused at load rather than left to cap
+ *  out on every unit. */
+export const SHIP_MIN_MAX_MINUTES = (SHIP_LOOP_RESERVE_MS + SHIP_ROUND_RESERVE_MS) / MIN;
+
 /** What a ship pipeline's thread and card say when the bot died under it (run-
  *  history item 36): the work it did stands on GitHub with nobody driving it,
  *  so the note names the PR when one was opened and the exact re-issue that
@@ -407,7 +430,15 @@ export type CoordinatorAction =
   | { type: "spawn"; step: string; preset: ChildPreset; round: RoundRef; budgetMinutes: number; brief: Brief }
   | { type: "wait"; step: string; runId: string; timeoutMs: number }
   | { type: "read-record"; step: string; runId: string }
-  | { type: "pr-check"; step: string }
+  | {
+      type: "pr-check";
+      step: string;
+      /** Set after a coding child died: the bot opens the pull request from the
+       *  pushed branch itself (title from the unit, body from this run's
+       *  submitted description when the record holds one) instead of answering
+       *  `none` over stranded work. */
+      recover?: { runId: string };
+    }
   | { type: "merge"; step: string; prNumber: number; headSha: string }
   | { type: "sleep"; step: string; ms: number }
   | { type: "end"; step: string; ending: UnitEnding };
@@ -442,7 +473,14 @@ export type ChildFacts =
 /** What heads the unit's branch on GitHub: nothing, an open pull request, or —
  *  with no open one — a merged one, `sha` the merge commit on the base. */
 export type PrCheck =
-  | { state: "none" }
+  | {
+      state: "none";
+      /** After a recover pr-check (a dead coding child): why nothing was
+       *  recovered — `no_commits` (GitHub refused the create: nothing between
+       *  the base and the head) or `no_base` (the instance names no base to
+       *  open against, so no create was tried). Absent on a plain check. */
+      unrecovered?: "no_commits" | "no_base";
+    }
   | { state: "open"; prNumber: number; url: string; headSha?: string; autoMergeEnabled?: boolean }
   | { state: "merged"; prNumber: number; url: string; sha: string; mergedAt: string };
 
@@ -473,7 +511,12 @@ export type UnitEnding =
   | { kind: "merge_ready"; pr: PrRef; reviewRounds: number }
   | { kind: "merge_refused"; pr: PrRef; reason: string; reviewRounds: number }
   | { kind: "round_cap"; maxRounds: number; reviewRounds: number }
-  | { kind: "wall_clock_cap"; remainingMs: number; reviewRounds: number }
+  | { kind: "wall_clock_cap"; remainingMs: number; reviewRounds: number; spent: ShipBudgetSpent }
+  /** The wall clock capped AFTER the coding child opened or updated the pull
+   *  request: the work stands and only the review is missing, so the ending
+   *  names the pull request and "review pending" instead of calling the unit a
+   *  failure — the re-issued attempt starts at the review round (`lastPush`). */
+  | { kind: "review_pending"; pr: PrRef; headSha?: string; reviewRounds: number; spent: ShipBudgetSpent }
   | {
       kind: "stopped";
       mode: "soft" | "hard";
@@ -494,6 +537,12 @@ export type CoordinatorNote =
   | { type: "round"; index: number; agent: ChildPreset; outcome: ShipRoundOutcome }
   | { type: "ended"; ending: UnitEnding };
 
+/** How the pipeline's budget went, in ms: the coding rounds' (round 0 and the
+ *  findings steps), the review rounds', and everything else (branching,
+ *  pr-checks, busy waits, merge polls) — reported on the cap endings so a
+ *  person can see whether the cap or the child is the problem. */
+export type ShipBudgetSpent = Readonly<Record<"coding" | "review" | "waiting", number>>;
+
 export interface UnitPipelineInput {
   unit: { id: string; branch: string };
   repo: string;
@@ -513,6 +562,11 @@ export interface UnitPipelineInput {
   generated: boolean;
   /** Resume at review: an open pull request of ship's own the requester named. */
   resume?: { pr: number; headSha?: string; url?: string };
+  /** The head the previous attempt's coding child last pushed (a
+   *  `review_pending` ending's `headSha`, carried on the unit's row): when the
+   *  pre-check finds the open pull request still at exactly this head, there is
+   *  nothing to code and the attempt starts at the review round. */
+  lastPush?: string;
 }
 
 type Phase =
@@ -524,7 +578,17 @@ type Phase =
   /** `until`: when the child's budget plus the margin runs out, counted from the spawn's answer — the wait's last slice ends there. */
   | { at: "wait"; round: RoundRef; runId: string; n: number; until: number }
   | { at: "read"; round: RoundRef; runId: string; n: number; until: number }
-  | { at: "pr-check"; round: RoundRef; runId: string; childHead?: string; finalReply?: string }
+  | {
+      at: "pr-check";
+      round: RoundRef;
+      runId: string;
+      childHead?: string;
+      finalReply?: string;
+      /** The coding child died (`failed` or `interrupted`) after it may have
+       *  pushed: the pr-check recovers a pushed branch by opening its pull
+       *  request; with nothing pushed the unit ends with the child's own reason. */
+      dead?: "failed" | "interrupted";
+    }
   | { at: "merge"; pr: PrRef; headSha: string; n: number; since: number }
   | { at: "merge-sleep"; pr: PrRef; headSha: string; n: number; since: number }
   | { at: "ended" };
@@ -551,6 +615,8 @@ export interface UnitPipelineState {
   readonly findingsRunByRound: Readonly<Record<number, string>>;
   /** The last coding run (round 0's child or a findings step's): its record carries the unit's handoff. */
   readonly lastCodingRunId?: string;
+  /** How the budget went so far, accrued as each answer moves the clock. */
+  readonly spentMs: ShipBudgetSpent;
   readonly ending?: UnitEnding;
 }
 
@@ -579,6 +645,7 @@ export function openUnitPipeline(input: UnitPipelineInput, at: number): UnitPipe
     clock: at,
     phase: { at: "pre-check" },
     reviewRounds: 0,
+    spentMs: { coding: 0, review: 0, waiting: 0 },
     findingsByRound: {},
     dispositionsByRound: {},
     reviewRunByRound: {},
@@ -609,8 +676,25 @@ function waitSliceMs(clock: number, until: number): number {
 /** The child's budget: its preset's own, clipped to the pipeline's remaining
  *  wall clock (agent-ship item 8's clip), never under the two minutes a
  *  spawn accepts. */
-function budgetMinutesFor(s: UnitPipelineState, preset: ChildPreset): number {
-  return Math.max(2, Math.min(s.input.childMinutes[preset], Math.floor(remainingMs(s) / MIN)));
+function budgetMinutesFor(s: UnitPipelineState, round: RoundRef): number {
+  const headroom = remainingMs(s) - reserveFor(round.kind);
+  return Math.max(2, Math.min(s.input.childMinutes[presetOf(round.kind)], Math.floor(headroom / MIN)));
+}
+
+/** What a child of each round kind leaves on the pipeline's clock: round 0's
+ *  coding child the whole loop (two reviews and the merge poll,
+ *  SHIP_LOOP_RESERVE_MS), a findings child the re-review and the merge poll
+ *  (SHIP_FIX_RESERVE_MS), a review child nothing — the review is what the
+ *  reserve was held for. */
+function reserveFor(kind: RoundKind): number {
+  switch (kind) {
+    case "coding":
+      return SHIP_LOOP_RESERVE_MS;
+    case "findings":
+      return SHIP_FIX_RESERVE_MS;
+    case "review":
+      return 0;
+  }
 }
 
 const roundStep = (s: UnitPipelineState, round: RoundRef) => `${s.input.unit.id}/${round.index}/${round.kind}`;
@@ -668,7 +752,7 @@ export function nextAction(s: UnitPipelineState): CoordinatorAction {
         step: roundStep(s, p.round),
         preset,
         round: p.round,
-        budgetMinutes: budgetMinutesFor(s, preset),
+        budgetMinutes: budgetMinutesFor(s, p.round),
         brief: briefFor(s, p.round),
       };
     }
@@ -687,7 +771,11 @@ export function nextAction(s: UnitPipelineState): CoordinatorAction {
     case "read":
       return { type: "read-record", step: `${roundStep(s, p.round)}/read/${p.n}`, runId: p.runId };
     case "pr-check":
-      return { type: "pr-check", step: `${roundStep(s, p.round)}/pr-check` };
+      return {
+        type: "pr-check",
+        step: `${roundStep(s, p.round)}/pr-check`,
+        ...(p.dead !== undefined ? { recover: { runId: p.runId } } : {}),
+      };
     case "merge":
       return { type: "merge", step: `${unit}/merge/${p.n}`, prNumber: p.pr.number, headSha: p.headSha };
     case "merge-sleep":
@@ -717,12 +805,26 @@ const roundNote = (round: RoundRef, outcome: ShipRoundOutcome): CoordinatorNote
   outcome,
 });
 
+/** The cap's ending: `review_pending` when the clock ran out entering a
+ *  review round with the child's pull request standing — the work shipped and
+ *  only the review is missing — else the wall-clock cap. Both carry the split. */
+function capEnding(s: UnitPipelineState, round?: RoundRef): UnitEnding {
+  if (round?.kind === "review" && s.pr !== undefined)
+    return {
+      kind: "review_pending",
+      pr: s.pr,
+      ...(s.lastReviewHead !== undefined ? { headSha: s.lastReviewHead } : {}),
+      reviewRounds: s.reviewRounds,
+      spent: s.spentMs,
+    };
+  return { kind: "wall_clock_cap", remainingMs: remainingMs(s), reviewRounds: s.reviewRounds, spent: s.spentMs };
+}
+
 /** Start a round if the reservation holds (agent-ship item 8's check: a
  *  child clipped under the reserve cannot do useful work). */
 function enterRound(s: UnitPipelineState, round: RoundRef, notes: CoordinatorNote[] = []): Transition {
   const remaining = remainingMs(s);
-  if (remaining < SHIP_ROUND_RESERVE_MS)
-    return end(s, { kind: "wall_clock_cap", remainingMs: remaining, reviewRounds: s.reviewRounds }, notes);
+  if (remaining < SHIP_ROUND_RESERVE_MS) return end(s, capEnding(s, round), notes);
   const reviewRounds = round.kind === "review" ? round.index : s.reviewRounds;
   return { state: { ...s, reviewRounds, phase: { at: "spawn", round, busy: 0 } }, notes };
 }
@@ -773,17 +875,12 @@ function settleCoding(
       },
       [roundNote(round, "stopped")],
     );
+  // A failed coding child no longer aborts outright: the pr-check looks at the
+  // branch first — a push before the death is recovered as the round's pull
+  // request (agent-ship items 10 and 15), and only a branch with
+  // nothing on it ends the unit with the child's own reason.
   if (facts.status === "failed")
-    return end(
-      next,
-      {
-        kind: "aborted",
-        reason: `⚠️ The coding child of round ${round.index} (run ${runId}) ended \`failed\` — its run page has the error; nothing was opened or edited from it.`,
-        round,
-        reviewRounds: next.reviewRounds,
-      },
-      [roundNote(round, "aborted")],
-    );
+    return { state: { ...next, phase: { at: "pr-check", round, runId, dead: "failed" } }, notes: [] };
   next = {
     ...next,
     phase: {
@@ -919,6 +1016,32 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
   // completed without a pull request of its own, and the unit is done.
   if (pr.state === "merged") return foundMerged(s, pr, [roundNote(round, "completed")]);
   if (pr.state === "none") {
+    // A dead child left nothing on the branch to recover: the unit ends with
+    // the child's own reason — never the budget clip.
+    if (phase.dead === "interrupted")
+      return end(s, { kind: "interrupted", round, runId: phase.runId, reviewRounds: s.reviewRounds }, [
+        roundNote(round, "aborted"),
+      ]);
+    if (phase.dead === "failed") {
+      // The abort repeats the bot's reason for recovering nothing, and claims
+      // no more than the answer carried.
+      const why =
+        pr.unrecovered === "no_commits"
+          ? `nothing heads \`${s.input.unit.branch}\`: no commits were pushed, so there was no work to recover`
+          : pr.unrecovered === "no_base"
+            ? `\`${s.input.unit.branch}\` could not be given a pull request: the instance names no base branch to open it against, so whatever was pushed stays on the branch`
+            : `the pr-check found no pull request heading \`${s.input.unit.branch}\`, so nothing was recovered`;
+      return end(
+        s,
+        {
+          kind: "aborted",
+          reason: `⚠️ The coding child of round ${round.index} (run ${phase.runId}) ended \`failed\` — its run page has the error — and ${why}.`,
+          round,
+          reviewRounds: s.reviewRounds,
+        },
+        [roundNote(round, "aborted")],
+      );
+    }
     const reason =
       round.index === 0
         ? `⚠️ Ship ended at round 0: the coding round ended without opening a pull request (a clarifying question, a budget write-up, an unproven push or a description-less push ends the pipeline here). No review round ran.`
@@ -944,6 +1067,25 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
     const codingHead = normalizeHead(head);
     const reviewedAt = normalizeHead(s.lastReviewHead);
     if (codingHead !== undefined && reviewedAt !== undefined && sameCommit(codingHead, reviewedAt)) {
+      // A findings child that died before it pushed: the recover pr-check found
+      // the round's own pull request, still at the reviewed head. The unit
+      // ends with the child's own reason — the ship-restart note for a bot
+      // roll, the failure for a failed run — never as the round's inaction.
+      if (phase.dead === "interrupted")
+        return end(next, { kind: "interrupted", round, runId: phase.runId, reviewRounds: next.reviewRounds }, [
+          roundNote(round, "aborted"),
+        ]);
+      if (phase.dead === "failed")
+        return end(
+          next,
+          {
+            kind: "aborted",
+            reason: `⚠️ The findings child of round ${round.index} (run ${phase.runId}) ended \`failed\` — its run page has the error — and the branch still sits at \`${codingHead.slice(0, 7)}\`, the commit the review already read, so nothing new was pushed to re-review.`,
+            round,
+            reviewRounds: next.reviewRounds,
+          },
+          [roundNote(round, "aborted")],
+        );
       const findings = s.findingsByRound[round.index] ?? [];
       const dispositions = s.dispositionsByRound[round.index] ?? [];
       const allDeclined =
@@ -967,6 +1109,17 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
   ]);
 }
 
+/** Move the clock and charge the elapsed time to the budget's bucket: a phase
+ *  inside a coding or findings round is the coding child's time, a review
+ *  round's is the review's, everything else — the pre-check, the branch, busy
+ *  waits, the merge polls — is waiting. The split rides the cap endings. */
+function withClock(s: UnitPipelineState, at: number): UnitPipelineState {
+  const delta = Math.max(0, at - s.clock);
+  const round = "round" in s.phase ? s.phase.round : undefined;
+  const bucket = round === undefined ? "waiting" : round.kind === "review" ? "review" : "coding";
+  return { ...s, clock: at, spentMs: { ...s.spentMs, [bucket]: s.spentMs[bucket] + delta } };
+}
+
 /**
  * Feed a step's answer to the machine. An answer for any step but the one the
  * machine is at — a duplicate `run finished`, a replayed spawn — changes
@@ -976,7 +1129,7 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
   const expected = nextAction(s);
   if (expected.type === "end" || ret.step !== expected.step || ret.type !== expected.type)
     return { state: s, notes: [] };
-  const clocked: UnitPipelineState = "at" in ret ? { ...s, clock: ret.at } : s;
+  const clocked: UnitPipelineState = "at" in ret ? withClock(s, ret.at) : s;
   const p = s.phase;
   switch (p.at) {
     case "pre-check": {
@@ -987,6 +1140,20 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
       // by the coding child and adopted at the round's own pr-check.
       const r = ret as Extract<StepReturn, { type: "pr-check" }>;
       if (r.pr.state === "merged") return foundMerged(clocked, r.pr);
+      // The open pull request still heads at the child's own last push (the
+      // previous attempt ended `review_pending`): nothing to code, so the
+      // attempt adopts it and starts at the review round — never a fresh
+      // coding round on an already-shipped pull request.
+      if (r.pr.state === "open") {
+        const head = normalizeHead(r.pr.headSha);
+        const lastPush = normalizeHead(s.input.lastPush);
+        if (head !== undefined && lastPush !== undefined && sameCommit(head, lastPush))
+          return nextReview({
+            ...clocked,
+            pr: { number: r.pr.prNumber, url: r.pr.url },
+            lastReviewHead: head,
+          });
+      }
       return { state: { ...clocked, phase: { at: "branch" } }, notes: [] };
     }
     case "branch": {
@@ -1004,7 +1171,7 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
         case "spawned":
         case "alreadySpawned": {
           // The child's budget runs from the spawn's answer; the wait walks it, plus the margin, in chunks.
-          const until = clocked.clock + budgetMinutesFor(s, presetOf(p.round.kind)) * MIN + WAIT_MARGIN_MS;
+          const until = clocked.clock + budgetMinutesFor(s, p.round) * MIN + WAIT_MARGIN_MS;
           const runs =
             p.round.kind === "review"
               ? { reviewRunByRound: { ...s.reviewRunByRound, [p.round.index]: r.runId } }
@@ -1022,12 +1189,7 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
         case "busy": {
           // Another run holds the unit's thread: wait for its end, then ask
           // again — unless the pipeline's wall clock ran out meanwhile.
-          if (remainingMs(clocked) < SHIP_ROUND_RESERVE_MS)
-            return end(clocked, {
-              kind: "wall_clock_cap",
-              remainingMs: remainingMs(clocked),
-              reviewRounds: s.reviewRounds,
-            });
+          if (remainingMs(clocked) < SHIP_ROUND_RESERVE_MS) return end(clocked, capEnding(clocked, p.round));
           return {
             state: {
               ...clocked,
@@ -1076,10 +1238,19 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
           },
           notes: [],
         };
-      if (r.run.status === "interrupted")
+      if (r.run.status === "interrupted") {
+        // A dead CODING child may have pushed before the ledger closed it: the
+        // pr-check recovers the branch. A review child has nothing on the
+        // branch to recover, so its interruption still ends the unit at once.
+        if (p.round.kind !== "review")
+          return {
+            state: { ...clocked, phase: { at: "pr-check", round: p.round, runId: p.runId, dead: "interrupted" } },
+            notes: [],
+          };
         return end(clocked, { kind: "interrupted", round: p.round, runId: p.runId, reviewRounds: s.reviewRounds }, [
           roundNote(p.round, "aborted"),
         ]);
+      }
       return p.round.kind === "review"
         ? settleReview(clocked, p.round, r.run)
         : settleCoding(clocked, p.round, p.runId, r.run);
@@ -1135,6 +1306,12 @@ function dispositionFor(s: UnitPipelineState, finding: Finding, round: number):
   return undefined;
 }
 
+/** How the budget went, in the card's words: coding, review, waiting minutes. */
+function budgetSplitLine(spent: ShipBudgetSpent, maxMinutes: number): string {
+  const min = (ms: number) => Math.round(ms / MIN);
+  return `Budget split (${maxMinutes} min): coding ${min(spent.coding)} min, review ${min(spent.review)} min, waiting ${min(spent.waiting)} min.`;
+}
+
 /** The cap report's declined-vs-unaddressed split over the last review round's findings. */
 function splitReport(s: UnitPipelineState): string {
   if (s.reviewRounds === 0) return "No review round ran before the cap — there are no findings to report.";
@@ -1222,9 +1399,16 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
     case "wall_clock_cap":
       return join([
         `🧢 Ship stopped at a cap: the remaining pipeline time (~${Math.max(0, Math.round(e.remainingMs / MIN))} min of the ${s.input.caps.maxMinutes}-minute budget) cannot hold another round — no approval after ${rounds}.${prLine}`,
+        budgetSplitLine(e.spent, s.input.caps.maxMinutes),
         splitReport(s),
         reissue,
       ]);
+    case "review_pending":
+      return join([
+        `⏳ Review pending: the coding child shipped ${e.pr.url}${e.headSha !== undefined ? ` (head \`${e.headSha.slice(0, 7)}\`)` : ""} but the remaining pipeline time cannot hold the review round — the work stands, only the review is missing. The next attempt starts at the review round while the pull request still heads at the child's own last push.`,
+        budgetSplitLine(e.spent, s.input.caps.maxMinutes),
+        reissue,
+      ]);
     case "stopped":
       return join([
         `${e.mode === "hard" ? "⛔" : "⏹"} Ship stopped by operator (${e.mode} stop) after ${rounds}.${prLine}`,

package/dist/assets/src/core/trace/types.ts

@@ -68,6 +68,11 @@ export interface SpanOptions {
  *  plain fetch it was. */
 export interface TraceOptions {
   span?: Span;
+  /** Which door the call came through when it was not the surface's own
+   *  grammar: `route` for a command the request router bound from prose
+   *  (record 0036). Copied onto the registry's audit line, never read by a
+   *  handler. Absent for a typed command. */
+  source?: "route";
 }
 
 export interface Span {

package/dist/assets/src/execution/residentDisk.ts

@@ -11,7 +11,7 @@
 // the disk. Two facts fix that: the failure is classified `disk-full` (never
 // serviceable, so the bot skips the attach and the card names the disk), and
 // the resident recycles its container — the disk is a cache; the next refresh
-// cycle restores mirror + checkout from R2 — once nothing live would be lost.
+// cycle restores mirror + checkout from R2 — once no run is using it.
 
 /** The errno wording tools print for ENOSPC: Node's `ENOSPC` code and libc's
  *  strerror text (git, cp, tar, pnpm all pass it through). A message carrying
@@ -76,17 +76,27 @@ export const DISK_FULL_RECYCLE_COOLDOWN_MS = 60 * 60_000;
 export type DiskFullRecovery = { action: "recycle" } | { action: "wait"; why: string };
 
 /** Whether a disk-full resident may stop its container now. The disk is a
- *  cache, but two things on it are not: work in flight (a recycle kills the
- *  process) and a live worktree's uncommitted or unpushed changes (a recycle
- *  destroys the tree; the next attach recreates it from the mirror). Both keep
- *  the container; so does the cooldown. `treesClean` must be computed as the
- *  thread users (never root git in a thread tree) and treated as false when a
- *  check could not run — an unreadable tree is kept, never guessed clean. */
+ *  cache — the next cycle restores mirror + checkout from R2, and a live
+ *  binding's tree is recreated on its next attach — so the one question is
+ *  whether a RUN is using it, never what the trees hold (item 17: a run
+ *  starts from a clean tree; what it wants kept, it commits and pushes). Two
+ *  facts say a run may be: an operation in flight (a recycle kills it), and a
+ *  live binding attached to or used within the idle floor — the op counter is
+ *  0 between a run's tool calls, so the recent-use floor is what stands for a
+ *  run mid-flight. That is the idle-sleep gate's own predicate (item 16b): a
+ *  platform sleep destroys the disk exactly as a recycle does, so one rule
+ *  says when the disk may go away. Both keep the container; so does the
+ *  cooldown. */
 export function planDiskFullRecovery(input: {
   now: number;
   lastRecycleAt?: number;
   inFlight: number;
-  treesClean: boolean;
+  /** A live binding was attached to or used (an exec bumps `lastAttachAt`
+   *  too) within `idleFloorS` — computed once by the Worker, for the idle
+   *  gate and this plan alike. */
+  recentlyUsed: boolean;
+  /** The floor `recentlyUsed` was measured against, named in the refusal. */
+  idleFloorS: number;
 }): DiskFullRecovery {
   if (input.lastRecycleAt !== undefined && input.now - input.lastRecycleAt < DISK_FULL_RECYCLE_COOLDOWN_MS) {
     const min = Math.round((input.now - input.lastRecycleAt) / 60_000);
@@ -97,10 +107,11 @@ export function planDiskFullRecovery(input: {
   }
   if (input.inFlight > 0)
     return { action: "wait", why: `${input.inFlight} operation(s) in flight — a recycle would kill them` };
-  if (!input.treesClean) {
+  if (input.recentlyUsed) {
+    const min = Math.round(input.idleFloorS / 60);
     return {
       action: "wait",
-      why: "a live worktree has (or could not prove it has no) uncommitted or unpushed work — a recycle would destroy it",
+      why: `a live worktree was attached to or used within the last ${min} min — a run may be mid-flight between two tool calls, and a recycle would destroy its tree`,
     };
   }
   return { action: "recycle" };

package/dist/assets/src/execution/sandboxErrors.ts

@@ -125,6 +125,78 @@ export function fleetBusyExhaustedMessage(waitedMs: number): string {
   );
 }
 
+// ---------------------------------------------------------------------------
+// A container that is still starting (docs/reference/specs/execution.md item 23).
+//
+// Why this exists: a thread's first request finds no running container, and
+// the SDK's first exec then carries the whole start — the platform's instance
+// grant (its default wait 30 s), the image pull on a machine that has not seen
+// this image, the microVM boot and the runtime's port (90 s) — before the
+// command runs. The executor's per-send deadline for a 60 s command is 90 s,
+// so every fresh-sandbox run died with "gave no answer within 90s" while its
+// container came up a minute later and sat idle. The Worker now names the
+// condition instead: it starts the container in the background and answers
+// `sandbox-starting` at once, the executor waits on the token exactly as it
+// waits on `fleet-busy` — the identical request re-sent, nothing ran — under a
+// start budget of its own, and the command runs once the container is up.
+
+/** The machine token the executor waits on, beside `fleet-busy`. */
+export const SANDBOX_STARTING_REASON = "sandbox-starting" as const;
+
+/** What the token means, in the words the model and the operator see. */
+export const SANDBOX_STARTING_EXPLANATION =
+  "the thread's sandbox container is starting (image pull, boot, runtime) — nothing ran yet; the request is re-sent once it is up";
+
+/** The executor waits at most this long for a container to start, whatever
+ *  the command's own budget: the platform's own start allowances (30 s for an
+ *  instance, 90 s for the port) plus a slow image pull fit inside it, and a
+ *  60 s command is never killed by a two-minute start it did not cause. */
+export const SANDBOX_START_WAIT_MAX_MS = 5 * 60_000;
+
+/** Backoff between re-sends while a container starts: 5 s, 10 s, then 15 s.
+ *  A start takes tens of seconds, not minutes, so the poll is denser than the
+ *  fleet wait's and a ready container is used within 15 s of coming up. */
+export const SANDBOX_START_BACKOFF_MS: readonly number[] = [5_000, 10_000, 15_000];
+
+/** The reasons whose answers the executor re-sends after a wait. Every other
+ *  `reason` — or none — is an ordinary failure after one send. */
+export type WaitReason = typeof FLEET_BUSY_REASON | typeof SANDBOX_STARTING_REASON;
+
+export function isWaitReason(reason: unknown): reason is WaitReason {
+  return reason === FLEET_BUSY_REASON || reason === SANDBOX_STARTING_REASON;
+}
+
+/** The Worker's answer on /read and /write (sent as HTTP 503) while the
+ *  container starts: the token, and the start's own phase as the cause. */
+export function sandboxStartingAnswer(cause: string): { error: string; reason: typeof SANDBOX_STARTING_REASON } {
+  return {
+    error: `${SANDBOX_STARTING_REASON}: ${SANDBOX_STARTING_EXPLANATION} (${cause})`,
+    reason: SANDBOX_STARTING_REASON,
+  };
+}
+
+/** The Worker's answer on /exec, in-body under the streamed HTTP 200 in the
+ *  item-3 dual shape, like `fleetBusyExecAnswer`. */
+export function sandboxStartingExecAnswer(cause: string): {
+  error: string;
+  reason: typeof SANDBOX_STARTING_REASON;
+  stdout: "";
+  stderr: string;
+  exitCode: 127;
+} {
+  const { error, reason } = sandboxStartingAnswer(cause);
+  return { error, reason, stdout: "", stderr: error, exitCode: 127 };
+}
+
+/** The message `ExecCapacityError` carries when a container did not start
+ *  inside the start budget: the wait, and what to do. */
+export function startWaitExhaustedMessage(waitedMs: number): string {
+  return (
+    `sandbox not ready — the thread's container did not finish starting within ${Math.round(waitedMs / 1000)}s; ` +
+    "try again in a few minutes"
+  );
+}
+
 /** The text the Worker carries in-body for a thrown value: the SDK's own
  *  message when it has one, else a sentence that says the SDK gave none —
  *  naming the error's name and code, and the one condition known to produce

package/dist/assets/src/execution/sandboxStart.ts

@@ -0,0 +1,90 @@
+// The start gate of a thread's sandbox (docs/reference/specs/execution.md
+// item 23): the Durable Object's decision, on every request, between running
+// the operation and answering `sandbox-starting`. Deliberately free of node:
+// imports so wrangler can bundle it into the sandbox Worker, like
+// sandboxErrors.ts and sandboxIdle.ts.
+//
+// Why: a thread's first request finds no running container, and the SDK's
+// first exec then carries the whole start — the platform's instance grant,
+// the image pull, the microVM boot, the runtime's port — before the command
+// runs; the executor's per-send deadline for a 60 s command is 90 s, so every
+// fresh-sandbox run died with "gave no answer within 90s" while its container
+// came up a minute later. The gate starts the container in the background
+// through a warm-up the host provides, answers the named token at once, and
+// lets the operation through only once the container is up. A warm-up that
+// fails hands its error to the next request, so a full fleet or a silent
+// runtime keeps its own name (item 14, item 9) — the gate never swallows it.
+
+/** What the gate needs from the Durable Object. */
+export interface StartGateHost {
+  /** `ctx.container?.running`: true once the platform runs the container,
+   *  false when it is stopped, undefined when there is no container binding
+   *  (treated as not running: the warm-up will say what is wrong). */
+  containerRunning(): boolean | undefined;
+  /** Start the container and wait for its runtime: one trivial command
+   *  through the SDK, which does the start itself. Resolves when the runtime
+   *  answered; rejects with the SDK's own error otherwise. */
+  warmUp(): Promise<void>;
+  now(): number;
+  log(event: Record<string, unknown>): void;
+}
+
+/** The gate's answer when the operation cannot run yet: the phase the start
+ *  is in, in words, for the answer's cause. */
+export type StartingCause = "container not running; starting it" | "container starting";
+
+export class StartGate {
+  private starting: Promise<void> | null = null;
+  private startedAt = 0;
+  private failure: { error: unknown } | null = null;
+
+  constructor(private readonly host: StartGateHost) {}
+
+  /** Run `op` when the container is up; otherwise answer `starting(cause)`
+   *  at once — beginning the warm-up on the first such request — and let the
+   *  executor's wait re-send. A warm-up that failed is thrown here once, on
+   *  the next request, so the caller classifies it as it would any SDK error
+   *  (a full fleet, a silent control port); the request after that starts a
+   *  fresh warm-up if the container is still not running. */
+  async through<T, S>(op: () => Promise<T>, starting: (cause: StartingCause) => S): Promise<T | S> {
+    if (this.failure) {
+      const { error } = this.failure;
+      this.failure = null;
+      throw error;
+    }
+    if (this.starting) return starting("container starting");
+    if (this.host.containerRunning() !== true) {
+      this.begin();
+      return starting("container not running; starting it");
+    }
+    return op();
+  }
+
+  /** Whether a warm-up is in flight — for the wiring test and the card. */
+  get isStarting(): boolean {
+    return this.starting !== null;
+  }
+
+  private begin(): void {
+    this.startedAt = this.host.now();
+    this.host.log({ event: "sandbox.starting" });
+    this.starting = this.host
+      .warmUp()
+      .then(
+        () => {
+          this.host.log({ event: "sandbox.started", durationMs: this.host.now() - this.startedAt });
+        },
+        (error: unknown) => {
+          this.host.log({
+            event: "sandbox.start-failed",
+            durationMs: this.host.now() - this.startedAt,
+            error: String(error),
+          });
+          this.failure = { error };
+        },
+      )
+      .finally(() => {
+        this.starting = null;
+      });
+  }
+}