@coreplane/switchboard 1.227.0 → 1.229.0

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

@@ -317,19 +317,13 @@ workspaceDir: ./workspaces
 #   maxRounds: 3      # review rounds per unit
 #   maxMinutes: 120   # the ship preset's wall-clock budget in minutes (the registry's default)
 
-# Which loop drives each preset's runs (docs/reference/specs/harness-pi.md):
-# `native`, the in-process turn loop, or `pi`, the pi coding agent started
-# inside the run's own execution container and driven over its RPC protocol —
-# with the run's model-proxy bearer as its only key, every event bridged onto
-# the run's own record, our tools and tool rules as its extension. Every
-# preset declares `native` until the pi series moves it; a deployment moves a
-# preset early here. A preset with a workspace (coding, review, explore) runs
-# pi in the run's container; a preset without one (general, research,
-# conductor) runs it as a child of the bot, with none of pi's own shell or
-# file tools. A preset the registry does not know, or a value that is
-# neither harness, fails the load by name.
-# harness:
-#   coding: pi
+# `harness` is a retired key (docs/reference/specs/harness-pi.md item 1). It
+# moved the presets onto pi one at a time; every preset runs on pi now — the pi
+# coding agent started inside the run's own execution container (or as a child
+# of the bot for a preset without a workspace) with the run's model-proxy
+# bearer as its only key — and there is no other loop. A block written during
+# the series still loads when every value is `pi`; `native` names the deleted
+# loop and fails the load by name, as does an unknown preset. Remove the block.
 
 # What the harness writes into pi's per-run settings for every run on pi
 # (docs/reference/specs/harness-pi.md item 4): pi's compaction thresholds, in

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

@@ -56,6 +56,14 @@ import {
   textOfStoredRow,
 } from "../../src/core/runLedger/sessionLog.ts";
 import type { RunEvent } from "../../src/core/runEvents.ts";
