@coreplane/switchboard 1.235.0 → 1.236.0

package/dist/assets/Dockerfile

@@ -87,6 +87,17 @@ RUN npm install -g @earendil-works/pi-coding-agent@0.85.1 \
   && pi --version | grep -qx '0.85.1' \
   && pi --help | grep -q -- '--mode <mode>'
 
+# OpenCode, the second harness (docs/reference/specs/harness.md): `@opencode/cli`
+# at the EXACT pin held by src/deploy/imageOpenCodeHarness.test.ts, beside pi.
+# The wrapper's postinstall hard-links the platform binary into place, so it
+# is the one install script allowed by name; the grep proves the binary on
+# PATH prints the pin's version text (`opencode v2.0.3`, exactly); the npm
+# cache (a 200 MB tarball) is dropped in the same layer. Dark until a
+# deployment names it: nothing here starts it on its own.
+RUN npm install -g --allow-scripts=@opencode/cli @opencode/cli@2.0.3 \
+  && npm cache clean --force \
+  && opencode --version | grep -qx 'opencode v2.0.3'
+
 # Non-root user; agents run bash with this user's (container-scoped) permissions.
 RUN useradd -m -u 1001 switchboard
 WORKDIR /app

package/dist/assets/config/config.example.yaml

@@ -311,10 +311,15 @@ workspaceDir: ./workspaces
 # them the request is refused naming what is missing. Per unit: at most
 # `maxRounds` review rounds and `maxMinutes` minutes of wall clock — whichever
 # hits first ends the unit, and each child round's own budget is clipped to the
-# remaining time. `maxMinutes` is the ship preset's declared budget: a channel or
-# user `boundary.maxMinutes` and a per-message `budget:` directive clip it like
-# any preset's, and the card says so. Defaults shown; both must be integers >= 1;
-# any other key under `ship` fails the load by name.
+# remaining time. The pipeline is budgeted for the loop, not one round: the
+# coding child's directive is additionally capped to leave two review rounds and
+# one merge poll (11 minutes) on the clock, so a child that uses its whole
+# budget still hands the review its time — which is why `maxMinutes` must be an
+# integer >= 14 (the loop's reserve plus one round). `maxMinutes` is the ship
+# preset's declared budget: a channel or user `boundary.maxMinutes` and a
+# per-message `budget:` directive clip it like any preset's, and the card says
+# so. Defaults shown; `maxRounds` must be an integer >= 1; any other key under
+# `ship` fails the load by name.
 # ship:
 #   maxRounds: 3      # review rounds per unit
 #   maxMinutes: 120   # the ship preset's wall-clock budget in minutes (the registry's default)

package/dist/assets/deploy/cloudflare-memory/worker.ts

