@coreplane/switchboard 0.0.0 → 1.18.0

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

@@ -0,0 +1,95 @@
+/** The worktree clean-check as ONE spawn, kept pure and
+ *  dependency-free so it is unit-testable from src/ and imported by the
+ *  resident Worker (deploy/cloudflare-resident/worker.ts
+ *  `worktreeCleanliness`) like residentDepCache — the tested code IS the
+ *  shipped code.
+ *
+ *  Background: the check used to be three sequential container spawns per
+ *  binding (`test -d`, `su … git status --porcelain`, `su … git rev-list
+ *  --count HEAD --not --remotes`), and `isIdle()` ran it serially per live
+ *  binding — every refresh cycle's idle gate paid 3×N process round-trips.
+ *  The three probes fold into one `sh -c` script; the DECISION semantics are
+ *  unchanged and encoded in `parseWorktreeCleanliness`:
+ *    - no `.git` dir → clean ("worktree missing (disk recycled)" — nothing
+ *      to preserve);
+ *    - a git probe failing → NOT clean ("never destroy work on a guess"),
+ *      reason `clean-check failed: <first error line>`;
+ *    - tracked changes or unpushed commits → NOT clean, both counts named;
+ *    - else clean.
+ *
+ *  Security posture, preserved exactly: the git probes run AS THE
+ *  THREAD USER via `su` — the worktree is thread-owned, root git in it would
+ *  be refused by safe.directory and would be the repo-local-config execution
+ *  vector safe.directory exists to block. Only the `test -d` runs as the
+ *  caller (root), same as before.
+ *
+ *  Output is tagged lines (the readRefreshDisk idiom): parsing keys on the
+ *  tag, never line position, so a su/PAM banner cannot shift a field. */
+
+import { shellQuote } from "./shellQuote.js";
+
+/** Build the one-spawn probe script. Run it via `sh -c` as root with the
+ *  usual GIT_TERMINAL_PROMPT=0 injection; feed the result to
+ *  `parseWorktreeCleanliness`. */
+export function worktreeCleanlinessScript(worktreePath: string, user: string): string {
+  const gitDir = shellQuote(`${worktreePath}/.git`);
+  const wt = shellQuote(worktreePath);
+  // The inner script (as the thread user) captures each probe's stdout and
+  // stderr separately — stderr via a temp file, first non-empty line kept —
+  // so a stderr warning on a SUCCESSFUL probe can never inflate the change
+  // count, and the failure reason stays the first stderr line exactly as the
+  // old per-probe code reported it.
+  const inner = [
+    `t=$(mktemp) || { echo gitrc=1; echo 'giterr=mktemp failed'; exit 0; }`,
+    `cd ${wt} 2>"$t" || { echo gitrc=1; printf 'giterr=%s\\n' "$(grep -m 1 . "$t" || echo 'cd failed')"; rm -f "$t"; exit 0; }`,
+    `s_out=$(git status --porcelain 2>"$t"); s_rc=$?; s_err=$(grep -m 1 . "$t" || true)`,
+    `a_out=$(git rev-list --count HEAD --not --remotes 2>"$t"); a_rc=$?; a_err=$(grep -m 1 . "$t" || true)`,
+    `rm -f "$t"`,
+    `if [ "$s_rc" -ne 0 ] || [ "$a_rc" -ne 0 ]; then`,
+    `  echo gitrc=1`,
+    `  if [ -n "$s_err" ]; then printf 'giterr=%s\\n' "$s_err"`,
+    `  elif [ -n "$a_err" ]; then printf 'giterr=%s\\n' "$a_err"`,
+    `  else echo 'giterr=git exited non-zero'; fi`,
+    `  exit 0`,
+    `fi`,
+    `echo gitrc=0`,
+    `printf 'changes=%s\\n' "$(printf '%s' "$s_out" | grep -c .)"`,
+    `printf 'unpushed=%s\\n' "$a_out"`,
+  ].join("\n");
+  return [
+    `if ! test -d ${gitDir}; then echo present=no; exit 0; fi`,
+    `echo present=yes`,
+    `su -s /bin/bash ${shellQuote(user)} -c ${shellQuote(inner)}`,
+  ].join("\n");
+}
+
+export interface WorktreeCleanliness {
+  clean: boolean;
+  reason?: string;
+}
+
+/** Decide from the script's tagged output. Unknown (missing/failed tags,
+ *  non-zero exit, timeout) counts as NOT clean — never destroy work on a
+ *  guess — matching the pre-fold decision exactly. */
+export function parseWorktreeCleanliness(r: {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  timedOut: boolean;
+}): WorktreeCleanliness {
+  const tags = new Map<string, string>();
+  for (const line of r.stdout.split("\n")) {
+    const m = /^(present|gitrc|giterr|changes|unpushed)=(.*)$/.exec(line.trim());
+    if (m && !tags.has(m[1])) tags.set(m[1], m[2].trim());
+  }
+  if (tags.get("present") === "no") return { clean: true, reason: "worktree missing (disk recycled)" };
+  if (r.timedOut || r.exitCode !== 0 || tags.get("gitrc") !== "0") {
+    const why = tags.get("giterr") || (r.stderr || "git exited non-zero").trim().split("\n")[0];
+    return { clean: false, reason: `clean-check failed: ${why}` };
+  }
+  const changes = Number(tags.get("changes")) || 0;
+  const unpushed = Number(tags.get("unpushed")) || 0;
+  if (changes > 0 || unpushed > 0)
+    return { clean: false, reason: `dirty: ${changes} uncommitted change(s), ${unpushed} unpushed commit(s)` };
+  return { clean: true };
+}

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

