@coreplane/switchboard 1.251.0 → 1.252.0

package/dist/assets/src/core/trace/attrs.ts

@@ -17,6 +17,10 @@ export interface AttrDomain {
   status: "completed" | "failed" | "refused" | "stopped";
   queuedBeforeMs: number;
   queuedBehindMs: number;
+  /** The run this request restarts (a restart from its request, run-history
+   *  item 54): the page names the predecessor by id instead of inventing a
+   *  wait out of its lifetime. On the root at start, like the queued numbers. */
+  restartOfRunId: string;
   runId: string;
   // slack.receive
   caughtUp: boolean;
@@ -60,6 +64,14 @@ export interface AttrDomain {
   outputTokens: number;
   cacheReadTokens: number;
   cacheWriteTokens: number;
+  /** The meter row (model-proxy.md item 6): who bills the turn (the
+   *  block), the vendor the card names, the turn's dollars with the layer
+   *  that priced them, and on a BYOK turn the aggregator's fee (inside `usd`). */
+  biller: string;
+  vendor: string;
+  usd: number;
+  feeUsd: number;
+  priceSource: "provider" | "operator" | "registry" | "none";
   ttftMs: number;
   thinkingMs: number;
   textMs: number;
@@ -103,6 +115,8 @@ export interface AttrDomain {
   signal: "SIGTERM" | "SIGINT" | "other";
   channels: number;
   missed: number;
+  /** Catch-up candidates a receipt (or a fresh verdict) silenced — read, never re-run (slack-channel.md item 7). */
+  silenced: number;
   orphans: number;
   skipped: number;
   runs: number;
@@ -125,6 +139,7 @@ export type SpanAttrs = { readonly [K in SpanAttrKey]?: AttrDomain[K] };
  *  from a closed table, never free text (no whitespace, no `?`/`&`, at most 64
  *  chars). */
 const IDENTIFIER_KEYS: ReadonlySet<SpanAttrKey> = new Set<SpanAttrKey>([
+  "restartOfRunId",
   "runId",
   "outcome",
   "refusal",
@@ -135,6 +150,8 @@ const IDENTIFIER_KEYS: ReadonlySet<SpanAttrKey> = new Set<SpanAttrKey>([
   "callId",
   "agent",
   "model",
+  "biller",
+  "vendor",
 ]);
 const IDENTIFIER_RE = /^[A-Za-z0-9_./:@+-]{1,64}$/;
 /** A Workflow instance id: the platform's rule (`^[a-zA-Z0-9_][a-zA-Z0-9-_]*$`, at most 100). */
@@ -172,6 +189,7 @@ const ATTR_TYPE: Record<SpanAttrKey, "string" | "number" | "boolean"> = {
   status: "string",
   queuedBeforeMs: "number",
   queuedBehindMs: "number",
+  restartOfRunId: "string",
   runId: "string",
   caughtUp: "boolean",
   files: "number",
@@ -195,6 +213,11 @@ const ATTR_TYPE: Record<SpanAttrKey, "string" | "number" | "boolean"> = {
   outputTokens: "number",
   cacheReadTokens: "number",
   cacheWriteTokens: "number",
+  biller: "string",
+  vendor: "string",
+  usd: "number",
+  feeUsd: "number",
+  priceSource: "string",
   ttftMs: "number",
   thinkingMs: "number",
   textMs: "number",
@@ -230,6 +253,7 @@ const ATTR_TYPE: Record<SpanAttrKey, "string" | "number" | "boolean"> = {
   signal: "string",
   channels: "number",
   missed: "number",
+  silenced: "number",
   orphans: "number",
   skipped: "number",
   runs: "number",

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

@@ -230,13 +230,13 @@ export interface UploadTicket {
 /** What the core needs from a channel to serve one request. */
 /** What a channel shows for a confirmation (`ChannelIO.offer`): the id its
  *  affordance carries back, the full command line to run, the one risk line
- *  (empty when the command declares none), the footer naming the scope that
- *  asked, and when the offer expires (ms epoch, the config object's clock). */
+ *  (empty when the command declares none), and when the offer expires (ms
+ *  epoch, the config object's clock). No footer: the button is the affordance,
+ *  and which scope asked is an operator's fact (`config show` names it). */
 export interface ConfirmationOffer {
   id: string;
   line: string;
   risk: string;
-  footer: string;
   expiresAt: number;
   /** Present on a question's offer (record 0054): the refusal's sentence,
    *  shown above the line, and the evidence naming the match, shown under it.
@@ -286,8 +286,8 @@ export interface ChannelIO {
   /**
    * Show the confirmation a routed write is offered as
    * (docs/reference/specs/routing-and-config.md item 25, record 0044): the full
-   * command line the router bound, its one risk line, the footer naming the
-   * scope that asked, and the id the channel's affordance carries back to
+   * command line the router bound, its one risk line, and the id the
+   * channel's affordance carries back to
    * `dispatchClick` — a button whose value is the id, on a channel with
    * components. Optional; a channel without it (the CLI, an HTTP reply, the
    * browser) is answered the pasteable line instead, and nothing below the

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

@@ -0,0 +1,48 @@
+// Verbosity: how much of itself the bot says in the conversation
+// (docs/reference/specs/routing-and-config.md item 28). Three levels on the
+// log-level pattern — each level shows everything the ones below it show:
+//
+//   quiet    (default)  only what needs the person: answers, results, verdicts,
+//                       refusals, questions, and the card's own progress.
+//   verbose             plus every acknowledgement of what the system is doing
+//                       for the person — a follow-up folded into a live run,
+//                       a plan handed to the runner, the workspace the run is
+//                       on, a budget clipped by a boundary.
+//   debug               plus what an operator debugging the bot reads — the
+//                       router's reason, the ledger's word on the run.
+//
+// A config dimension resolved through the same layers as `effort` (item 2):
+// a `verbosity:<level>` directive on the request (sticky in the thread from
+// the user's turns, item 3) > the user's scope > the channel's > `defaults`.
+// Nothing here decides WHAT a message is; each message site names the level
+// it belongs to, and the spec's table is the one list of them.
+
+export const VERBOSITY_LEVELS = ["quiet", "verbose", "debug"] as const;
+export type Verbosity = (typeof VERBOSITY_LEVELS)[number];
+
+/** The level a request runs at when no layer sets one. */
+export const DEFAULT_VERBOSITY: Verbosity = "quiet";
+
+/** The valid levels, for error messages: `quiet, verbose, debug`. */
+export const VERBOSITY_LEVELS_HINT = VERBOSITY_LEVELS.join(", ");
+
+export function isVerbosity(value: unknown): value is Verbosity {
+  return typeof value === "string" && (VERBOSITY_LEVELS as readonly string[]).includes(value);
+}
+
+/** Whether a message that belongs at `floor` is shown at `level`: a level
+ *  shows its own messages and every lower level's. */
+export function shows(level: Verbosity, floor: Verbosity): boolean {
+  return VERBOSITY_LEVELS.indexOf(level) >= VERBOSITY_LEVELS.indexOf(floor);
+}
+
+/** The level for a request through the layers, most specific first; the
+ *  default when no layer sets one. */
+export function resolveVerbosity(layers: {
+  request?: Verbosity;
+  user?: Verbosity;
+  channel?: Verbosity;
+  defaults?: Verbosity;
+}): Verbosity {
+  return layers.request ?? layers.user ?? layers.channel ?? layers.defaults ?? DEFAULT_VERBOSITY;
+}

package/dist/assets/src/deploy/liveGate.ts

@@ -1,4 +1,4 @@
-import { COLD_START_ALLOWANCE_MS, DRAIN_DEADLINE_MS } from "../core/drain.js";
+import { COLD_START_ALLOWANCE_MS, DRAIN_DEADLINE_MS, heldRunsText, type HeldRun } from "../core/drain.js";
 
 // "Deployed" is not "live". `wrangler deploy` uploads a Worker version and
 // starts a container rollout, but the OLD bot container keeps serving while it
@@ -17,6 +17,8 @@ export interface HealthzBody {
   inFlight?: unknown;
   draining?: unknown;
   drainStartedAt?: unknown;
+  /** While draining: the registry-active runs holding the drain (`HeldRun[]`). */
+  held?: unknown;
   build?: { commit?: unknown; builtAt?: unknown } | unknown;
   /** ISO process start — `deploy restart`'s identity (the image, hence `build.commit`, is unchanged). */
   startedAt?: unknown;
@@ -53,7 +55,8 @@ export type ReadyDecision<Identity> =
 export type LiveDecision = ReadyDecision<{ commit: string }>;
 export type RestartDecision = ReadyDecision<{ startedAt: string }>;
 
-function servedCommit(body: HealthzBody): string | undefined {
+/** The `build.commit` a Worker's `/healthz` reports — the commit it serves; undefined when absent. */
+export function servedCommit(body: HealthzBody): string | undefined {
   const b = body.build;
   if (typeof b !== "object" || b === null) return undefined;
   const c = (b as { commit?: unknown }).commit;
@@ -84,14 +87,35 @@ function decideReady<Identity>(
     const verdict = identify(body);
     if (verdict.live) return { kind: "live", ...verdict.identity };
     if (body.draining === true && !verdict.sameIdentity) {
-      const n = typeof body.inFlight === "number" ? body.inFlight : "?";
       const since = typeof body.drainStartedAt === "string" ? ` since ${body.drainStartedAt}` : "";
-      reason = `old container still draining — ${n} run(s) in flight${since}`;
+      // What is actually held, when the body says: the registry-active run ids
+      // and why. The dispatcher's `inFlight` can read 0 while a registry row
+      // holds the drain for its full deadline — a count that mystifies the
+      // operator watching the wait; the ids do not.
+      const held = heldRuns(body);
+      if (held.length > 0) {
+        reason = `old container still draining — holding ${held.length} registry-active run(s): ${heldRunsText(held)}${since}`;
+      } else {
+        const n = typeof body.inFlight === "number" ? body.inFlight : "?";
+        reason = `old container still draining — ${n} run(s) in flight${since}`;
+      }
     } else reason = verdict.reason;
   }
   return elapsedMs >= deadlineMs ? { kind: "timeout", reason } : { kind: "waiting", reason };
 }
 
+/** The `held` rows of a `/healthz` body (src/channels/health.ts): the
+ *  registry-active runs holding the drain. Rows that are not `{id, why}`
+ *  strings — an older container's body, or no drain — parse to none. */
+export function heldRuns(body: HealthzBody): HeldRun[] {
+  if (!Array.isArray(body.held)) return [];
+  return body.held.flatMap((r: unknown) => {
+    if (typeof r !== "object" || r === null) return [];
+    const { id, why } = r as { id?: unknown; why?: unknown };
+    return typeof id === "string" && typeof why === "string" ? [{ id, why }] : [];
+  });
+}
+
 /** Two commit identities name the same commit when one is a prefix of the other
  *  (≥7 chars) — `git rev-parse HEAD` vs. a short form; a `-dirty` suffix never matches. */
 export function sameCommit(a: string, b: string): boolean {
@@ -195,25 +219,28 @@ export interface GaveUpWords {
   force: string;
 }
 
-/** `deploy all`'s words: the release job is re-run once the runs finish. */
+/** `deploy all`'s words: the release job is re-run once what refuses clears.
+ *  In-flight bot runs never refuse (they hand off — run-history item 39); what
+ *  a bot refusal names is a rollout still settling, and a resident refusal is
+ *  its runs in flight — which `--force` over the resident would kill. */
 export const DEPLOY_GAVE_UP_WORDS: GaveUpWords = {
   notDone: "NOT deployed",
-  rerun: "re-run the deploy once they finish (a CI job: `gh run rerun RUN_ID --failed`)",
-  force: "--force to deploy over them (kills the runs in flight that no resume recovers)",
+  rerun: "re-run the deploy once it clears (a CI job: `gh run rerun RUN_ID --failed`)",
+  force: "--force to deploy over it (kills any resident runs in flight that no resume recovers)",
 };
 
-/** `deploy restart`'s words. */
+/** `deploy restart`'s words. Its refusals are the fail-closed cases only —
+ *  runs in flight hand off and never refuse. */
 export const RESTART_GAVE_UP_WORDS: GaveUpWords = {
   notDone: "NOT restarted",
-  rerun: "re-run `deploy restart` once they finish",
-  force: "--force to stop over them (kills the runs in flight that no resume recovers)",
+  rerun: "re-run `deploy restart` once the bot answers",
+  force: "--force to stop blind",
 };
 
 /** The failure a preflight still refusing at the end of the wait budget
  *  produces. The wait is only how long to hold before failing: it never ends
- *  in a deploy over what refused (a rolled container kills the runs it drives,
- *  and a handoff is a recovery, not a guarantee), so the line names the budget,
- *  the refusal, that nothing was done, and the two ways forward. */
+ *  in a deploy over what refused, so the line names the budget, the refusal,
+ *  that nothing was done, and the two ways forward. */
 export function preflightGaveUpLine(
   waitMaxMs: number,
   reason: string,

package/dist/assets/src/deploy/restart.ts

@@ -53,21 +53,20 @@ export const RESTART_SCOPE = "deploy:write";
 export interface RestartVerdict {
   allow: boolean;
   forced: boolean;
-  /** What refuses: runs in flight (a stop rolls the container under them), and the fail-closed cases (no JSON body, an impossible count). */
+  /** What refuses (fail-closed: no JSON body, an impossible count). */
   problems: string[];
-  /** What is said but does not refuse: a drain under way with nothing in flight. */
+  /** What is said but does not refuse: runs in flight (they hand off), a drain under way. */
   warnings: string[];
   message: string;
 }
 /**
  * Whether the container may be stopped now — the deploy preflight's rules
  * (deploy/cloudflare/preflight.mjs `decide`) minus the rollout-state check (a
- * restart is not a rollout). Runs in flight REFUSE: the stop rolls the
- * container under them, and the handoff (docs/reference/specs/run-history.md
- * item 39) is a recovery the next generation may fail, not a guarantee — the
- * CLI waits the 409 out instead. A drain under way with nothing in flight is a
- * warning. Fail closed on a body that is not JSON or an impossible count;
- * `force` allows everything anyway, flagged, naming what it kills.
+ * restart is not a rollout). Since the handoff (docs/reference/specs/run-history.md item
+ * 39) runs in flight and a drain under way are WARNINGS, not refusals: SIGTERM
+ * hands every resumable run to the next generation. Fail closed on a body
+ * that is not JSON or an impossible count; `force` allows those anyway, with
+ * the warning.
  */
 export function decideRestart(body: HealthzBody | undefined, opts: { force: boolean }): RestartVerdict {
   const problems: string[] = [];
@@ -80,8 +79,8 @@ export function decideRestart(body: HealthzBody | undefined, opts: { force: bool
     if (!Number.isInteger(body.inFlight) || (body.inFlight as number) < 0) {
       problems.push(`bot reports an impossible inFlight=${JSON.stringify(body.inFlight)} (counter bug or old Worker)`);
     } else if ((body.inFlight as number) > 0) {
-      problems.push(
-        `${body.inFlight} run(s) in flight — a stop rolls the bot container under them (a handoff is a recovery, not a guarantee)`,
+      warnings.push(
+        `${body.inFlight} run(s) in flight — handed to the next generation on SIGTERM (run-history item 39); they continue there`,
       );
     }
     if (body.draining === true)
@@ -99,14 +98,14 @@ export function decideRestart(body: HealthzBody | undefined, opts: { force: bool
       forced: true,
       problems,
       warnings,
-      message: `restart WARNING: stopping by force despite —\n${detail}\n  this WILL kill the runs in flight that no resume recovers`,
+      message: `restart WARNING: stopping by force despite —\n${detail}`,
     };
   return {
     allow: false,
     forced: false,
     problems,
     warnings,
-    message: `restart REFUSED —\n${detail}\n  wait for them to finish and retry, or pass --force to stop over them`,
+    message: `restart REFUSED —\n${detail}\n  wait and retry, or pass --force to stop blind`,
   };
 }
 

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

@@ -17,6 +17,7 @@
  *  fully owned by the thread user, overwritable, and still isolated from the
  *  warm checkout (a copy shares nothing). */
 
+import { nestedNodeModulesListCmd } from "./residentDepsStore.js";
 import { shellQuote } from "./shellQuote.js";
 
 export const DEP_CACHE_DIRS = ["node_modules", "dist", "build", "out", ".next"] as const;
@@ -217,6 +218,10 @@ export interface DepCacheScriptParse {
    *  node_modules) it left in place because the source has no counterpart —
    *  tree-private entries, not shared inodes (see `mutableCacheSwapScript`). */
   skipped: string[];
+  /** Tree-relative nested node_modules dirs the script hardlinked from the
+   *  store entry (`deploy/w/node_modules`): each needs its own tool-cache
+   *  swap, scoped to that root. */
+  nested: string[];
   failedStep: string | null;
 }
 
@@ -273,6 +278,47 @@ export function depCacheScript(
       `fi`,
     ].join("\n");
   });
+  // A store-backed view also materializes every NESTED node_modules the entry
+  // carries (item 59: the entry holds everything the install produced under a
+  // node_modules — npm installs a workspace's conflicting versions into the
+  // workspace's own node_modules, and a tree without them drifts from its
+  // lockfile: hoisted packages lose their dependent and `npm ls --omit=dev`
+  // misattributes their subtrees to production). Same mechanism per dir as the
+  // top-level one — cp -al, the combined chown/harden walk, the mutable-cache
+  // listing — gated on the tree having the parent dir (a worktree at another
+  // sha may not) and nothing already there. Each hardlinked dir is named on a
+  // `nested=<tree-relative path>` line so the Worker swaps its tool caches.
+  const entryRoot = opts.nodeModulesSrc?.endsWith("/node_modules")
+    ? opts.nodeModulesSrc.slice(0, -"/node_modules".length)
+    : undefined;
+  if (entryRoot) {
+    const entryQ = shellQuote(entryRoot);
+    const wtQ = shellQuote(worktree);
+    const nestedWalk = `find "$dst" \\( -type d -exec chown ${owner} {} + \\) -o \\( -type f \\( -perm -g+w -o -perm -o+w \\) -exec chmod go-w {} + \\)`;
+    blocks.push(
+      [
+        `if test -d ${entryQ}; then`,
+        `  ${nestedNodeModulesListCmd(entryRoot)} | while IFS= read -r rel; do`,
+        `    src=${entryQ}/"$rel"`,
+        `    dst=${wtQ}/"$rel"`,
+        `    pdir="\${dst%/node_modules}"`,
+        `    if test -d "$pdir" && ! test -e "$dst"; then`,
+        `      if cp -al "$src" "$dst"; then`,
+        `        ${nestedWalk} || { echo err=deps-perms; exit 1; }`,
+        `        if ! mlist=$(find "$dst" -mindepth 1 \\( -path "$dst/.*" -o -type d -name .cache \\)); then echo err=deps-mutable-list; exit 1; fi`,
+        `        if [ -n "$mlist" ]; then printf '%s\\n' "$mlist" | sed 's/^/mutable=/'; fi`,
+        `        echo "nested=$rel"`,
+        `      else`,
+        `        rm -rf "$dst"`,
+        `        cp -R "$src" "$dst" || { echo err=deps-copy; exit 1; }`,
+        `        chown -Rh ${owner} "$dst" || { echo err=deps-copy-chown; exit 1; }`,
+        `      fi`,
+        `    fi`,
+        `  done || exit 1`,
+        `fi`,
+      ].join("\n"),
+    );
+  }
   return blocks.join("\n");
 }
 
@@ -280,6 +326,7 @@ export function parseDepCacheScriptOutput(stdout: string): DepCacheScriptParse {
   let mech: DepCacheMaterialization | "none" = "none";
   const mutableListing: string[] = [];
   const skipped: string[] = [];
+  const nested: string[] = [];
   let failedStep: string | null = null;
   for (const raw of stdout.split("\n")) {
     const line = raw.trim();
@@ -292,11 +339,13 @@ export function parseDepCacheScriptOutput(stdout: string): DepCacheScriptParse {
       mutableListing.push(m[1]);
     } else if ((m = /^skipped=(.+)$/.exec(line))) {
       skipped.push(m[1]);
+    } else if ((m = /^nested=(.+)$/.exec(line))) {
+      nested.push(m[1]);
     } else if ((m = /^err=(.+)$/.exec(line))) {
       failedStep ??= m[1];
     }
   }
-  return { mech, mutableListing, skipped, failedStep };
+  return { mech, mutableListing, skipped, nested, failedStep };
 }
 
 /** The per-path swaps for a hardlinked node_modules' tool-managed entries

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

@@ -115,11 +115,30 @@ export function planDepsMaterialization(input: {
 /** The checkout snapshot leaves out its top-level node_modules: since item 59
  *  that directory is a hardlink view of an immutable store entry, and the
  *  entry has its own backup (below). Nested node_modules (a workspace package's
- *  own) stay in — small, and the view mechanism does not cover them. The
+ *  own) stay in — small, and adoption of an old snapshot re-reads them. The
  *  pattern is anchored at the archive root (mksquashfs wildcard semantics:
  *  a bare name matches only there; `...`-prefixed patterns match anywhere). */
 export const CHECKOUT_SNAPSHOT_EXCLUDES: readonly string[] = ["node_modules"];
 
+/** The entry archive is the entry dir itself minus its markers: `.complete`
+ *  must be written by the restore's own commit, LAST, never extracted — a
+ *  partial download that carried the marker would read as a complete entry. */
+export const DEPS_ENTRY_BACKUP_EXCLUDES: readonly string[] = [".complete", ".used"];
+
+/** List every OUTERMOST node_modules under `rootDir` EXCEPT the top-level
+ *  one, tree-relative (`deploy/w/node_modules`), one per line. npm installs a
+ *  workspace's conflicting versions into the workspace's own node_modules
+ *  (the lockfile names those paths), so an entry or a view that carries only
+ *  the top-level dir leaves the tree short of what its lockfile mandates —
+ *  packages hoisted for a nested dependent then read as extraneous, and
+ *  `npm ls --omit=dev` misattributes their subtrees to production (the
+ *  licenses:check LGPL failure that named this). `-prune` keeps copies
+ *  nested INSIDE a listed node_modules with their parent; `.git` is never a
+ *  source of entries. */
+export function nestedNodeModulesListCmd(rootDir: string): string {
+  return `(cd ${shellQuote(rootDir)} && find . \\( -path ./node_modules -o -name .git \\) -prune -o -name node_modules -type d -prune -print | sed 's|^\\./||')`;
+}
+
 /** One backup per lockfile key, taken ONCE right after the entry is committed
  *  (install or adoption) and never again: the entry is immutable, so its
  *  archive is too. Recorded on the DO under this prefix, by key. */
@@ -194,10 +213,20 @@ export function depsHardenScript(input: {
   emptyOk: boolean;
 }): string {
   const nm = shellQuote(`${input.scratchDir}/node_modules`);
+  const scratch = shellQuote(input.scratchDir);
   const absent = input.emptyOk
     ? `mkdir ${nm} && chown ${input.owner} ${nm}`
     : `echo "install produced no node_modules in ${input.scratchDir}" >&2; exit 1`;
-  return [`set -e`, `test -d ${nm} || { ${absent}; }`, `find ${nm} -type f -perm -u+w -exec chmod u-w {} +`].join("\n");
+  return [
+    `set -e`,
+    `test -d ${nm} || { ${absent}; }`,
+    `find ${nm} -type f -perm -u+w -exec chmod u-w {} +`,
+    // Nested workspace node_modules become entry content too (the commit
+    // script moves them), so their inodes are hardened the same way.
+    `${nestedNodeModulesListCmd(input.scratchDir)} | while IFS= read -r rel; do`,
+    `  find ${scratch}/"$rel" -type f -perm -u+w -exec chmod u-w {} + || exit 1`,
+    `done`,
+  ].join("\n");
 }
 
 /** Commit an install to the store, as root, in the order that makes the entry
@@ -221,6 +250,7 @@ export function depsStoreCommitScript(input: {
   keepScratch?: boolean;
 }): string {
   const scratchNm = shellQuote(`${input.scratchDir}/node_modules`);
+  const scratchDirQ = shellQuote(input.scratchDir);
   const staging = shellQuote(input.stagingDir);
   const stagingNm = shellQuote(`${input.stagingDir}/node_modules`);
   const entry = shellQuote(input.entryDir);
@@ -232,6 +262,14 @@ export function depsStoreCommitScript(input: {
     `rm -rf ${staging}`,
     `mkdir ${staging}`,
     `mv ${scratchNm} ${stagingNm}`,
+    // Every outermost NESTED node_modules moves too, at its tree-relative
+    // path (the top-level one is already in staging, so the walk never sees
+    // it): the entry must hold everything the install produced under a
+    // node_modules, or every view of it drifts from its lockfile.
+    `${nestedNodeModulesListCmd(input.scratchDir)} | while IFS= read -r rel; do`,
+    `  mkdir -p ${staging}/"$(dirname "$rel")" || exit 1`,
+    `  mv ${scratchDirQ}/"$rel" ${staging}/"$rel" || exit 1`,
+    `done`,
     // An entry dir WITHOUT its marker is crash debris (the shell died between
     // the rename and the touch): remove it, or the rename below would nest
     // the new staging inside it and the touch would mark the pair complete.

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

@@ -93,15 +93,67 @@ export function planRefresh(input: {
  *  through shared inodes (review 1b). Pruned at any depth (workspaces). */
 export const NODE_MODULES_CACHE_DIRS = [".cache", ".vite"] as const;
 
-/** The checkout-update shell for the build user (runs inside the checkout):
- *  fetch from the local mirror, hard-reset to `sha`, then the `-x` clean.
+/** The one command of the rebuild that READS THE MIRROR — run as the build
+ *  user in the staging tree, inside the stage lock (`stageCheckoutScript`'s
+ *  lease): an attach's `fetch --prune` into the mirror could otherwise delete
+ *  a ref out from under this fetch's negotiation. Everything after it (reset,
+ *  clean, build) touches only the staging tree and runs outside the lock. */
+export const CHECKOUT_FETCH_COMMAND = "git fetch --quiet origin";
+
+/** The directories of the staged rebuild (resident-repos.md item 47): the
+ *  warm checkout, the staging tree the rebuild happens in, and the retired
+ *  path the replaced checkout waits at between the swap's rename and its
+ *  removal. All on one filesystem, so every move below is a rename. */
+export interface CheckoutSwapDirs {
+  checkout: string;
+  staging: string;
+  retired: string;
+}
+
+/** Root shell that seeds the staging tree, under the mirror lock — the one
+ *  hardlink copy of the checkout the lock still covers, exactly
+ *  materializeThreadDeps' consistency guarantee. First the self-heal: a
+ *  container killed between the swap's two renames leaves no checkout and a
+ *  complete retired tree, which is moved back before anything else reads the
+ *  checkout path. Then a previous attempt's leftovers go — the caller already
+ *  dropped the staging tree OFF the lock (a failed build leaves hundreds of
+ *  thousands of inodes; the tree is private, so its removal needs no lock),
+ *  leaving this `rm` a near-instant residual guard; the retired tree's
+ *  heal-then-remove ordering is what needs the lock. Last, `cp -al` takes
+ *  the copy (hardlinks — seconds, never a byte copy; run by root, ownership
+ *  preserved). */
+export function stageCheckoutScript(dirs: CheckoutSwapDirs): string {
+  const { checkout, staging, retired } = dirs;
+  return (
+    `if [ ! -d ${checkout}/.git ] && [ -d ${retired}/.git ]; then mv ${retired} ${checkout}; fi && ` +
+    `rm -rf ${staging} ${retired} && cp -al ${checkout} ${staging}`
+  );
+}
+
+/** Root shell that swaps the built staging tree into the checkout path, under
+ *  the mirror lock: two renames — milliseconds, so an attach's 60 s wait is
+ *  never spent on a build. If the second rename fails the retired tree is put
+ *  back (the checkout path is never left empty for a copier) and the step
+ *  fails; the retired tree itself is removed by the caller AFTER the lock is
+ *  released, so the lock is never held for a large `rm`. */
+export function swapCheckoutScript(dirs: CheckoutSwapDirs): string {
+  const { checkout, staging, retired } = dirs;
+  return (
+    `mv ${checkout} ${retired} && mv ${staging} ${checkout} || ` +
+    `{ if [ ! -d ${checkout} ] && [ -d ${retired}/.git ]; then mv ${retired} ${checkout}; fi; exit 1; }`
+  );
+}
+
+/** The checkout-update shell for the build user (runs inside the staging
+ *  tree, OUTSIDE the mirror lock — the fetch is `CHECKOUT_FETCH_COMMAND`,
+ *  under the stage lock): hard-reset to `sha`, then the `-x` clean.
  *  `-e node_modules` is a git exclude pattern (matches at any depth, so
  *  workspace packages keep theirs too) that survives `-x`; everything else
  *  gitignored — build output above all — is still removed so the build
  *  allocates fresh inodes (review 1b). Keep-deps additionally sweeps the
  *  build-written caches inside node_modules (NODE_MODULES_CACHE_DIRS). */
 export function checkoutUpdateCommand(sha: string, clean: CleanScope): string {
-  const base = `git fetch --quiet origin && git reset --hard --quiet ${sha}`;
+  const base = `git reset --hard --quiet ${sha}`;
   if (clean === "all") return `${base} && git clean -fdx`;
   const names = NODE_MODULES_CACHE_DIRS.map((d) => `-name ${d}`).join(" -o ");
   const sweep = `find . -path '*/node_modules/*' -type d \\( ${names} \\) -prune -exec rm -rf {} +`;

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

@@ -18,6 +18,10 @@ export const RESIDENT_STEP_LABELS = {
   "for-each-ref": "listing the branches",
   checkout: "checking out the branch",
   "checkout-update": "updating the checkout",
+  "checkout-stage": "staging the checkout rebuild",
+  "checkout-stage-clear": "removing the leftover staging tree",
+  "checkout-swap": "swapping in the rebuilt checkout",
+  "checkout-retire": "removing the replaced checkout",
   "rev-parse": "reading the commit",
   "cat-file": "checking the mirror for the commit",
   "show-ref": "reading the branch tip",

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

@@ -344,6 +344,14 @@ export function runtimeUnreachableExecAnswer(message: string): {
 /** The named reason the Worker answers with, beside `fleet-busy` and `sandbox-starting`. */
 export const RUNTIME_BUSY_REASON = "runtime-busy" as const;
 
+/** The resident's own word for a container near its cgroup memory cap
+ *  (resident-repos.md item 70): a new attach above the soft threshold and a
+ *  new exec above the hard one are refused with this token — the same 503
+ *  shape as `mirror-busy`, so the bot falls back or waits legibly while the
+ *  commands already running finish. Defined here, beside the other machine
+ *  tokens both sides read, so the Worker and the bot cannot drift. */
+export const MEMORY_PRESSURE_REASON = "memory-pressure" as const;
+
 /** What the token means, in the words the model and the operator see. */
 export const RUNTIME_BUSY_EXPLANATION =
   "the thread's sandbox container is running but did not accept the connection inside the platform's allowance — nothing ran, the request is re-sent once it accepts";