@coreplane/switchboard 1.259.0 → 1.260.0

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

@@ -97,7 +97,8 @@ defaults:
   # thinks per turn; lower = much faster turns). Same layering as models —
   # per-channel/user `effort` / `efforts.<agent>` and a per-request `effort:`
   # directive override these; unset → the agent's built-in effort, else the
-  # provider default. Skipped for models without effort support.
+  # provider default. Skipped for models without effort support. The `general`
+  # entry also controls the operator turn on `defaults.models.general`.
   # efforts:
   #   coding: medium
   # How much the bot says about its own doing (docs/reference/specs/routing-and-config.md
@@ -368,7 +369,10 @@ workspaceDir: ./workspaces
 #                       # records (soft delete, status `evicted`) in the same write.
 #   model: anthropic/claude-haiku-4-5
 #                       # <provider>/<model> for the reflection pass — pick a
-#                       # cheap tier. Absent → the run's own resolved model.
+#                       # cheap level. Absent → the run's own resolved model.
+#   effort: low         # how hard the reflection model thinks per distillation —
+#                       # low | medium | high | xhigh | max, applied through the
+#                       # model card; unset → the model's own default.
 
 # Self-improvement proposals (docs/reference/specs/run-friction.md). Every finished run's friction
 # diagnosis (docs/reference/specs/run-friction.md) is stored with its run record, so the
@@ -479,26 +483,11 @@ workspaceDir: ./workspaces
 # spawn:
 #   maxChildren: 3
 
-# The request router (docs/reference/specs/routing-and-config.md item 21). ON BY
-# DEFAULT: a plain message — no `agent:` directive, no sticky preset, no channel
-# or user `agent` — asks the fast model which preset it means and runs as that
-# preset, the card saying why (`routed: <reason>`) and how to run it another way.
-# `ship` is never routed. The one way off, so every plain message runs
-# `defaults.agent` as before the router: `auto: false`. `model` is the router's
-# model; default `defaults.models.general`. `answer` is how that model answers:
-# `tool` (default) forces a call to the router's `route` tool, whose schema is
-# the answer, so prose cannot occur; `text` is the one-JSON-object text contract
-# alone — set it for a provider or model that cannot take a forced tool call.
-# `operator` is the one door's flag (routing-and-config item 29): `on`
-# (default) — the operator's decision is what runs; `shadow` — one operator
-# turn per admitted chat event, ahead of stage A, its decision written beside
-# the routed request in the run store and nothing run from it; `off` — the
-# rollback lever: it turns the operator back off after a bad day, not a choice
-# to make up front. `shadow` and `on` run even under `auto: false`.
+# The one door's mode (routing-and-config item 29): `on` (default) — the
+# operator's typed decision is what runs; `shadow` — one operator turn per
+# admitted chat event, its decision recorded and nothing run from it; `off` —
+# the rollback lever. The retired readers' router has no model or effort key.
 # routing:
-#   auto: false
-#   model: anthropic/claude-haiku-4-5
-#   answer: text
 #   operator: off
 
 # The thread-reply intake gate (docs/decisions/0058-a-thread-reply-is-read-before-it-is-answered-intake-decides-whether-the-bot-was-addressed.md;
@@ -512,14 +501,17 @@ workspaceDir: ./workspaces
 # model call) or `always` (today's answer-every-reply path, byte for byte).
 # Also settable per channel and per user: `intake: { threadReplies: <mode> }`
 # on a `channels.<id>` or `users.<id>` scope, user over channel over here.
-# `model` is the verdict's model; default `routing.model`, else
-# `defaults.models.general`. A mention, a DM and a top-level post never pass
-# through the gate in any mode. A model whose operator card (`providers.<p>.
+# `model` is the verdict's model; default `defaults.models.general`. `effort`
+# is how hard that model thinks per verdict — low | medium | high | xhigh |
+# max, applied through the model card; unset → the model's own default. A
+# mention, a DM and a top-level post never pass through the gate in any mode.
+# A model whose operator card (`providers.<p>.
 # models.<id>.answers`) declares it answers neither a forced tool call nor the
 # text contract is refused at load when the default mode is `classify`.
 # intake:
 #   threadReplies: classify
 #   model: anthropic/claude-haiku-4-5
