@coreplane/switchboard 1.233.0 → 1.235.0

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

@@ -16,21 +16,34 @@
  *
  *  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:
+ *  named). The move is a decision about the BINDING alone; the tree is the
+ *  attach's business afterwards (item 17: a run starts from a clean tree at
+ *  the bound ref, so the attach provisions the tree at the moved ref as it
+ *  provisions any other). 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 —
- *    unless its HEAD is already the branch: the run made the branch in this
- *    tree and left an edit after pushing, so the record alone moves and no
- *    git command touches the tree.
- *  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 thread was not rebound before, or its earlier move was returned (the
+ *    second movement below) — a thread moves once per pull request;
+ *  - the branch is the thread's own: remembered from a release (`ownBranches`,
+ *    the branches its runs pushed), or, when nothing was remembered, a local
+ *    branch of the thread's surviving tree — the physical fact that this
+ *    thread's run created it. A branch neither remembered nor local is
+ *    refused whatever the caller says; so is one the mirror does not hold
+ *    even after a fetch (the Worker's check: the tree is cloned from it).
+ *  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 pull request the thread's own run opened, and its head branch — the
  *  reason a caller's refHint is that branch. */
@@ -145,15 +158,29 @@ export function boundByOf(binding: { ref: string; boundBy?: BoundBy }, defaultRe
   return binding.boundBy ?? (binding.ref === defaultRef ? "default" : "name");
 }
 
-/** The record a rebind leaves on the binding and in the attach answer. */
+/** The record a rebind leaves on the binding and in the attach answer: from
+ *  which ref, onto which branch, for which pull request, when. `returnedAt`:
+ *  that branch was gone from the mirror at a later attach and the binding
+ *  went back to the default (the second movement) — a returned move no
+ *  longer counts as the thread's one move. */
 export interface Rebound {
   from: string;
   to: string;
   pr: number;
   at: string;
+  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. */
+export interface Returned {
+  from: string;
+  to: string;
+  pr: number;
+  at: string;
 }
 
-export type RebindRefusal = "named-ref" | "already-rebound" | "branch-absent" | "dirty" | "checkout-failed";
+export type RebindRefusal = "named-ref" | "already-rebound" | "branch-absent";
 
 /** Why the binding stood, in the attach answer: the branch it was asked to
  *  move to, the pull request, the reason and its sentence. */
@@ -182,9 +209,10 @@ export type RebindPlan =
   | { 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. */
+  /** The binding allows it and has a live tree. `own`: the thread's own runs
+   *  pushed the branch, as the binding remembers it — the fact that decides;
+   *  when nothing was remembered, the tree's local branch is the fallback
+   *  evidence (`rebindVerdict`). */
   | { 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
@@ -217,7 +245,10 @@ export function rebindPlan(input: {
       ),
     };
   }
-  if (binding.rebound) {
+  // A move that was returned (its branch gone, the binding back on the
+  // default) no longer stands in the way: the thread may follow its next
+  // pull request as it followed the first.
+  if (binding.rebound && binding.rebound.returnedAt === undefined) {
     const r = binding.rebound;
     return {
       kind: "refuse",
@@ -243,42 +274,30 @@ export function rebindPlan(input: {
   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. */
+/** What the attach measured about the thread's tree, as the thread user —
+ *  only when the binding remembers no push of the branch: the tree is then
+ *  the only place the branch's origin can be read. */
 export interface RebindTreeFacts {
   /** `<worktree>/.git` is a directory. */
   exists: boolean;
-  /** `git rev-parse --verify --quiet refs/heads/<to>` succeeded in the tree. */
+  /** `git rev-parse --verify --quiet refs/heads/<to>` succeeded in the tree;
+   *  false for a branch the tree never made and for a tree git cannot read
+   *  (neither verifies anything). */
   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;
-  /** `git rev-parse --abbrev-ref HEAD` in the tree — the branch checked out
-   *  (`HEAD` when detached) — measured once the tree is dirty: the one fact
-   *  that tells a dirty tree already on the branch from one elsewhere. */
-  head?: string;
 }
 
 export type RebindVerdict =
-  /** Move the binding. `checkout: true`: check the branch out in the existing
-   *  tree. `checkout: false`: the tree is dirty but its HEAD is already the
-   *  branch — the run made it here and left an edit after pushing — so only
-   *  the record moves; no checkout, no fetch, no reset, the tree not touched
-   *  by the rebind (`note` says so for the log). */
-  | { kind: "rebind"; checkout: true }
-  | { kind: "rebind"; checkout: false; note: string }
-  /** 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 branch is the thread's own: move the binding. The tree is not this
+   *  verdict's concern — the attach provisions it at the moved ref (item 17),
+   *  once the Worker has seen the mirror hold the branch. */
+  { kind: "rebind" } | { kind: "refuse"; refused: RebindRefused };
 
-/** The tree's verdict on a measured plan. */
+/** Whether the branch is the thread's own, for a measured plan: the memory of
+ *  a release decides by itself; without it, the surviving tree must hold the
+ *  branch as a local branch. */
 export function rebindVerdict(plan: { to: string; pr: number; own?: boolean }, tree: RebindTreeFacts): RebindVerdict {
+  if (plan.own === true) return { kind: "rebind" };
   if (!tree.exists) {
-    if (plan.own === true) return { kind: "recreate" };
     return {
       kind: "refuse",
       refused: rebindRefused(
@@ -288,46 +307,42 @@ export function rebindVerdict(plan: { to: string; pr: number; own?: boolean }, t
       ),
     };
   }
-  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`,
+        `${JSON.stringify(plan.to)} is not a local branch of the thread's worktree and none of its runs pushed it; only a branch this thread's own run made moves it`,
       ),
     };
   }
-  if (tree.dirty === true) {
-    // A dirty tree whose HEAD is the branch has nothing a checkout could
-    // cost: the run created the branch in this very tree and left the edit
-    // after pushing, and only the record still names the old ref. Moving
-    // the record is the whole move. Any other HEAD keeps the guard.
-    if (tree.head === plan.to) {
-      return {
-        kind: "rebind",
-        checkout: false,
-        note: `the worktree is dirty but its HEAD is already ${JSON.stringify(plan.to)} (the run made the branch here); the binding moves, the tree is not touched`,
-      };
-    }
-    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", checkout: true };
+  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 },
+  defaultRef: string,
+): boolean {
+  const r = binding.rebound;
+  if (r === undefined || r.returnedAt !== undefined || binding.ref !== r.to) return false;
+  return binding.ref !== defaultRef && boundByOf(binding, defaultRef) === "default";
+}
+
+/** 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 },
+  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 };
 }

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

@@ -16,11 +16,11 @@
  *  PROVISIONS (a fresh one). A reusing attach keeps a readable tree exactly
  *  as it stands, dirt and stale HEAD included, and refuses by name a tree it
  *  cannot keep (gone, unreadable, built for the other mode) without touching
- *  it. A provisioning attach keeps the dirty/stale discipline byte for byte —
- *  with one exception it is told about (`keepTree`): when its own rebind onto
- *  the thread's pull request branch found the tree dirty with that branch
- *  already checked out and moved the record alone, the dirt is the thread's
- *  own work and the tree is kept as it stands. */
+ *  it. A provisioning attach keeps the dirty/stale discipline byte for byte:
+ *  a run starts from a clean tree at the bound ref's tip, and what a run
+ *  wants kept it commits and pushes (docs/reference/specs/resident-repos.md
+ *  item 17) — so a tree left dirty, or on a branch the binding has since
+ *  moved away from, is recreated, never repaired. */
 
 export type ParsedReuse = { reuse: boolean } | { error: string };
 
@@ -62,15 +62,6 @@ export type WorktreeDecision =
 export function decideWorktree(input: {
   /** True for a resumed run's attach: keep the tree, never wipe it. */
   reuse: boolean;
-  /** True when this attach's rebind moved the binding onto the branch the
-   *  tree already had checked out, dirty, and promised not to touch it
-   *  (residentRebind.ts, the `checkout: false` verdict): the dirt is the
-   *  thread's own uncommitted work on its own pull request branch, so a
-   *  readable tree is kept as it stands — dirt and HEAD included, like a
-   *  resumed run's — while a tree that turns out missing, unreadable or built
-   *  for the other mode has nothing to keep and is provisioned like any fresh
-   *  attach's. Absent on every attach that did not make that move. */
-  keepTree?: boolean;
   /** The tree was built for the other mode (read-only against writable). */
   modeSwitch: boolean;
   /** The commit a provisioning attach checks out: the ref's tip, or the expected head. */
@@ -78,7 +69,7 @@ export function decideWorktree(input: {
   worktreePath: string;
   facts: WorktreeFacts;
 }): WorktreeDecision {
-  const { reuse, keepTree = false, modeSwitch, sha, worktreePath, facts } = input;
+  const { reuse, modeSwitch, sha, worktreePath, facts } = input;
   if (modeSwitch) {
     return reuse
       ? {
@@ -105,9 +96,7 @@ export function decideWorktree(input: {
   }
   // A reusing attach judges nothing past readability: the dirt and the HEAD are the run's own state.
   if (reuse) return { kind: "reuse" };
-  // The rebind promised a dirty tree on its own branch would not be touched;
-  // the dirt is the reason it made that promise, so it is not a reason to wipe.
-  if (facts.dirty) return keepTree ? { kind: "reuse" } : { kind: "recreate", why: "dirty" };
+  if (facts.dirty) return { kind: "recreate", why: "dirty" };
   if (facts.head !== sha && facts.descendsFromTip !== true) return { kind: "recreate", why: "stale" };
   return { kind: "reuse" };
 }

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

@@ -18,7 +18,6 @@ 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

@@ -48,6 +48,11 @@ const FLEET_BUSY_PATTERNS: readonly RegExp[] = [
   /^Failed to create session: 503\b/i,
   /no container instance (?:that can be provided|available)/i,
   /\bCONTAINER_UNAVAILABLE\b/,
+  // The platform's wording since the 0.13 line ("… Try again later, or try
+  // configuring a higher value for max_instances"): the 0.13 SDK's own warm
+  // pool matches on this exact phrase. Seen live passing through as a plain
+  // in-body error and ending two reviews in under a minute each.
+  /Maximum number of running container instances exceeded/i,
 ];
 
 export function isFleetBusy(message: string): boolean {

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

@@ -0,0 +1,220 @@
+// The per-thread sandbox's idle deadline, decided by the Durable Object from
+// the one fact it owns (docs/reference/specs/execution.md item 22): when it
+// last served a request. Deliberately free of node: imports so wrangler can
+// bundle it into the sandbox Worker, like sandboxErrors.ts and
+// sandboxLifecycle.ts.
+//
+// Why this exists: on the 0.13 SDK line the Container's `sleepAfter` is no
+// longer a deadline. At expiry the SDK asks its runtime whether any tracked
+// process or terminal is still active and, if so — or if the probe fails at
+// all — renews the timeout instead of stopping. A detached pi holds its
+// command's stdio open, a bot deploy mid-run orphans that pi until the same
+// thread's next run, and the container is awake for good: twenty-five
+// sandboxes were found running 10–16 h after their last request against a
+// 5-minute sleepAfter with three runs in flight, and the fleet answered every
+// new thread "Maximum number of running container instances exceeded". The
+// guard below makes the deadline ours again: served-time is recorded on every
+// request, a sweep the Durable Object schedules for itself checks it once a
+// minute (and the SDK's own expiry hook is answered by the same verdict), and
+// a container past the window is destroyed — through the SDK's clean teardown
+// when that finishes in time, by the platform's own kill when it does not.
+// Nothing inside the container can extend its life; only a request can.
+
+import { BASH_TIMEOUT_MAX_MS } from "./bashTimeout.js";
+
+/** The idle window in milliseconds — the twin of `SANDBOX_SLEEP_AFTER` ("5m",
+ *  sandboxLifecycle.ts), which stays the SDK's own setting so its alarm loop
+ *  still calls `onActivityExpired` on this cadence. A test holds the two
+ *  together. */
+export const SANDBOX_SLEEP_AFTER_MS = 5 * 60_000;
+
+/** The guard's own cadence: a scheduled callback the Durable Object re-arms
+ *  after each run while there is a container to guard. Independent of the
+ *  SDK's activity renewals, so a deadline is met within a minute of passing
+ *  even when the SDK's busy poll renews its timeout every second. */
+export const IDLE_SWEEP_INTERVAL_MS = 60_000;
+
+/** A request in flight this long is stuck, not service: the longest command
+ *  `/exec` admits (`BASH_TIMEOUT_MAX_MS`, 20 min) plus the SDK backstop and
+ *  output-wait margins with room to spare. Requests are measured one by one
+ *  (each carries its own start), so an overlapping chain of short polls beside
+ *  a long command is never read as one long request. */
+export const INFLIGHT_STUCK_MS = BASH_TIMEOUT_MAX_MS + 10 * 60_000;
+
+/** How often the served-time reaches Durable Object storage: the in-memory
+ *  fact is exact while the object lives, storage is the baseline for the next
+ *  wake, and the pi harness polls every 750 ms — one write per poll would be
+ *  the loudest thing the Worker does. */
+export const PERSIST_EVERY_MS = 10_000;
+
+/** How long the SDK's clean `destroy()` may take before the platform's own
+ *  kill ends the container regardless. The SDK bounds its runtime cleanup at
+ *  30 s; a teardown that has not finished twice that is not going to. */
+export const DESTROY_GRACE_MS = 60_000;
+
+/** The facts the verdict is drawn from. `inflight` holds the start time of
+ *  every request being served right now — a list, not a count, so the oldest
+ *  LIVE request decides "stuck" and a finished one stops counting. */
+export interface IdleLedger {
+  lastServedAt: number;
+  inflight: number[];
+  lastPersistedAt: number;
+}
+
+export function newIdleLedger(now: number): IdleLedger {
+  return { lastServedAt: now, inflight: [], lastPersistedAt: now };
+}
+
+export type IdleVerdict =
+  | { action: "destroy"; why: "idle" | "stuck"; idleMs: number }
+  | { action: "keep"; why: "warm" | "serving"; recheckInMs: number };
+
+/** The decision, pure: destroy when nothing is in flight and the last request
+ *  finished a full window ago, or when the oldest request in flight has been
+ *  there longer than any command may run; keep otherwise. A clock that went
+ *  backwards reads as a fresh request, never as an idle container. */
+export function idleVerdict(ledger: IdleLedger, now: number, sleepAfterMs = SANDBOX_SLEEP_AFTER_MS): IdleVerdict {
+  if (ledger.inflight.length > 0) {
+    const oldest = Math.min(...ledger.inflight);
+    const inflightMs = now - oldest;
+    if (inflightMs >= INFLIGHT_STUCK_MS) return { action: "destroy", why: "stuck", idleMs: inflightMs };
+    return { action: "keep", why: "serving", recheckInMs: IDLE_SWEEP_INTERVAL_MS };
+  }
+  const idleMs = now - ledger.lastServedAt;
+  if (idleMs >= sleepAfterMs) return { action: "destroy", why: "idle", idleMs };
+  return { action: "keep", why: "warm", recheckInMs: sleepAfterMs - idleMs };
+}
+
+/** What the guard needs from the Durable Object, as plain functions so the
+ *  whole decision — arming, counting, destroying, forcing — is exercised
+ *  against a fake in tests and the Worker's class only forwards. */
+export interface IdleGuardHost {
+  now(): number;
+  /** `ctx.container?.running`: false when the platform says stopped, true when
+   *  running, undefined when the object cannot tell — guarded like running. */
+  containerRunning(): boolean | undefined;
+  /** Whether a sweep callback is already scheduled (the SDK's schedule table). */
+  sweepScheduled(): Promise<boolean>;
+  scheduleSweep(delayMs: number): Promise<void>;
+  /** The SDK's clean teardown (`Sandbox.destroy()`): sessions closed, the
+   *  container SIGKILLed at the end. May hang or throw; the guard bounds it. */
+  destroySandbox(): Promise<void>;
+  /** The platform primitive (`ctx.container.destroy()`): the microVM is gone. */
+  killContainer(): Promise<void>;
+  loadLastServedAt(): Promise<number | undefined>;
+  saveLastServedAt(at: number): Promise<void>;
+  log(event: Record<string, unknown>): void;
+  wait(ms: number): Promise<void>;
+}
+
+export type IdleStopSource = "sweep" | "sdk-expiry";
+
+export class IdleGuard {
+  readonly ledger: IdleLedger;
+  private armed = false;
+  private destroying: Promise<void> | null = null;
+
+  constructor(private readonly host: IdleGuardHost) {
+    this.ledger = newIdleLedger(host.now());
+  }
+
+  /** On every Durable Object wake (its constructor): the stored served-time is
+   *  the baseline when there is one — a container found awake with no record
+   *  is idle from now, so a fleet leaked before this code arrived is gone one
+   *  window after the deploy — and one sweep is armed when a container may be
+   *  running and none is scheduled. */
+  async wake(): Promise<void> {
+    const stored = await this.host.loadLastServedAt();
+    if (stored !== undefined) {
+      this.ledger.lastServedAt = stored;
+      this.ledger.lastPersistedAt = stored;
+    }
+    if (this.guarding()) await this.arm();
+  }
+
+  /** Every request the object serves runs inside this: counted in flight from
+   *  its start (so a live command is never idle), recorded at its finish
+   *  (success or failure alike), persisted on the persist cadence. */
+  async served<T>(op: () => Promise<T>): Promise<T> {
+    const startedAt = this.host.now();
+    this.ledger.inflight.push(startedAt);
+    try {
+      await this.arm();
+      return await op();
+    } finally {
+      const i = this.ledger.inflight.indexOf(startedAt);
+      if (i >= 0) this.ledger.inflight.splice(i, 1);
+      const now = this.host.now();
+      this.ledger.lastServedAt = now;
+      if (now - this.ledger.lastPersistedAt >= PERSIST_EVERY_MS) {
+        this.ledger.lastPersistedAt = now;
+        try {
+          await this.host.saveLastServedAt(now);
+        } catch (err) {
+          this.host.log({ event: "sandbox.idle-ledger.persist-failed", error: String(err) });
+        }
+      }
+    }
+  }
+
+  /** The scheduled callback. The SDK deletes a schedule row once it has run,
+   *  so the guard re-arms itself here while there is a container to guard;
+   *  with none (destroyed, or never started), the next request arms it. */
+  async sweep(): Promise<void> {
+    this.armed = false;
+    await this.enforce("sweep");
+    if (this.guarding()) await this.arm();
+  }
+
+  /** The SDK's `onActivityExpired`, answered by the same verdict — its
+   *  process and terminal probes never decide. */
+  async expired(): Promise<void> {
+    await this.enforce("sdk-expiry");
+  }
+
+  private guarding(): boolean {
+    return this.host.containerRunning() !== false || this.ledger.inflight.length > 0;
+  }
+
+  private async arm(): Promise<void> {
+    if (this.armed) return;
+    if (!(await this.host.sweepScheduled())) await this.host.scheduleSweep(IDLE_SWEEP_INTERVAL_MS);
+    this.armed = true;
+  }
+
+  private async enforce(source: IdleStopSource): Promise<void> {
+    if (this.destroying) return this.destroying;
+    if (!this.guarding()) return;
+    const verdict = idleVerdict(this.ledger, this.host.now());
+    if (verdict.action === "keep") return;
+    this.destroying = this.destroy(verdict, source).finally(() => {
+      this.destroying = null;
+    });
+    return this.destroying;
+  }
+
+  /** The SDK's clean destroy, bounded; then the platform's kill unless the
+   *  container is known stopped. The guarantee lives in the second step. */
+  private async destroy(verdict: Extract<IdleVerdict, { action: "destroy" }>, source: IdleStopSource): Promise<void> {
+    const base = { why: verdict.why, idleMs: verdict.idleMs, source, sleepAfterMs: SANDBOX_SLEEP_AFTER_MS };
+    this.host.log({ event: "sandbox.idle-stop", ...base });
+    let outcome: "done" | "timeout" | "failed";
+    let error: string | undefined;
+    try {
+      outcome = await Promise.race([
+        this.host.destroySandbox().then(() => "done" as const),
+        this.host.wait(DESTROY_GRACE_MS).then(() => "timeout" as const),
+      ]);
+    } catch (err) {
+      outcome = "failed";
+      error = String(err);
+    }
+    if (outcome === "done" && this.host.containerRunning() === false) return;
+    this.host.log({ event: "sandbox.idle-stop.forced", ...base, outcome, ...(error ? { error } : {}) });
+    try {
+      await this.host.killContainer();
+    } catch (err) {
+      this.host.log({ event: "sandbox.idle-stop.kill-failed", ...base, error: String(err) });
+    }
+  }
+}