@@ -0,0 +1,81 @@
+/** The per-exec credential-refresh decision of the resident Worker
+ *  (deploy/cloudflare-resident/worker.ts `execThreadImpl`), kept pure and
+ *  dependency-free so it is unit-testable from src/ and imported across
+ *  packages by the Worker (like residentDetach/shellQuote) — the tested code
+ *  IS the shipped code.
+ *
+ *  Background: attach writes a 1-hour GitHub App installation token
+ *  into `<worktree>/.git/github-credentials` and points git's `store` helper
+ *  at it. Nothing used to refresh it during a run, so a push more than ~60
+ *  minutes after attach got 401 — and git's `store` helper ERASES a rejected
+ *  credential from its file, leaving the agent staring at an empty file. The
+ *  Worker now asks this function before every writable `/exec` and re-mints
+ *  (cached per slug) + rewrites the file when it says so.
+ *
+ *  The refresh is driven by the TOKEN'S OWN EXPIRY, not the file's age.
+ *  `mintRepoScopedToken` caches per repository slug, so a token minted for an
+ *  earlier thread — with only a few minutes of life left — could be written
+ *  for a brand-new attach and, keyed on file age alone, read "fresh" for ~45
+ *  minutes while every writable exec in between ran on a dead token (the first
+ *  git write 401s, `store` blanks the file, and only the NEXT exec refreshed).
+ *  Now the binding records the token's `expiresAtMs`, and this predicate
+ *  refreshes once the token is within `CREDENTIAL_EXPIRY_MARGIN_MS` of expiry
+ *  — so a writable exec never starts on a token that cannot outlive it. */
+
+import { BASH_TIMEOUT_MAX_MS } from "./bashTimeout.js";
+
+/** Backstop for bindings that predate `tokenExpiresAtMs`: re-mint
+ *  this long after the file was written when the token's real expiry is
+ *  unknown — comfortably before the 60-minute token expiry. New bindings carry
+ *  the expiry and take the margin path below instead. */
+export const CREDENTIAL_REFRESH_AFTER_MS = 45 * 60_000;
+
+/** Refresh once the token is within this much of expiry, so a writable exec
+ *  never starts on a token that cannot outlive the command it is about to run.
+ *  Sized like the sandbox's per-command credential margin: the longest
+ *  single exec is `BASH_TIMEOUT_MAX_MS` (20 min), plus slack for the mint +
+ *  file write and clock skew ⇒ 25 min. This is also `mintRepoScopedToken`'s
+ *  cache serve threshold, so the cache and this predicate agree: a token the
+ *  cache would still hand out is a token this predicate would not refresh. */
+export const CREDENTIAL_EXPIRY_MARGIN_MS = BASH_TIMEOUT_MAX_MS + 5 * 60_000;
+
+export type CredentialRefreshReason =
+  /** The token is within `CREDENTIAL_EXPIRY_MARGIN_MS` of its expiry (or past it). */
+  | "expiring"
+  /** No token expiry recorded (binding predates the field) and the file is
+   *  older than `CREDENTIAL_REFRESH_AFTER_MS`, or its write time is unknown. */
+  | "stale"
+  /** The file exists with zero bytes — git's `store` helper erased a rejected token. */
+  | "empty"
+  /** No file at all (never written on this tree, or removed). */
+  | "missing";
+
+export function shouldRefreshThreadCredentials(input: {
+  /** When the binding's credential file was last written; null when the
+   *  binding predates the field. Only consulted on the file-age backstop. */
+  writtenAtMs: number | null;
+  /** When the written token expires (epoch ms); null/undefined when the
+   *  binding predates the field — then the file-age backstop applies. */
+  tokenExpiresAtMs?: number | null;
+  nowMs: number;
+  /** Size of `<worktree>/.git/github-credentials`; null when the file is absent. */
+  fileBytes: number | null;
+  /** Read-only bindings (item 50) never carry credentials — never refresh. */
+  readonly: boolean;
+}): { refresh: boolean; reason: CredentialRefreshReason | null } {
+  const { writtenAtMs, tokenExpiresAtMs, nowMs, fileBytes, readonly } = input;
+  if (readonly) return { refresh: false, reason: null };
+  if (fileBytes === null) return { refresh: true, reason: "missing" };
+  if (fileBytes === 0) return { refresh: true, reason: "empty" };
+  // Known expiry: drive the refresh off the token's own life, not the
+  // file's age. Replaces the file-age heuristic for any binding that records it.
+  if (tokenExpiresAtMs != null) {
+    if (nowMs > tokenExpiresAtMs - CREDENTIAL_EXPIRY_MARGIN_MS) return { refresh: true, reason: "expiring" };
+    return { refresh: false, reason: null };
+  }
+  // Backstop for a binding written before the expiry was recorded: fall back to
+  // file age so an old binding still refreshes.
+  if (writtenAtMs === null || nowMs - writtenAtMs > CREDENTIAL_REFRESH_AFTER_MS)
+    return { refresh: true, reason: "stale" };
+  return { refresh: false, reason: null };
+}

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