+import {
+  aggregateUsageByUser,
+  isRunUsage,
+  usageOfEvents,
+  type RunUsage,
+  type RunUsageReport,
+  type UsageRun,
+} from "../../src/core/runUsage.ts";
 import {
   checkFence,
   decideClaim,
@@ -1160,6 +1168,10 @@ export class RunHistoryDO extends DurableObject<Env> {
     // The session a run was a range of (session-log item 7), so the sweep can
     // tell which sessions still have a kept run; null for a record without one.
     if (!columns.has("session_key")) this.sql.exec(`ALTER TABLE runs ADD COLUMN session_key TEXT`);
+    // What the run cost in tokens (costs.md, cost by user): the record's `usage`
+    // as JSON; NULL for a record written before the field existed, until the
+    // by-user aggregate fills it in from the run's stored events.
+    if (!columns.has("usage_json")) this.sql.exec(`ALTER TABLE runs ADD COLUMN usage_json TEXT`);
     this.sql.exec(`
       CREATE INDEX IF NOT EXISTS runs_channel_finished ON runs(channel_id, finished_at DESC, run_id DESC);
       CREATE INDEX IF NOT EXISTS runs_visibility_finished ON runs(channel_visibility, finished_at DESC, run_id DESC);
@@ -1820,8 +1832,8 @@ export class RunHistoryDO extends DurableObject<Env> {
         );
       this.sql.exec(
         `INSERT INTO runs (run_id, label, agent, model, channel_id, user_id, thread_key, channel_visibility, repo, started_at, finished_at, stored_at, status,
-                           event_count, stored_event_count, truncated, bytes, diagnosis_json, summary_json, session_key)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                           event_count, stored_event_count, truncated, bytes, diagnosis_json, summary_json, session_key, usage_json)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
          ON CONFLICT(run_id) DO UPDATE SET
            label = excluded.label, agent = excluded.agent, model = excluded.model, channel_id = excluded.channel_id,
            user_id = excluded.user_id, thread_key = excluded.thread_key, channel_visibility = excluded.channel_visibility,
@@ -1829,7 +1841,8 @@ export class RunHistoryDO extends DurableObject<Env> {
            finished_at = excluded.finished_at, stored_at = excluded.stored_at, status = excluded.status,
            event_count = excluded.event_count, stored_event_count = excluded.stored_event_count, truncated = excluded.truncated,
            bytes = excluded.bytes, diagnosis_json = excluded.diagnosis_json, summary_json = excluded.summary_json,
-           session_key = excluded.session_key`,
+           session_key = excluded.session_key,
+           usage_json = COALESCE(excluded.usage_json, runs.usage_json)`,
         stored.id,
         stored.label ?? null,
         stored.agent ?? null,
@@ -1850,6 +1863,7 @@ export class RunHistoryDO extends DurableObject<Env> {
         JSON.stringify(stored.diagnosis),
         JSON.stringify(summary),
         stored.session?.key ?? null,
+        stored.usage ? JSON.stringify(stored.usage) : null,
       );
       // The session's registry row learns its newest finish (session-log item
       // 7); a record that reaches the store without a claim (the plain put
@@ -2053,6 +2067,83 @@ export class RunHistoryDO extends DurableObject<Env> {
     return summary ? { ...summary, bytes: row.bytes } : null;
   }
 
+  /**
+   * Who spent what, per UTC day (costs.md, cost by user), over the runs that
+   * finished in [sinceMs, untilMs) and are inside the retention window. A row
+   * written before `usage_json` existed is filled in here from its stored
+   * `model.turn` events — up to USAGE_BACKFILL_PER_CALL a call, the rest
+   * reported as `pending` — so the history heals as it is read, with no
+   * operator step; a run without turns is written back as the zero usage so it
+   * is not re-read. A child is billed to its parent's requester; a parent
+   * outside the range is looked up by id.
+   */
+  usageByUser(sinceMs: number, untilMs: number): RunUsageReport {
+    const now = systemClock();
+    const { policy } = this.policyState();
+    const cutoff = now - policy.retentionDays * 86_400_000;
+    const rows = this.sql
+      .exec<UsageRow>(
+        `SELECT run_id, user_id, started_at, finished_at, usage_json, summary_json FROM runs
+          WHERE finished_at >= ? AND finished_at < ? ORDER BY finished_at ASC, run_id ASC`,
+        Math.max(sinceMs, cutoff),
+        untilMs,
+      )
+      .toArray();
+    let backfilled = 0;
+    const runs: UsageRun[] = rows.map((row) => {
+      let usage = parseUsageJson(row.usage_json);
+      if (usage === undefined && backfilled < USAGE_BACKFILL_PER_CALL) {
+        usage = usageOfEvents(this.modelTurnEvents(row.run_id));
+        this.sql.exec(`UPDATE runs SET usage_json = ? WHERE run_id = ?`, JSON.stringify(usage), row.run_id);
+        backfilled += 1;
+      }
+      const who = identityOfSummary(row.summary_json);
+      return {
+        id: row.run_id,
+        userId: row.user_id,
+        ...(who.userName ? { userName: who.userName } : {}),
+        ...(who.parentRunId ? { parentRunId: who.parentRunId } : {}),
+        startedAt: row.started_at,
+        finishedAt: row.finished_at,
+        ...(usage ? { usage } : {}),
+      };
+    });
+    const lookupParent = (id: string) => {
+      const p = this.sql
+        .exec<{ user_id: string; summary_json: string }>(`SELECT user_id, summary_json FROM runs WHERE run_id = ?`, id)
+        .toArray()[0];
+      if (!p) return undefined;
+      const who = identityOfSummary(p.summary_json);
+      return { userId: p.user_id, ...(who.userName ? { userName: who.userName } : {}) };
+    };
+    const { rows: out, pending } = aggregateUsageByUser(runs, lookupParent);
+    const earliest = this.sql
+      .exec<{ m: number | null }>(`SELECT MIN(finished_at) AS m FROM runs WHERE finished_at >= ?`, cutoff)
+      .one().m;
+    return {
+      rows: out,
+      pending,
+      ...(earliest !== null ? { earliestFinishedAt: earliest } : {}),
+      retentionDays: policy.retentionDays,
+    };
+  }
+
+  /** The stored `model.turn` span ends of one run — the rows a backfill prices. */
+  private modelTurnEvents(runId: string): RunEvent[] {
+    const out: RunEvent[] = [];
+    for (const r of this.sql
+      .exec<{ json: string }>(`SELECT json FROM run_events WHERE run_id = ? AND json LIKE '%"model.turn"%'`, runId)
+      .toArray()) {
+      try {
+        const e = JSON.parse(r.json) as RunEvent;
+        if (e && e.type === "span_end") out.push(e);
+      } catch {
+        // an unparsable event row prices nothing
+      }
+    }
+    return out;
+  }
+
   /**
    * Newest first (finished_at desc, run_id desc) among the rows the policy
    * keeps, filtered, capped at RUN_LIST_MAX_LIMIT. The `before`/`beforeId`
@@ -2181,6 +2272,43 @@ function parseEventRows(rows: readonly EventRow[]): StoredRunEvent[] {
 }
 
 /** The stored summary (record minus events); null when the row is unreadable. */
+/** How many usage-less rows one by-user read prices from their events before
+ *  reporting the rest as pending: a page load stays quick while the history heals. */
+const USAGE_BACKFILL_PER_CALL = 200;
+
+type UsageRow = {
+  run_id: string;
+  user_id: string;
+  started_at: number;
+  finished_at: number;
+  usage_json: string | null;
+  summary_json: string;
+};
+
+/** A stored `usage_json`, or undefined when absent or unreadable (then it is recomputed). */
+function parseUsageJson(raw: string | null): RunUsage | undefined {
+  if (raw === null) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isRunUsage(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The two identity fields the by-user aggregate needs off a summary, read leniently. */
+function identityOfSummary(raw: string): { userName?: string; parentRunId?: string } {
+  try {
+    const s = JSON.parse(raw) as Record<string, unknown>;
+    return {
+      ...(typeof s.userName === "string" && s.userName ? { userName: s.userName } : {}),
+      ...(typeof s.parentRunId === "string" && s.parentRunId ? { parentRunId: s.parentRunId } : {}),
+    };
+  } catch {
+    return {};
+  }
+}
+
 function parseSummary(row: RunRow): Omit<RunRecord, "events"> | null {
   try {
     const parsed: unknown = JSON.parse(row.summary_json);
@@ -2237,6 +2365,23 @@ function parseRunPut(body: unknown): Validated<{ storeKey: string; record: RunRe
 }
 
 /** `{storeKey, id}` — the body of /runs/get, /runs/summary and /runs/delete, and the base of /runs/events. */
+/** At most a year of runs a call — the page asks for 90 days at most. */
+const USAGE_QUERY_MAX_SPAN_MS = 366 * 86_400_000;
+
+function parseRunUsageQuery(body: unknown): Validated<{ storeKey: string; sinceMs: number; untilMs: number }> {
+  if (typeof body !== "object" || body === null) return invalid("body must be a JSON object");
+  const b = body as Record<string, unknown>;
+  const key = parseStoreKey(b);
+  if (!key.ok) return key;
+  const { sinceMs, untilMs } = b;
+  if (typeof sinceMs !== "number" || !Number.isFinite(sinceMs) || sinceMs < 0)
+    return invalid("sinceMs must be a non-negative number");
+  if (typeof untilMs !== "number" || !Number.isFinite(untilMs) || untilMs <= sinceMs)
+    return invalid("untilMs must be a number after sinceMs");
+  if (untilMs - sinceMs > USAGE_QUERY_MAX_SPAN_MS) return invalid("the range may span at most 366 days");
+  return { ok: true, value: { storeKey: key.value, sinceMs, untilMs } };
+}
+
 function parseRunTarget(body: unknown): Validated<{ storeKey: string; id: string }> {
   if (typeof body !== "object" || body === null) return invalid("body must be a JSON object");
   const b = body as Record<string, unknown>;
@@ -3504,6 +3649,14 @@ async function handleRuns(pathname: string, body: unknown, env: Env): Promise<Re
     );
     return json(result ?? { events: null });
   }
+  if (pathname === "/runs/usage-by-user") {
+    const parsed = parseRunUsageQuery(body);
+    if (!parsed.ok) return json({ error: parsed.error }, 400);
+    const { storeKey, sinceMs, untilMs } = parsed.value;
+    const report = await stub(storeKey).usageByUser(sinceMs, untilMs);
+    console.log(`[runs/usage-by-user] ${storeKey} -> ${report.rows.length} rows, ${report.pending} pending`);
+    return json(report);
+  }
   // /runs/delete
   const parsed = parseRunTarget(body);
   if (!parsed.ok) return json({ error: parsed.error }, 400);
@@ -3526,6 +3679,7 @@ const ROUTES = new Set([
   "/runs/summary",
   "/runs/list",
   "/runs/events",
+  "/runs/usage-by-user",
   "/runs/delete",
   ...LEDGER_ROUTES,
 ]);

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

@@ -88,12 +88,16 @@ import { decideWorktree, parseReuse, type WorktreeFacts } from "../../src/execut
 import {
   boundByFor,
   parseOwnPr,
+  parsePushed,
   parseRefByDefault,
   rebindPlan,
   rebindRefused,
   rebindVerdict,
+  rememberOwnBranches,
   type BoundBy,
+  type OwnBranch,
   type OwnPr,
+  type PushedBranch,
   type Rebound,
   type RebindRefused,
   type RebindTreeFacts,
@@ -994,6 +998,13 @@ interface ThreadBinding {
    *  to, onto the branch the thread's own run opened a pull request on. Set,
    *  the binding never moves again. */
   rebound?: Rebound;
+  /** The branches the thread's own runs pushed and the pull requests they
+   *  head, as each run's release handed them over (`/detach` `pushed`, item
+   *  16a) — written before any eviction decision, so the fact outlives the
+   *  tree: a clean tree is released the moment a run ends, and this is what
+   *  lets the follow-up's attach move onto the branch and recreate the tree
+   *  there. Newest last; the oldest fall off past `OWN_BRANCHES_MAX`. */
+  ownBranches?: OwnBranch[];
   /** Allocated OS user (worker2..worker17); "" once evicted (pool released). */
   user: string;
   worktreePath: string;
@@ -1092,6 +1103,15 @@ interface RefHintReason {
 /** The body every bot always sent: a hint with no reason attached. */
 const NO_REF_HINT_REASON: RefHintReason = { ownPr: null, refByDefault: false };
 
+/** What the rebind decided under the mutex (item 16): nothing to move (the
+ *  row is already on the branch), a named refusal, or the move — written on
+ *  the row, whether a checkout in the live tree or a ref the attach will
+ *  recreate the tree at. */
+type RebindOutcome =
+  | { kind: "none"; binding: ThreadBinding }
+  | { kind: "refuse"; refused: RebindRefused }
+  | { kind: "rebound"; moved: ThreadBinding; rebound: Rebound };
+
 /** Result of one /op test/build execution. `ok` is the command's
  *  verdict — a failing test run is a RESULT with ok:false, never an error. */
 interface OpRunOk {
@@ -4358,6 +4378,7 @@ export class ResidentDO extends Sandbox<Env> {
         ? {
             ...(existing.boundBy !== undefined ? { boundBy: existing.boundBy } : {}),
             ...(existing.rebound !== undefined ? { rebound: existing.rebound } : {}),
+            ...(existing.ownBranches !== undefined ? { ownBranches: existing.ownBranches } : {}),
           }
         : { boundBy }),
     };
@@ -4497,6 +4518,7 @@ export class ResidentDO extends Sandbox<Env> {
       reason.ownPr,
       reuse,
       facts.defaultRef,
+      slug,
     );
     if ("error" in rebind) return rebind;
     const prior = rebind.binding;
@@ -4579,19 +4601,26 @@ export class ResidentDO extends Sandbox<Env> {
     ownPr: OwnPr | null,
     reuse: boolean,
     defaultRef: string,
+    slug: string,
   ): Promise<{ binding: ThreadBinding | undefined; rebound?: Rebound; rebindRefused?: RebindRefused } | ThreadErr> {
     const plan = rebindPlan({ ownPr, reuse, binding: prior, defaultRef });
     if (plan.kind === "none" || prior === undefined) return { binding: prior };
     if (plan.kind === "refuse") return { binding: prior, rebindRefused: plan.refused };
     const key = threadBindingKey(prior.threadKey);
-    type Outcome =
-      | { kind: "none"; binding: ThreadBinding }
-      | { kind: "refuse"; refused: RebindRefused }
-      | { kind: "rebound"; moved: ThreadBinding; rebound: Rebound };
-    let outcome: Outcome;
+    // A tree that is gone is recreated at the branch by the attach (item 16):
+    // the mirror must hold the branch first, and a branch pushed since the
+    // last refresh cycle is fetched for — with a token minted here, before
+    // the mutex, like the attach's own recovery fetch. Only when the binding
+    // allows a recreate at all: an evicted tree, or a live one whose runs
+    // pushed the branch (the tree may turn out missing).
+    const fetchToken =
+      (plan.kind === "recreate" || plan.own) && githubAppConfigured(this.env)
+        ? ((await mintRepoScopedToken(this.env, slug).catch(() => null))?.token ?? null)
+        : null;
+    let outcome: RebindOutcome;
     try {
       outcome = (
-        await this.withMirrorLock(async (): Promise<Outcome> => {
+        await this.withMirrorLock(async (): Promise<RebindOutcome> => {
           // The binding as it stands NOW, under the mutex — not the snapshot
           // the plan read before the wait: the move is judged on, and written
           // over, the row's current fields (its last attach time, its
@@ -4602,6 +4631,7 @@ export class ResidentDO extends Sandbox<Env> {
           const again = rebindPlan({ ownPr, reuse, binding: current, defaultRef });
           if (again.kind === "none") return { kind: "none", binding: current };
           if (again.kind === "refuse") return again;
+          if (again.kind === "recreate") return this.recreateAtOwnBranch(current, again, fetchToken);
           const wt = current.worktreePath;
           // The facts, as the thread user in the thread's own tree: is the
           // branch a local branch here (the physical trace of this thread's
@@ -4612,7 +4642,7 @@ export class ResidentDO extends Sandbox<Env> {
             const branch = await this.threadRun(
               current.user,
               wt,
-              `git rev-parse --verify --quiet ${shellQuote(`refs/heads/${plan.to}`)}`,
+              `git rev-parse --verify --quiet ${shellQuote(`refs/heads/${again.to}`)}`,
               DEFAULT_EXEC_TIMEOUT_MS,
             );
             tree.branchExists = branch.exitCode === 0;
@@ -4625,13 +4655,16 @@ export class ResidentDO extends Sandbox<Env> {
             tree.readable = status.exitCode === 0;
             if (tree.readable) tree.dirty = status.stdout.trim() !== "";
           }
-          const verdict = rebindVerdict(plan, tree);
+          // Judged on the re-read plan: it carries whether the branch is the
+          // thread's own, which the pre-lock plan lacks when it was a recreate.
+          const verdict = rebindVerdict(again, tree);
+          if (verdict.kind === "recreate") return this.recreateAtOwnBranch(current, again, fetchToken);
           if (verdict.kind !== "rebind") return verdict;
           const startedAt = systemClock();
           const checkout = await this.threadRun(
             current.user,
             wt,
-            `git checkout --quiet ${shellQuote(plan.to)}`,
+            `git checkout --quiet ${shellQuote(again.to)}`,
             DEFAULT_EXEC_TIMEOUT_MS,
           );
           this.stepTrace.getStore()?.record("rebind-checkout", {
@@ -4643,15 +4676,15 @@ export class ResidentDO extends Sandbox<Env> {
           if (checkout.exitCode !== 0) {
             const detail =
               checkout.stderr.trim().split("\n")[0]?.slice(0, 200) || `git checkout exited ${checkout.exitCode}`;
-            return { kind: "refuse", refused: rebindRefused(plan, "checkout-failed", detail) };
+            return { kind: "refuse", refused: rebindRefused(again, "checkout-failed", detail) };
           }
           const rebound: Rebound = {
             from: current.ref,
-            to: plan.to,
-            pr: plan.pr,
+            to: again.to,
+            pr: again.pr,
             at: new Date(systemClock()).toISOString(),
           };
-          const moved: ThreadBinding = { ...current, ref: plan.to, rebound };
+          const moved: ThreadBinding = { ...current, ref: again.to, rebound };
           await this.ctx.storage.put(key, moved);
           return { kind: "rebound", moved, rebound };
         }, ATTACH_MUTEX_WAIT_MS)
@@ -4677,6 +4710,77 @@ export class ResidentDO extends Sandbox<Env> {
     return { binding: moved, rebound };
   }
 
+  /** The move when the thread's tree is gone (item 16): the binding's ref
+   *  becomes the branch its own run pushed, and the attach that follows
+   *  recreates the tree at it — `ensureThreadWorktree` finds no tree and
+   *  clones the branch from the mirror. So the mirror must hold the branch:
+   *  one pushed since the last refresh cycle is fetched for here, under the
+   *  mutex; a branch still missing after the fetch (deleted after a merge, or
+   *  never pushed) is a `branch-absent` refusal and the binding stands — the
+   *  attach then goes on at the ref it had, never `unknown-ref`. Nothing on
+   *  disk is touched: no checkout (there is no tree), no clone (the attach's). */
+  private async recreateAtOwnBranch(
+    current: ThreadBinding,
+    plan: { to: string; pr: number },
+    fetchToken: string | null,
+  ): Promise<RebindOutcome> {
+    let present = await this.refExists(plan.to);
+    if (!present) {
+      // A fetch that fails — GitHub unreachable, no token for a private repo —
+      // is not the attach's failure: the branch is then simply not in the
+      // mirror, and the refusal below names it, so the binding stands and the
+      // run goes on at the ref it had instead of the attach ending 500.
+      try {
+        await this.gitWithCred(
+          fetchToken,
+          ["-C", MIRROR_DIR, "fetch", "--prune", "origin"],
+          "fetch",
+          GIT_NETWORK_TIMEOUT_MS,
+        );
+      } catch (err) {
+        console.log(
+          `attach ${current.threadKey}: the fetch for ${plan.to} failed (${errMsg(err)}) — the rebind is refused, the attach goes on`,
+        );
+      }
+      present = await this.refExists(plan.to);
+    }
+    if (!present) {
+      return {
+        kind: "refuse",
+        refused: rebindRefused(
+          plan,
+          "branch-absent",
+          `the thread's worktree is gone and the mirror does not hold ${JSON.stringify(plan.to)} (deleted after a merge, or never pushed); the tree cannot be recreated at it`,
+        ),
+      };
+    }
+    const rebound: Rebound = {
+      from: current.ref,
+      to: plan.to,
+      pr: plan.pr,
+      at: new Date(systemClock()).toISOString(),
+    };
+    const moved: ThreadBinding = { ...current, ref: plan.to, rebound };
+    await this.ctx.storage.put(threadBindingKey(current.threadKey), moved);
+    return { kind: "rebound", moved, rebound };
+  }
+
+  /** The release's word on what the run pushed (`/detach` `pushed`, item
+   *  16a), remembered on the binding BEFORE the detach decides anything: a
+   *  clean tree is evicted at once, a dirty one kept, an already-evicted
+   *  binding answered as such — and in every case the fact must outlive the
+   *  tree, since it is what a follow-up's rebind onto the thread's own pull
+   *  request branch reads once the tree is gone. No binding → nothing to
+   *  remember on (the detach answers its 404 next). */
+  private async rememberOwnBranches(threadKey: string, pushed: readonly PushedBranch[]): Promise<void> {
+    const binding = await this.ctx.storage.get<ThreadBinding>(threadBindingKey(threadKey));
+    if (!binding) return;
+    await this.ctx.storage.put(threadBindingKey(threadKey), {
+      ...binding,
+      ownBranches: rememberOwnBranches(binding.ownBranches, pushed, new Date(systemClock()).toISOString()),
+    } satisfies ThreadBinding);
+  }
+
   /** The second half of an attach, past disk admission: mint, fetch + clone
    *  under the mirror lock, deps, credentials, the binding write. Split from
    *  `attachThreadBody` only so the admission's commitment is released on every
@@ -5313,14 +5417,13 @@ export class ResidentDO extends Sandbox<Env> {
           "deps-seed",
           REFRESH_BUILD_TIMEOUT_MS,
         );
-        const paths = mutableCachePaths(`${scratch}/node_modules`, parsed.mutableListing);
-        if (paths.length > 0) {
-          await this.runDepScript(
-            mutableCacheSwapScript(seedNm, `${scratch}/node_modules`, BUILD_USER, paths),
-            "deps-seed-swap",
-            GIT_NETWORK_TIMEOUT_MS,
-          );
-        }
+        await this.swapMutableCaches(
+          seedNm,
+          `${scratch}/node_modules`,
+          BUILD_USER,
+          parsed.mutableListing,
+          "deps-seed-swap",
+        );
         console.log(`deps: ${key.slice(0, 8)} seeded from ${seed.slice(0, 8)} (${parsed.mech})`);
       }
       // Unprivileged and token-free, in a tree only this attempt
@@ -5423,16 +5526,42 @@ export class ResidentDO extends Sandbox<Env> {
       "deps-materialize",
       REFRESH_BUILD_TIMEOUT_MS,
     );
-    const nmDst = `${tree}/node_modules`;
-    const paths = mutableCachePaths(nmDst, parsed.mutableListing);
-    if (paths.length > 0) {
-      await this.runDepScript(
-        mutableCacheSwapScript(entryNodeModules ?? `${CHECKOUT_DIR}/node_modules`, nmDst, user, paths),
-        "deps-mutable-swap",
-        GIT_NETWORK_TIMEOUT_MS,
+    await this.swapMutableCaches(
+      entryNodeModules ?? `${CHECKOUT_DIR}/node_modules`,
+      `${tree}/node_modules`,
+      user,
+      parsed.mutableListing,
+      "deps-mutable-swap",
+    );
+    return parsed.mech;
+  }
+
+  /** The tool-cache swap for a freshly hardlinked node_modules: the listing
+   *  through `mutableCachePaths`, every swap in one fork
+   *  (`mutableCacheSwapScript`). A path the source has no counterpart for is
+   *  a tree-private entry the script leaves in place and names on a
+   *  `skipped=` line; the log carries those names so a refresh that read warm
+   *  still says what it left alone (the failure path already quotes the
+   *  script's stdout). */
+  private async swapMutableCaches(
+    srcNodeModules: string,
+    dstNodeModules: string,
+    user: string,
+    mutableListing: string[],
+    step: "deps-mutable-swap" | "deps-seed-swap",
+  ): Promise<void> {
+    const paths = mutableCachePaths(dstNodeModules, mutableListing);
+    if (paths.length === 0) return;
+    const swapped = await this.runDepScript(
+      mutableCacheSwapScript(srcNodeModules, dstNodeModules, user, paths),
+      step,
+      GIT_NETWORK_TIMEOUT_MS,
+    );
+    if (swapped.skipped.length > 0) {
+      console.log(
+        `deps: ${step} left ${swapped.skipped.length} tree-private node_modules entr${swapped.skipped.length === 1 ? "y" : "ies"} with no store counterpart in place: ${swapped.skipped.join(", ")}`,
       );
     }
-    return parsed.mech;
   }
 
   /** Adopt a checkout that already holds node_modules but whose key has no
@@ -5910,7 +6039,10 @@ export class ResidentDO extends Sandbox<Env> {
   async detachThread(
     threadKey: string,
     force: boolean,
+    /** What the ending run pushed (item 16a): remembered on the binding first, whatever the detach then decides. */
+    pushed: readonly PushedBranch[] = [],
   ): Promise<{ released: boolean; reason?: string; user?: string } | ThreadErr> {
+    if (pushed.length > 0) await this.rememberOwnBranches(threadKey, pushed);
     const binding = await this.ctx.storage.get<ThreadBinding>(threadBindingKey(threadKey));
     if (!binding) return { error: `no-binding: ${threadKey} has never attached to this resident`, status: 404 };
     if (binding.evicted || !binding.user) return { released: false, reason: "already-evicted" };
@@ -7785,7 +7917,15 @@ async function handleAttach(env: Env, body: Record<string, unknown>, traceparent
 async function handleDetach(env: Env, body: Record<string, unknown>): Promise<Response> {
   const ctx = await resolveThreadRoute(env, body);
   if (ctx instanceof Response) return ctx;
-  const result = await ctx.stub.detachThread(ctx.threadKey, body.force === true);
+  // What the run pushed (item 16a), each ref through the one ref pattern
+  // before it can be stored or become a git argument.
+  const pushed = parsePushed(body.pushed);
+  if ("error" in pushed) return json({ error: pushed.error }, 400);
+  for (const entry of pushed.pushed) {
+    const ref = parseRef(entry.ref, "pushed[].ref");
+    if ("error" in ref) return json({ error: ref.error }, 400);
+  }
+  const result = await ctx.stub.detachThread(ctx.threadKey, body.force === true, pushed.pushed);
   if ("error" in result) return threadErrResponse(result);
   return json(result);
 }

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

@@ -13,19 +13,21 @@
 FROM --platform=linux/amd64 docker.io/library/node:24.21.0-slim AS node
 
 # The tag MUST match the @cloudflare/sandbox version in package.json exactly
-# (no 'latest' tag exists) — bump both together.
-FROM docker.io/cloudflare/sandbox:0.12.9
+# (no 'latest' tag exists on the @next line) — bump both together. The same
+# base as the resident image: its container server is compiled with a Bun
+# whose directory watcher no longer dies on an entry removed under it, which
+# ended the 0.12.9 line's server mid-command (docs/reference/specs/execution.md
+# item 21).
+FROM docker.io/cloudflare/sandbox:0.13.0-next.751.1
 USER root
-# The SDK's container server kills any command after COMMAND_TIMEOUT_MS. On
-# 0.12.x the default is unlimited (unset → no limit; 0.3.x defaulted to 30s),
-# a per-exec `timeout` option wins over it, and a kill by it lands as a normal
-# result with a synthetic exit code (143/137), not a rejection. worker.ts
-# passes no per-call timeout, so this env var is the container-level lever.
-# Pure BACKSTOP: the real per-command limit is coreutils `timeout` in
-# worker.ts (280s default, raisable per call via the bash tool's timeoutMs up
-# to the 20-min ceiling BASH_TIMEOUT_MAX_MS), which yields a genuine exit 124
-# through the normal result path. This sits 40s above the 20-min ceiling so it
-# never wins the race. Bump alongside BASH_TIMEOUT_MAX_MS
+# The SDK's container server kills any command after COMMAND_TIMEOUT_MS
+# (unset → no limit). Pure BACKSTOP behind two closer ones: the real
+# per-command limit is coreutils `timeout` in worker.ts (280s default,
+# raisable per call via the bash tool's timeoutMs up to the 20-min ceiling
+# BASH_TIMEOUT_MAX_MS), which yields a genuine exit 124 through the normal
+# result path, and worker.ts launches each process with the SDK's own
+# per-process `timeout` a margin above that. This sits 40s above the 20-min
+# ceiling so it never wins the race. Bump alongside BASH_TIMEOUT_MAX_MS
 # (src/execution/bashTimeout.ts); changing it requires a container rebuild +
 # redeploy.
 ENV COMMAND_TIMEOUT_MS=1240000
@@ -53,8 +55,8 @@ RUN apt-get update \
 # execs the real client. src/deploy/sandboxDocker.test.ts holds its shape.
 COPY --chmod=0755 docker-wrapper.sh /usr/local/bin/docker
 
-# Node 24, not the base's. The published 0.12.9 base ships Node 22.23.2
-# (copied from node:22-slim: the binary at /usr/local/bin/node, npm and
+# Node 24, not the base's. The 0.13.0-next base ships Node 22.23.2 like the
+# 0.12.9 one (copied from node:22-slim: the binary at /usr/local/bin/node, npm and
 # corepack under /usr/local/lib/node_modules, npm/npx symlinked into it), while
 # this repository builds and tests on Node 24 (.nvmrc, CI) and its published
 # CLI requires `>=24`. A run that exercised the suite inside this image read a
@@ -174,9 +176,11 @@ RUN npm install -g @earendil-works/pi-coding-agent@0.85.1 \
   && pi --version | grep -qx '0.85.1' \
   && pi --help | grep -q -- '--mode <mode>'
 
-# PID 1 keeps the container alive across a crash of the SDK's container
-# server (the supervisor's header says why); the base image's ENTRYPOINT is
-# the server itself, so one uncaught exception there ended the container.
+# The container outlives a crash of the SDK's container server (the
+# supervisor's header says why). The base image's ENTRYPOINT is tini running
+# the server, so one uncaught exception there ended the container; here tini
+# stays PID 1 — it reaps orphans and forwards the platform's signals — and
+# runs the supervisor, which starts the server again when it exits.
 # src/deploy/sandboxRuntimeSupervisor.test.ts holds this pair of lines.
 COPY --chmod=0755 runtime-supervisor.sh /usr/local/bin/sandbox-runtime-supervisor
-ENTRYPOINT ["/usr/local/bin/sandbox-runtime-supervisor"]
+ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/sandbox-runtime-supervisor"]

package/dist/assets/deploy/cloudflare-sandbox/package.json

@@ -16,7 +16,7 @@
     "secrets": "npm --prefix ../.. run --silent cli -- deploy secrets sandbox"
   },
   "dependencies": {
-    "@cloudflare/sandbox": "0.12.9"
+    "@cloudflare/sandbox": "0.13.0-next.751.1"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^5.20260904.1",