@coreplane/switchboard 1.226.1 → 1.228.0

package/dist/assets/src/core/runUsage.ts

@@ -0,0 +1,199 @@
+import type { RunEvent } from "./runEvents.js";
+
+// What a run cost in tokens, and who it belongs to — the data behind "cost by
+// user" on the costs page (docs/reference/specs/costs.md). Every provider call a
+// run makes is one `model.turn` span with the provider's own token counts as
+// attrs (metered by the model proxy or the runner; docs/reference/specs/tracing.md), so a
+// run's usage is the sum of those spans, per model. It is computed ONCE, at
+// finish, from the events still in memory (`assembleRunRecord`), and rides the
+// record — a record's events may be cut to fit the byte budget, so an aggregate
+// taken then is more faithful than one re-read later. A record written before
+// the field existed has none; the store fills it in from the run's stored
+// events on demand (the lazy backfill), and reports how many still wait.
+
+export interface ModelUsage {
+  turns: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+}
+
+export interface RunUsage {
+  /** Every `model.turn` span, whatever its model. */
+  turns: number;
+  /** Per `<provider>/<model>` as the span named it; `unknown` for a turn without a model attr. */
+  byModel: Record<string, ModelUsage>;
+}
+
+export const UNKNOWN_MODEL = "unknown";
+
+const MODEL_TURN = "model.turn";
+
+const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0);
+
+export const emptyUsage = (): RunUsage => ({ turns: 0, byModel: {} });
+
+/** The run's usage from its events: one `model.turn` span end per provider call. */
+export function usageOfEvents(events: readonly RunEvent[]): RunUsage {
+  const usage = emptyUsage();
+  for (const e of events) {
+    if (e.type !== "span_end" || e.name !== MODEL_TURN) continue;
+    const attrs = (e.attrs ?? {}) as Record<string, unknown>;
+    const model = typeof attrs.model === "string" && attrs.model ? attrs.model : UNKNOWN_MODEL;
+    const m = usage.byModel[model] ?? {
+      turns: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+    };
+    m.turns += 1;
+    m.inputTokens += num(attrs.inputTokens);
+    m.outputTokens += num(attrs.outputTokens);
+    m.cacheReadTokens += num(attrs.cacheReadTokens);
+    m.cacheWriteTokens += num(attrs.cacheWriteTokens);
+    usage.byModel[model] = m;
+    usage.turns += 1;
+  }
+  return usage;
+}
+
+export function addUsage(a: RunUsage, b: RunUsage): RunUsage {
+  const out: RunUsage = { turns: a.turns + b.turns, byModel: {} };
+  for (const src of [a.byModel, b.byModel]) {
+    for (const [model, m] of Object.entries(src)) {
+      const acc = out.byModel[model] ?? {
+        turns: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+      };
+      acc.turns += m.turns;
+      acc.inputTokens += m.inputTokens;
+      acc.outputTokens += m.outputTokens;
+      acc.cacheReadTokens += m.cacheReadTokens;
+      acc.cacheWriteTokens += m.cacheWriteTokens;
+      out.byModel[model] = acc;
+    }
+  }
+  return out;
+}
+
+const isModelUsage = (v: unknown): v is ModelUsage =>
+  typeof v === "object" &&
+  v !== null &&
+  (["turns", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens"] as const).every(
+    (k) => typeof (v as Record<string, unknown>)[k] === "number",
+  );
+
+export function isRunUsage(v: unknown): v is RunUsage {
+  if (typeof v !== "object" || v === null) return false;
+  const u = v as Record<string, unknown>;
+  if (typeof u.turns !== "number") return false;
+  if (typeof u.byModel !== "object" || u.byModel === null || Array.isArray(u.byModel)) return false;
+  return Object.values(u.byModel).every(isModelUsage);
+}
+
+// ---- the aggregate: who spent what, per UTC day ---------------------------------------
+
+/** One finished run as the aggregate sees it — the record's identity fields and its usage. */
+export interface UsageRun {
+  id: string;
+  userId: string;
+  userName?: string;
+  /** A child run is billed to whoever started its parent (run-history item 46). */
+  parentRunId?: string;
+  startedAt: number;
+  finishedAt: number;
+  /** Absent on a record written before usage existed and not yet backfilled. */
+  usage?: RunUsage;
+}
+
+export interface UserDayUsage {
+  userId: string;
+  userName?: string;
+  /** The UTC day the run finished, `YYYY-MM-DD`. */
+  day: string;
+  runs: number;
+  /** Summed wall-clock of the runs (finish − start), for allocating shared cloud spend. */
+  wallMs: number;
+  usage: RunUsage;
+}
+
+export interface RunUsageQuery {
+  /** Runs that finished at or after this epoch ms … */
+  sinceMs: number;
+  /** … and before this one. */
+  untilMs: number;
+}
+
+export interface RunUsageReport {
+  rows: UserDayUsage[];
+  /** Runs in range whose usage is not known yet (written before the field; backfill outstanding). */
+  pending: number;
+  /** The oldest finish the store still holds, so a page can bound its range to the data. */
+  earliestFinishedAt?: number;
+  retentionDays: number;
+}
+
+export const dayOf = (epochMs: number): string => new Date(epochMs).toISOString().slice(0, 10);
+
+/** Who a run is billed to: its parent's requester when it is a child and the
+ *  parent is known (in the batch, or through `lookupParent`), else its own. */
+export function billedTo(
+  run: UsageRun,
+  batch: ReadonlyMap<string, UsageRun>,
+  lookupParent: (id: string) => Pick<UsageRun, "userId" | "userName"> | undefined,
+): Pick<UsageRun, "userId" | "userName"> {
+  if (!run.parentRunId) return { userId: run.userId, ...(run.userName ? { userName: run.userName } : {}) };
+  const parent = batch.get(run.parentRunId) ?? lookupParent(run.parentRunId);
+  if (!parent) return { userId: run.userId, ...(run.userName ? { userName: run.userName } : {}) };
+  return { userId: parent.userId, ...(parent.userName ? { userName: parent.userName } : {}) };
+}
+
+/** Pure: the runs summed per (billed user, UTC day of finish). A run without
+ *  usage counts as pending and contributes its run and wall-clock only. Rows
+ *  come out oldest day first, then by user id. */
+export function aggregateUsageByUser(
+  runs: readonly UsageRun[],
+  lookupParent: (id: string) => Pick<UsageRun, "userId" | "userName"> | undefined = () => undefined,
+): { rows: UserDayUsage[]; pending: number } {
+  const batch = new Map(runs.map((r) => [r.id, r]));
+  const rows = new Map<string, UserDayUsage>();
+  let pending = 0;
+  for (const run of runs) {
+    const who = billedTo(run, batch, lookupParent);
+    const day = dayOf(run.finishedAt);
+    const key = `${day} ${who.userId}`;
+    const row = rows.get(key) ?? { userId: who.userId, day, runs: 0, wallMs: 0, usage: emptyUsage() };
+    if (who.userName && !row.userName) row.userName = who.userName;
+    row.runs += 1;
+    row.wallMs += Math.max(0, run.finishedAt - run.startedAt);
+    if (run.usage) row.usage = addUsage(row.usage, run.usage);
+    else pending += 1;
+    rows.set(key, row);
+  }
+  return {
+    rows: [...rows.values()].sort((a, b) => (a.day < b.day ? -1 : a.day > b.day ? 1 : a.userId < b.userId ? -1 : 1)),
+    pending,
+  };
+}
+
+export function isRunUsageReport(v: unknown): v is RunUsageReport {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v as Record<string, unknown>;
+  if (!Array.isArray(r.rows) || typeof r.pending !== "number" || typeof r.retentionDays !== "number") return false;
+  if (r.earliestFinishedAt !== undefined && typeof r.earliestFinishedAt !== "number") return false;
+  return r.rows.every(
+    (row) =>
+      typeof row === "object" &&
+      row !== null &&
+      typeof (row as UserDayUsage).userId === "string" &&
+      typeof (row as UserDayUsage).day === "string" &&
+      typeof (row as UserDayUsage).runs === "number" &&
+      typeof (row as UserDayUsage).wallMs === "number" &&
+      isRunUsage((row as UserDayUsage).usage),
+  );
+}

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

@@ -424,7 +424,9 @@ export interface UnitPipelineInput {
   /** Each child preset's own wall-clock budget (its `maxMinutes`), the number a
    *  round's budget is clipped from — supplied by the bot, which holds the registry. */
   childMinutes: Readonly<Record<ChildPreset, number>>;
-  /** Who merges: the runner (a plan branch, under its grant) or a person (any other branch). */
+  /** Who merges: the instance's `merge` field as the plan route answers it —
+   *  `runner` (a seeded plan, under its grant) or `person` (a task, or a
+   *  record without the field). */
   merge: "runner" | "person";
   /** Resume at review: an open pull request of ship's own the requester named. */
   resume?: { pr: number; headSha?: string; url?: string };
@@ -1102,7 +1104,7 @@ export function renderUnitReport(s: UnitPipelineState): string {
         `✅ Merge-ready after ${rounds}: ${e.pr.url}`,
         verdictLine,
         declinedLine,
-        "Remaining gate: a person's merge — the runner merges only a plan branch's pull request, and ship never approves.",
+        "Remaining gate: a person's merge — the runner merges only when the instance's `merge` field says runner, and ship never approves.",
       ].join("\n");
     case "merge_refused":
       return join([

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

@@ -0,0 +1,310 @@
+/** The one exception to the resident's sticky ref binding
+ *  (deploy/cloudflare-resident/worker.ts `attachThreadBody`), kept pure and
+ *  dependency-free so it is unit-testable from src/ and imported by the
+ *  resident Worker like residentReuse and residentHead: the tested code IS the
+ *  shipped code.
+ *
+ *  Background: a thread's first attach binds a ref, and every later attach in
+ *  the thread keeps it — a differing hint is ignored, so a stray word can never
+ *  move a thread onto a stranger's branch. That rule has one blind spot: a
+ *  thread bound to the repo default because its first message named no branch,
+ *  whose own run then created a branch, pushed it and opened a pull request.
+ *  The follow-up's target resolution binds that branch (the thread's own PR,
+ *  docs/reference/specs/resident-repos.md item 29), the resident ignores it, and
+ *  the follow-up runs on the default branch while the thread's work sits on
+ *  the branch it made — a push from there would land on the default.
+ *
+ *  Shape: the caller names the reason for its hint (`ownPr`: the pull request
+ *  the thread's own run opened and its head branch — never a PR a person
+ *  named). The resident moves the binding only when all of these hold:
+ *  - the binding was made by default (the first message named no branch), read
+ *    off `boundBy`, or, for a binding made before that field, off whether the
+ *    ref is the default branch — a ref a person named is never moved;
+ *  - the thread was not rebound before — a thread moves once;
+ *  - the branch is a local branch of the thread's OWN worktree — the physical
+ *    fact that this thread's run created it; a branch the tree never made is
+ *    refused whatever the caller says;
+ *  - the tree has no uncommitted tracked changes — never at the cost of work.
+ *  The move is a `git checkout` inside the existing tree: same path, same pool
+ *  user, deps and snapshot lineage untouched. Every refusal is named in the
+ *  attach answer so the bot can say why the follow-up runs where it does. */
+
+/** The pull request the thread's own run opened, and its head branch — the
+ *  reason a caller's refHint is that branch. */
+export interface OwnPr {
+  number: number;
+  ref: string;
+}
+
+export type ParsedOwnPr = { ownPr: OwnPr | null } | { error: string };
+
+const OWN_PR_ERROR = "ownPr must be {number: <positive integer>, ref: <branch>} when present";
+
+/** `/attach` body field `ownPr`: absent → null (the body every bot always
+ *  sent); `{number, ref}` with a positive integer and a non-empty string →
+ *  itself; anything else → a 400-shaped error. The ref's PATTERN is the
+ *  Worker's to check, where it checks every ref (`parseRef`), before the
+ *  string can become a git argument. */
+export function parseOwnPr(value: unknown): ParsedOwnPr {
+  if (value === undefined) return { ownPr: null };
+  if (typeof value !== "object" || value === null) return { error: OWN_PR_ERROR };
+  const { number, ref } = value as { number?: unknown; ref?: unknown };
+  if (typeof number !== "number" || !Number.isSafeInteger(number) || number <= 0) return { error: OWN_PR_ERROR };
+  if (typeof ref !== "string" || ref.length === 0) return { error: OWN_PR_ERROR };
+  return { ownPr: { number, ref } };
+}
+
+export type ParsedRefByDefault = { refByDefault: boolean } | { error: string };
+
+/** `/attach` body field `refByDefault`: the caller bound the resident's own
+ *  default branch because its message named none (item 30). Absent → false; a
+ *  boolean → itself; anything else → a 400-shaped error. */
+export function parseRefByDefault(value: unknown): ParsedRefByDefault {
+  if (value === undefined) return { refByDefault: false };
+  if (typeof value === "boolean") return { refByDefault: value };
+  return { error: "refByDefault must be a boolean when present" };
+}
+
+/** A branch a run pushed and the pull request it heads — what the run's
+ *  release hands the resident (`/detach` body `pushed`), read off the run's
+ *  own `pr_opened` events. */
+export interface PushedBranch {
+  ref: string;
+  pr: number;
+}
+
+/** The same fact as the binding remembers it, with when it was told. */
+export interface OwnBranch extends PushedBranch {
+  at: string;
+}
+
+/** The most branches one release may hand over: a run pushes a handful at most. */
+export const PUSHED_MAX = 20;
+/** The most branches a binding remembers: the newest are kept. */
+export const OWN_BRANCHES_MAX = 50;
+
+export type ParsedPushed = { pushed: PushedBranch[] } | { error: string };
+
+const PUSHED_ERROR = "pushed must be a list of {ref: <branch>, pr: <positive integer>} when present";
+
+/** `/detach` body field `pushed`: absent → nothing (the body every bot always
+ *  sent); a list of up to `PUSHED_MAX` well-formed `{ref, pr}` → itself;
+ *  anything else → a 400-shaped error. Each ref's PATTERN is the Worker's to
+ *  check (`parseRef`), like every ref. */
+export function parsePushed(value: unknown): ParsedPushed {
+  if (value === undefined) return { pushed: [] };
+  if (!Array.isArray(value) || value.length > PUSHED_MAX) return { error: PUSHED_ERROR };
+  const pushed: PushedBranch[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "object" || entry === null) return { error: PUSHED_ERROR };
+    const { ref, pr } = entry as { ref?: unknown; pr?: unknown };
+    if (typeof ref !== "string" || ref.length === 0) return { error: PUSHED_ERROR };
+    if (typeof pr !== "number" || !Number.isSafeInteger(pr) || pr <= 0) return { error: PUSHED_ERROR };
+    pushed.push({ ref, pr });
+  }
+  return { pushed };
+}
+
+/** The binding's memory after a release: every branch handed over is
+ *  remembered once — a branch pushed again moves to the end with its current
+ *  pull request and time — and only the newest `OWN_BRANCHES_MAX` are kept.
+ *  Stored BEFORE any eviction decision, so the fact survives the tree. */
+export function rememberOwnBranches(
+  existing: readonly OwnBranch[] | undefined,
+  pushed: readonly PushedBranch[],
+  at: string,
+): OwnBranch[] {
+  const refs = new Set(pushed.map((p) => p.ref));
+  const kept = (existing ?? []).filter((b) => !refs.has(b.ref));
+  const added = pushed.map((p) => ({ ref: p.ref, pr: p.pr, at }));
+  return [...kept, ...added].slice(-OWN_BRANCHES_MAX);
+}
+
+/** Whether the thread's own runs pushed `ref`, as the binding remembers it. */
+export function isOwnBranch(binding: { ownBranches?: readonly OwnBranch[] }, ref: string): boolean {
+  return (binding.ownBranches ?? []).some((b) => b.ref === ref);
+}
+
+/** How a binding's ref was chosen: the repo default for want of a named
+ *  branch, or a branch someone named. */
+export type BoundBy = "default" | "name";
+
+/** What a NEW binding records: `default` only when the caller said it bound
+ *  the default for want of a name AND the ref is that default — a flag on any
+ *  other ref is a caller bug, and `name` is the direction that never moves. */
+export function boundByFor(input: { refByDefault: boolean; ref: string; defaultRef: string }): BoundBy {
+  return input.refByDefault && input.ref === input.defaultRef ? "default" : "name";
+}
+
+/** How an EXISTING binding's ref was chosen: the recorded value, or, for a
+ *  binding made before the field, `default` iff its ref is the default branch. */
+export function boundByOf(binding: { ref: string; boundBy?: BoundBy }, defaultRef: string): BoundBy {
+  return binding.boundBy ?? (binding.ref === defaultRef ? "default" : "name");
+}
+
+/** The record a rebind leaves on the binding and in the attach answer. */
+export interface Rebound {
+  from: string;
+  to: string;
+  pr: number;
+  at: string;
+}
+
+export type RebindRefusal = "named-ref" | "already-rebound" | "branch-absent" | "dirty" | "checkout-failed";
+
+/** Why the binding stood, in the attach answer: the branch it was asked to
+ *  move to, the pull request, the reason and its sentence. */
+export interface RebindRefused {
+  to: string;
+  pr: number;
+  reason: RebindRefusal;
+  why: string;
+}
+
+/** What the plan reads off the thread's binding. */
+export interface RebindableBinding {
+  ref: string;
+  /** "" once evicted: no tree, no user to measure it as. */
+  user: string;
+  evicted?: boolean;
+  boundBy?: BoundBy;
+  rebound?: Rebound;
+  /** The branches the thread's own runs pushed, handed over at each release. */
+  ownBranches?: OwnBranch[];
+}
+
+export type RebindPlan =
+  /** No hint, no binding yet (the hint binds as any refHint), the binding is
+   *  already on that branch, or a resumed run's attach. */
+  | { kind: "none" }
+  /** The binding alone rules it out; nothing on disk is consulted. */
+  | { kind: "refuse"; refused: RebindRefused }
+  /** The binding allows it and has a live tree; the tree decides
+   *  (`rebindVerdict`). `own`: the thread's own runs pushed the branch, so a
+   *  tree that turns out missing may still be recreated at it. */
+  | { kind: "measure"; from: string; to: string; pr: number; own: boolean }
+  /** The binding allows it, its tree was evicted, and the thread's own runs
+   *  pushed the branch: the binding moves and the attach recreates the tree
+   *  at the branch — once the mirror is known to hold it. */
+  | { kind: "recreate"; from: string; to: string; pr: number };
+
+export function rebindRefused(plan: { to: string; pr: number }, reason: RebindRefusal, why: string): RebindRefused {
+  return { to: plan.to, pr: plan.pr, reason, why };
+}
+
+/** Whether the binding may move, read off the binding alone. */
+export function rebindPlan(input: {
+  ownPr: OwnPr | null;
+  /** A resumed run's attach keeps the tree exactly as it stands (item 66): its
+   *  HEAD is where the run left it and must not move under the run. */
+  reuse: boolean;
+  binding: RebindableBinding | undefined;
+  defaultRef: string;
+}): RebindPlan {
+  const { ownPr, reuse, binding, defaultRef } = input;
+  if (ownPr === null || reuse || binding === undefined || binding.ref === ownPr.ref) return { kind: "none" };
+  const plan = { to: ownPr.ref, pr: ownPr.number };
+  if (boundByOf(binding, defaultRef) === "name") {
+    return {
+      kind: "refuse",
+      refused: rebindRefused(
+        plan,
+        "named-ref",
+        `the thread is bound to ${JSON.stringify(binding.ref)} by name; a named branch is never moved`,
+      ),
+    };
+  }
+  if (binding.rebound) {
+    const r = binding.rebound;
+    return {
+      kind: "refuse",
+      refused: rebindRefused(
+        plan,
+        "already-rebound",
+        `the thread was already rebound from ${JSON.stringify(r.from)} to ${JSON.stringify(r.to)} (its pull request #${r.pr}); a thread moves once`,
+      ),
+    };
+  }
+  const own = isOwnBranch(binding, plan.to);
+  if (binding.evicted || !binding.user) {
+    if (own) return { kind: "recreate", from: binding.ref, ...plan };
+    return {
+      kind: "refuse",
+      refused: rebindRefused(
+        plan,
+        "branch-absent",
+        `the thread's worktree was evicted and none of its runs pushed ${JSON.stringify(plan.to)}; only a branch this thread's own run pushed moves it`,
+      ),
+    };
+  }
+  return { kind: "measure", from: binding.ref, ...plan, own };
+}
+
+/** What the attach measured about the thread's tree, as the thread user. Each
+ *  probe past `exists` is measured only when the tree is there. */
+export interface RebindTreeFacts {
+  /** `<worktree>/.git` is a directory. */
+  exists: boolean;
+  /** `git rev-parse --verify --quiet refs/heads/<to>` succeeded in the tree. */
+  branchExists?: boolean;
+  /** `git status --porcelain -uno` ran: false is a tree git cannot read
+   *  (corrupt, or owned by an earlier pool user), where nothing is verifiable. */
+  readable?: boolean;
+  /** `git status --porcelain -uno` listed a tracked change (untracked scratch
+   *  files are the thread's own state and survive a checkout). */
+  dirty?: boolean;
+}
+
+export type RebindVerdict =
+  /** Check the branch out in the existing tree. */
+  | { kind: "rebind" }
+  /** The tree is gone (a slept container) and the thread's own runs pushed the
+   *  branch: move the binding and let the attach recreate the tree at it. */
+  | { kind: "recreate" }
+  | { kind: "refuse"; refused: RebindRefused };
+
+/** The tree's verdict on a measured plan. */
+export function rebindVerdict(plan: { to: string; pr: number; own?: boolean }, tree: RebindTreeFacts): RebindVerdict {
+  if (!tree.exists) {
+    if (plan.own === true) return { kind: "recreate" };
+    return {
+      kind: "refuse",
+      refused: rebindRefused(
+        plan,
+        "branch-absent",
+        `the thread's worktree is missing and none of its runs pushed ${JSON.stringify(plan.to)}; the branch cannot be verified there`,
+      ),
+    };
+  }
+  if (tree.readable === false) {
+    return {
+      kind: "refuse",
+      refused: rebindRefused(
+        plan,
+        "branch-absent",
+        "the thread's worktree cannot be read; the branch cannot be verified there",
+      ),
+    };
+  }
+  if (tree.branchExists !== true) {
+    return {
+      kind: "refuse",
+      refused: rebindRefused(
+        plan,
+        "branch-absent",
+        `${JSON.stringify(plan.to)} is not a local branch of the thread's worktree; only a branch this thread's own run made moves it`,
+      ),
+    };
+  }
+  if (tree.dirty === true) {
+    return {
+      kind: "refuse",
+      refused: rebindRefused(
+        plan,
+        "dirty",
+        "the worktree has uncommitted changes on the bound branch; the binding stands until they are committed or discarded",
+      ),
+    };
+  }
+  return { kind: "rebind" };
+}

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

@@ -18,6 +18,7 @@ export const RESIDENT_STEP_LABELS = {
   "for-each-ref": "listing the branches",
   checkout: "checking out the branch",
   "checkout-update": "updating the checkout",
+  "rebind-checkout": "checking out the thread's own branch",
   "rev-parse": "reading the commit",
   "cat-file": "checking the mirror for the commit",
   "show-ref": "reading the branch tip",

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

@@ -90,16 +90,6 @@ export function isFleetBusyError(err: unknown): boolean {
   );
 }
 
-/** The 0.12.x Durable Object's answer while its container is still booting:
- *  no session exists yet and nothing ran, so the SAME request can be re-sent
- *  after a short pause — the one retry the Worker still does itself. */
-export const CONTAINER_STARTING_PATTERN = /^Container is starting\. Please retry in a moment\.?$/i;
-
-export function isContainerStarting(err: unknown): boolean {
-  const { message } = thrownShape(err);
-  return !!message && CONTAINER_STARTING_PATTERN.test(message.trim());
-}
-
 /** The Worker's answer on /read and /write (sent as HTTP 503): the named
  *  reason plus an `error` that keeps the SDK's own message as the cause, so
  *  the logs and the model can still see what the platform actually said. */
@@ -157,3 +147,88 @@ export function thrownText(shape: ThrownShape): string {
     "while a Worker/image rollout is in progress — retry in a minute"
   );
 }
+
+// ---- A runtime that did not answer (docs/reference/specs/execution.md item 9) ----
+//
+// Every command and file operation reaches the container through the SDK's
+// control connection to the container's port. When nothing answers there —
+// the SDK's server exited, or the image's PID 1 is starting it again — the
+// SDK's connect aborts after 30 s with a bare `The operation was aborted`:
+// no container, no cause, nothing a card can act on. The Durable Object
+// names the condition instead, with the facts a reader needs.
+
+/** The named reason the Worker answers with, like `fleet-busy`: a machine
+ *  token the executor matches on, never the SDK's text. */
+export const RUNTIME_UNREACHABLE_REASON = "runtime-unreachable" as const;
+
+/** The name the Worker's typed error carries across the Durable Object RPC
+ *  boundary (which keeps `name`/`message` and drops the prototype). */
+export const RUNTIME_UNREACHABLE_ERROR_NAME = "SandboxRuntimeUnreachableError";
+
+export interface RuntimeUnreachableFacts {
+  /** The Durable Object's id — the same word the `containers` log dataset carries as the container id. */
+  containerId: string;
+  /** The platform's view at the moment of the failure (`ctx.container.running`). */
+  running: boolean | undefined;
+  /** The Worker's `@cloudflare/sandbox` pin, which is also the image tag. */
+  sdkVersion: string;
+  /** The SDK's own text, verbatim: what it saw. */
+  cause: string;
+}
+
+/** The text that names the condition: the token first (the executor and the
+ *  harness read it), then the facts a reader needs to find the container in
+ *  the logs and to judge the command — it may not have run, and the workspace
+ *  is still there because the container is. */
+export function runtimeUnreachableMessage(f: RuntimeUnreachableFacts): string {
+  const platform = f.running === true ? "running" : f.running === false ? "stopped" : "in a state it did not report";
+  return (
+    `${RUNTIME_UNREACHABLE_REASON}: the sandbox container's runtime did not answer ` +
+    `(container ${f.containerId}, sandbox SDK ${f.sdkVersion}; the platform reports the container ${platform}) — ` +
+    "nothing ran; if the container still runs, /workspace is intact and its runtime is being started again: " +
+    `wait a moment, then retry (${f.cause.trim() || "no detail from the SDK"})`
+  );
+}
+
+/** The Worker's typed error for a silent control port: built inside the
+ *  Durable Object with its facts, read by the fetch handler on the other side
+ *  of the RPC boundary, so it is matched by name and by its message token,
+ *  never by `instanceof`. */
+export class SandboxRuntimeUnreachableError extends Error {
+  readonly reason = RUNTIME_UNREACHABLE_REASON;
+  constructor(readonly facts: RuntimeUnreachableFacts) {
+    super(runtimeUnreachableMessage(facts));
+    this.name = RUNTIME_UNREACHABLE_ERROR_NAME;
+  }
+}
+
+/** Name first, token second: the typed error after the RPC boundary, or any
+ *  message that starts with the token (an executor reading a Worker's text). */
+export function isRuntimeUnreachableError(err: unknown): boolean {
+  const s = thrownShape(err);
+  return s.name === RUNTIME_UNREACHABLE_ERROR_NAME || !!s.message?.startsWith(`${RUNTIME_UNREACHABLE_REASON}:`);
+}
+
+/** The `/read` and `/write` answer (sent as HTTP 503): the named reason and the
+ *  text as the error — a 503 the executor's transport retry re-sends, which is
+ *  safe: a file op that never reached a server did nothing. */
+export function runtimeUnreachableAnswer(message: string): {
+  error: string;
+  reason: typeof RUNTIME_UNREACHABLE_REASON;
+} {
+  return { error: message, reason: RUNTIME_UNREACHABLE_REASON };
+}
+
+/** The `/exec` answer, in-body under the streamed HTTP 200 like every other exec
+ *  failure: the dual `error` + exit-127/stderr shape (item 3) plus the reason.
+ *  Never re-sent by anyone: the executor re-sends nothing in-body, and the
+ *  text tells the model to wait, then retry. */
+export function runtimeUnreachableExecAnswer(message: string): {
+  error: string;
+  reason: typeof RUNTIME_UNREACHABLE_REASON;
+  stdout: "";
+  stderr: string;
+  exitCode: 127;
+} {
+  return { error: message, reason: RUNTIME_UNREACHABLE_REASON, stdout: "", stderr: message, exitCode: 127 };
+}