@@ -0,0 +1,321 @@
+/** Per-directory mechanism for the resident's dep/build cache
+ *  (docs/reference/specs/resident-repos.md item 18), kept pure and dependency-free so it
+ *  is unit-testable from src/ and imported by the resident Worker
+ *  (deploy/cloudflare-resident/worker.ts `materializeThreadDeps`) like
+ *  residentReadonly / residentHead — the tested code IS the shipped code.
+ *
+ *  Background: every cached dir used to be
+ *  hardlink-copied (`cp -al`) from the warm checkout with the FILE inodes
+ *  left worker1-owned and stripped of group/world write — right for
+ *  node_modules, which a thread only ever reads, and the whole point of the
+ *  tamper-proofing (a thread must never mutate bytes the warm checkout or a
+ *  peer tree sees). But the review agent is told to RUN the project's build,
+ *  and `/op build` runs it too; compilers rewrite `dist/**` in place
+ *  (open+truncate through the existing inode), so with a hardlinked `dist/`
+ *  the build died with EACCES and the agent reported the tree as read-only.
+ *  Build outputs are therefore materialized as plain copies: fresh inodes
+ *  fully owned by the thread user, overwritable, and still isolated from the
+ *  warm checkout (a copy shares nothing). */
+
+import { shellQuote } from "./shellQuote.js";
+
+export const DEP_CACHE_DIRS = ["node_modules", "dist", "build", "out", ".next"] as const;
+export type DepCacheDir = (typeof DEP_CACHE_DIRS)[number];
+
+/** How one cached dir is brought into a thread tree. `hardlink` = `cp -al`
+ *  (shared worker1-owned read-only inodes; falls back to `copy` when the
+ *  hardlink fails, e.g. cross-device). `copy` = `cp -R` + `chown -R` (fresh
+ *  thread-owned inodes). */
+export type DepCacheMaterialization = "hardlink" | "copy";
+
+export function depCacheMaterialization(dir: DepCacheDir): DepCacheMaterialization {
+  return dir === "node_modules" ? "hardlink" : "copy";
+}
+
+// -- the per-attach plan ----------------------------------------------------------
+
+/** What `materializeThreadDeps` does for one tree: `seed` = bring the cached
+ *  dirs in from the warm checkout (node_modules hardlinked, per
+ *  depCacheMaterialization); `install` = run the command table's install in the
+ *  tree afterwards. A lockfile-diverged thread gets BOTH — the install then
+ *  reconciles only the delta on top of the seed, because npm/pnpm replace a
+ *  changed package with fresh inodes and can never write through a shared one
+ *  (the seed's file inodes are worker1-owned with group/world write stripped).
+ *  Before this the diverged case installed from an empty tree: gigabytes
+ *  projected and minutes on the 1 vCPU it shares with the refresh cycle, long
+ *  enough for the bot's /attach to die first. No install command
+ *  (item 52's package.json-less table) leaves a diverged tree unseeded: a seed
+ *  nothing can reconcile would be the WRONG deps presented as ready. */
+export interface ThreadDepsPlan {
+  seed: boolean;
+  install: boolean;
+  why: string;
+}
+
+export function planThreadDeps(input: {
+  hasDeps: boolean;
+  threadLockKey: string;
+  warmLockKey: string;
+  installCmd: string | undefined;
+}): ThreadDepsPlan {
+  if (input.hasDeps) return { seed: false, install: false, why: "reused tree — cache already in place" };
+  if (input.threadLockKey === input.warmLockKey) {
+    return {
+      seed: true,
+      install: false,
+      why: "lockfile matches the warm checkout — shared cache, nothing to reconcile",
+    };
+  }
+  if (input.installCmd === undefined) {
+    return {
+      seed: false,
+      install: false,
+      why: "lockfile differs and the command table has no install — nothing to reconcile with",
+    };
+  }
+  return {
+    seed: true,
+    install: true,
+    why: "lockfile differs from the warm checkout — seeded from the shared cache, install reconciles the delta",
+  };
+}
+
+/** The `deps` field on the attach answer. `reconcile` = seeded then installed
+ *  (the seed's own mechanism is secondary: the install decided the tree's
+ *  contents); otherwise the seed's mechanism, or `none`. */
+export type ThreadDepsMechanism = DepCacheMaterialization | "reconcile" | "none";
+
+export function threadDepsMechanism(input: {
+  seeded: DepCacheMaterialization | "none";
+  installed: boolean;
+}): ThreadDepsMechanism {
+  return input.installed ? "reconcile" : input.seeded;
+}
+
+/** Inside a HARDLINKED node_modules, the paths tools rewrite in place and so
+ *  must be real copies (fresh thread-owned inodes) rather than shared
+ *  read-only inodes — the same EACCES class as the build dirs, one level
+ *  down. Packages themselves are immutable after install; the mutable parts
+ *  are tool-managed: every TOP-LEVEL dot entry of node_modules (`.cache` —
+ *  babel-loader/eslint/prettier/webpack; `.vite` + `.vitest` — vite's dep
+ *  optimizer and vitest's results file; `.prisma` — the client `prisma
+ *  generate` rewrites during a build; `.bin` — shims some installers
+ *  regenerate; `.package-lock.json` — npm's hidden lockfile) plus any
+ *  `.cache` directory nested deeper (a package's own on-disk cache, e.g.
+ *  `node_modules/<loader>/.cache`). Scoped packages (`@scope`) are not dot
+ *  entries. Nested dot dirs OTHER than `.cache` (a vendored `.github`, a
+ *  package's `.bin`) stay shared: they are package content, not caches.
+ *
+ *  The ONE top-level dot entry that is package content, not a cache, is
+ *  `.pnpm` — pnpm's virtual store, where every installed package's files
+ *  actually live (the top-level entries are symlinks into it). It is
+ *  immutable after install, exactly like the packages it holds, so it stays
+ *  hardlinked; a `.cache` nested inside it is still a cache and still copied.
+ *  Swapping it for a plain copy makes every thread tree of a pnpm workspace a
+ *  full copy of its dependencies (gigabytes, minutes per fresh attach) — one
+ *  thread can fill a resident's disk that way.
+ *
+ *  `mutableCacheFindArgv` is the exact `find` the Worker runs to enumerate
+ *  those paths; `mutableCachePaths` turns its output lines into the list to
+ *  replace, dropping anything already covered by a listed ancestor (the
+ *  ancestor copy brings its subtree along) and anything outside the root. */
+export function mutableCacheFindArgv(nodeModulesDir: string): string[] {
+  // `-path "<root>/.*"` (find's -path glob does not treat "/" specially)
+  // matches every top-level dot entry AND its descendants — the descendants
+  // are dropped by mutableCachePaths' ancestor rule. Deliberately not
+  // `-maxdepth`: GNU find applies -maxdepth GLOBALLY even inside parentheses
+  // (with a warning), which would cap the nested .cache search at depth 1.
+  return [
+    "find",
+    nodeModulesDir,
+    "-mindepth",
+    "1",
+    "(",
+    "-path",
+    `${nodeModulesDir}/.*`,
+    "-o",
+    "-type",
+    "d",
+    "-name",
+    ".cache",
+    ")",
+  ];
+}
+
+/** Top-level dot entries of node_modules that hold PACKAGE CONTENT rather than
+ *  a tool's cache — shared like any package, never copied per thread. */
+const PACKAGE_STORE_ENTRIES: ReadonlySet<string> = new Set([".pnpm"]);
+
+export function mutableCachePaths(nodeModulesDir: string, findOutputLines: readonly string[]): string[] {
+  const root = nodeModulesDir.replace(/\/+$/, "");
+  const candidates = findOutputLines
+    .map((l) => l.trim())
+    .filter((l) => l !== "" && l.startsWith(`${root}/`))
+    .filter((l) => {
+      const rel = l.slice(root.length + 1);
+      const parts = rel.split("/");
+      if (parts.length === 1) return parts[0].startsWith(".") && !PACKAGE_STORE_ENTRIES.has(parts[0]);
+      return parts[parts.length - 1] === ".cache";
+    })
+    .sort((a, b) => a.length - b.length);
+  const kept: string[] = [];
+  for (const c of candidates) {
+    if (kept.some((k) => c.startsWith(`${k}/`))) continue;
+    kept.push(c);
+  }
+  // Preserve the find's own order among the kept paths for readable logs.
+  const order = new Map(findOutputLines.map((l, i) => [l.trim(), i] as const));
+  return kept.sort((a, b) => (order.get(a) ?? 0) - (order.get(b) ?? 0));
+}
+
+/** What the attach answer's `deps` field reports after each dir is
+ *  materialized. `node_modules` is the dependency cache the field exists to
+ *  describe (`hardlink` = warm shared cache, `copy` = cp -al fell back), so
+ *  it decides whenever the warm checkout has one; build-dir copies are the
+ *  norm and must not mask that signal — they only fill in when nothing else
+ *  has. `none` in = nothing materialized yet. */
+export function foldDepsMechanism(
+  prev: DepCacheMaterialization | "none",
+  dir: DepCacheDir,
+  used: DepCacheMaterialization | "none",
+): DepCacheMaterialization | "none" {
+  if (dir === "node_modules") return used;
+  return prev === "none" ? used : prev;
+}
+
+// ---------------------------------------------------------------------------
+// One-fork materialization
+// ---------------------------------------------------------------------------
+//
+// materializeThreadDeps used to spawn per dir: `test -d`, `test -e`, the
+// `cp -al`/`cp -R`, a full `find -type d -exec chown` walk, a SECOND full
+// `find -type f -exec chmod` walk, the mutable-cache `find` listing, then
+// rm/cp/chown per mutable path — ~25 container round-trips for five dirs,
+// all while holding the mirror mutex (which every concurrent attach and the
+// refresh cycle queue behind). The same work now runs as TWO forks:
+// `depCacheScript` handles all five dirs (per-dir gating, mechanism,
+// permissions in ONE combined find walk, the mutable-cache listing) and
+// emits one tagged line per materialized dir plus the raw listing; the DO
+// parses with `parseDepCacheScriptOutput`, filters the listing through the
+// unchanged `mutableCachePaths`, and `mutableCacheSwapScript` performs every
+// swap in the second fork. The resulting ownership/permission state is
+// byte-identical to the per-spawn version (the security posture is in the
+// ownership and mode bits — see each block's comment); only the fork count
+// changed.
+
+/** What the DO reads back from one script run. `failedStep` carries the
+ *  `err=` tag a failing block emitted (the old per-spawn StepError names:
+ *  deps-perms — the combined chown+harden walk, formerly deps-chown +
+ *  deps-harden — deps-mutable-list, deps-copy, deps-copy-chown, and the swap
+ *  script's deps-mutable-rm/copy/chown). */
+export interface DepCacheScriptParse {
+  mech: DepCacheMaterialization | "none";
+  /** Raw `find` output for the hardlinked node_modules (the exact
+   *  `mutableCacheFindArgv` shape), for `mutableCachePaths`. */
+  mutableListing: string[];
+  failedStep: string | null;
+}
+
+/** Build the one-fork materialization script over every DEP_CACHE_DIRS entry.
+ *  Per dir, exactly the old per-spawn behavior:
+ *   - src missing or dst present → skip (no line emitted, mechanism unfolded);
+ *   - hardlink dirs (node_modules): `cp -al`, then ONE find walk chowning
+ *     DIRECTORIES to the thread user and stripping group/world write from the
+ *     shared FILE inodes (`( -type d -exec chown … + ) -o ( -type f ( -perm
+ *     -g+w -o -perm -o+w ) -exec chmod go-w … + )` — the -o short-circuits on
+ *     the first alternative's always-true `-exec +`, so dirs get the chown and
+ *     only files reach the perm test: the union of the two old walks, one
+ *     traversal); then the mutable-cache listing (`mutableCacheFindArgv`,
+ *     emitted as `mutable=` lines). `cp -al` failure → rm + plain-copy
+ *     fallback, same as before;
+ *   - copy dirs: `cp -R` + `chown -Rh` (never dereference a planted symlink). */
+export function depCacheScript(
+  checkoutDir: string,
+  worktree: string,
+  user: string,
+  /** `nodeModulesSrc`: the deps store entry's node_modules (item 59) — the
+   *  immutable source every view hardlinks from; the checkout stays the
+   *  source for the build dirs (they are build output at the checkout's sha).
+   *  Omitted → the checkout's own node_modules, the pre-store behavior. */
+  opts: { nodeModulesSrc?: string } = {},
+): string {
+  const owner = shellQuote(`${user}:${user}`);
+  const blocks = DEP_CACHE_DIRS.map((dir) => {
+    const src = shellQuote(
+      dir === "node_modules" && opts.nodeModulesSrc ? opts.nodeModulesSrc : `${checkoutDir}/${dir}`,
+    );
+    const dst = shellQuote(`${worktree}/${dir}`);
+    const copyFallback = [
+      `  cp -R ${src} ${dst} || { echo err=deps-copy; exit 1; }`,
+      `  chown -Rh ${owner} ${dst} || { echo err=deps-copy-chown; exit 1; }`,
+      `  echo 'dir:${dir}=copy'`,
+    ];
+    if (depCacheMaterialization(dir) !== "hardlink") {
+      return [`if test -d ${src} && ! test -e ${dst}; then`, ...copyFallback, `fi`].join("\n");
+    }
+    const walk = `find ${dst} \\( -type d -exec chown ${owner} {} + \\) -o \\( -type f \\( -perm -g+w -o -perm -o+w \\) -exec chmod go-w {} + \\)`;
+    const listing = mutableCacheFindArgv(`${worktree}/${dir}`).map(shellQuote).join(" ");
+    return [
+      `if test -d ${src} && ! test -e ${dst}; then`,
+      `  if cp -al ${src} ${dst}; then`,
+      `    ${walk} || { echo err=deps-perms; exit 1; }`,
+      `    if ! mlist=$(${listing}); then echo err=deps-mutable-list; exit 1; fi`,
+      `    if [ -n "$mlist" ]; then printf '%s\\n' "$mlist" | sed 's/^/mutable=/'; fi`,
+      `    echo 'dir:${dir}=hardlink'`,
+      `  else`,
+      `    rm -rf ${dst}`,
+      ...copyFallback,
+      `  fi`,
+      `fi`,
+    ].join("\n");
+  });
+  return blocks.join("\n");
+}
+
+export function parseDepCacheScriptOutput(stdout: string): DepCacheScriptParse {
+  let mech: DepCacheMaterialization | "none" = "none";
+  const mutableListing: string[] = [];
+  let failedStep: string | null = null;
+  for (const raw of stdout.split("\n")) {
+    const line = raw.trim();
+    let m: RegExpExecArray | null;
+    if ((m = /^dir:([^=]+)=(hardlink|copy)$/.exec(line))) {
+      if ((DEP_CACHE_DIRS as readonly string[]).includes(m[1])) {
+        mech = foldDepsMechanism(mech, m[1] as DepCacheDir, m[2] as DepCacheMaterialization);
+      }
+    } else if ((m = /^mutable=(.+)$/.exec(line))) {
+      mutableListing.push(m[1]);
+    } else if ((m = /^err=(.+)$/.exec(line))) {
+      failedStep ??= m[1];
+    }
+  }
+  return { mech, mutableListing, failedStep };
+}
+
+/** The per-path swaps for a hardlinked node_modules' tool-managed entries
+ *  (`mutableCachePaths` output), all in one fork: `rm -rf` the shared
+ *  subtree, `cp -R` the warm checkout's matching subpath (fresh inodes),
+ *  `chown -Rh` to the thread user (-h: a postinstall-planted symlink is
+ *  re-owned as a LINK, never followed to an out-of-tree target). Same steps,
+ *  same order, same flags as the old per-spawn loop. */
+export function mutableCacheSwapScript(
+  srcRoot: string,
+  dstRoot: string,
+  user: string,
+  paths: readonly string[],
+): string {
+  const owner = shellQuote(`${user}:${user}`);
+  const root = dstRoot.replace(/\/+$/, "");
+  const lines: string[] = [];
+  for (const p of paths) {
+    const rel = p.slice(root.length);
+    lines.push(`rm -rf ${shellQuote(p)} || { echo err=deps-mutable-rm; exit 1; }`);
+    lines.push(`cp -R ${shellQuote(`${srcRoot}${rel}`)} ${shellQuote(p)} || { echo err=deps-mutable-copy; exit 1; }`);
+    // cp copies mode bits: a store entry's files are owner-read-only (item 59,
+    // hardened so no consumer can write through the shared inodes), and a
+    // cache the tree's own tools must rewrite in place has to be writable.
+    lines.push(`chmod -R u+w ${shellQuote(p)} || { echo err=deps-mutable-chmod; exit 1; }`);
+    lines.push(`chown -Rh ${owner} ${shellQuote(p)} || { echo err=deps-mutable-chown; exit 1; }`);
+  }
+  return lines.join("\n");
+}