@coreplane/switchboard 1.234.0 → 1.235.0

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

@@ -1,7 +1,7 @@
 // Residency garbage collection — the PURE decision logic, kept free of
 // the Sandbox SDK and DO storage so it runs under plain-Node vitest
 // (gc.test.ts). worker.ts feeds it what it observed (mirror refs, the GitHub
-// pulls list, tree cleanliness, live views) and acts on the answers.
+// pulls list, ops in flight, live views) and acts on the answers.
 //
 // Two mechanisms:
 //   1. Event-triggered reclamation: after every refresh-cycle `fetch --prune`,
@@ -79,9 +79,6 @@ export interface ReclaimInput {
   isDefaultRef: boolean;
   /** Thread exec/read/write currently running on this binding. */
   busy: number;
-  /** Tree cleanliness as the thread user; `null` = the runtime is down, so
-   *  the tree is already gone with the disk and there is nothing to preserve. */
-  clean: boolean | null;
 }
 
 /** The PR that decided the fate (for the audit trail): the open one, else the
@@ -97,13 +94,14 @@ export type ReclaimWhy =
   | "fate-unknown"
   | "busy"
   | "re-attached"
-  | "dirty"
   | Extract<RefFate, "gone" | "merged" | "closed">;
 
 /** Evict this binding now? A finished ref (gone/merged/closed) is reclaimed
- *  only when nothing runs on it and its tree is provably clean — a merged PR
- *  can still have unpushed local commits, and destroying work on a signal is
- *  exactly what this must never do. Keeps are named so the pass is auditable. */
+ *  when nothing runs on it — and nothing else is asked. What its tree holds
+ *  is never a reason to keep it: a run starts from a clean tree, so dirt in a
+ *  tree no run is using protects nothing (the next attach wipes it); the
+ *  Worker measures and records what it removes instead. Keeps are named so
+ *  the pass is auditable. */
 export function reclaimDecision(input: ReclaimInput): { reclaim: boolean; why: ReclaimWhy } {
   if (input.isDefaultRef) return { reclaim: false, why: "default-ref" };
   switch (input.fate) {
@@ -115,7 +113,6 @@ export function reclaimDecision(input: ReclaimInput): { reclaim: boolean; why: R
       return { reclaim: false, why: "fate-unknown" };
   }
   if (input.busy > 0) return { reclaim: false, why: "busy" };
-  if (input.clean === false) return { reclaim: false, why: "dirty" };
   return { reclaim: true, why: input.fate };
 }
 

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

@@ -116,10 +116,13 @@ import {
   type ThreadDepsMechanism,
 } from "../../src/execution/residentDepCache.js";
 import {
-  leftBehindOf,
+  evictedTreeOf,
+  evictedTreeSentence,
   parseWorktreeCleanliness,
   worktreeCleanlinessScript,
+  type EvictedTree,
   type LeftBehind,
+  type WorktreeCleanliness,
 } from "../../src/execution/residentCleanliness.js";
 import {
   base64LengthOf,
@@ -1023,8 +1026,17 @@ interface ThreadBinding {
   evicted?: boolean;
   evictedAt?: string;
   /** Why the last eviction happened (the audit trail): `ttl`, `clean-idle`,
-   *  `detach`, or a reclamation fate — `merged #N` / `closed #N` / `gone`. */
+   *  `detach`, `disk-pressure`, or a reclamation fate — `merged #N` /
+   *  `closed #N` / `gone`. */
   evictedWhy?: string;
+  /** What the tree held when that eviction removed it (item 17: never a
+   *  reason to keep the tree, never discarded silently): the tracked changes
+   *  and unpushed commits measured as the thread user. Absent when the tree
+   *  was clean, already gone with the disk, or not measured (a force detach). */
+  evictedLeftBehind?: LeftBehind;
+  /** 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;
   /** 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
@@ -3786,15 +3798,16 @@ export class ResidentDO extends Sandbox<Env> {
     });
   }
 
-  /** Idle = no live binding attached within IDLE_AFTER_S AND (when the
-   *  runtime is up) no live tree is dirty. Bindings are storage; dirtiness
-   *  needs the container — if it is already asleep there is nothing to lose. */
+  /** 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();
     const recent = systemClock() - IDLE_AFTER_S * 1000;
     if (live.some((b) => Date.parse(b.lastAttachAt) >= recent)) return false;
-    if (this.inFlightCount() > 0) return false;
-    return this.liveTreesClean(live);
+    return this.inFlightCount() === 0;
   }
 
   /** Bindings that hold a pool user and a tree on disk (not evicted). */
@@ -3803,14 +3816,13 @@ export class ResidentDO extends Sandbox<Env> {
     return [...all.values()].filter((b) => !b.evicted && b.user);
   }
 
-  /** True when no live tree holds work a lost disk would destroy: every one
-   *  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. */
+  /** 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 — the idle gate does not pay a serial
-    // 3-probe round-trip per live binding.
+    // 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
   }
@@ -3948,10 +3960,11 @@ export class ResidentDO extends Sandbox<Env> {
    *  already on disk is `reuse` (0 — a dirty/stale recreate frees the old one
    *  first). A ref not yet in the mirror (fetched under the lock, moments later)
    *  is projected as `hardlink`, the common case. When it does not fit, the
-   *  coldest clean idle trees go first (`orderEvictionCandidates`: never the
+   *  coldest idle trees go first (`orderEvictionCandidates`: never the
    *  requesting thread, a busy tree, the default branch, or one attached within
-   *  DISK_EVICT_MIN_IDLE_MS; cleanliness checked as the thread user, dirty or
-   *  unreadable kept — the sweep's rules), `df` re-probed after each; still
+   *  DISK_EVICT_MIN_IDLE_MS), whatever they hold — item 17: dirt never keeps a
+   *  tree; each is measured as its thread user for the eviction's record —
+   *  `df` re-probed after each; still
    *  short → `503 {reason:"disk-pressure"}` with the whole math in `error`, the
    *  same shape as `mirror-busy`, so the bot falls back cold legibly. Never a
    *  lifecycle flip: the checkout is intact and every existing tree keeps
@@ -4021,12 +4034,10 @@ export class ResidentDO extends Sandbox<Env> {
         if (verdict.fits) break;
         const binding = live.find((b) => b.threadKey === c.threadKey);
         if (!binding) continue;
-        const clean = await this.worktreeCleanliness(binding);
-        if (!clean.clean) {
-          kept.push({ threadKey: c.threadKey, why: "dirty" });
-          continue;
-        }
-        // Same re-read guards as the sweep: the clean check awaited.
+        // What the tree holds goes on the eviction's record (item 17), never
+        // into a keep; the runtime is up — this attach is running on it.
+        const tree = await this.measureTreeBeforeEviction(binding);
+        // Same re-read guards as the sweep: the measurement awaited.
         const current = await this.ctx.storage.get<ThreadBinding>(threadBindingKey(c.threadKey));
         if (
           !current ||
@@ -4037,7 +4048,7 @@ export class ResidentDO extends Sandbox<Env> {
           kept.push({ threadKey: c.threadKey, why: "busy" });
           continue;
         }
-        if (!(await this.evictBinding(current, true, "disk-pressure", DISK_PRESSURE_REASON))) {
+        if (!(await this.evictBinding(current, true, "disk-pressure", DISK_PRESSURE_REASON, tree))) {
           kept.push({ threadKey: c.threadKey, why: "other" });
           continue;
         }
@@ -6022,13 +6033,21 @@ export class ResidentDO extends Sandbox<Env> {
 
   /** Remove a thread's worktree (when the runtime is up — a slept container
    *  already lost it) and release its pool user; the binding is KEPT, marked
-   *  evicted, so the ref stays sticky and the next attach recreates the tree
-   *  with it. Shared by the inactivity sweep and /detach. */
+   *  evicted with the cause (`evictedWhy`) and with what the tree held
+   *  (`evictedLeftBehind`, or `evictedUnmeasured` when git could not read it
+   *  — item 17: never a reason to keep the tree, never discarded silently), so
+   *  the ref stays sticky and the next attach recreates the tree with it.
+   *  Shared by the inactivity sweep, the reclamation pass, the disk-pressure
+   *  path and /detach. */
   private async evictBinding(
     binding: ThreadBinding,
     runtimeActive: boolean,
     logCtx: string,
     why: string,
+    /** What the caller measured in the tree first (`measureTreeBeforeEviction`,
+     *  as the thread user with the runtime up); absent when the tree was clean,
+     *  already gone with the disk, or not measured (a force detach). */
+    tree?: EvictedTree,
   ): Promise<boolean> {
     const threadDir = parentDir(binding.worktreePath);
     if (runtimeActive && threadDir.startsWith(`${THREADS_DIR}/`)) {
@@ -6064,7 +6083,10 @@ export class ResidentDO extends Sandbox<Env> {
       evicted: true,
       evictedAt: new Date(systemClock()).toISOString(),
       evictedWhy: why,
+      evictedLeftBehind: tree && "leftBehind" in tree ? tree.leftBehind : undefined,
+      evictedUnmeasured: tree && "unmeasured" in tree ? tree.unmeasured : undefined,
     } satisfies ThreadBinding);
+    if (tree) console.log(`${logCtx}: ${binding.threadKey} evicted (${why}) — ${evictedTreeSentence(tree)}`);
     return true;
   }
 
@@ -6105,17 +6127,13 @@ export class ResidentDO extends Sandbox<Env> {
       if (left > 0) return { released: false, reason: busyAfterKillReason(left), user: binding.user };
     }
     const active = await this.isRuntimeActive().catch(() => false);
-    // What the tree still holds, for the answer — never a reason to keep it.
-    // Not measured on a force release: a read-only tree holds nothing, and a
-    // hard stop's tree is whatever the killed command left. A probe that
-    // fails names nothing (never a guess) and is a log line.
-    let leftBehind: LeftBehind | undefined;
-    if (!force && active) {
-      const measured = await this.worktreeCleanliness(binding);
-      leftBehind = leftBehindOf(measured);
-      if (!measured.clean && leftBehind === undefined)
-        console.log(`detach: ${threadKey}: the tree could not be measured before its release (${measured.reason})`);
-    }
+    // What the tree still holds, for the answer and the eviction's record —
+    // never a reason to keep it. Not measured on a force release: a read-only
+    // tree holds nothing, and a hard stop's tree is whatever the killed
+    // command left. A probe that fails names nothing in the answer (never a
+    // guess); the record and the log say it could not be measured.
+    let tree: EvictedTree | undefined;
+    if (!force && active) tree = await this.measureTreeBeforeEviction(binding);
     // Re-check right before removal: the measurement above awaited (the DO
     // yields at each await), so an exec that arrived mid-detach would otherwise
     // have its tree removed under it.
@@ -6136,16 +6154,12 @@ export class ResidentDO extends Sandbox<Env> {
     // Same as the sweep: `active` was read before the measurement's awaits; a
     // container that woke meanwhile must get the rm, not an orphaned tree.
     const activeNow = await this.isRuntimeActive().catch(() => false);
-    if (!(await this.evictBinding(current, activeNow, `detach`, "detach"))) {
+    if (!(await this.evictBinding(current, activeNow, `detach`, "detach", tree))) {
       return { released: false, reason: "re-attached during eviction — kept", user };
     }
-    if (leftBehind) {
-      console.log(
-        `detach: ${threadKey} released — left behind ${leftBehind.uncommittedChanges} uncommitted change(s) and ${leftBehind.unpushedCommits} unpushed commit(s), discarded with the tree`,
-      );
-    }
     // Item 55: the tree is gone; the gauge catches up at the next refresh
     // instance's `measure` step, and the admission's `df` sees the space now.
+    const leftBehind = tree && "leftBehind" in tree ? tree.leftBehind : undefined;
     return { released: true, user, ...(leftBehind !== undefined ? { leftBehind } : {}) };
   }
 
@@ -6183,20 +6197,22 @@ export class ResidentDO extends Sandbox<Env> {
     }
   }
 
-  /** Is this thread's tree safe to destroy? The git probes run AS THE THREAD
-   *  USER (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. Unknown (git
-   *  failed) counts as NOT clean — never destroy work on a guess. A tree
-   *  that no longer exists (disk recycled by a sleep/wake) has nothing to
-   *  preserve: releasable, so a post-wake binding does not hold a pool user
-   *  for 7 days on behalf of files that are already gone.
+  /** What this thread's tree holds: the tracked changes and unpushed commits,
+   *  or that git could not read it. The git probes run AS THE THREAD USER
+   *  (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.
    *
    *  ONE spawn: the presence test and both git probes fold
    *  into the pure `worktreeCleanlinessScript` (test -d as root, both git
    *  commands inside a single privilege-dropped `su`, tagged lines out);
    *  `parseWorktreeCleanliness` encodes the exact decision table above. */
-  private async worktreeCleanliness(binding: ThreadBinding): Promise<{ clean: boolean; reason?: string }> {
+  private async worktreeCleanliness(binding: ThreadBinding): Promise<WorktreeCleanliness> {
     const injected = { GIT_TERMINAL_PROMPT: "0" }; // same injection as threadRun — fail fast, never prompt
     validateEnvNames(injected);
     const r = await this.run(["sh", "-c", worktreeCleanlinessScript(binding.worktreePath, binding.user)], {
@@ -6206,6 +6222,14 @@ export class ResidentDO extends Sandbox<Env> {
     return parseWorktreeCleanliness(r);
   }
 
+  /** What a tree holds right before its eviction, 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. */
+  private async measureTreeBeforeEviction(binding: ThreadBinding): Promise<EvictedTree | undefined> {
+    return evictedTreeOf(await this.worktreeCleanliness(binding));
+  }
+
   /** Anything that must not be interrupted by a container stop or counted
    *  as idle: thread exec/read/write, disposable /op runs, and attaches past
    *  their own image check (mid clone/install under the mirror lock). */
@@ -6278,8 +6302,17 @@ export class ResidentDO extends Sandbox<Env> {
       // attach), and an eviction decided on a stale "inactive" would skip the
       // rm and orphan a real tree.
       const activeNow = await this.isRuntimeActive().catch(() => false);
+      // What the tree holds goes on the eviction's record (item 17), measured
+      // while the runtime is up; a slept container has no tree to measure.
+      const tree = activeNow ? await this.measureTreeBeforeEviction(current) : undefined;
       if (
-        await this.evictBinding(current, activeNow, `worktree-sweep ${resource}`, last >= cutoff ? "clean-idle" : "ttl")
+        await this.evictBinding(
+          current,
+          activeNow,
+          `worktree-sweep ${resource}`,
+          last >= cutoff ? "clean-idle" : "ttl",
+          tree,
+        )
       )
         evicted.push(binding.threadKey);
       else kept++;
@@ -6537,9 +6570,11 @@ export class ResidentDO extends Sandbox<Env> {
    *  mirror (the refresh cycle's `fetch --prune` just ran) or its PR was
    *  merged/closed. Runs inside the refresh cycle — a poll on the existing
    *  cadence, since the GitHub App has webhooks off — and via /debug
-   *  reclaim-now. Never touches the default branch, a busy thread, or a dirty
-   *  tree (reclaimDecision); every keep is named. The eviction itself is the
-   *  sweep's `evictBinding` with the same re-read guards. */
+   *  reclaim-now. Never touches the default branch or a busy thread
+   *  (reclaimDecision); every keep is named. What the tree holds is never a
+   *  reason to keep it (item 17) — it is measured once as the thread user and
+   *  recorded by the eviction, the sweep's `evictBinding` with the same
+   *  re-read guards. */
   async reclaimFinishedRefs(
     resource: string,
     defaultRef: string,
@@ -6599,21 +6634,16 @@ export class ResidentDO extends Sandbox<Env> {
       // by name), so its fate is never looked up.
       const { fate, detail } = (!isDefaultRef && fates.get(binding.ref)) || { fate: "unknown" as RefFate, detail: "" };
       const busy = this.threadOpsInFlight.get(binding.threadKey) ?? 0;
-      // The clean check runs as the thread user and only when it can decide
-      // anything: a finished ref, nothing running, runtime up (down → the tree
-      // is already gone with the disk → null).
-      const finished = fate === "gone" || fate === "merged" || fate === "closed";
-      const clean = !active
-        ? null
-        : finished && !isDefaultRef && busy === 0
-          ? (await this.worktreeCleanliness(binding)).clean
-          : null;
-      const decision = reclaimDecision({ fate, isDefaultRef, busy, clean });
+      const decision = reclaimDecision({ fate, isDefaultRef, busy });
       if (!decision.reclaim) {
         kept.push({ threadKey: binding.threadKey, ref: binding.ref, why: decision.why });
         continue;
       }
-      // Same guards as the sweep: the clean check awaited, so re-read the
+      // What the tree holds goes on the eviction's record (item 17), never
+      // into the decision: measured as the thread user while the runtime is
+      // up; down → the tree is already gone with the disk.
+      const tree = active ? await this.measureTreeBeforeEviction(binding) : undefined;
+      // Same guards as the sweep: the measurement awaited, so re-read the
       // binding (a re-attach means a fresh tree) and the op counter.
       const busyNow = this.threadOpsInFlight.get(binding.threadKey) ?? 0;
       const current = await this.ctx.storage.get<ThreadBinding>(threadBindingKey(binding.threadKey));
@@ -6627,7 +6657,7 @@ export class ResidentDO extends Sandbox<Env> {
       }
       const activeNow = await this.isRuntimeActive().catch(() => false);
       const why = `${decision.why}${detail}`;
-      if (await this.evictBinding(current, activeNow, `reclaim ${resource}`, why)) {
+      if (await this.evictBinding(current, activeNow, `reclaim ${resource}`, why, tree)) {
         reclaimed.push({ threadKey: binding.threadKey, ref: binding.ref, why });
         console.log(`reclaim ${resource}: evicted ${binding.threadKey} on ${binding.ref} — ${why}`);
       } else kept.push({ threadKey: binding.threadKey, ref: binding.ref, why: "re-attached" });
@@ -6738,18 +6768,35 @@ export class ResidentDO extends Sandbox<Env> {
     // left out; nothing here is secret (credential files are never persisted).
     const threads = [...bindings.values()]
       .sort((a, b) => b.lastAttachAt.localeCompare(a.lastAttachAt))
-      .map(({ threadKey, ref, sha, user, deps, boundAt, lastAttachAt, evicted, evictedAt, evictedWhy }) => ({
-        threadKey,
-        ref,
-        sha: sha ?? null,
-        user,
-        deps: deps ?? null,
-        boundAt,
-        lastAttachAt,
-        evicted: evicted ?? false,
-        evictedAt: evictedAt ?? null,
-        evictedWhy: evictedWhy ?? null,
-      }));
+      .map(
+        ({
+          threadKey,
+          ref,
+          sha,
+          user,
+          deps,
+          boundAt,
+          lastAttachAt,
+          evicted,
+          evictedAt,
+          evictedWhy,
+          evictedLeftBehind,
+          evictedUnmeasured,
+        }) => ({
+          threadKey,
+          ref,
+          sha: sha ?? null,
+          user,
+          deps: deps ?? null,
+          boundAt,
+          lastAttachAt,
+          evicted: evicted ?? false,
+          evictedAt: evictedAt ?? null,
+          evictedWhy: evictedWhy ?? null,
+          evictedLeftBehind: evictedLeftBehind ?? null,
+          evictedUnmeasured: evictedUnmeasured ?? null,
+        }),
+      );
     return {
       resource: map.get(RESOURCE_KEY) ?? null,
       state: map.get(STATE_KEY) ?? "down",

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

@@ -43,6 +43,7 @@ import {
   recycledMidCommandMessage,
 } from "../../src/execution/sandboxLifecycle.js";
 import { envFromRequest } from "../../src/execution/sandboxEnv.js";
+import { IdleGuard, type IdleGuardHost } from "../../src/execution/sandboxIdle.js";
 import { RUNTIME_REPLACEMENT_WORDING, isRuntimeUnreachableSignal } from "../../src/execution/residentRefresh.js";
 import {
   fleetBusyAnswer,
@@ -166,16 +167,66 @@ interface FileRefusal {
   reason?: string;
 }
 
+/** 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). */
+const IDLE_SWEEP_CALLBACK = "idleSweep";
+
 export class SwitchboardSandbox extends Sandbox<Env> {
-  // Idle lifetime of a thread's container (the SDK's own default is 10 min).
-  // Idle means idle: the SDK renews the activity timeout every second while a
-  // command's stream is open (its control connection's busy poll), so a
-  // running command never counts toward it and the shell-level `timeout` is
-  // the one deadline a command can hit (docs/reference/specs/execution.md item 2).
-  // 5 minutes frees the slot sooner while a prompt follow-up still reuses the
-  // warm workspace.
+  // The SDK's idle setting (its own default is 10 min), kept so its alarm
+  // loop calls `onActivityExpired` on this cadence — but on the 0.13 line that
+  // hook is a question to the runtime ("anything still running?"), not a
+  // deadline, and the answer kept twenty-five containers awake for 16 hours.
+  // The deadline itself is the guard's (docs/reference/specs/execution.md
+  // item 22): 5 minutes after the last request this object served, the
+  // container is destroyed, whatever runs inside; the shell-level `timeout`
+  // stays the one deadline a command can hit (item 2), since a request in
+  // flight is service.
   sleepAfter = SANDBOX_SLEEP_AFTER;
 
+  private readonly idle: IdleGuard;
+
+  constructor(...args: ConstructorParameters<typeof Sandbox<Env>>) {
+    super(...args);
+    this.idle = new IdleGuard(this.idleHost());
+    // 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());
+  }
+
+  /** The guard's view of this object: the platform's running flag, the SDK's
+   *  schedule table and clean destroy, the platform's kill, and storage. */
+  private idleHost(): IdleGuardHost {
+    return {
+      now: systemClock,
+      containerRunning: () => this.ctx.container?.running,
+      sweepScheduled: async () => (await this.listSchedules(IDLE_SWEEP_CALLBACK)).length > 0,
+      scheduleSweep: async (delayMs) => {
+        await this.schedule(Math.ceil(delayMs / 1000), IDLE_SWEEP_CALLBACK);
+      },
+      destroySandbox: () => this.destroy(),
+      killContainer: async () => {
+        await this.ctx.container?.destroy();
+      },
+      loadLastServedAt: () => this.ctx.storage.get<number>(IDLE_LEDGER_KEY),
+      saveLastServedAt: (at) => this.ctx.storage.put(IDLE_LEDGER_KEY, at),
+      log: (event) => console.log(JSON.stringify({ ...event, thread: this.ctx.id.name ?? this.ctx.id.toString() })),
+      wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    };
+  }
+
+  /** 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> {
+    await this.idle.sweep();
+  }
+
+  /** The SDK's activity expiry, answered by the guard's verdict instead of the
+   *  runtime's process probes. */
+  override async onActivityExpired(): Promise<void> {
+    await this.idle.expired();
+  }
+
   /** One command as one supervised process (docs/reference/specs/execution.md
    *  item 4): `timeout -k 10 <secs> bash -c 'mkdir -p /workspace && cd
    *  /workspace && <command>'`, the caller's env on the process alone (item 5),
@@ -188,6 +239,16 @@ export class SwitchboardSandbox extends Sandbox<Env> {
     command: string,
     execTimeoutSecs: number,
     envVars: Record<string, string>,
+  ): Promise<ExecAnswer | ExecFailure> {
+    return this.idle.served(() => this.execute(command, execTimeoutSecs, envVars));
+  }
+
+  /** `runCommand` without the ledger entry: the body, and the internal caller
+   *  (`readBase64`'s stat) that is already inside a served request. */
+  private async execute(
+    command: string,
+    execTimeoutSecs: number,
+    envVars: Record<string, string>,
   ): Promise<ExecAnswer | ExecFailure> {
     const startedAt = systemClock();
     const full = `mkdir -p ${WORKDIR} && cd ${WORKDIR} && ${command}`;
@@ -277,7 +338,9 @@ export class SwitchboardSandbox extends Sandbox<Env> {
   }
 
   async readText(path: string): Promise<{ content: string } | FileRefusal> {
-    return this.fileOp(async () => ({ content: (await this.readFile(path, { encoding: "utf-8" })).content }));
+    return this.idle.served(() =>
+      this.fileOp(async () => ({ content: (await this.readFile(path, { encoding: "utf-8" })).content })),
+    );
   }
 
   /** `encoding: "base64"` (src/execution/binaryRead.ts): the size first, from
@@ -285,7 +348,11 @@ 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> {
-    const stat = await this.runCommand(statCommandFor(path), 60, {});
+    return this.idle.served(() => this.readBase64Now(path));
+  }
+
+  private async readBase64Now(path: string): Promise<Base64ReadAnswer | FileRefusal> {
+    const stat = await this.execute(statCommandFor(path), 60, {});
     if ("error" in stat) {
       // The stat's own named failure — a full fleet, a silent control port —
       // is the read's, token included, so the executor waits as it would
@@ -309,10 +376,12 @@ export class SwitchboardSandbox extends Sandbox<Env> {
   }
 
   async write(path: string, content: string): Promise<{ ok: true } | FileRefusal> {
-    return this.fileOp(async () => {
-      await this.writeFile(path, content);
-      return { ok: true as const };
-    });
+    return this.idle.served(() =>
+      this.fileOp(async () => {
+        await this.writeFile(path, content);
+        return { ok: true as const };
+      }),
+    );
   }
 }
 

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.234.0",
+  "version": "1.235.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.234.0",
+      "version": "1.235.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -20032,7 +20032,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.234.0",
+      "version": "1.235.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@earendil-works/pi-ai": "0.85.1",

package/dist/assets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard",
-  "version": "1.234.0",
+  "version": "1.235.0",
   "private": true,
   "description": "Mention it in Slack and an agent reviews the PR, ships the fix, or answers the question — on the model you choose, with its tools running where you decide.",
   "license": "Apache-2.0",

package/dist/assets/source.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.234.0",
-  "commit": "0c5f8c5e4657cd12a9bbf85177bee69b61505ac3",
-  "builtAt": "2026-09-16T16:44:55.183Z"
+  "version": "1.235.0",
+  "commit": "091ab2f1f6d89290bde9c84e933d23525f9c8873",
+  "builtAt": "2026-09-16T17:37:07.278Z"
 }

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

@@ -367,6 +367,11 @@ export type RunEvent =
    *  past the summary cap. The status card and friction analyzer keep reading
    *  `summary`. */
   /** `spanId` (docs/reference/specs/tracing.md): the `tool.*` span this call ran under, once the runner emits spans. */
+  /** `logIndex` (docs/reference/specs/run-history.md item 53): the row of the run's
+   *  session log holding the assistant turn this call rode in — on a `tool_result`,
+   *  the user turn its batch's results make. How a search hit's turn finds its
+   *  step on the page. Absent for a run without a session, a record from before
+   *  the field, and a call the mirror could not place. */
   | {
       type: "tool_call";
       tool: string;
@@ -374,6 +379,7 @@ export type RunEvent =
       command?: string;
       callId?: string;
       spanId?: string;
+      logIndex?: number;
       seq?: number;
       at?: number;
     }
@@ -393,6 +399,7 @@ export type RunEvent =
       output?: string;
       infra?: true;
       spanId?: string;
+      logIndex?: number;
       seq?: number;
       at?: number;
     }