@coreplane/switchboard 1.259.0 → 1.260.1

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

@@ -1221,9 +1221,12 @@ interface ThreadBinding {
 /** What one image reconcile decided (`reconcileImage`): the container was
  *  stopped to restart on the current image (`restarted`), already runs it
  *  (`current`), is not running so the next start uses it anyway (`inactive`),
- *  or is busy — an operation, an attach or a registered run in flight — and
- *  the restart is deferred to the next quiet check (`deferred`). */
-type ImageReconcileResult = "restarted" | "current" | "inactive" | "deferred";
+ *  is busy — an operation, an attach or a registered run in flight — and the
+ *  restart is deferred to the next quiet check (`deferred`), or predates the
+ *  deploy on the attach path, which never stops a container (issue 2101): the
+ *  attach is refused so the new run takes the fallback sandbox, and the
+ *  restart stays the refresh cycle's or the deploy's (`stale`). */
+type ImageReconcileResult = "restarted" | "current" | "inactive" | "deferred" | "stale";
 
 interface AttachOk {
   workspace: string;
@@ -3406,6 +3409,7 @@ export class ResidentDO extends Sandbox<Env> {
     if ((await this.restoreCheckout(snap, deadlineMs)).done) {
       // Raced a container start that already had the right disk.
       await this.setResidentState("warm");
+      await this.reportPendingImageCurrent("hydrate");
       return;
     }
     // The snapshot carries the checkout's tree, not the store (item 59): adopt
@@ -3479,6 +3483,11 @@ export class ResidentDO extends Sandbox<Env> {
       lastRestore: { at: new Date(systemClock()).toISOString(), ms: systemClock() - t0 },
     } satisfies RepoFacts);
     await this.setResidentState("warm");
+    // This is the deploy reconcile's missing fact: the replacement itself has
+    // started, restored its snapshot and become usable. Reporting after `warm`
+    // avoids both clearing the marker on stop and probing while restore still
+    // owns the fresh container (issue 2101).
+    await this.reportPendingImageCurrent("hydrate");
   }
 
   // -- freshness (the refresh cycle's phases, one per instance step) -----------
@@ -4177,8 +4186,8 @@ export class ResidentDO extends Sandbox<Env> {
   }
 
   /** Run one step of the refresh instance: counted in flight once past the
-   *  entry gates (so an attach-path reconcileImage never stops the container
-   *  under it — while the gates themselves, `isIdle`, `reconcileImage("refresh")`
+   *  entry gates (so a concurrent reconcile — the deploy's — never stops the
+   *  container under it — while the gates themselves, `isIdle`, `reconcileImage("refresh")`
    *  and the disk-full recycle, must not see the probing cycle as an operation
    *  in flight, or no resident would ever park, restart a stale image or
    *  recycle a full disk; the step is handed `cycle.count` and calls it once
@@ -5011,26 +5020,26 @@ export class ResidentDO extends Sandbox<Env> {
    *  restart decided on the op counters alone stops the container under a live
    *  run — stop the container so it restarts on the current image (state is DO
    *  storage + R2 — the disk is a cache). A deferred restart re-checks on
-   *  every later attach and refresh cycle until the resident is quiet; a
-   *  registration whose release never came defers it only until the clean-idle
-   *  sweep drains that registration. Answers `restarted` when a stop was
-   *  issued, else why not. */
-  private async reconcileImage(where: string, force = false): Promise<ImageReconcileResult> {
+   *  every later refresh cycle until the resident is quiet; a registration
+   *  whose release never came defers it only until the clean-idle sweep drains
+   *  that registration. The attach path never stops the container (issue 2101,
+   *  the `stale` answer below); the stop is the refresh cycle's or the
+   *  deploy's alone. Answers `restarted` when a stop was issued, else why
+   *  not. */
+  private async reconcileImage(where: "attach" | "refresh" | "deploy", force = false): Promise<ImageReconcileResult> {
     if (!(await this.isRuntimeActive().catch(() => false))) {
-      // An inactive container's next start is on the deployed image by
-      // construction — and a held resident whose container idled out has no
-      // other reporter left: new attaches are refused by the very drain the
-      // hold keeps standing, so without this report the fleet stays closed
-      // until the drain's `until` backstop (issue 1931).
-      await this.reportPendingImageCurrent(where);
+      // Inactivity proves only that the old process is gone, not that its
+      // replacement started successfully. Keep the marker: the next refresh's
+      // hydration starts the deployed image and reports only after it reaches
+      // `warm` (issue 2101).
       return "inactive";
     }
     const last = THREAD_USERS[THREAD_USERS.length - 1];
     // A pending report marker (issue 1931) means a deploy could not verify this
     // container on its image: the probe shortcut below is a POOL-USER check the
     // pre-deploy image passes when the pool did not change, so it can never
-    // satisfy the marker — the container is treated as stale until it is cycled
-    // post-deploy and the fresh start reported.
+    // satisfy the marker — the container is treated as stale until it is
+    // cycled post-deploy.
     const pending = await this.ctx.storage.get<{ resource: string }>(IMAGE_REPORT_PENDING_KEY);
     if (!force && pending === undefined) {
       const probe = await this.run(["id", "-u", last]);
@@ -5041,6 +5050,22 @@ export class ResidentDO extends Sandbox<Env> {
       : pending !== undefined
         ? "a deploy's new-image report is pending, so the running container cannot be trusted current"
         : `${last} missing in the running container`;
+    if (where === "attach") {
+      // An attach is never what restarts the container (issue 2101): the
+      // post-deploy restart loop was exactly this — each attach stopped the
+      // container the previous attach had stopped and probed a fresh start
+      // still restoring, so the marker never cleared. While the marker is
+      // pending every NEW attach is refused (`stale`) — the run takes the
+      // fallback sandbox and the resident can go quiet for the refresh cycle's
+      // restart; a stale pool with no marker keeps admitting onto a busy
+      // container, as the deferral always did.
+      if (pending === undefined && (this.inFlightCount() > 0 || (await this.registeredRunsBeyondOps()) > 0)) {
+        console.log(`image-stale (attach): ${stale} but the container is busy — deferring to the refresh cycle`);
+        return "deferred";
+      }
+      console.log(`image-stale (attach): ${stale} — the attach is refused; the refresh cycle restarts the container`);
+      return "stale";
+    }
     const busy = this.inFlightCount();
     if (busy > 0) {
       console.log(`image-stale (${where}): ${stale} but ${busy} operation(s)/attach(es) in flight — deferring restart`);
@@ -5056,32 +5081,22 @@ export class ResidentDO extends Sandbox<Env> {
     console.log(`image-stale (${where}): ${stale} — stopping so it restarts on the current image`);
     this.swapIncarnation(); // deliberate incarnation swap
     await this.stop().catch((err) => console.log(`image-stale: stop failed: ${errMsg(err)}`));
-    if (pending !== undefined) {
-      // The post-deploy cycle just happened: probe the FRESH container — the
-      // SDK boots it for this command on the image the deployed Worker pins,
-      // so a fresh start answering after the deploy is the verified fact
-      // (issue 1931), never the pool-user probe on the old process. A failed
-      // probe keeps the marker: the next reconcile tries the cycle again.
-      const fresh = await this.run(["id", "-u", last])
-        .then((p) => p.exitCode === 0)
-        .catch(() => false);
-      if (fresh) await this.reportPendingImageCurrent(where);
-      else
-        console.log(`image-stale (${where}): the fresh container's probe failed — the new-image report stays pending`);
-    }
+    // A successful stop proves only that the old process is gone. The pending
+    // marker deliberately survives it: the replacement's own hydration reports
+    // after reaching `warm`, so `imageReport: current` can never precede a
+    // successful post-deploy start (issue 2101).
     return "restarted";
   }
 
   /** The report a held drain waits for (issue 1931): when the deploy's
    *  reconcile could not verify this resident's fresh container on the new
    *  image, a marker stays in storage and the registry holds the drain. The
-   *  fact the report stands on is a fresh container start AFTER the deploy —
-   *  the marker makes `reconcileImage` treat the container as stale until the
-   *  cycle happens, so this is called only behind that fresh start (or on an
-   *  inactive resident, whose next start is on the new image by construction).
-   *  The marker is deleted only after a successful report: a transient failure
-   *  keeps it for the next reconcile, and the drain's `until` is the backstop
-   *  for a report that never lands. */
+   *  fact the report stands on is the replacement's own completed hydration:
+   *  the fresh container has restored its snapshot and reached `warm`. A stop
+   *  or inactive runtime does not report; each keeps the marker for that next
+   *  start (issue 2101). The marker is deleted only after a successful report:
+   *  a transient failure keeps it for the next reconcile, and the drain's
+   *  `until` is the backstop for a report that never lands. */
   private async reportPendingImageCurrent(where: string): Promise<boolean> {
     const pending = await this.ctx.storage.get<{ resource: string }>(IMAGE_REPORT_PENDING_KEY);
     if (pending === undefined) return true;
@@ -5107,12 +5122,12 @@ export class ResidentDO extends Sandbox<Env> {
    *  tell the pre-deploy image from the new one when the pool did not change,
    *  and the platform replaces the container processes asynchronously after an
    *  image-changing deploy (issue 1931) — so this path never trusts "current":
-   *  an active, quiet container is always cycled, and the fresh start —
-   *  necessarily on the deploy's image, which landed before this call — is
-   *  probed. `verified` true is the fact the reopen may stand on; anything
-   *  else (deferred, a failed fresh probe) leaves a hold on the drain, cleared
-   *  by this resident's later report (`reportPendingImageCurrent`), never by a
-   *  timer.
+   *  an active, quiet container is always cycled, but that stop is not a report.
+   *  The marker survives until the replacement hydrates and reaches `warm` on
+   *  the deploy's image (issue 2101: the old probe raced that restore and lost).
+   *  `verified` true is the fact the reopen may stand on; a cycle or inactive
+   *  result leaves a hold on the drain, cleared by this resident's later
+   *  `reportPendingImageCurrent`, never by a timer.
    *
    *  The hold lands BEFORE the marker: the marker is what lets any concurrent
    *  attach/refresh reconcile report, and a report that reaches the registry
@@ -5124,10 +5139,10 @@ export class ResidentDO extends Sandbox<Env> {
     await this.ctx.storage.put(IMAGE_REPORT_PENDING_KEY, { resource });
     const result = await this.reconcileImage("deploy", true);
     if (result === "deferred") return { result, verified: false };
-    // Inactive: the inactive early-return reported (the next start is on the
-    // new image by construction). Restarted: the cycle's fresh probe and
-    // report ran inside reconcileImage. Either way the marker gone is the
-    // verification.
+    // Neither inactivity nor a successful stop is verification: only the
+    // replacement's completed hydration clears the marker. A concurrent fresh
+    // start may have done so while this reconcile yielded, hence the storage
+    // read rather than an unconditional false.
     const verified = (await this.ctx.storage.get(IMAGE_REPORT_PENDING_KEY)) === undefined;
     return { result, verified };
   }
@@ -5471,12 +5486,19 @@ export class ResidentDO extends Sandbox<Env> {
       const memory = await this.memoryGate("attach", registered);
       if (memory) return memory;
       const resourceId = (await this.ctx.storage.get<string>(RESOURCE_KEY)) ?? "";
-      if ((await this.reconcileImage("attach")) === "restarted") {
+      // An attach never restarts the container (issue 2101): a `stale` verdict
+      // refuses the NEW run — it falls back to the seeded sandbox — while a
+      // registered run's re-attach passes exactly as it passes the drain and
+      // the memory gate; the restart itself is the refresh cycle's or the
+      // deploy's.
+      if ((await this.reconcileImage("attach")) === "stale" && !registered) {
+        const s = await this.getStatus();
         return {
-          error: "image-stale: the container predates the current pool and is restarting; retry shortly",
+          error:
+            "image-stale: the container predates the deploy and restarts on the next quiet refresh; new runs use the fallback sandbox until then",
           status: 503,
-          state: "restoring",
-          stateReason: "",
+          state: s.state,
+          stateReason: s.reason,
           reason: "image-stale",
         };
       }

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

@@ -48,11 +48,14 @@ ENV NODE_OPTIONS=--max-old-space-size=8192
 # item 25) restores the resident's snapshot with the SDK's presigned restore,
 # which MOUNTS the archive (squashfuse + fuse-overlayfs) instead of extracting
 # it; the Worker extracts it onto the disk the way the resident does
-# (resident-repos item 61) so the checkout is one plain ext4 tree. The build
-# asserts the binary with the probe the extract script uses (`command -v`).
+# (resident-repos item 61) so the checkout is one plain ext4 tree.
+# ripgrep (`rg`): the search binary is an image invariant for both fresh and
+# seeded sandboxes; restoring a seed changes the disk, not the image tools.
+# The build asserts both binaries with the probes their callers use.
 RUN apt-get update \
-  && apt-get install -y --no-install-recommends git curl ca-certificates docker.io iptables squashfs-tools \
+  && apt-get install -y --no-install-recommends git curl ca-certificates docker.io iptables squashfs-tools ripgrep \
   && command -v unsquashfs >/dev/null \
+  && command -v rg >/dev/null \
   && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
        -o /usr/share/keyrings/githubcli-archive-keyring.gpg \
   && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \

package/dist/assets/deploy/profile.example.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "The deployment profile: where THIS installation runs. Copy to deploy/profile.json and fill it in (or run `switchboard deploy init`). The account is your Cloudflare account id; every hostname must be under `zone`, a zone in that account, unless the Worker names its own `zone` (also in the account); `workers.bot` is the one required Worker — leave `memory`, `resident` or `sandbox` out and `deploy plan` has no step for them (a bot-only profile is a one-step plan; without `memory` the config is not pushed anywhere). The project's docs site is not a Worker of an installation: it is the project's website, deployed by the project's own CI from project.json, so there is no `docs` entry. `configSource` is where `deploy all` reads the bot's runtime config from before building the image — a path, `github://owner/repo/path@ref` (needs CONFIG_REPO_TOKEN), or `op://Vault/Item/field` (needs OP_SERVICE_ACCOUNT_TOKEN); `secretsSource` is where `secrets put` reads values from — a directory of <NAME> files (the default when absent) or `op://Vault/Item`. `images` is where the bot, resident and sandbox container images come from: `registry` — the release's published images, copied once per version into your account registry by `deploy all` itself (or `deploy images` ahead of it) over HTTPS and referenced from there — no Docker anywhere, a Cloudflare API token with Containers Edit in CLOUDFLARE_API_TOKEN for the copy (an installation deploying published images; what `init` writes from the published package); or `build` (the default when absent) — each Worker's Dockerfile, built by wrangler where `deploy all` runs (a checkout; the project's own production). `artifacts` (optional) names the R2 bucket a run's files move through (docs/reference/specs/execution.md item 20): with it the bot Worker binds the bucket and `deploy` creates it before the upload (the credential then needs Workers R2 Storage: Edit); the bot's runtime config `artifacts.r2.bucket` must say the same name. `metrics` (optional) names the Analytics Engine dataset every finished run's point is written to (docs/reference/specs/run-metrics.md): the state Worker's template then binds it as `RUN_METRICS` with the name beside it in `RUN_METRICS_DATASET` — nothing is created ahead of the deploy, the platform creates the dataset on first write — and the bot's runtime config `metrics.dataset` must say the same name (the bot warns at boot when the two differ). `deploy plan` reads this example when no profile exists; `deploy all` refuses it.",
+  "$comment": "The deployment profile: where THIS installation runs. Copy to deploy/profile.json and fill it in (or run `switchboard deploy init`). The account is your Cloudflare account id; every hostname must be under `zone`, a zone in that account, unless the Worker names its own `zone` (also in the account); `workers.bot` is the one required Worker — leave `memory`, `resident` or `sandbox` out and `deploy plan` has no step for them (a bot-only profile is a one-step plan; without `memory` the config is not pushed anywhere). The project's docs site is not a Worker of an installation: it is the project's website, deployed by the project's own CI from project.json, so there is no `docs` entry. `configSource` is where `deploy all` reads the bot's runtime config from before building the image — a path, `github://owner/repo/path@ref` (needs CONFIG_REPO_TOKEN), or `op://Vault/Item/field` (needs OP_SERVICE_ACCOUNT_TOKEN); `restart.deployer` is the SWITCHBOARD_INGRESS_TOKENS subject the Worker itself allows to restart the bot, independent of runtime config so config recovery cannot lock itself out; `secretsSource` is where `secrets put` reads values from — a directory of <NAME> files (the default when absent) or `op://Vault/Item`. `images` is where the bot, resident and sandbox container images come from: `registry` — the release's published images, copied once per version into your account registry by `deploy all` itself (or `deploy images` ahead of it) over HTTPS and referenced from there — no Docker anywhere, a Cloudflare API token with Containers Edit in CLOUDFLARE_API_TOKEN for the copy (an installation deploying published images; what `init` writes from the published package); or `build` (the default when absent) — each Worker's Dockerfile, built by wrangler where `deploy all` runs (a checkout; the project's own production). `artifacts` (optional) names the R2 bucket a run's files move through (docs/reference/specs/execution.md item 20): with it the bot Worker binds the bucket and `deploy` creates it before the upload (the credential then needs Workers R2 Storage: Edit); the bot's runtime config `artifacts.r2.bucket` must say the same name. `metrics` (optional) names the Analytics Engine dataset every finished run's point is written to (docs/reference/specs/run-metrics.md): the state Worker's template then binds it as `RUN_METRICS` with the name beside it in `RUN_METRICS_DATASET` — nothing is created ahead of the deploy, the platform creates the dataset on first write — and the bot's runtime config `metrics.dataset` must say the same name (the bot warns at boot when the two differ). `deploy plan` reads this example when no profile exists; `deploy all` refuses it.",
   "account": "00000000000000000000000000000000",
   "zone": "example.com",
   "workers": {
@@ -9,5 +9,6 @@
     "sandbox": { "script": "switchboard-sandbox", "hostname": "switchboard-sandbox.example.com" }
   },
   "configSource": "config/config.yaml",
+  "restart": { "deployer": "deployer" },
   "images": "registry"
 }

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.259.0",
+  "version": "1.260.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.259.0",
+      "version": "1.260.1",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -20445,7 +20445,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.259.0",
+      "version": "1.260.1",
       "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.259.0",
+  "version": "1.260.1",
   "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.259.0",
-  "commit": "0b28f0fb4925d069547233cbae61f1d3187972d8",
-  "builtAt": "2026-09-21T02:10:55.399Z"
+  "version": "1.260.1",
+  "commit": "c57cb7b614e8916b3fd0ab86c848a8398d8dc781",
+  "builtAt": "2026-09-21T18:18:08.788Z"
 }

package/dist/assets/src/agents/registry.ts

@@ -47,11 +47,9 @@ export function machineNeedsRepo(machine: MachineClass): boolean {
 export const IDENTITIES = ["none", "read", "write"] as const;
 export type Identity = (typeof IDENTITIES)[number];
 
-/** The model tiers a preset may run on (the one-door plan's tiers rule): the
- *  `fast` tier is the router's own model (`routing.model`), everything else is
- *  `strong`. Each preset declares its allowed set below (`AgentDef.tiers`);
- *  a parent choosing a child's model at spawn is held to the child preset's
- *  set, and escalation is a new run — a run's tier is fixed at dispatch. */
+/** The model tiers a preset may run on. The retired classifier leaves no
+ *  configured fast-tier ref, so current run models resolve strong; declarations
+ *  remain explicit for model-card tiering and future configured catalogues. */
 export const MODEL_TIERS = ["fast", "strong"] as const;
 export type ModelTier = (typeof MODEL_TIERS)[number];
 

package/dist/assets/src/core/authz/policy.ts

@@ -118,6 +118,11 @@ export const POLICY: readonly Rule[] = [
   // `pulls rebase` force-pushes the pipeline's branches and can start a paid
   // fix round (record 0071): a grant, never a chat baseline.
   { action: "pulls:write", resource: "command", when: [grant("pulls:write")] },
+  // `pulls merge|enqueue` (record 0070, criterion 4): a person's merge through
+  // the door — the grant, never a baseline, so a grant-less person has a
+  // thread that reads everything and merges nothing. The release pull
+  // request's handoff and the approval fences are the handler's own refusals.
+  { action: "merge:write", resource: "command", when: [grant("merge:write")] },
 
   // ── repos ────────────────────────────────────────────────────────────────
   { action: "repo:read", resource: "command", when: [grant("repo:read")] },

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

@@ -104,11 +104,18 @@ export const HARNESS_PROBE_WAIT_MS = 5 * MINUTE_MS;
  *  `maxMinutes` so one nobody lifted is an hour and a half, not a day. A run
  *  asked during a drain waits at its attach one `pollMs` at a time under its
  *  own lease less `leaseReserveMs` (what the attach and the work after it
- *  need), `waitMaxMs` with no lease to clip it. */
+ *  need), `waitMaxMs` with no lease to clip it — unless a fallback stands
+ *  behind the attach: `fallbackWaitMs` bounds the wait by the FALLBACK's own
+ *  cost, never the deploy's (issue 2101: a run refused by the drain waited
+ *  18 minutes for the whole deploy, then did the job in a seeded sandbox that
+ *  stands up in about two), so a drain refusal on a first attach falls to the
+ *  seeded sandbox after at most a few minutes; a re-attach with no fallback —
+ *  a resumed run, a mid-run recovery — keeps the lease's bound. */
 export const DRAIN = {
   pollMs: 30_000,
   waitMaxMs: 60 * MINUTE_MS,
   leaseReserveMs: 10 * MINUTE_MS,
+  fallbackWaitMs: 3 * MINUTE_MS,
   deployWaitMaxMs: 60 * MINUTE_MS,
   marginMinutes: 5,
   maxMinutes: 90,
@@ -218,11 +225,10 @@ export const MERGE_WAIT_ASK_MINUTES = 60;
  *  request's line with the conflict named, never a retry loop. */
 export const PULL_SWEEP = { leaseMinutes: 15, spendCapUsd: 5 } as const;
 
-/** The provider retry ladder (issue 1932): the backoff before each retry of a
- *  transient model-call failure — a gateway 5xx, a stream cut before
- *  `message_stop`, a gateway timeout. Three attempts with growing waits,
- *  charged to the run's lease; the waits stay small next to the run's minutes
- *  because the observed blips are edge transients of seconds. */
+/** The provider retry ladder: the first backoffs for a transport-class
+ *  model-call failure. The final rung repeats while the run's loop lease has
+ *  time, so these are pacing intervals rather than a three-attempt terminal
+ *  budget. */
 export const PROVIDER_RETRY_BACKOFFS_MS = [5_000, 15_000, 45_000] as const;
 
 /** A hosted ship parent's deadline margin past the pipeline's wall clock
@@ -236,6 +242,13 @@ export const HOSTED_DEADLINE_MARGIN_MINUTES = 60;
  *  and the pause before a busy spawn is asked again. */
 export const SHIP_WAIT = { marginMinutes: 5, chunkMinutes: 5, mergeChunkMinutes: 5, busyRetryMinutes: 2 } as const;
 
+/** How long a restarting close gives its replacement dispatch to claim the
+ *  same run before a read with no successor treats the close as final
+ *  (run-history item 47a). One whole coordinator wait chunk lets an ordinary
+ *  replacement claim without shortening the parent's first wait; a successor
+ *  found after this deadline still wins because read-record searches first. */
+export const RESTART_CLAIM_GRACE_MS = minutesToMs(SHIP_WAIT.chunkMinutes);
+
 /** The plane's table (docs/decisions/0064): how long a finished run stays on
  *  it, a reservation's window, and the default re-ask cadence — how often a
  *  silent resident something waits on is probed (`plane.reaskMinutes`

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

@@ -111,12 +111,24 @@ export interface ThreadEventAttachment {
   mediaType: string;
   data: string;
   name?: string;
+  /** The accepted channel file's by-reference source, when one exists, so the
+   *  coding child can stage it without moving the inline bytes through a
+   *  second request. */
+  staged?: {
+    name: string;
+    size: number;
+    type: string;
+    url: string;
+    messageId: string;
+    workspaceIndex?: number;
+  };
 }
 
 export interface ThreadEvent {
   /** Assigned by the store's append, in arrival order, per unit. */
   seq: number;
-  /** The channel's message id, when the platform gave one. */
+  /** The channel's message id, or another producer's stable event id. An
+   *  append that repeats it on one unit returns the original row. */
   id?: string;
   /** The sender (platform-namespaced) and the display name the channel knew. */
   sender: string;
@@ -174,11 +186,24 @@ export function capThreadEvent<T extends Omit<ThreadEvent, "seq"> & { seq?: numb
   }
 }
 
+const isThreadEventStagedFile = (v: unknown): v is NonNullable<ThreadEventAttachment["staged"]> =>
+  isObject(v) &&
+  typeof v.name === "string" &&
+  typeof v.size === "number" &&
+  Number.isInteger(v.size) &&
+  v.size > 0 &&
+  typeof v.type === "string" &&
+  typeof v.url === "string" &&
+  typeof v.messageId === "string" &&
+  (v.workspaceIndex === undefined ||
+    (typeof v.workspaceIndex === "number" && Number.isInteger(v.workspaceIndex) && v.workspaceIndex >= 0));
+
 const isThreadEventAttachment = (v: unknown): v is ThreadEventAttachment =>
   isObject(v) &&
   typeof v.mediaType === "string" &&
   typeof v.data === "string" &&
-  (v.name === undefined || typeof v.name === "string");
+  (v.name === undefined || typeof v.name === "string") &&
+  (v.staged === undefined || isThreadEventStagedFile(v.staged));
 
 const isThreadEventMode = (v: unknown): v is ThreadEventMode => v === "steer" || v === "wake" || v === "interrupt";
 
@@ -399,6 +424,26 @@ export interface UnitIdle {
   wakes: number;
 }
 
+/** The durable answer to one indexed idle wait. The wait id is the key on the
+ * unit row, so a reclaimed runner receives byte-for-byte the decision the
+ * first caller stored instead of spending a renewal or consuming an event
+ * twice. */
+export type UnitWakeAnswer =
+  | {
+      kind: "segment";
+      index: number;
+      from?: string;
+      runId?: string;
+      spendUsd: number | null;
+      handoff?: Handoff;
+      texts: string[];
+      senders: string[];
+      leaseMs?: number;
+    }
+  | { kind: "answered"; reply: string }
+  | { kind: "stopped" }
+  | { kind: "expired" };
+
 /** What the severity gate caught on a round: the level in force and the gated findings as `id (severity)`. */
 export interface RoundGate {
   level: AddressSeverity;
@@ -456,14 +501,20 @@ export interface CoordinatorUnit {
    *  (null once any run's cost is unknown), `handoff` that child's lists, and
    *  `wakes` how many wakes this idle has answered — zero at the write. */
   idle?: UnitIdle;
+  /** Answers to indexed idle waits, keyed by the wait step's durable identity. */
+  wakes?: Record<string, UnitWakeAnswer>;
   /** The round boundaries the coordinator reported, oldest first (the `ship_round`
    *  vocabulary). `gate` rides an approve the machine's severity check caught
    *  carrying a finding at or above the level in force ([agent-ship](../../../docs/reference/specs/agent-ship.md)
    *  item 9) — a mismatch to be seen, since the child's parser holds an approve
    *  to the same level. */
   rounds: Array<{ index: number; agent: string; outcome: string; at: number; gate?: RoundGate }>;
-  /** How the unit ended: the ending's kind and the thread's report, when it has. */
-  ending?: { kind: string; report: string; at: number };
+  /** How the unit ended: the ending's kind and the thread's report, when it
+   *  has. `cause` names the machine's reason behind a driver-posted kind;
+   *  `step` and `round` locate that reason without parsing the report. For a
+   *  `step_threw` failure the driver records all available fields before it
+   *  rethrows (issue 2100); unit-start has no round yet. */
+  ending?: { kind: string; report: string; at: number; cause?: string; step?: string; round?: number };
   startedAt?: number;
 }
 
@@ -548,6 +599,27 @@ const isSegment = (v: unknown): boolean =>
   (v.runId === undefined || isText(v.runId)) &&
   typeof v.at === "number";
 
+export const isUnitWakeAnswer = (v: unknown): v is UnitWakeAnswer => {
+  if (!isObject(v)) return false;
+  if (v.kind === "answered") return typeof v.reply === "string";
+  if (v.kind === "stopped" || v.kind === "expired") return true;
+  return (
+    v.kind === "segment" &&
+    typeof v.index === "number" &&
+    Number.isInteger(v.index) &&
+    v.index >= 1 &&
+    (v.from === undefined || isText(v.from)) &&
+    (v.runId === undefined || isText(v.runId)) &&
+    (v.spendUsd === null || isFinite(v.spendUsd)) &&
+    (v.handoff === undefined || isHandoffShape(v.handoff)) &&
+    Array.isArray(v.texts) &&
+    v.texts.every((text) => typeof text === "string") &&
+    Array.isArray(v.senders) &&
+    v.senders.every((sender) => isText(sender)) &&
+    (v.leaseMs === undefined || (isFinite(v.leaseMs) && v.leaseMs > 0))
+  );
+};
+
 export function isCoordinatorUnit(v: unknown): v is CoordinatorUnit {
   if (!isObject(v)) return false;
   const r = v;
@@ -562,6 +634,13 @@ export function isCoordinatorUnit(v: unknown): v is CoordinatorUnit {
   if (r.lastPush !== undefined && !isText(r.lastPush)) return false;
   if (r.segments !== undefined && (!Array.isArray(r.segments) || !r.segments.every(isSegment))) return false;
   if (r.idle !== undefined && !isUnitIdle(r.idle)) return false;
+  if (
+    r.wakes !== undefined &&
+    (!isObject(r.wakes) ||
+      Array.isArray(r.wakes) ||
+      !Object.entries(r.wakes).every(([waitId, answer]) => STEP_NAME_PATTERN.test(waitId) && isUnitWakeAnswer(answer)))
+  )
+    return false;
   if (
     !Array.isArray(r.rounds) ||
     r.rounds.length > MAX_ROUNDS ||
@@ -578,7 +657,16 @@ export function isCoordinatorUnit(v: unknown): v is CoordinatorUnit {
     return false;
   if (
     r.ending !== undefined &&
-    !(isObject(r.ending) && isText(r.ending.kind) && isText(r.ending.report, MAX_REPORT) && isFinite(r.ending.at))
+    !(
+      isObject(r.ending) &&
+      isText(r.ending.kind) &&
+      isText(r.ending.report, MAX_REPORT) &&
+      isFinite(r.ending.at) &&
+      (r.ending.cause === undefined || isText(r.ending.cause, 64)) &&
+      (r.ending.step === undefined || (typeof r.ending.step === "string" && STEP_NAME_PATTERN.test(r.ending.step))) &&
+      (r.ending.round === undefined ||
+        (typeof r.ending.round === "number" && Number.isInteger(r.ending.round) && r.ending.round >= 0))
+    )
   )
     return false;
   if (r.startedAt !== undefined && !isFinite(r.startedAt)) return false;