+#   effort: low
 
 # The orchestration plane (docs/decisions/0064-the-plane-owns-every-runs-state-a-refusal-becomes-a-queue-position-an-ending-is-judged-by-the-ledger-that-saw-it-and-a-release-is-a-quiet-window-a-person-closes.md;
 # docs/reference/specs/routing-and-config.md item 31; orchestration-plane.md).

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

@@ -109,13 +109,16 @@ import {
   isCoordinatorInstance,
   isCoordinatorUnit,
   isThreadEvent,
+  isUnitWakeAnswer,
   sendChildSignal,
   sendRunFinished,
+  STEP_NAME_PATTERN,
   UNIT_PATTERN,
   type CoordinatorInstance,
   type CoordinatorUnit,
   type RunFinishedSend,
   type ThreadEvent,
+  type UnitWakeAnswer,
 } from "../../src/core/coordinator/contract.ts";
 import {
   GEN_PATTERN,
@@ -1848,10 +1851,27 @@ export class RunHistoryDO extends DurableObject<Env> {
         queuedAt: r.queued_at,
         state: r.state as PlaneQueueRow["state"],
       }));
-    const liveThreads = this.sql
-      .exec<{ thread_key: string }>(`SELECT thread_key FROM live_runs WHERE run_id IS NOT ?`, excludeRunId ?? null)
-      .toArray()
-      .map((r) => r.thread_key);
+    const liveRows = this.sql
+      .exec<{ run_id: string; thread_key: string; meta_json: string }>(
+        `SELECT run_id, thread_key, meta_json FROM live_runs WHERE run_id IS NOT ?`,
+        excludeRunId ?? null,
+      )
+      .toArray();
+    const liveThreads = liveRows.map((r) => r.thread_key);
+    const liveRuns = Object.fromEntries(
+      liveRows.flatMap((r) => {
+        const meta = JSON.parse(r.meta_json) as Record<string, unknown>;
+        return typeof meta.channelId === "string"
+          ? [[r.run_id, { channelId: meta.channelId, threadKey: r.thread_key }] as const]
+          : [];
+      }),
+    );
+    const inboxSeqs = Object.fromEntries(
+      this.sql
+        .exec<{ run_id: string; seq: number }>(`SELECT run_id, MAX(seq) AS seq FROM run_inbox GROUP BY run_id`)
+        .toArray()
+        .map((r) => [r.run_id, r.seq]),
+    );
     const levels = this.sql
       .exec<{ resident: string; name: string; side: string; reported_at: number; generation: string }>(
         `SELECT * FROM plane_levels`,
@@ -1864,7 +1884,7 @@ export class RunHistoryDO extends DurableObject<Env> {
         reportedAt: r.reported_at,
         generation: r.generation,
       }));