@@ -1807,6 +1807,18 @@ export class RunHistoryDO extends DurableObject<Env> {
     this.ctx.storage.transactionSync(() => {
       result = this.upsertInTransaction(record, proposal);
     });
+    // A coordinator child closed OUTSIDE the ledger's finish — the run loop or
+    // a reclaim writing an `interrupted` record, the pi harness's typed restart,
+    // a resume abandoning a lost workspace — still wakes its parent's wait at
+    // once (run-history item 47): the same `run-finished-<runId>` event rides
+    // this commit. The tombstone a run writes at its start is excluded (its
+    // `finishedAt` equals `startedAt`); the parent confirms by `read-record`
+    // before it acts, so a duplicate send is harmless.
+    if (result.stored && record.parentInstanceId !== undefined && record.finishedAt > record.startedAt) {
+      const event = await sendRunFinished(this.env.SHIP_COORDINATOR, record);
+      if (event.kind === "failed")
+        console.warn(`[runs/put] ${record.id} → ${event.type} not delivered to ${event.instance}: ${event.reason}`);
+    }
     if ((await this.ctx.storage.getAlarm()) === null)
       await this.ctx.storage.setAlarm(systemClock() + RUN_SWEEP_INTERVAL_MS);
     return result;

package/dist/assets/deploy/cloudflare-resident/Dockerfile

@@ -201,6 +201,18 @@ RUN npm install -g @earendil-works/pi-coding-agent@0.85.1 \
   && pi --version | grep -qx '0.85.1' \
   && pi --help | grep -q -- '--mode <mode>'
 
+# OpenCode, the second harness (docs/reference/specs/harness.md): `@opencode/cli`
+# at the EXACT pin held by src/deploy/imageOpenCodeHarness.test.ts, beside pi.
+# The wrapper's postinstall hard-links the platform binary into place, so it
+# is the one install script allowed by name; the grep proves the binary on
+# PATH prints the pin's version text (`opencode v2.0.3`, exactly); the npm
+# cache (a 200 MB tarball) is dropped in the same layer, and the proof runs
+# again as worker1 below. Dark until a deployment names it: nothing here
+# starts it on its own.
+RUN npm install -g --allow-scripts=@opencode/cli @opencode/cli@2.0.3 \
+  && npm cache clean --force \
+  && opencode --version | grep -qx 'opencode v2.0.3'
+
 # Agent commands never run as root (repo code runs unprivileged, one user per
 # thread — docs/reference/specs/resident-repos.md). The SDK's exec has no user/uid option
 # (verified against 0.13.0-next.751.1), so the container server itself runs as
@@ -230,6 +242,12 @@ RUN su -s /bin/bash worker1 -c "playwright screenshot --viewport-size=640,480 'd
 # own, named by PI_CODING_AGENT_DIR at start).
 RUN su -s /bin/bash worker1 -c "pi --version | grep -qx '0.85.1'"
 
+# OpenCode once more, as worker1: a run's server is started as the thread's
+# user through the same `su`, so the BUILD proves an unprivileged user finds
+# the pin on PATH and the binary runs without a writable home (its roots are
+# the run's own, named by the XDG variables at start).
+RUN su -s /bin/bash worker1 -c "opencode --version | grep -qx 'opencode v2.0.3'"
+
 # bun once more, as worker1: a thread's `bun install` runs as the thread's user
 # through the same `su`, whose PATH is /etc/environment's rather than this
 # file's — so the BUILD proves that PATH resolves the pin, not the base's bun.

package/dist/assets/deploy/cloudflare-resident/worker.ts

@@ -505,16 +505,18 @@ const FORCE_DETACH_KILL_TIMEOUT_MS = 2_000;
  *  binding record is KEPT so the next attach recreates with the same
  *  ref. Overridable per resident via the onboard-time `worktreeTtlDays`. */
 const WORKTREE_TTL_DAYS_DEFAULT = 7;
-/** A live binding whose last attach is older than this AND whose tree is clean
- *  (no uncommitted/unpushed work) is released by the sweep step (every refresh
- *  instance runs one) — runs that ended before /detach existed, or whose
- *  release call was lost. Dirty trees keep to the TTL. */
+/** A live binding whose last attach is older than this and has no op in
+ *  flight is released by the sweep step (every refresh instance runs one),
+ *  whatever its tree holds (item 17) — runs that ended before /detach existed,
+ *  or whose release call was lost. */
 const CLEAN_IDLE_RELEASE_S = 60 * 60;
-/** Idle sleep: when no thread has attached within this window and no live
- *  tree is dirty, the refresh cycle skips the fetch and the cron holds the
- *  next instance to the idle cadence, so the container can actually sleep
- *  (SLEEP_AFTER); the next attach refreshes first if the mirror is stale
- *  (refresh-on-attach). */
+/** Idle sleep: when no live binding was attached to or used within this
+ *  window and nothing is in flight, the refresh cycle skips the fetch and the
+ *  cron holds the next instance to the idle cadence, so the container can
+ *  actually sleep (SLEEP_AFTER); the next attach refreshes first if the mirror
+ *  is stale (refresh-on-attach). The disk-full recycle (item 54) reads the
+ *  same window through the same predicate (`recentlyUsed`): a sleep and a
+ *  recycle destroy the same disk, so one rule says when it may go away. */
 const IDLE_AFTER_S = 60 * 60;
 /** LRU eviction floor: an over-cap onboard with `evictColdest:true` may
  *  offboard the coldest eligible warm resident, but never one whose last
@@ -1037,6 +1039,15 @@ interface ThreadBinding {
   /** Why the tree could not be measured before that eviction (git could not
    *  read it) — so an unreadable tree is never recorded as clean. */
   evictedUnmeasured?: string;
+  /** What the tree held when the last disk-full recycle (item 54) discarded
+   *  it with the disk — the same measurement as `evictedLeftBehind`, under its
+   *  own name because the binding is not evicted: its user is kept and the
+   *  next attach recreates the tree (`worktree-missing`). Both rewritten on
+   *  every recycle; absent when the tree was clean or already gone. */
+  recycledLeftBehind?: LeftBehind;
+  /** Why the tree could not be measured before that recycle (git could not
+   *  read it) — still discarded with the disk, never recorded as clean. */
+  recycledUnmeasured?: string;
   /** How deps were last materialized (evidence that the per-branch reconciliation ran). */
   deps?: ThreadDepsMechanism;
   /** Commit the worktree was last attached at (the ref's tip in the mirror
@@ -2945,12 +2956,11 @@ export class ResidentDO extends Sandbox<Env> {
       throw new CycleRestartError("image-stale-restart");
     }
 
-    // Idle sleep: nobody has attached for IDLE_AFTER_S and no live tree is
-    // dirty → skip this fetch; the cron holds the next instance to the idle
+    // Idle sleep: no live binding used within IDLE_AFTER_S and nothing in
+    // flight → skip this fetch; the cron holds the next instance to the idle
     // cadence, so SLEEP_AFTER can elapse. Staleness is repaid at the next
-    // attach (refreshIfStale). A
-    // dirty live tree pins the container awake: sleep destroys the disk and
-    // uncommitted work is not snapshotted.
+    // attach (refreshIfStale). What a live tree holds is not asked (item 17):
+    // sleep destroys the disk, and a tree no run is using protects nothing.
     // Only a SETTLED resident may park: a cycle that finds `refreshing`/
     // `restoring` at entry is looking at a marker left by a cycle that died
     // mid-flight (a deploy evicting the DO: stuck `refreshing` + parked →
@@ -3002,7 +3012,7 @@ export class ResidentDO extends Sandbox<Env> {
       await this.ctx.storage.delete(DEGRADED_STREAK_KEY);
     }
     if (settled && (await this.isIdle())) {
-      // isIdle awaited (git status per live tree) — re-read before writing.
+      // isIdle awaited (the bindings listing) — re-read before writing.
       const now = (await this.ctx.storage.get<RepoFacts>(FACTS_KEY)) ?? facts;
       if (!now.idleSince)
         await this.ctx.storage.put(FACTS_KEY, {
@@ -3798,15 +3808,24 @@ export class ResidentDO extends Sandbox<Env> {
     });
   }
 
-  /** Idle = no live binding attached within IDLE_AFTER_S and nothing in
-   *  flight. What a live tree holds is not asked (item 17): a dirty tree no
-   *  run is using protects nothing — the next attach wipes it — so it is
-   *  never a reason to keep the container awake; the sweep's release records
-   *  what it held. Bindings are storage, so this needs no container. */
-  private async isIdle(): Promise<boolean> {
-    const live = await this.liveBindings();
+  /** Whether a run may be using this disk: a live binding attached to or
+   *  used (an exec bumps `lastAttachAt` too, item 21) within IDLE_AFTER_S.
+   *  The op counter is 0 between a run's tool calls, so this floor is what
+   *  stands for a run mid-flight. The one predicate behind "the disk may go
+   *  away": the idle-sleep gate (item 16b — a platform sleep destroys the
+   *  disk) and the disk-full recycle (item 54) both read it, and neither asks
+   *  what a tree holds (item 17): a dirty tree no run is using protects
+   *  nothing — the next attach wipes it. Bindings are storage, so this needs
+   *  no container. */
+  private recentlyUsed(live: ThreadBinding[]): boolean {
     const recent = systemClock() - IDLE_AFTER_S * 1000;
-    if (live.some((b) => Date.parse(b.lastAttachAt) >= recent)) return false;
+    return live.some((b) => Date.parse(b.lastAttachAt) >= recent);
+  }
+
+  /** Idle = no live binding used within the floor and nothing in flight; the
+   *  sweep's release records what an idle tree held. */
+  private async isIdle(): Promise<boolean> {
+    if (this.recentlyUsed(await this.liveBindings())) return false;
     return this.inFlightCount() === 0;
   }
 
@@ -3816,17 +3835,6 @@ export class ResidentDO extends Sandbox<Env> {
     return [...all.values()].filter((b) => !b.evicted && b.user);
   }
 
-  /** The disk-full recycle's tree guard (item 54), its one reader: true when
-   *  every live tree is clean as its thread user, or the runtime is already
-   *  down — a sleep has destroyed the disk, so there is nothing left to lose. */
-  private async liveTreesClean(live: ThreadBinding[]): Promise<boolean> {
-    if (!(await this.isRuntimeActive().catch(() => false))) return true;
-    // Concurrent: each check touches only its own (disjoint) tree, and one
-    // spawn each — no serial 3-probe round-trip per live binding.
-    const checks = await Promise.all(live.map((b) => this.worktreeCleanliness(b)));
-    return checks.every((c) => c.clean); // any dirty or unknown → not clean
-  }
-
   // -- disk-full (docs/reference/specs/resident-repos.md item 54) ---------------------------
 
   /** Free space on the workspace mount in KiB; `null` when df cannot answer.
@@ -3852,28 +3860,54 @@ export class ResidentDO extends Sandbox<Env> {
 
   /** The disk is a cache: stop the container so the next cycle attempt
    *  restores mirror + checkout from R2 onto an empty disk — the same wake
-   *  path as a platform sleep. Only when the pure plan allows it: nothing in
-   *  flight (`selfInFlight` excludes the calling refresh cycle from the
-   *  count), every live tree clean, and no recycle within the cooldown. A
-   *  refused recycle is written to `lastRefreshError` with its why, so
-   *  `/residents` says what an operator must do; the `degraded` reason stays
-   *  the clean `disk-full: …`. Answers whether the container was recycled. */
+   *  path as a platform sleep. Only when the pure plan allows it: no recycle
+   *  within the cooldown, nothing in flight (`selfInFlight` excludes the
+   *  calling refresh cycle from the count) and no live binding used within
+   *  the idle floor — the idle-sleep gate's own predicate (`recentlyUsed`),
+   *  because a sleep and a recycle destroy the same disk: it may go away when
+   *  no run is using it, never for what the trees hold (item 17). A recycle
+   *  discards every live tree the way an eviction does, so each is measured
+   *  first, as its thread user, and its binding records what went
+   *  (`recordRecycledTree`); the plan is decided again after those awaits,
+   *  right before the stop. A refused recycle is written to
+   *  `lastRefreshError` with its why, so `/residents` says what an operator
+   *  must do; the `degraded` reason stays the clean `disk-full: …`. Answers
+   *  whether the container was recycled. */
   private async recoverFromDiskFull(reason: string, selfInFlight: number): Promise<boolean> {
     const lastRecycleAt = await this.ctx.storage.get<number>(DISK_FULL_RECYCLE_KEY);
-    const plan = planDiskFullRecovery({
-      now: systemClock(),
-      lastRecycleAt,
-      inFlight: this.inFlightCount() - selfInFlight,
-      treesClean: await this.liveTreesClean(await this.liveBindings()),
-    });
-    if (plan.action === "wait") {
-      console.log(`disk-full: container kept — ${plan.why}`);
-      await this.recordRefreshError(`${reason} — container kept: ${plan.why}`);
+    const plan = (live: ThreadBinding[]) =>
+      planDiskFullRecovery({
+        now: systemClock(),
+        lastRecycleAt,
+        inFlight: this.inFlightCount() - selfInFlight,
+        recentlyUsed: this.recentlyUsed(live),
+        idleFloorS: IDLE_AFTER_S,
+      });
+    const kept = async (why: string) => {
+      console.log(`disk-full: container kept — ${why}`);
+      await this.recordRefreshError(`${reason} — container kept: ${why}`);
       return false;
-    }
+    };
+    const live = await this.liveBindings();
+    const first = plan(live);
+    if (first.action === "wait") return kept(first.why);
+    // What each live tree holds, for its record — never a reason to keep the
+    // container. Concurrent: each probe touches only its own tree, one spawn
+    // each. Runtime down: the disk, and every tree with it, is already gone.
+    const active = await this.isRuntimeActive().catch(() => false);
+    const trees = active
+      ? await Promise.all(
+          live.map(async (binding) => [binding, await this.measureTreeBeforeEviction(binding)] as const),
+        )
+      : live.map((binding) => [binding, undefined] as const);
+    // The measurement awaited (the DO yields at each await): decide again over
+    // fresh facts — an attach or an op that landed meanwhile keeps the container.
+    const verdict = plan(await this.liveBindings());
+    if (verdict.action === "wait") return kept(verdict.why);
     console.log(
       `disk-full: recycling the container — the next cycle restores mirror + checkout from R2 onto an empty disk (${reason})`,
     );
+    for (const [binding, tree] of trees) await this.recordRecycledTree(binding, tree);
     await this.ctx.storage.put(DISK_FULL_RECYCLE_KEY, systemClock());
     await this.recordRefreshError(`${reason} — container recycled; restoring from R2 on the next cycle`);
     this.swapIncarnation(); // deliberate incarnation swap
@@ -3881,6 +3915,27 @@ export class ResidentDO extends Sandbox<Env> {
     return true;
   }
 
+  /** The disk-full recycle's record for one live tree (item 54), written the
+   *  way `evictBinding` writes an eviction's — but the binding stays live, its
+   *  pool user kept and its tree recreated on the next attach, so this is not
+   *  an eviction and the record sits under its own name beside
+   *  `evictedLeftBehind`: the counts when something was there, the probe's
+   *  first error line when git could not read the tree, both rewritten on
+   *  every recycle so nothing lingers from an earlier one, and one log line
+   *  when the tree held something. Re-read first: a binding evicted or
+   *  re-attached during the measurement is left as is. */
+  private async recordRecycledTree(binding: ThreadBinding, tree: EvictedTree | undefined): Promise<void> {
+    const now = await this.ctx.storage.get<ThreadBinding>(threadBindingKey(binding.threadKey));
+    if (!now || now.evicted || now.lastAttachAt !== binding.lastAttachAt) return;
+    await this.ctx.storage.put(threadBindingKey(binding.threadKey), {
+      ...now,
+      recycledLeftBehind: tree && "leftBehind" in tree ? tree.leftBehind : undefined,
+      recycledUnmeasured: tree && "unmeasured" in tree ? tree.unmeasured : undefined,
+    } satisfies ThreadBinding);
+    if (tree)
+      console.log(`disk-full: ${binding.threadKey} tree discarded with the disk — ${evictedTreeSentence(tree)}`);
+  }
+
   // -- disk budget (docs/reference/specs/resident-repos.md item 55) -------------------------
 
   /** The `df` half: total/used/free of the workspace mount; null when df
@@ -6202,11 +6257,10 @@ export class ResidentDO extends Sandbox<Env> {
    *  (su), never as root: the worktree is thread-owned, so root git in it
    *  would be refused by safe.directory and would be the exact repo-local-
    *  config execution vector safe.directory exists to block. Read by
-   *  `measureTreeBeforeEviction` for the eviction's record — never a reason
-   *  to keep a tree (item 17) — and by the disk-full recycle's guard (item
-   *  54), where unknown (git failed) counts as NOT clean. A tree that no
-   *  longer exists (disk recycled by a sleep/wake) is clean with nothing
-   *  measured: there was nothing to discard.
+   *  `measureTreeBeforeEviction` alone, for the record of an eviction or of
+   *  the disk-full recycle — never a reason to keep a tree or a container
+   *  (item 17). A tree that no longer exists (disk recycled by a sleep/wake)
+   *  is clean with nothing measured: there was nothing to discard.
    *
    *  ONE spawn: the presence test and both git probes fold
    *  into the pure `worktreeCleanlinessScript` (test -d as root, both git
@@ -6222,7 +6276,8 @@ export class ResidentDO extends Sandbox<Env> {
     return parseWorktreeCleanliness(r);
   }
 
-  /** What a tree holds right before its eviction, for the record and the log
+  /** What a tree holds right before its eviction — or before the disk-full
+   *  recycle discards it with the disk (item 54) — for the record and the log
    *  (item 17): the one-spawn probe as the thread user, read once into
    *  `evictedTreeOf` — never into a keep decision. Callers skip it when the
    *  runtime is down: the disk, and the tree with it, is already gone. */
@@ -6782,6 +6837,8 @@ export class ResidentDO extends Sandbox<Env> {
           evictedWhy,
           evictedLeftBehind,
           evictedUnmeasured,
+          recycledLeftBehind,
+          recycledUnmeasured,
         }) => ({
           threadKey,
           ref,
@@ -6795,6 +6852,8 @@ export class ResidentDO extends Sandbox<Env> {
           evictedWhy: evictedWhy ?? null,
           evictedLeftBehind: evictedLeftBehind ?? null,
           evictedUnmeasured: evictedUnmeasured ?? null,
+          recycledLeftBehind: recycledLeftBehind ?? null,
+          recycledUnmeasured: recycledUnmeasured ?? null,
         }),
       );
     return {

package/dist/assets/deploy/cloudflare-sandbox/Dockerfile

@@ -176,6 +176,17 @@ RUN npm install -g @earendil-works/pi-coding-agent@0.85.1 \
   && pi --version | grep -qx '0.85.1' \
   && pi --help | grep -q -- '--mode <mode>'
 
+# OpenCode, the second harness (docs/reference/specs/harness.md): `@opencode/cli`
+# at the EXACT pin held by src/deploy/imageOpenCodeHarness.test.ts, beside pi.
+# The wrapper's postinstall hard-links the platform binary into place, so it
+# is the one install script allowed by name; the grep proves the binary on
+# PATH prints the pin's version text (`opencode v2.0.3`, exactly); the npm
+# cache (a 200 MB tarball) is dropped in the same layer. Dark until a
+# deployment names it: nothing here starts it on its own.
+RUN npm install -g --allow-scripts=@opencode/cli @opencode/cli@2.0.3 \
+  && npm cache clean --force \
+  && opencode --version | grep -qx 'opencode v2.0.3'
+
 # The container outlives a crash of the SDK's container server (the
 # supervisor's header says why). The base image's ENTRYPOINT is tini running
 # the server, so one uncaught exception there ended the container; here tini

package/dist/assets/deploy/cloudflare-sandbox/worker.ts

@@ -44,6 +44,7 @@ import {
 } from "../../src/execution/sandboxLifecycle.js";
 import { envFromRequest } from "../../src/execution/sandboxEnv.js";
 import { IdleGuard, type IdleGuardHost } from "../../src/execution/sandboxIdle.js";
+import { StartGate, type StartGateHost, type StartingCause } from "../../src/execution/sandboxStart.js";
 import { RUNTIME_REPLACEMENT_WORDING, isRuntimeUnreachableSignal } from "../../src/execution/residentRefresh.js";
 import {
   fleetBusyAnswer,
@@ -53,6 +54,8 @@ import {
   runtimeUnreachableAnswer,
   runtimeUnreachableExecAnswer,
   SandboxRuntimeUnreachableError,
+  sandboxStartingAnswer,
+  sandboxStartingExecAnswer,
   thrownShape,
   thrownText,
 } from "../../src/execution/sandboxErrors.js";
@@ -167,6 +170,12 @@ interface FileRefusal {
   reason?: string;
 }
 
+/** The SDK's own limit on the warm-up command (`true`): generous, since the
+ *  SDK's start — an instance grant up to 30 s, the runtime's port up to 90 s
+ *  by its defaults — happens inside this one call. The executor's wait for
+ *  the `sandbox-starting` token is bounded on its own side. */
+const WARM_UP_BACKSTOP_MS = 4 * 60_000;
+
 /** Durable Object storage key of the idle ledger's served-time. */
 const IDLE_LEDGER_KEY = "switchboard.idle.lastServedAt";
 /** The scheduled-callback name of the idle sweep (a method below). */
@@ -185,10 +194,12 @@ export class SwitchboardSandbox extends Sandbox<Env> {
   sleepAfter = SANDBOX_SLEEP_AFTER;
 
   private readonly idle: IdleGuard;
+  private readonly gate: StartGate;
 
   constructor(...args: ConstructorParameters<typeof Sandbox<Env>>) {
     super(...args);
     this.idle = new IdleGuard(this.idleHost());
+    this.gate = new StartGate(this.startHost());
     // Every wake, including the one the SDK's own alarm causes on a leaked
     // container: the baseline is read and a sweep armed before any request.
     this.ctx.blockConcurrencyWhile(() => this.idle.wake());
@@ -215,6 +226,25 @@ export class SwitchboardSandbox extends Sandbox<Env> {
     };
   }
 
+  /** The start gate's view of this object (docs/reference/specs/execution.md
+   *  item 23): the platform's running flag, and a warm-up that is one trivial
+   *  command through the SDK — which does the start (instance grant, image
+   *  pull, boot, the runtime's port) and answers when the runtime does. The
+   *  warm-up runs inside the idle ledger so the guard sees a request in flight
+   *  for as long as the start takes. */
+  private startHost(): StartGateHost {
+    return {
+      now: systemClock,
+      containerRunning: () => this.ctx.container?.running,
+      warmUp: () =>
+        this.idle.served(async () => {
+          const proc = await createExtensionProcessSandbox(this).exec(["true"], { timeout: WARM_UP_BACKSTOP_MS });
+          await proc.output({ encoding: "utf8", timeout: WARM_UP_BACKSTOP_MS });
+        }),
+      log: (event) => console.log(JSON.stringify({ ...event, thread: this.ctx.id.name ?? this.ctx.id.toString() })),
+    };
+  }
+
   /** The idle sweep, scheduled by the guard through the SDK's schedule table
    *  and re-armed by it while a container is running. */
   async idleSweep(): Promise<void> {
@@ -240,7 +270,19 @@ export class SwitchboardSandbox extends Sandbox<Env> {
     execTimeoutSecs: number,
     envVars: Record<string, string>,
   ): Promise<ExecAnswer | ExecFailure> {
-    return this.idle.served(() => this.execute(command, execTimeoutSecs, envVars));
+    const startedAt = systemClock();
+    return this.idle.served(async () => {
+      try {
+        return await this.gate.through(
+          () => this.execute(command, execTimeoutSecs, envVars),
+          (cause) => sandboxStartingExecAnswer(cause),
+        );
+      } catch (err) {
+        // The warm-up's own failure, handed on by the gate: a full fleet or a
+        // silent control port keeps its name; anything else propagates.
+        return this.execFailure(err, startedAt);
+      }
+    });
   }
 
   /** `runCommand` without the ledger entry: the body, and the internal caller
@@ -337,9 +379,19 @@ export class SwitchboardSandbox extends Sandbox<Env> {
     }
   }
 
+  /** A file route's answer while the container starts: HTTP 503 with the
+   *  token, like a full fleet's. */
+  private startingRefusal(cause: StartingCause): FileRefusal {
+    const { error, reason } = sandboxStartingAnswer(cause);
+    return { error, status: 503, reason };
+  }
+
   async readText(path: string): Promise<{ content: string } | FileRefusal> {
     return this.idle.served(() =>
-      this.fileOp(async () => ({ content: (await this.readFile(path, { encoding: "utf-8" })).content })),
+      this.gate.through(
+        () => this.fileOp(async () => ({ content: (await this.readFile(path, { encoding: "utf-8" })).content })),
+        (cause) => this.startingRefusal(cause),
+      ),
     );
   }
 
@@ -348,7 +400,12 @@ export class SwitchboardSandbox extends Sandbox<Env> {
    *  decoded bytes to it — an SDK read that came back short would otherwise
    *  pass as the file. A file over the cap is refused by name inside a 200. */
   async readBase64(path: string): Promise<Base64ReadAnswer | FileRefusal> {
-    return this.idle.served(() => this.readBase64Now(path));
+    return this.idle.served(() =>
+      this.gate.through(
+        () => this.readBase64Now(path),
+        (cause) => this.startingRefusal(cause),
+      ),
+    );
   }
 
   private async readBase64Now(path: string): Promise<Base64ReadAnswer | FileRefusal> {
@@ -377,10 +434,14 @@ export class SwitchboardSandbox extends Sandbox<Env> {
 
   async write(path: string, content: string): Promise<{ ok: true } | FileRefusal> {
     return this.idle.served(() =>
-      this.fileOp(async () => {
-        await this.writeFile(path, content);
-        return { ok: true as const };
-      }),
+      this.gate.through(
+        () =>
+          this.fileOp(async () => {
+            await this.writeFile(path, content);
+            return { ok: true as const };
+          }),
+        (cause) => this.startingRefusal(cause),
+      ),
     );
   }
 }