create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/agent-bundle/codex-install.js

@@ -0,0 +1,558 @@
+'use strict';
+
+/**
+ * WP-6 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-14, the D-14 decision row, §6.3, §8
+ * WP-6 row, AC-6a..AC-6c): CODEX INSTALL-MODE — the one place the box writes into its own home.
+ *
+ * Codex has no session-scoped skills root (`--add-dir` is a Claude-only flag, and `CODEX_HOME` also
+ * holds the user's sign-in, so it cannot be swapped per session — D-14's decision row, read
+ * codex-rs/ext/skills/src/host_roots.rs:48-185), so the bundle's `codex/<name>/` items are
+ * INSTALLED into `$HOME/.agents/skills/<name>/` with the SAME dpkg-conffile rule the box's own
+ * managed-skill installer already uses (lib/coding-cli-skill-installer.js): a pristine copy is
+ * created/updated, an edited copy is kept and reported, a folder CTM never wrote is untouched.
+ *
+ * REPLACE/REUSE, never a parallel installer: the marker/record constants, the root-record reader,
+ * the root-record writer and D-8's `writeAllowed` all come from lib/coding-cli-skill-installer.js.
+ * A directory-source plan is a genuinely different shape from that module's one-file template plan
+ * (its `buildPlan` classifies a single SKILL.md against a known-hash SET; here the unit is a whole
+ * directory compared hash-for-hash against the tree copy), so the planner lives here and calls the
+ * shared helpers; folding the two into one function would make the single-file path read worse.
+ *
+ * Classification (first match wins), per name:
+ *   1. target dir missing            -> `removed` when the root record remembers an `agent-bundle`
+ *                                       entry (the user deleted it — never resurrect), else `create`.
+ *                                       EXCEPTION: a leftover `.<name>.ctm-retired-*` (crash
+ *                                       mid-swap) means `create`.
+ *   2. no marker, or `source !== 'agent-bundle'` -> `conflict` (user-authored, or another
+ *                                       installer's copy — untouched, not even hashed).
+ *   3. `diskDirHash !== marker.sha256` -> `edited` (kept; WP-7 reports "changed on box").
+ *   4. `diskDirHash === bundleDirHash` -> `noop`.
+ *   5. else                             -> `update`.
+ *   retire: an installed `agent-bundle` copy of THIS hub, pristine, ABSENT from the current tree ->
+ *           `retire` (the hub deleted that skill). Edited or other-hub copies are never retired.
+ *
+ * Write order per skill: staging dir (0644/0755 — the tree's read-only modes must NOT be copied, the
+ * user has to be able to edit) holding the copied bytes + the marker, then the swap (rename old to
+ * `.<name>.ctm-retired-*`, rename staging into place, remove the retired dir), then the root-record
+ * entry (atomic writes throughout, mirroring the installer's D-6 order).
+ *
+ * EVENT-DRIVEN, never a timer (stabilization lint): the store only changes at the two moments
+ * lib/agent-bundle/gc.js already names (boot, and a manifest PUT), so the codex install is scheduled
+ * from the manifest-PUT seam and is single-flight exactly like `scheduleCollectGarbage`.
+ */
+
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+const { atomicWriteFile } = require('../../atomic-write');
+const store = require('./store');
+const installer = require('../coding-cli-skill-installer');
+
+/** D-14: the box-home write target. NOT `$CODEX_HOME/skills` — Codex marks that root deprecated. */
+const AGENTS_SKILLS_DIR = '.agents';
+const SKILLS_DIR = 'skills';
+/** The id shape an item name must have to be usable as a directory name (store.js's ID_RE). */
+const NAME_RE = /^[A-Za-z0-9._-]{1,128}$/;
+const STAGING_RE = /^\.(.+)\.ctm-staging-[0-9a-f]+$/;
+const RETIRED_RE = /^\.(.+)\.ctm-retired-[0-9a-f]+$/;
+/** The marker `source` THIS module writes (the installer's own copies carry its own source string). */
+const SOURCE = 'agent-bundle';
+
+const { writeAllowed, MANAGED_SKILLS } = installer;
+const { MARKER_FILE, ROOT_RECORD_FILE, readMarker, readRootRecord, writeRootRecord } = installer._internals;
+
+/** REPORT sink: a throwing reporting backend must never turn a per-skill failure into a throw. */
+function _report(report, error) {
+  if (typeof report !== 'function') return;
+  try {
+    report(error);
+  } catch {
+    /* expected: the report sink is best-effort telemetry; its own failure is not an install failure */
+  }
+}
+
+function _rand() {
+  return crypto.randomBytes(6).toString('hex');
+}
+
+function _sha256(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+/** The install root (D-14). Absolute; `homeDir` is injected so a test never reads the real home. */
+function skillsRoot(homeDir) {
+  return path.join(homeDir, AGENTS_SKILLS_DIR, SKILLS_DIR);
+}
+
+async function _statOrNull(target) {
+  try {
+    return await fsp.lstat(target);
+  } catch (error) {
+    if (error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) return null;
+    throw error; // RETHROW: an unreadable path is a real fault the caller REPORTs
+  }
+}
+
+async function _isDir(target) {
+  const stat = await _statOrNull(target);
+  return stat !== null && stat.isDirectory();
+}
+
+/** readdir of a directory that may not exist yet (an empty root is not an error). */
+async function _readdirOrEmpty(dir) {
+  try {
+    return await fsp.readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) return []; /* expected: no root yet */
+    throw error; // RETHROW: an unreadable directory is a real fault
+  }
+}
+
+/** Recursive remove that tolerates a vanished path (a concurrent run, or the rename that consumed it). */
+async function _removeQuiet(target) {
+  try {
+    await fsp.rm(target, { recursive: true, force: true });
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return; /* expected: already gone */
+    throw error; // RETHROW: a failed removal is a real fault (the caller REPORTs it)
+  }
+}
+
+/**
+ * sha256 over the sorted `{relPath, exec, sha256}` of every regular file under `dir`, EXCLUDING
+ * dot-names at any depth (so a `.ctm-managed` marker or a `.SKILL.md.edited-*.bak` backup never
+ * counts) and never following a symlink out of the directory (symlinks and other non-regular files
+ * are skipped — the hub builder already excludes them from the tree, so the tree copy and the
+ * installed copy hash equal iff their bytes match).
+ *
+ * @returns {Promise<string>} 64-hex digest
+ */
+async function dirHash(dir) {
+  const files = [];
+  await _walk(dir, '', files);
+  files.sort((a, b) => (a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0));
+  const payload = files.map((file) => `${file.relPath}\0${file.exec ? 'x' : '-'}\0${file.sha256}\n`).join('');
+  return _sha256(payload);
+}
+
+async function _walk(base, rel, out) {
+  const current = rel ? path.join(base, rel) : base;
+  for (const dirent of await _readdirOrEmpty(current)) {
+    if (dirent.name.startsWith('.')) continue; // markers/backups are never content
+    const childRel = rel ? `${rel}/${dirent.name}` : dirent.name;
+    if (dirent.isDirectory()) {
+      await _walk(base, childRel, out);
+      continue;
+    }
+    if (!dirent.isFile()) continue; // symlink/socket/fifo: never followed, never hashed
+    const full = path.join(base, ...childRel.split('/'));
+    const stat = await fsp.lstat(full);
+    const content = await fsp.readFile(full);
+    out.push({ relPath: childRel, exec: (stat.mode & 0o111) !== 0, sha256: _sha256(content) });
+  }
+}
+
+/** Copy a tree item into `destDir` with USER-writable modes: files 0644 (the exec bit preserved as
+ *  0755), dirs 0755. The tree's 0444/0555 read-only modes must never be reproduced — the user edits
+ *  these copies, and a 0444 SKILL.md would make that a chmod first. */
+async function _copyDir(srcDir, destDir) {
+  await fsp.mkdir(destDir, { recursive: true });
+  await fsp.chmod(destDir, 0o755);
+  for (const dirent of await fsp.readdir(srcDir, { withFileTypes: true })) {
+    if (dirent.name.startsWith('.')) continue; // a tree never carries one, but a marker never travels
+    const src = path.join(srcDir, dirent.name);
+    const dest = path.join(destDir, dirent.name);
+    if (dirent.isDirectory()) {
+      await _copyDir(src, dest);
+      continue;
+    }
+    if (!dirent.isFile()) continue;
+    const stat = await fsp.lstat(src);
+    await fsp.copyFile(src, dest);
+    await fsp.chmod(dest, (stat.mode & 0o111) !== 0 ? 0o755 : 0o644);
+  }
+}
+
+/** The bundle's codex item names (directories under `<treeDir>/codex`), sorted, dot-names excluded. */
+async function _bundleItemNames(treeDir) {
+  const dirents = await _readdirOrEmpty(path.join(treeDir, 'codex'));
+  return dirents
+    .filter((dirent) => dirent.isDirectory() && !dirent.name.startsWith('.') && NAME_RE.test(dirent.name))
+    .map((dirent) => dirent.name)
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/** The names under `root` a hub copy could own: real directories that are not our bookkeeping dirs. */
+function _installedNames(dirents) {
+  return dirents
+    .filter((dirent) => dirent.isDirectory() && !dirent.name.startsWith('.') && NAME_RE.test(dirent.name))
+    .map((dirent) => dirent.name)
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/** The names a leftover DIRECTORY in `root` belongs to — the fingerprint of a crash between the two
+ *  renames of a swap (or of a retire that never finished). */
+function _leftoverPrefixes(dirents) {
+  const names = new Set();
+  for (const dirent of dirents) {
+    if (!dirent.isDirectory()) continue;
+    const match = RETIRED_RE.exec(dirent.name) || STAGING_RE.exec(dirent.name);
+    if (match) names.add(match[1]);
+  }
+  return names;
+}
+
+function _recordEntry(record, name) {
+  const entry = record && record.skills && record.skills[name];
+  return entry && typeof entry === 'object' ? entry : null;
+}
+
+/**
+ * Plan the install. Read-only: not a single write happens here.
+ *
+ * @param {string} treeDir absolute materialized tree dir (`trees/<hex>`)
+ * @param {object} [options]
+ * @param {string} [options.hubPeerId] the hub whose copy this is (marker + retire ownership)
+ * @param {string} [options.homeDir=os.homedir()] the box user's home (a test passes a temp HOME)
+ * @param {boolean} [options.isPrimary=false] D-8: only a primary may write the real home
+ * @param {string} [options.realHome=os.userInfo().homedir] the password-database home (ignores $HOME)
+ * @param {Function} [options.log]
+ * @returns {Promise<{root: string, writeAllowed: boolean, plans: object[]}>} plus the re-plan inputs
+ *          an apply needs (`treeDir`, `hubPeerId`, `treeHash`, `homeDir`, `isPrimary`, `realHome`).
+ */
+async function planBundleCodexInstall(treeDir, {
+  hubPeerId = '', homeDir = os.homedir(), isPrimary = false, realHome = os.userInfo().homedir, log,
+  // Apply's per-name re-plan passes the one name it is about to write, so a run hashes each
+  // directory a bounded number of times instead of re-hashing every skill once per skill.
+  onlyName = null,
+} = {}) {
+  const root = skillsRoot(homeDir);
+  const hub = String(hubPeerId == null ? '' : hubPeerId).trim();
+  const baseName = path.basename(treeDir);
+  const treeHash = /^[0-9a-f]{64}$/.test(baseName) ? `sha256:${baseName}` : null;
+
+  const [allowed, record, bundleNames, rootDirents] = await Promise.all([
+    writeAllowed(root, { isPrimary, realHome }),
+    readRootRecord(root, { log }),
+    _bundleItemNames(treeDir),
+    _readdirOrEmpty(root),
+  ]);
+  const leftovers = _leftoverPrefixes(rootDirents);
+
+  const plans = [];
+  for (const name of bundleNames) {
+    if (onlyName !== null && name !== onlyName) continue;
+    const targetDir = path.join(root, name);
+    const bundleDirHash = await dirHash(path.join(treeDir, 'codex', name));
+    if (Object.hasOwn(MANAGED_SKILLS, name)) {
+      // The box installs its OWN `delegate` from its own release; a hub copy must never shadow it.
+      plans.push({ name, action: 'skipped_managed', targetDir, bundleDirHash, diskDirHash: null, marker: null });
+      continue;
+    }
+    let action;
+    let diskDirHash = null;
+    let marker = null;
+    if (!(await _isDir(targetDir))) {
+      // Rule 1. The leftover-retired exception is checked FIRST: a name the tree still HAS must be
+      // restored even though a record entry (which the crashed run never dropped) would say `removed`.
+      if (leftovers.has(name)) action = 'create';
+      else {
+        const entry = _recordEntry(record, name);
+        action = entry && entry.source === SOURCE ? 'removed' : 'create';
+      }
+    } else {
+      marker = await readMarker(targetDir, name);
+      if (!marker || marker.source !== SOURCE) {
+        action = 'conflict'; // user-authored, or another installer's copy — not even hashed
+      } else {
+        diskDirHash = await dirHash(targetDir);
+        if (marker.sha256 !== diskDirHash) action = 'edited';
+        else if (diskDirHash === bundleDirHash) action = 'noop';
+        else action = 'update';
+      }
+    }
+    plans.push({ name, action, targetDir, bundleDirHash, diskDirHash, marker });
+  }
+
+  // Retire: installed agent-bundle copies of THIS hub that the current tree no longer has.
+  const inTree = new Set(bundleNames);
+  for (const name of _installedNames(rootDirents)) {
+    if (inTree.has(name)) continue;
+    if (onlyName !== null && name !== onlyName) continue;
+    const targetDir = path.join(root, name);
+    const marker = await readMarker(targetDir, name);
+    if (!marker || marker.source !== SOURCE || marker.hubPeerId !== hub) continue; // not ours: never retired
+    const diskDirHash = await dirHash(targetDir);
+    if (marker.sha256 !== diskDirHash) continue; // edited on the box: kept, never retired
+    plans.push({ name, action: 'retire', targetDir, bundleDirHash: null, diskDirHash, marker });
+  }
+
+  return { root, writeAllowed: allowed, plans, treeDir, hubPeerId: hub, treeHash, homeDir, isPrimary, realHome };
+}
+
+/**
+ * Dirs a crashed run left behind, removed once they are older than this run (nothing of OURS is
+ * younger than `runStartMs`).
+ *
+ * `wanted(name)` splits the job in two, and that split is load-bearing: a `.<name>.ctm-retired-*` dir
+ * is the ONLY evidence that a swap crashed mid-flight (rule 1's exception), so it must still be there
+ * when the apply-time re-plan classifies the name — hence the start-of-apply sweep skips the names
+ * this run is about to act on, and those get their leftovers removed after the run's own swaps.
+ */
+async function _sweepLeftovers(root, runStartMs, wanted = () => true) {
+  for (const dirent of await _readdirOrEmpty(root)) {
+    if (!dirent.isDirectory()) continue;
+    const match = RETIRED_RE.exec(dirent.name) || STAGING_RE.exec(dirent.name);
+    if (!match || !wanted(match[1])) continue;
+    const target = path.join(root, dirent.name);
+    const stat = await _statOrNull(target);
+    if (!stat || stat.mtimeMs > runStartMs) continue; // younger than this run: not ours to touch
+    await _removeQuiet(target);
+  }
+}
+
+/** Remove the root-record entry for `name`. `writeRootRecord` only merges, so a drop reads and writes
+ *  through the shared reader/format — a re-add by the hub must then classify `create`, not `removed`. */
+async function _dropRecordEntry(root, name, log) {
+  const current = await readRootRecord(root, { log });
+  if (!current || !current.skills || !Object.hasOwn(current.skills, name)) return;
+  delete current.skills[name];
+  await atomicWriteFile(path.join(root, ROOT_RECORD_FILE), JSON.stringify(current, null, 2) + '\n');
+}
+
+/**
+ * Apply a plan. Never throws for a per-skill failure — that skill's result carries `skipped:'error'`
+ * and the fault reaches `report`; the run continues (REPORT + continue, like syncManagedSkills).
+ *
+ * @param {object} plan from planBundleCodexInstall
+ * @param {object} [options]
+ * @param {string} [options.hubPeerId] falls back to the plan's
+ * @param {string} [options.treeHash] falls back to the plan's (derived from the tree dir name)
+ * @param {() => Date} [options.now]
+ * @param {Function} [options.report]
+ * @param {Function} [options.log]
+ * @returns {Promise<{results: Array<{name: string, action: string, written: boolean, skipped: string|null}>}>}
+ */
+async function applyBundleCodexInstall(plan, {
+  hubPeerId = null, treeHash = null, now = () => new Date(), report = null, log,
+} = {}) {
+  const root = plan.root;
+  const hub = String((hubPeerId == null ? plan.hubPeerId : hubPeerId) || '').trim();
+  const hash = treeHash == null ? plan.treeHash : treeHash;
+
+  if (!plan.writeAllowed) {
+    // D-8: a non-primary instance never writes the real home. Every result says so; nothing is touched.
+    return {
+      results: plan.plans.map((entry) => ({
+        name: entry.name, action: entry.action, written: false, skipped: 'write_blocked_real_home',
+      })),
+    };
+  }
+
+  const stamp = now();
+  const plannedNames = new Set(plan.plans.map((entry) => entry.name));
+  const results = [];
+  try {
+    // Start of apply: everything older than this run EXCEPT the names below — their leftover is the
+    // crash fingerprint the re-plan still has to read (see _sweepLeftovers).
+    await _sweepLeftovers(root, stamp.getTime(), (name) => !plannedNames.has(name));
+  } catch (error) {
+    _report(report, error); // REPORT: a failed cleanup must not stop this run's real work
+  }
+
+  for (const entry of plan.plans) {
+    const result = { name: entry.name, action: entry.action, written: false, skipped: null };
+    try {
+      // Re-plan THIS name and refuse if its action moved (a lost race): never write against a stale plan.
+      const fresh = await planBundleCodexInstall(plan.treeDir, {
+        hubPeerId: hub, homeDir: plan.homeDir, isPrimary: plan.isPrimary, realHome: plan.realHome, log,
+        onlyName: entry.name,
+      });
+      const current = fresh.plans.find((candidate) => candidate.name === entry.name) || null;
+      if (!current || current.action !== entry.action) {
+        result.skipped = 'plan_changed';
+        results.push(result);
+        continue;
+      }
+      if (current.action === 'create' || current.action === 'update') {
+        await _installOne(root, current, fresh, { hub, hash, stamp, report, log });
+        result.written = true;
+      } else if (current.action === 'retire') {
+        await _retireOne(root, current, log);
+        result.written = true;
+      }
+      // noop / conflict / edited / removed / skipped_managed: nothing is written.
+    } catch (error) {
+      // REPORT: one skill's failure never aborts the others (and never rejects the caller).
+      result.skipped = 'error';
+      _report(report, error);
+    }
+    results.push(result);
+  }
+
+  try {
+    // End of apply: the names the start sweep had to leave alone (no swap of ours survives this).
+    await _sweepLeftovers(root, stamp.getTime(), (name) => plannedNames.has(name));
+  } catch (error) {
+    _report(report, error); // REPORT: leftover cleanup is best-effort and retried by the next run
+  }
+  return { results };
+}
+
+async function _installOne(root, current, fresh, { hub, hash, stamp, report, log }) {
+  const name = current.name;
+  const installedAt = (current.marker && current.marker.installedAt) || stamp.toISOString();
+  const staging = path.join(root, `.${name}.ctm-staging-${_rand()}`);
+  try {
+    await _copyDir(path.join(fresh.treeDir, 'codex', name), staging);
+    await atomicWriteFile(path.join(staging, MARKER_FILE), JSON.stringify({
+      schema: 2,
+      name,
+      source: SOURCE,
+      hubPeerId: hub,
+      treeHash: hash,
+      sha256: current.bundleDirHash,
+      installedAt,
+      updatedAt: stamp.toISOString(),
+    }, null, 2) + '\n');
+    if (current.action === 'update') {
+      // Crash window: between these two renames the target is missing and `.<name>.ctm-retired-*`
+      // is present — which is exactly what the planner's rule-1 exception turns back into `create`.
+      const retired = path.join(root, `.${name}.ctm-retired-${_rand()}`);
+      await fsp.rename(current.targetDir, retired);
+      try {
+        await fsp.rename(staging, current.targetDir);
+      } catch (error) {
+        await _removeQuiet(retired); // then RETHROW: never leave a half-swapped install behind
+        throw error;
+      }
+      await _removeQuiet(retired);
+    } else {
+      await fsp.rename(staging, current.targetDir);
+    }
+  } catch (error) {
+    await _removeQuiet(staging); // RETHROW: the caller REPORTs it and the original directory survives
+    throw error;
+  }
+  await writeRootRecord(root, name, {
+    source: SOURCE,
+    hubPeerId: hub,
+    lastSha256: current.bundleDirHash,
+    lastWrittenAt: stamp.toISOString(),
+    firstInstalledAt: installedAt,
+  }, log);
+}
+
+async function _retireOne(root, current, log) {
+  const retired = path.join(root, `.${current.name}.ctm-retired-${_rand()}`);
+  await fsp.rename(current.targetDir, retired);
+  await _removeQuiet(retired);
+  // Drop the record entry: a later re-add by the hub is `create`, never `removed`.
+  await _dropRecordEntry(root, current.name, log);
+}
+
+let _inFlight = null;
+// hubPeerId -> { dataDir, deps } for calls that arrived while a run was in flight. Unlike the GC
+// (one sweep covers everything), a run installs ONE hub's tree as of when it read the pointer, so a
+// call for another hub — or the same hub after a newer PUT — must get a run of its own afterwards.
+const _pending = new Map();
+
+/**
+ * Single-flight trigger for the manifest-PUT seam (and any future boot hook). A call while an install
+ * is running returns THAT run's promise and queues one follow-up run for its hub (coalesced: the
+ * latest deps per hub win), started as soon as the current run settles; a call after it settles
+ * starts a new one. Never rejects: the returned promise always resolves (a fault reaches `report`).
+ * The tree is resolved through the hub's CURRENT pointer, so the caller needs nothing but the hub
+ * identity.
+ *
+ * Deliberately not `async` — an async wrapper would hand every caller a fresh promise and break the
+ * "same promise" contract the single-flight test asserts (gc.js's own reasoning).
+ *
+ * @param {string} dataDir
+ * @param {object} [deps]
+ * @param {string} [deps.hubPeerId] the hub whose CURRENT tree to install
+ * @param {boolean} [deps.isPrimary]
+ * @param {string} [deps.homeDir]
+ * @param {string} [deps.realHome]
+ * @param {() => Date} [deps.now]
+ * @param {Function} [deps.report]
+ * @param {Function} [deps.log]
+ * @returns {Promise<{results: object[]}>}
+ */
+function scheduleBundleCodexInstall(dataDir, deps = {}) {
+  if (_inFlight) {
+    _pending.set(String((deps && deps.hubPeerId) || ''), { dataDir, deps });
+    return _inFlight;
+  }
+  const run = Promise.resolve()
+    .then(() => _runCodexInstall(dataDir, deps))
+    .catch((error) => {
+      // REPORT: a run that fails as a whole (not per skill) must not reject into a `void` caller.
+      _report(deps && deps.report, error);
+      return { results: [] };
+    });
+  _inFlight = run;
+  // `run` never rejects, so this settlement tail cannot itself create an unhandled rejection.
+  const settle = () => {
+    if (_inFlight !== run) return;
+    _inFlight = null;
+    if (!_pending.size) return;
+    const [key, next] = _pending.entries().next().value;
+    _pending.delete(key);
+    scheduleBundleCodexInstall(next.dataDir, next.deps); // never rejects (see above)
+  };
+  run.then(settle, settle);
+  return run;
+}
+
+async function _runCodexInstall(dataDir, deps) {
+  const hubPeerId = String((deps && deps.hubPeerId) == null ? '' : deps.hubPeerId).trim();
+  if (!hubPeerId) return { results: [] }; // no hub, no install (D-14: there is nothing to install)
+  const treeHash = await store.currentHubTree(dataDir, hubPeerId);
+  if (!treeHash) return { results: [] };
+  const treeDir = path.join(store.storeRoot(dataDir), 'trees', treeHash.replace(/^sha256:/, ''));
+  if (!(await _isDir(treeDir))) return { results: [] }; // the tree is gone: nothing to install, not a fault
+  const plan = await planBundleCodexInstall(treeDir, {
+    hubPeerId,
+    homeDir: deps.homeDir,
+    isPrimary: deps.isPrimary,
+    realHome: deps.realHome,
+    log: deps.log,
+  });
+  return applyBundleCodexInstall(plan, {
+    hubPeerId,
+    treeHash,
+    now: deps.now,
+    report: deps.report,
+    log: deps.log,
+  });
+}
+
+/** Test-only: drop the single-flight latch so each test observes its own run. */
+function _resetForTests() {
+  _inFlight = null;
+  _pending.clear();
+}
+
+/** Test-only: resolve once no run is in flight and none is queued. `settle` starts the queued run
+ *  synchronously before any later continuation, so awaiting the current run and re-checking
+ *  observes every follow-up without a timer. */
+async function _whenIdleForTests() {
+  while (_inFlight) await _inFlight;
+}
+
+module.exports = {
+  planBundleCodexInstall,
+  applyBundleCodexInstall,
+  scheduleBundleCodexInstall,
+  dirHash,
+  // WP-8: `retireBoxSkill` moves an edited agent-bundle copy aside and must ALSO drop its root-record
+  // entry, or the hub's next push would read the missing target as a user DELETION (`removed`) and
+  // never re-install the pristine bundle copy. Both helpers are named here rather than re-derived.
+  skillsRoot,
+  dropRecordEntry: _dropRecordEntry,
+  _resetForTests,
+  _whenIdleForTests,
+};

package/template/coding-task-manager/lib/agent-bundle/drift.js

@@ -0,0 +1,120 @@
+'use strict';
+
+// WP-3 (docs/agent-bundle-darwin-readonly-rename-2026-10-27.html §16 D-6/D-9/D-13, §17): the PURE
+// bundle-drift rules. No fs, no db, no net — the process argv arrives as a string (or an argv
+// array), the store's answer arrives as an already-resolved tree hash, and a session arrives as a
+// plain view object. Everything the reconciler needs to decide is decidable here, which is why the
+// whole decision surface is unit-testable without a server.
+//
+// The contract (D-6): `applied` is the tree hex the RUNNING process was spawned with — null when it
+// was spawned with none, the string 'unknown' when the process could not be read. `expected` is what
+// `store.resolveSpawnBundle(dataDir, sessionId)` answers right now, as hex (null when the box has no
+// hub tree). Drift is `expected !== null && applied !== expected`; 'unknown' is NEVER drift, because
+// an unreadable process is not evidence that the process is wrong.
+
+/** D-13: at most this many relaunch attempts per (session, expected tree) pair. */
+const DRIFT_MAX_ATTEMPTS = 2;
+
+// The spawn's own shape: `--add-dir <...>/trees/<64 hex>/claude`, followed by whitespace or the end
+// of the line. Anchored on the literal `--add-dir` so a `/trees/<hex>/claude` path that appears in
+// some OTHER token (a cwd, a log line, a `--settings` value) is not mistaken for the bundle.
+const ADD_DIR_TREE_RE = /--add-dir (\S+?)\/trees\/([0-9a-f]{64})\/claude(?=\s|$)/;
+
+/**
+ * Group 2 of the `--add-dir <dir>/trees/<hex>/claude` token in an argv (array) or a `ps` line
+ * (string), or null when the spawn carried no bundle. A `ps -o args=` line is the argv joined by
+ * single spaces, so both forms are read the same way.
+ *
+ * @param {string[]|string|null|undefined} argvOrLine
+ * @returns {string|null} 64 lowercase hex characters
+ */
+function treeHashFromArgv(argvOrLine) {
+  const line = Array.isArray(argvOrLine)
+    ? argvOrLine.map((value) => String(value == null ? '' : value)).join(' ')
+    : String(argvOrLine == null ? '' : argvOrLine);
+  if (!line) return null;
+  const match = ADD_DIR_TREE_RE.exec(line);
+  return match ? match[2] : null;
+}
+
+/**
+ * The hex of `'sha256:<hex>'` or a bare `'<hex>'`; null for anything else (including null,
+ * undefined and the 'unknown' sentinel, which is not a tree).
+ *
+ * @param {string|null|undefined} treeHash
+ * @returns {string|null}
+ */
+function treeHex(treeHash) {
+  if (typeof treeHash !== 'string') return null;
+  const value = treeHash.trim();
+  if (/^sha256:[0-9a-f]{64}$/.test(value)) return value.slice('sha256:'.length);
+  if (/^[0-9a-f]{64}$/.test(value)) return value;
+  return null;
+}
+
+/**
+ * D-6: does the RUNNING process need to be respawned to carry the tree the box expects now?
+ *
+ *   (null, X)      -> no-bundle   the process was spawned before a tree existed (deepseek)
+ *   (X, Y≠X)       -> stale       the hub pushed a different tree
+ *   (X, X)         -> none
+ *   (*, null)      -> none        the box has no hub tree: never force a relaunch onto nothing
+ *   ('unknown', X) -> unknown-applied, drift:false
+ *
+ * @returns {{drift: boolean, case: 'none'|'no-bundle'|'stale'|'unknown-applied'}}
+ */
+function computeDrift({ applied = null, expected = null } = {}) {
+  if (expected === null || expected === undefined) return { drift: false, case: 'none' };
+  if (applied === 'unknown') return { drift: false, case: 'unknown-applied' };
+  if (applied === null || applied === undefined) return { drift: true, case: 'no-bundle' };
+  if (applied === expected) return { drift: false, case: 'none' };
+  return { drift: true, case: 'stale' };
+}
+
+/**
+ * D-9: the manual-park gate (`evaluateManualPark`, so an unattended relaunch is exactly as
+ * acceptable as a park the user's own model switch performs) PLUS three drift-only refusals:
+ *
+ *   - `composer-unknown`: manual park treats an unreadable composer as "no draft" because a user
+ *     asked. Nobody asked here, so an unreadable composer protects (the opposite of D-4).
+ *   - `waiting-input`: manual park also rewrites `waiting_input`/`resuming` to `idle` (the user who
+ *     asked their own model switch is present to answer). An unattended relaunch would kill a turn
+ *     that is waiting for input, so the drift gate keeps the protection the raw gate carries.
+ *   - `input-in-flight`: a remote submission is mid-delivery (`_remoteTerminalSubmissionInFlight`).
+ *   - `transition`: a deferred restore or a lead-model transition is already in flight.
+ *   - `create-in-flight` (D-10): a new-session create is in flight on this box
+ *     (`host.createInFlight`: lib/session-create/prepared.js `inflightCreateCount() > 0`). On
+ *     2026-11-01 15:33-15:35Z this pass parked and cold-relaunched three live leads while a
+ *     create was in flight; the relaunch now waits until no create is in progress (not the
+ *     120 s restart lease, which outlives the create).
+ *
+ * A refusal DEFERS the relaunch (the caller records `drift-pending` and retries on the next sweep);
+ * it never force-parks.
+ *
+ * @returns {{ok: boolean, protections: string[]}} the shape §17 names
+ */
+function evaluateDriftRelaunch(session, host, config, { evaluateManualPark } = {}) {
+  if (typeof evaluateManualPark !== 'function') throw new TypeError('evaluateDriftRelaunch requires evaluateManualPark');
+  // AC-3c: `isActiveTab` / `isMru` are already dropped by evaluateManualPark's own view transform;
+  // `pinned` is NOT — it refuses there (tests/session-lifecycle.test.js:385) because a lifecycle pin
+  // is the user telling CTM not to RECLAIM the session's memory. A drift relaunch reclaims nothing:
+  // it respawns the same tab onto the tree the box already owes it, so pinning must not strand a
+  // session without skills. Cleared here rather than in evaluateManualPark (whose other callers rely
+  // on the refusal).
+  const base = evaluateManualPark({ ...session, pinned: false }, host, config) || { protections: [] };
+  const protections = Array.isArray(base.protections) ? base.protections.slice() : [];
+  if (session?.liveStatus === 'waiting_input' || session?.liveStatus === 'resuming') protections.push('waiting-input');
+  if (session?.composerDraft === 'unknown' && !protections.includes('composer-unknown')) protections.push('composer-unknown');
+  if (session?._remoteTerminalSubmissionInFlight) protections.push('input-in-flight');
+  if (session?._restoreDeferred === true || session?._activationStartPromise) protections.push('transition');
+  if (host?.createInFlight === true) protections.push('create-in-flight');
+  return { ok: protections.length === 0, protections };
+}
+
+module.exports = {
+  DRIFT_MAX_ATTEMPTS,
+  treeHashFromArgv,
+  treeHex,
+  computeDrift,
+  evaluateDriftRelaunch,
+};