-    return { queue, liveThreads, reservations, openWindows, levels };
+    return { queue, liveThreads, liveRuns, inboxSeqs, reservations, openWindows, levels };
   }
 
   /** The decider's writes, applied inside the same `transactionSync` that read
@@ -1971,21 +1991,19 @@ export class RunHistoryDO extends DurableObject<Env> {
           this.sql.exec<{ n: number }>(`SELECT COUNT(*) AS n FROM plane_effects WHERE acked_at IS NULL`).toArray()[0]
             ?.n ?? 0,
         );
+        const effectRunId = w.effect.kind === "admit" || w.effect.kind === "steer" ? w.effect.runId : undefined;
         const forRun =
-          w.effect.kind === "admit"
-            ? Number(
+          effectRunId === undefined
+            ? 0
+            : Number(
                 this.sql
-                  .exec<{
-                    n: number;
-                  }>(
-                    // Exact id matching (`admit:<runId>`): the seal runs with bot-minted
-                    // run ids, and a LIKE would read `%`/`_` in one as wildcards.
-                    `SELECT COUNT(*) AS n FROM plane_effects WHERE acked_at IS NULL AND id = 'admit:' || ?`,
-                    w.effect.runId,
+                  .exec<{ n: number }>(
+                    `SELECT COUNT(*) AS n FROM plane_effects
+                     WHERE acked_at IS NULL AND json_extract(body_json, '$.runId') = ?`,
+                    effectRunId,
                   )
                   .toArray()[0]?.n ?? 0,
-              )
-            : 0;
+              );
         const refusal = effectCapRefusal({ total, forRun }, w.effect);
         if (refusal !== undefined) throw new Error(refusal);
         // A re-offer lands after an ack for any kind — a probe re-probes after
@@ -2330,6 +2348,13 @@ export class RunHistoryDO extends DurableObject<Env> {
         // Exact id matching (`admit:<runId>`), never LIKE: a bot-minted run id
         // can carry `%` or `_`, which a pattern would read as wildcards.
         this.sql.exec(`DELETE FROM plane_effects WHERE acked_at IS NULL AND id = 'admit:' || ?`, runId);
+        this.sql.exec(
+          `DELETE FROM plane_effects
+           WHERE acked_at IS NULL
+             AND json_extract(body_json, '$.kind') = 'steer'
+             AND json_extract(body_json, '$.runId') = ?`,
+          runId,
+        );
         // The run's steer dedupe rows and any park go with it (record 0064):
         // a sealed run holds no turn and reads no steer.
         this.sql.exec(`DELETE FROM plane_reservations WHERE kind IN ('steer', 'park') AND run_id = ?`, runId);
@@ -2434,12 +2459,54 @@ export class RunHistoryDO extends DurableObject<Env> {
     this.sql.exec(`INSERT OR REPLACE INTO meta (key, value) VALUES ('plane_disagreements', ?)`, JSON.stringify(counts));
   }
 
+  /** Fence a pushed steer to the owning live generation before its local
+   *  registry is touched. The effect check, owner check and lease renewal are
+   *  one transaction: an expired owner may renew before reclaim, but reclaim
+   *  can never cross the synchronous local delivery that follows a success. */
+  async planeFenceSteer(
+    id: string,
+    runId: string,
+    gen: string,
+    leaseMs: number,
+    now: number,
+  ): Promise<{ accepted: boolean }> {
+    let accepted = false;
+    this.ctx.storage.transactionSync(() => {
+      const offered = this.sql
+        .exec<{ body_json: string }>(`SELECT body_json FROM plane_effects WHERE id = ? AND acked_at IS NULL`, id)
+        .toArray()[0];
+      if (!offered) return;
+      const effect = JSON.parse(offered.body_json) as PlaneEffect;
+      if (effect.kind !== "steer" || effect.runId !== runId) return;
+      const live = this.liveRow(runId);
+      if (!live || live.ownerGen !== gen || live.phase !== "live") return;
+      this.sql.exec(`UPDATE live_runs SET lease_until = ? WHERE run_id = ?`, now + leaseMs, runId);
+      accepted = true;
+    });
+    if (accepted) await this.ensurePlaneAlarm(now);
+    return { accepted };
+  }
+
   /** An effect's acknowledgement by id (orchestration-plane item 7): `done` and `skipped` close it,
-   *  `deferred` leaves it offered for the next answer. An unknown id is a
-   *  no-op — the bot may ack an effect an older table never held. */
-  planeAck(id: string, outcome: PlaneAckOutcome, now: number): { ok: true } {
-    if (outcome !== "deferred")
-      this.sql.exec(`UPDATE plane_effects SET acked_at = ? WHERE id = ? AND acked_at IS NULL`, now, id);
+   *  `deferred` leaves it offered for the next answer. A steer is special: the
+   *  acknowledging generation must still own its live row. A stale process
+   *  may retain registry state during reclaim overlap, but it cannot close the
+   *  durable offer. An unknown id is a no-op. */
+  planeAck(id: string, outcome: PlaneAckOutcome, now: number, owner?: { runId: string; gen: string }): { ok: true } {
+    if (outcome === "deferred") return { ok: true };
+    const offered = this.sql
+      .exec<{ body_json: string }>(`SELECT body_json FROM plane_effects WHERE id = ? AND acked_at IS NULL`, id)
+      .toArray()[0];
+    if (!offered) return { ok: true };
+    const effect = JSON.parse(offered.body_json) as PlaneEffect;
+    if (effect.kind === "steer") {
+      if (!owner || owner.runId !== effect.runId) return { ok: true };
+      const live = this.sql
+        .exec<{ owner_gen: string }>(`SELECT owner_gen FROM live_runs WHERE run_id = ?`, owner.runId)
+        .toArray()[0];
+      if (live?.owner_gen !== owner.gen) return { ok: true };
+    }
+    this.sql.exec(`UPDATE plane_effects SET acked_at = ? WHERE id = ? AND acked_at IS NULL`, now, id);
     return { ok: true };
   }
 
@@ -2543,7 +2610,8 @@ export class RunHistoryDO extends DurableObject<Env> {
   // ---- the thread events of a unit-owned thread (record 0051's reply-as-event rule) --------------
 
   /** The next sequence assigned in one transaction, the per-event cap applied
-   *  (attachments dropped whole, the row saying how many). */
+   *  (attachments dropped whole, the row saying how many). A stable event id
+   *  already on the unit returns its first sequence without another row. */
   async appendUnitEvent(
     instanceId: string,
     unit: string,
@@ -2551,6 +2619,20 @@ export class RunHistoryDO extends DurableObject<Env> {
   ): Promise<{ ok: true; seq: number }> {
     let seq = 1;
     this.ctx.storage.transactionSync(() => {
+      if (event.id !== undefined) {
+        const existing = this.sql
+          .exec<{ seq: number; json: string }>(
+            `SELECT seq, json FROM coordinator_unit_events WHERE instance_id = ? AND unit = ? ORDER BY seq`,
+            instanceId,
+            unit,
+          )
+          .toArray()
+          .find((row) => (JSON.parse(row.json) as ThreadEvent).id === event.id);
+        if (existing !== undefined) {
+          seq = existing.seq;
+          return;
+        }
+      }
       const max = this.sql
         .exec<{
           m: number | null;
@@ -2602,6 +2684,38 @@ export class RunHistoryDO extends DurableObject<Env> {
     return { ok: true };
   }
 
+  /** One transaction is the wake's decision: the indexed answer on the unit
+   * row and every event it consumed become visible together. */
+  async answerUnitWake(
+    unit: CoordinatorUnit,
+    waitId: string,
+    answer: UnitWakeAnswer,
+    seqs: number[],
+    by: string,
+    now: number,
+  ): Promise<{ ok: true }> {
+    this.ctx.storage.transactionSync(() => {
+      const updated = { ...unit, wakes: { ...(unit.wakes ?? {}), [waitId]: answer } };
+      this.sql.exec(
+        `INSERT INTO coordinator_units (instance_id, unit, json, updated_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(instance_id, unit) DO UPDATE SET json = excluded.json, updated_at = excluded.updated_at`,
+        unit.instanceId,
+        unit.unit,
+        JSON.stringify(updated),
+        now,
+      );
+      for (const seq of seqs)
+        this.sql.exec(
+          `UPDATE coordinator_unit_events SET consumed_by = ? WHERE instance_id = ? AND unit = ? AND seq = ? AND consumed_by IS NULL`,
+          by,
+          unit.instanceId,
+          unit.unit,
+          seq,
+        );
+    });
+    return { ok: true };
+  }
+
   // ---- the live-run ledger (run-history items 28–34) --------------------------
 
   private liveRow(runId: string): LiveRunRow | undefined {
@@ -4820,6 +4934,7 @@ const LEDGER_ROUTES = new Set([
   "/runs/coordinator/events/append",
   "/runs/coordinator/events/list",
   "/runs/coordinator/events/mark-consumed",
+  "/runs/coordinator/wake",
   "/runs/claim",
   "/runs/heartbeat",
   "/runs/append",
@@ -4854,12 +4969,13 @@ const LEDGER_ROUTES = new Set([
   "/runs/session/notepad/write",
 ]);
 
-/** The plane's routes (record 0064; orchestration-plane items 7 and 8): the shadow outcome post and the
- *  effect acknowledgement. Both land on the ledger object of the given store
- *  key, like every `/runs/*` route. */
+/** The plane's routes (record 0064; orchestration-plane items 7 and 8):
+ *  outcomes, effect delivery fencing and acknowledgements land on the ledger
+ *  object of the given store key, like every `/runs/*` route. */
 const PLANE_ROUTES = new Set([
   "/plane/outcome",
   "/plane/ack",
+  "/plane/steer/fence",
   "/plane/admit",
   "/plane/withdraw",
   "/plane/deploy",
@@ -4915,11 +5031,32 @@ async function handlePlane(pathname: string, body: unknown, env: Env): Promise<R
     );
     return json(r);
   }
+  if (pathname === "/plane/steer/fence") {
+    if (typeof b.id !== "string" || b.id.length === 0) return json({ error: "id must be a non-empty string" }, 400);
+    const runId = parseRunId(b.runId);
+    if (!runId.ok) return json({ error: runId.error }, 400);
+    const g = gen(b.gen);
+    if (!g.ok) return json({ error: g.error }, 400);
+    const lease = parseLeaseMs(b.leaseMs);
+    if (!lease.ok) return json({ error: lease.error }, 400);
+    return json(await stub.planeFenceSteer(b.id, runId.value, g.value, lease.value, now));
+  }
   if (pathname === "/plane/ack") {
     if (typeof b.id !== "string" || b.id.length === 0) return json({ error: "id must be a non-empty string" }, 400);
     if (typeof b.outcome !== "string" || !PLANE_ACK_OUTCOMES.has(b.outcome))
       return json({ error: "outcome must be done, skipped or deferred" }, 400);
-    return json(await stub.planeAck(b.id, b.outcome as PlaneAckOutcome, now));
+    let owner: { runId: string; gen: string } | undefined;
+    if (b.owner !== undefined) {
+      if (typeof b.owner !== "object" || b.owner === null || Array.isArray(b.owner))
+        return json({ error: "owner must name a runId and generation" }, 400);
+      const rawOwner = b.owner as Record<string, unknown>;
+      const runId = parseRunId(rawOwner.runId);
+      if (!runId.ok) return json({ error: runId.error }, 400);
+      if (typeof rawOwner.gen !== "string" || rawOwner.gen.length === 0)
+        return json({ error: "owner generation must be a non-empty string" }, 400);
+      owner = { runId: runId.value, gen: rawOwner.gen };
+    }
+    return json(await stub.planeAck(b.id, b.outcome as PlaneAckOutcome, now, owner));
   }
   if (pathname === "/plane/admit") {
     // The admission-stage ask (record 0064, "The queue"): the thread key, the
@@ -5457,8 +5594,22 @@ async function handleLedger(pathname: string, body: unknown, env: Env): Promise<
       return json({ error: "instanceId must be a Workflow instance id" }, 400);
     return json({ units: await stub.listUnits(b.instanceId) });
   }
+  if (pathname === "/runs/coordinator/wake") {
+    if (!isCoordinatorUnit(b.unit)) return json({ error: "unit must be a coordinator unit row" }, 400);
+    if (typeof b.waitId !== "string" || !STEP_NAME_PATTERN.test(b.waitId))
+      return json({ error: "waitId must be a step name" }, 400);
+    if (!isUnitWakeAnswer(b.answer)) return json({ error: "answer must be a unit wake answer" }, 400);
+    if (!Array.isArray(b.seqs) || !b.seqs.every((s) => typeof s === "number" && Number.isInteger(s) && s >= 1))
+      return json({ error: "seqs must be an array of sequence numbers" }, 400);
+    if (typeof b.by !== "string" || b.by.length === 0 || b.by.length > 200)
+      return json({ error: "by must name the consumer" }, 400);
+    const r = await stub.answerUnitWake(b.unit, b.waitId, b.answer, b.seqs as number[], b.by, now);
+    console.log(`[runs/coordinator/wake] ${key.value} ${b.unit.instanceId}:${b.unit.unit} ${b.waitId}`);
+    return json(r);
+  }
   // The thread events of a unit-owned thread (record 0051's reply-as-event rule): append assigns
-  // the sequence, list filters unconsumed, mark-consumed is idempotent.
+  // the sequence (or returns the row with the same stable id), list filters
+  // unconsumed, mark-consumed is idempotent.
   if (pathname.startsWith("/runs/coordinator/events/")) {
     if (typeof b.instanceId !== "string" || !INSTANCE_ID_PATTERN.test(b.instanceId))
       return json({ error: "instanceId must be a Workflow instance id" }, 400);

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" \