@coreplane/switchboard 1.235.0 → 1.237.0

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

@@ -151,9 +151,19 @@ export { parseDfKiB };
 // ---------------------------------------------------------------------------
 
 /** The refresh cycle snapshots mirror + checkout to R2 through the Sandbox
- *  SDK (`createBackup`); whether it stages a tarball on local disk is
- *  SDK-internal, so the budget holds room for one compressed copy of what it
- *  archives — the same ratio `instanceSizing.test.ts` sizes the instance with. */
+ *  SDK (`createBackup`), which stages each archive on the container's own disk
+ *  (`/var/backups/<id>.sqsh`, lz4 squashfs) before the upload and removes it
+ *  after, the pair concurrently — so the budget holds room for one compressed
+ *  copy of what the cycle archives, at the ratio `instanceSizing.test.ts` sizes
+ *  the instance with. Since item 61 PR B the checkout archive EXCLUDES
+ *  node_modules (`CHECKOUT_SNAPSHOT_EXCLUDES`): the deps are not in the
+ *  cycle's staging. The deps-store entry has its own archive, taken once per
+ *  lockfile key right after the entry is committed, and that one IS staged
+ *  from the deps — the reserve counts it only while such a backup is in
+ *  flight (`depsBackupInFlight`), never as a standing charge. Before this,
+ *  the standing term multiplied the deps too: on a resident whose deps are
+ *  6.9 GiB of an 8.3 GiB archived set, five gigabytes were held for an archive
+ *  of about one, and every attach was refused with 6.7 GiB free. */
 export const SNAPSHOT_STAGING_RATIO = 0.6;
 
 /** The fixed floor under the staging term: at least 1 GiB, or 5 % of the disk
@@ -173,13 +183,26 @@ export interface DiskReserve {
   totalKiB: number;
 }
 
+/** What the reserve knows beyond the sample: whether a deps-store entry
+ *  backup is being taken right now (item 61), whose archive is staged from
+ *  the deps and so needs their share of the ratio while it runs. */
+export interface DiskReserveInput {
+  depsBackupInFlight?: boolean;
+}
+
 /** `staging + floor`. Staging is computed from the MEASURED mirror and
- *  checkout (deps + rest); an unmeasured part counts as 0 there — the floor
- *  still stands, and `projectThreadCostKiB` refuses to project from missing
- *  parts, so an unmeasured resident never admits on a guess. */
-export function diskReserveKiB(sample: Pick<DiskSample, "totalKiB" | "parts">): DiskReserve {
-  const archived = (sample.parts.mirror ?? 0) + (sample.parts.deps ?? 0) + (sample.parts.checkout ?? 0);
-  const stagingKiB = Math.round(archived * SNAPSHOT_STAGING_RATIO);
+ *  checkout (the checkout's own bytes: history + tree + build output, never
+ *  the deps, which the checkout archive excludes), plus the deps while a
+ *  deps-store entry backup is in flight; an unmeasured part counts as 0 there
+ *  — the floor still stands, and `projectThreadCostKiB` refuses to project
+ *  from missing parts, so an unmeasured resident never admits on a guess. */
+export function diskReserveKiB(
+  sample: Pick<DiskSample, "totalKiB" | "parts">,
+  input: DiskReserveInput = {},
+): DiskReserve {
+  const staged = (sample.parts.mirror ?? 0) + (sample.parts.checkout ?? 0);
+  const depsStaged = input.depsBackupInFlight ? (sample.parts.deps ?? 0) : 0;
+  const stagingKiB = Math.round((staged + depsStaged) * SNAPSHOT_STAGING_RATIO);
   const floorKiB = Math.max(DISK_FLOOR_MIN_KIB, Math.round(sample.totalKiB * DISK_FLOOR_FRACTION));
   return { stagingKiB, floorKiB, totalKiB: stagingKiB + floorKiB };
 }
@@ -261,11 +284,14 @@ export function checkDiskAdmission(input: {
   committedKiB?: number;
   diskBudgetMb?: number;
   kind: ThreadCostKind;
+  /** A deps-store entry backup is in flight: its archive is staged from the
+   *  deps, so the reserve holds their share for as long as it runs. */
+  depsBackupInFlight?: boolean;
 }): AdmissionVerdict {
   const rawFree = Math.max(0, (input.freeKiB ?? input.sample.freeKiB) - (input.committedKiB ?? 0));
   const live = { ...input.sample, freeKiB: rawFree, usedKiB: input.sample.totalKiB - rawFree };
   const { capacityKiB, freeKiB, capped } = effectiveFreeKiB(live, input.diskBudgetMb);
-  const reserve = diskReserveKiB(input.sample);
+  const reserve = diskReserveKiB(input.sample, { depsBackupInFlight: input.depsBackupInFlight });
   const projectedKiB = projectThreadCostKiB(input.sample.parts, input.kind);
   const headroomKiB = freeKiB - reserve.totalKiB - (projectedKiB ?? 0);
   const math: AdmissionMath = { projectedKiB, kind: input.kind, freeKiB, capacityKiB, capped, reserve, headroomKiB };
@@ -401,6 +427,9 @@ export function diskPressureReason(input: {
   verdict: Extract<AdmissionVerdict, { fits: false }>;
   evicted: ReadonlyArray<{ freedKiB: number | null }>;
   kept: ReadonlyArray<{ why: DiskKeepWhy }>;
+  /** Deps-store spares removed first under the pressure (item 55), with the
+   *  bytes each gave back. */
+  spares?: ReadonlyArray<{ freedKiB: number }>;
 }): string {
   const { math } = input.verdict;
   const need =
@@ -412,10 +441,15 @@ export function diskPressureReason(input: {
     `${DISK_PRESSURE_REASON}: need ${need}, but ${formatGiB(math.freeKiB)} free${cap} minus the ${formatGiB(math.reserve.totalKiB)} reserve ` +
       `(snapshot staging ${formatGiB(math.reserve.stagingKiB)} + floor ${formatGiB(math.reserve.floorKiB)}) leaves ${formatGiB(Math.max(0, math.freeKiB - math.reserve.totalKiB))} — short by ${formatGiB(input.verdict.shortfallKiB)}`,
   ];
+  const spares = input.spares ?? [];
+  if (spares.length > 0) {
+    const freed = spares.reduce((a, e) => a + e.freedKiB, 0);
+    parts.push(`evicted ${spares.length} deps-store spare(s) (${formatGiB(freed)} back)`);
+  }
   if (input.evicted.length > 0) {
     const freed = input.evicted.reduce((a, e) => a + (e.freedKiB ?? 0), 0);
     parts.push(`evicted ${input.evicted.length} idle tree(s) (${formatGiB(freed)} back)`);
-  } else parts.push("evicted nothing");
+  } else parts.push(spares.length > 0 ? "evicted no idle tree" : "evicted nothing");
   if (input.kept.length > 0) {
     const counts = new Map<DiskKeepWhy, number>();
     for (const k of input.kept) counts.set(k.why, (counts.get(k.why) ?? 0) + 1);

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

@@ -42,19 +42,45 @@ export function wantShaForBinding(input: {
   return input.wantSha;
 }
 
-/** Whether the attach must fetch the mirror before cloning the thread tree.
- *  - the ref is not in the mirror → fetch (the only pre-existing rule);
+/** Why the attach fetches the mirror before cloning the thread tree. The
+ *  Worker treats the three differently when the fetch fails: a `missing-ref`
+ *  or `stale-tip` fetch that fails fails the attach, as it always did; a
+ *  `returnable-ref` fetch only verifies a ref the mirror holds, so its
+ *  failure is one log line and the attach goes on with the mirror's ref. */
+export type FetchReason = "missing-ref" | "stale-tip" | "returnable-ref";
+
+/** Whether — and why — the attach must fetch the mirror before cloning the
+ *  thread tree; null when the mirror is good enough as it stands.
+ *  - the ref is not in the mirror → `missing-ref` (the oldest rule);
  *  - a `wantSha` was named and the mirror's tip of the ref is not that
- *    commit → fetch;
- *  - otherwise the mirror is good enough as it stands.
+ *    commit → `stale-tip`;
+ *  - the bound ref is one the binding could return from — a branch a rebind
+ *    moved it onto, or one the thread's own runs pushed (`canReturnToDefault`,
+ *    resident-repos.md item 16) → `returnable-ref`: such a branch dies when
+ *    its pull request merges, and the deletion reaches the mirror only through
+ *    a `fetch --prune`. Trusting the mirror because it still holds the ref
+ *    would provision a tree at the deleted branch's stale tip until the
+ *    refresh cycle's prune caught up — whether the thread returned to the
+ *    default would depend on where in the cycle its follow-up landed. So the
+ *    ref is verified against the origin at every attach, and the return is
+ *    decided at the first attach after the deletion. The default cannot be
+ *    lost and a ref a person named that the thread never pushed has no way
+ *    back, so neither pays this fetch: the refresh cycle is their freshness.
+ *  - otherwise null.
  *  A fetch that STILL leaves the tip elsewhere (a push racing this attach, or
  *  a force-push) is not this function's concern: the attach proceeds on the
  *  fetched tip and reports it, and the reviewed-head guard decides what a
  *  review of it may do. */
-export function mirrorNeedsFetch(input: { refExists: boolean; mirrorSha?: string; wantSha: string | null }): boolean {
-  if (!input.refExists) return true;
-  if (input.wantSha === null) return false;
-  return input.mirrorSha !== input.wantSha;
+export function mirrorFetchReason(input: {
+  refExists: boolean;
+  mirrorSha?: string;
+  wantSha: string | null;
+  returnable: boolean;
+}): FetchReason | null {
+  if (!input.refExists) return "missing-ref";
+  if (input.wantSha !== null && input.mirrorSha !== input.wantSha) return "stale-tip";
+  if (input.returnable) return "returnable-ref";
+  return null;
 }
 
 /** What the attach checks out, once the mirror is as fresh as it will get. */

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

@@ -35,15 +35,21 @@
  *  Every refusal is named in the attach answer so the bot can say why the
  *  follow-up runs where it does.
  *
- *  The second movement: a rebound binding names a branch that can die — the
- *  pull request merges and the branch is deleted. A binding left on it would
- *  fail every later attach (`unknown-ref`) for the thread's whole life. So a
- *  binding a rebind moved, whose branch the mirror no longer holds after a
- *  fetch, goes back to the default it was bound to (`canReturnToDefault`,
- *  `returnToDefault`); the attach provisions the tree there, clean, and the
- *  thread is default-bound again, so a later own pull request may move it once
- *  more. A ref a person named that vanished keeps the `unknown-ref` refusal:
- *  that branch is the person's to sort out. */
+ *  The second movement: a binding can sit on a branch that dies — the pull
+ *  request merges and the branch is deleted. A binding left on it would fail
+ *  every later attach (`unknown-ref`) for the thread's whole life. So a
+ *  binding whose ref the mirror no longer holds after a fetch goes back to the
+ *  default (`canReturnToDefault`, `returnToDefault`) when the gone ref is
+ *  EITHER the branch a rebind moved it onto OR one of the thread's own
+ *  branches — a branch this thread's runs pushed (`ownBranches`), whatever
+ *  `boundBy` says: a ship unit's coding child binds its unit branch by name,
+ *  pushes it and opens the pull request, and the unit's merge deletes it. The
+ *  attach provisions the tree at the default, clean, and the thread is
+ *  default-bound again (`boundBy: default` — the default was chosen for want
+ *  of the branch it was on), so a later own pull request may move it once
+ *  more. A ref a person named that the thread never pushed keeps the
+ *  `unknown-ref` refusal: a person's branch that is gone is not this thread's
+ *  finished work, and the resident never swaps it for the default unasked. */
 
 /** The pull request the thread's own run opened, and its head branch — the
  *  reason a caller's refHint is that branch. */
@@ -136,9 +142,15 @@ export function rememberOwnBranches(
   return [...kept, ...added].slice(-OWN_BRANCHES_MAX);
 }
 
+/** The binding's memory of `ref` as a branch the thread's own runs pushed —
+ *  the pull request it heads and when it was told — or none. */
+export function ownBranchOf(binding: { ownBranches?: readonly OwnBranch[] }, ref: string): OwnBranch | undefined {
+  return (binding.ownBranches ?? []).find((b) => b.ref === ref);
+}
+
 /** 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);
+  return ownBranchOf(binding, ref) !== undefined;
 }
 
 /** How a binding's ref was chosen: the repo default for want of a named
@@ -171,8 +183,12 @@ export interface Rebound {
   returnedAt?: string;
 }
 
-/** The move back, in the attach answer: from the branch that is gone, to the
- *  default, for the pull request whose branch it was, when. */
+/** The move back (the second movement), on the binding and in the attach
+ *  answer: from the branch that is gone, to the default, for the pull request
+ *  whose branch it was — the rebind's, or the one the binding remembers the
+ *  branch heading — when. On the binding it is the LAST move back: a rebind's
+ *  own record keeps its `returnedAt` beside it, and a binding never rebound
+ *  (its unit branch bound by name and pushed) has only this. */
 export interface Returned {
   from: string;
   to: string;
@@ -199,6 +215,8 @@ export interface RebindableBinding {
   evicted?: boolean;
   boundBy?: BoundBy;
   rebound?: Rebound;
+  /** The binding's last move back to the default (the second movement). */
+  returned?: Returned;
   /** The branches the thread's own runs pushed, handed over at each release. */
   ownBranches?: OwnBranch[];
 }
@@ -320,29 +338,68 @@ export function rebindVerdict(plan: { to: string; pr: number; own?: boolean }, t
   return { kind: "rebind" };
 }
 
-/** Whether a binding whose ref the mirror no longer holds goes back to the
- *  default branch (the second movement): only a binding a rebind moved onto
- *  its own pull request's branch — bound by default in the first place, still
- *  on that branch, the move not yet returned. Anything else keeps the
- *  attach's `unknown-ref` refusal: a ref a person named is that person's to
- *  sort out, and a binding on the default cannot lose its ref. */
-export function canReturnToDefault(
-  binding: { ref: string; boundBy?: BoundBy; rebound?: Rebound },
+/** What the second movement reads off a binding. */
+export type ReturnableBinding = Pick<RebindableBinding, "ref" | "boundBy" | "rebound" | "ownBranches">;
+
+/** The way back a binding whose ref is gone may take, if any — the one place
+ *  the second movement is decided, so the predicate and the move cannot
+ *  disagree: `rebind` — a rebind moved the binding onto the branch (bound by
+ *  default in the first place, still on that branch, the move not yet
+ *  returned); `own` — the branch is one this thread's own runs pushed, as the
+ *  binding remembers it, whatever `boundBy` says. A binding on the default
+ *  cannot lose its ref, and a ref a person named that the thread never pushed
+ *  has no way back: that branch is the person's to sort out. */
+function wayBack(
+  binding: ReturnableBinding,
   defaultRef: string,
-): boolean {
+): { kind: "rebind"; rebound: Rebound } | { kind: "own"; branch: OwnBranch } | undefined {
+  if (binding.ref === defaultRef) return undefined;
   const r = binding.rebound;
-  if (r === undefined || r.returnedAt !== undefined || binding.ref !== r.to) return false;
-  return binding.ref !== defaultRef && boundByOf(binding, defaultRef) === "default";
+  if (
+    r !== undefined &&
+    r.returnedAt === undefined &&
+    binding.ref === r.to &&
+    boundByOf(binding, defaultRef) === "default"
+  ) {
+    return { kind: "rebind", rebound: r };
+  }
+  const branch = ownBranchOf(binding, binding.ref);
+  return branch === undefined ? undefined : { kind: "own", branch };
+}
+
+/** Whether a binding whose ref the mirror no longer holds goes back to the
+ *  default branch (the second movement): a binding a rebind moved onto its
+ *  own pull request's branch, or one on a branch this thread itself pushed.
+ *  Anything else keeps the attach's `unknown-ref` refusal. */
+export function canReturnToDefault(binding: ReturnableBinding, defaultRef: string): boolean {
+  return wayBack(binding, defaultRef) !== undefined;
 }
 
-/** The move back: the binding's ref becomes the default and the move that
- *  brought it here is stamped returned, so the thread may move again. Only
- *  ever applied to a binding `canReturnToDefault` admitted. */
-export function returnToDefault<B extends { ref: string; rebound?: Rebound }>(
-  binding: B & { rebound: Rebound },
+/** The move back: the binding's ref becomes the default, the binding reads as
+ *  bound by default (the default was chosen for want of the branch it was on,
+ *  so its next own pull request may move it — a binding that named its unit
+ *  branch included), a rebind's move is stamped returned, and the last move
+ *  back is recorded. The pull request named is the rebind's, else the one the
+ *  binding remembers the gone branch heading. Undefined for a binding
+ *  `canReturnToDefault` does not admit: nothing to write. */
+export function returnToDefault<B extends ReturnableBinding>(
+  binding: B,
   defaultRef: string,
   at: string,
-): { binding: B; returned: Returned } {
-  const returned: Returned = { from: binding.ref, to: defaultRef, pr: binding.rebound.pr, at };
-  return { binding: { ...binding, ref: defaultRef, rebound: { ...binding.rebound, returnedAt: at } }, returned };
+): { binding: B; returned: Returned } | undefined {
+  const way = wayBack(binding, defaultRef);
+  if (way === undefined) return undefined;
+  const pr = way.kind === "rebind" ? way.rebound.pr : way.branch.pr;
+  const returned: Returned = { from: binding.ref, to: defaultRef, pr, at };
+  const rebound = way.kind === "rebind" ? { ...way.rebound, returnedAt: at } : binding.rebound;
+  return {
+    binding: {
+      ...binding,
+      ref: defaultRef,
+      boundBy: "default",
+      ...(rebound !== undefined ? { rebound } : {}),
+      returned,
+    },
+    returned,
+  };
 }

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/sandboxLifecycle.ts

@@ -76,3 +76,36 @@ export function recycledMidCommandMessage(elapsedMs: number, msg: string, certai
     `check /workspace before continuing: it is empty if the container was replaced (re-clone), intact if only its runtime restarted (${msg})`
   );
 }
+
+/** The redirects a detached job's wrapper must carry so the command that
+ *  forked it owns none of its descriptors — the same string the harness seam
+ *  uses for its own start (`DETACHED_STDIO` in src/core/harness/container.ts;
+ *  a test holds the two equal). Without them the runtime waits for an end of
+ *  output the detached child never gives (item 24). */
+export const DETACH_REDIRECTS = "</dev/null >/dev/null 2>&1";
+
+/** The way a command detaches a job that must outlive it, as the exit-124
+ *  hint and the docs spell it: the job's own output into a file, the
+ *  wrapper's stdio to /dev/null. */
+export const DETACH_HINT = `setsid -f sh -c '<command> > /tmp/job.log 2>&1' ${DETACH_REDIRECTS}`;
+
+/** How long past the process's exit the Durable Object waits for its output
+ *  stream to end before it answers with the exit code alone. The runtime
+ *  reports the stream's end only when every holder of the command's stdout
+ *  and stderr is gone; a detached child that inherited them holds it open
+ *  for its own lifetime. Twenty seconds covers coreutils `timeout -k 10`'s
+ *  SIGKILL follow-up and the runtime's teardown, and stays inside the
+ *  executor's per-send margin (EXEC_CALL_MARGIN_MS, 30 s) so this answer
+ *  reaches the bot before it gives the command up. */
+export const OUTPUT_AFTER_EXIT_MS = 20_000;
+
+/** The stderr line an exec answers with when its process exited but its
+ *  output never ended: what happened, why the output is missing, and how to
+ *  detach a job so it does not happen again. */
+export function heldOutputNote(exitCode: number): string {
+  return (
+    `the command exited (code ${exitCode}) but its output could not be collected: a process it started still holds its stdout or stderr open ` +
+    `(a background job started without redirecting the wrapper's own stdio); its output is lost to this call, the job itself is still running — ` +
+    `detach with \`${DETACH_HINT}\` so the command's descriptors close when it does`
+  );
+}

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;
+      });
+  }
+}