create-walle 0.10.2 → 0.10.3

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

@@ -0,0 +1,119 @@
+'use strict';
+
+/**
+ * WP-4 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-6/D-7/D-8, §6.4): the BOX side of "the
+ * session spawns with the hub's bundle".
+ *
+ * A hub-created session has a `sessions/<id>.json` record (WP-3) and the hub's bundle is materialized
+ * in the store (WP-2). A box with EXACTLY ONE hub pointer also applies that hub's bundle to a session
+ * with no record at all — the pre-fix hub-created sessions (and box-local creates on a one-hub box)
+ * cannot otherwise be told apart from a local create (rev 3 D-10). This module turns the store's
+ * resolution of that bundle into argv/env for ONE spawn. Nothing here is persisted: the `--add-dir`
+ * pair and CLAUDE_CODE_PLUGIN_DIRS live only in the argv/env handed to `_spawnSessionPty`, so a
+ * restore re-resolves the hub's CURRENT tree instead of replaying a stale path (D-7, AC-4c/AC-4d).
+ *
+ * Measured on the box (design §5 decision table, 2026-10-25):
+ *   `claude --add-dir <treeDir>/claude`         loads `<treeDir>/claude/.claude/skills/*` bare-named
+ *   `CLAUDE_CODE_PLUGIN_DIRS=<treeDir>/plugins` loads every plugin folder under it (parent form)
+ * A missing `<treeDir>/plugins` is harmless to Claude (measured), so nothing here stats the
+ * filesystem — the transform stays PURE and unit-testable.
+ *
+ * D-8 (argv placement): `--add-dir` is VARIADIC — it swallows every following positional until the
+ * next option (tests/worker-launch-argv.test.js:206-208,231). Inserted before a positional prompt it
+ * would eat that prompt, so the pair goes immediately before the FIRST option token of the argv (and
+ * at the end when the argv has no option token at all).
+ */
+
+const path = require('node:path');
+
+/** Everything from the first `-`-prefixed token on is "option territory" as far as D-8 is concerned. */
+function _isOptionToken(value) {
+  return typeof value === 'string' && value.startsWith('-');
+}
+
+/**
+ * D-8: `launchArgs` with `['--add-dir', dir]` inserted before its first option token (appended when
+ * there is none). Every original token keeps its relative order; a fresh array is always returned.
+ *
+ * @param {string[]} launchArgs
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function insertAddDir(launchArgs, dir) {
+  const args = Array.isArray(launchArgs) ? launchArgs : [];
+  const tokens = ['--add-dir', dir];
+  const at = args.findIndex(_isOptionToken);
+  return at === -1 ? [...args, ...tokens] : [...args.slice(0, at), ...tokens, ...args.slice(at)];
+}
+
+/**
+ * §6.4/D-8: the bundle's argv/env contribution for THIS spawn.
+ *
+ * PURE: the inputs are never mutated and the identity (`applied:false`, the caller's own objects) is
+ * returned for every case that is not a Claude spawn with a resolved bundle — a `null` bundle, and
+ * every non-Claude agent (Codex has no session-scoped skills lever; WP-6 installs instead, D-14).
+ *
+ * @param {{launchArgs?: string[], spawnEnv?: object, agentType?: string, bundle?: ?{treeDir: string}}} spawn
+ * @returns {{launchArgs: string[], spawnEnv: object, applied: boolean}}
+ */
+function applyAgentBundleToSpawn({ launchArgs, spawnEnv, agentType, bundle }) {
+  if (agentType !== 'claude') return { launchArgs, spawnEnv, applied: false };
+  const treeDir = bundle && typeof bundle === 'object' ? String(bundle.treeDir == null ? '' : bundle.treeDir) : '';
+  if (!treeDir) return { launchArgs, spawnEnv, applied: false };
+  const env = spawnEnv && typeof spawnEnv === 'object' ? spawnEnv : {};
+  const existing = String(env.CLAUDE_CODE_PLUGIN_DIRS == null ? '' : env.CLAUDE_CODE_PLUGIN_DIRS).trim();
+  const pluginDirs = path.join(treeDir, 'plugins');
+  return {
+    launchArgs: insertAddDir(launchArgs, path.join(treeDir, 'claude')),
+    // Ours FIRST: the hub's plugins win a name collision against anything the box already had (D-8).
+    spawnEnv: { ...env, CLAUDE_CODE_PLUGIN_DIRS: existing ? `${pluginDirs}:${existing}` : pluginDirs },
+    applied: true,
+  };
+}
+
+/**
+ * D-6/D-7: the bundle for `sessionId`, or null. A bundle can never fail, delay or change a spawn.
+ *
+ * `options.report(event, details)` is the caller's diagnostic seam (wired to `recordSessionDiagnostic`
+ * at the spawn site) and is called with exactly one of:
+ *   `agent-bundle-resolve-failed`  the store could not answer (REPORT, then spawn without the overlay)
+ *   `agent-bundle-missing`         this session WAS created by a hub, but no tree resolves for it —
+ *                                  deleted/GC'd, or the hub has never pushed (AC-4e)
+ * A session with no hub record at all reports nothing: there was never a bundle to miss. On a
+ * one-hub box (rev 3 D-10) such a session still RESOLVES — `store.resolveSpawnBundle` falls back to
+ * the sole hub — so this path only stays silent when the box has zero or several hub pointers. When a
+ * sole hub exists but its tree is gone, `resolveSpawnBundle` returns null and `sessionHubRecord` is
+ * null too, so nothing is reported (acceptable: with no record there is no hub to name).
+ *
+ * @param {string} sessionId
+ * @param {{store?: object, report?: (event: string, details: object) => void, dataDir?: string}} [options]
+ * @returns {Promise<null | {treeDir: string, treeHash: string, hubPeerId: string}>}
+ */
+async function resolveSpawnBundleForSession(sessionId, options = {}) {
+  const store = options.store || require('./store');
+  const report = typeof options.report === 'function' ? options.report : () => undefined;
+  // createProviderSession has no data dir in scope, so the canonical resolver is required lazily here
+  // rather than threaded through every caller.
+  const dataDir = options.dataDir || require('../data-dir').getDataDir();
+  let bundle = null;
+  try {
+    bundle = await store.resolveSpawnBundle(dataDir, sessionId);
+  } catch (error) {
+    // REPORT: an unreadable store is not a spawn failure — the session starts without the overlay.
+    report('agent-bundle-resolve-failed', { message: String((error && error.message) || error).slice(0, 200) });
+    return null;
+  }
+  if (bundle) return bundle;
+  let record = null;
+  try {
+    record = await store.sessionHubRecord(dataDir, sessionId);
+  } catch (error) {
+    // REPORT: bundle bookkeeping never blocks a launch (D-6/D-7).
+    report('agent-bundle-resolve-failed', { message: String((error && error.message) || error).slice(0, 200) });
+    return null;
+  }
+  if (record) report('agent-bundle-missing', { hubPeerId: record.hubPeerId });
+  return null;
+}
+
+module.exports = { applyAgentBundleToSpawn, insertAddDir, resolveSpawnBundleForSession };

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

@@ -0,0 +1,568 @@
+'use strict';
+
+/**
+ * WP-2 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-1/D-2/D-5, §6.3): the BOX side of the
+ * hub's agent-skill bundle — a content-addressed blob store plus a manifest materializer.
+ *
+ * Layout under `<dataDir>/agent-bundles/`:
+ *   blobs/<hh>/<hex>                 content store, 0444, hh = first two hex chars
+ *   trees/<treeHashHex>/{claude,plugins,codex}/…   materialized read-only view, files 0444/0555,
+ *                                                  dirs 0555 (the entry paths already carry the
+ *                                                  `claude/`, `plugins/`, `codex/` prefixes)
+ *   trees/<treeHashHex>.manifest.json              WP-5: the manifest that tree was built from, the
+ *                                                  GC's blob-reference source (never a tree itself)
+ *   hubs/<peerInstanceId>.json       { treeHash, at } — the hub's CURRENT pointer
+ *   sessions/<ctmSessionId>.json     { hubPeerId, createdTreeHash, at }
+ *
+ * D-1: nothing is ever written into the box user's `~/.claude`; a bundle is a session overlay that
+ * lives only here. D-2: a bundle is addressed by `treeHash = computeTreeHash(entries)` (WP-1's
+ * builder), so identical content yields an identical directory on every hub. D-5: the box verifies
+ * what it is given — every blob is re-hashed on receipt, the manifest is accepted only when the
+ * recomputed tree hash matches the URL and every referenced blob is present at the declared size,
+ * and materialization is temp-dir + rename so a partially written tree is never visible.
+ *
+ * Identity rules (the reason `AgentBundleError` exists): `hex` must be 64 lowercase hex chars and
+ * `treeHash` the `sha256:<64 hex>` form (URL-encoded or raw — the URL carries it), so neither can
+ * ever name a file outside this store. `peerInstanceId` / `ctmSessionId` become file names and are
+ * held to `/^[A-Za-z0-9._-]{1,128}$/`.
+ */
+
+const crypto = require('crypto');
+const fsp = require('fs/promises');
+const path = require('path');
+
+const { computeTreeHash } = require('./build');
+const { atomicWriteFile } = require('../../atomic-write');
+
+const HEX_RE = /^[0-9a-f]{64}$/;
+const TREE_HASH_RE = /^sha256:([0-9a-f]{64})$/;
+/** The id shape shared by peerInstanceId / ctmSessionId — they are file names, nothing more. */
+const ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+/** = build.js's MAX_ENTRIES: the hub cannot produce more, so the box will not accept more. */
+const MAX_ENTRIES = 20000;
+/** D-5: files are one of exactly two modes; dirs are always 0555. */
+const FILE_MODES = new Set([0o444, 0o555]);
+const DIR_MODE = 0o555;
+/** D-5 / WP-1: every entry path starts with one of these three roots. */
+const PATH_PREFIXES = ['claude/.claude/skills/', 'plugins/', 'codex/'];
+
+class AgentBundleError extends Error {
+  constructor(code, status, details = {}) {
+    super(code);
+    this.name = 'AgentBundleError';
+    this.code = code;
+    this.status = status;
+    if (Array.isArray(details.missing)) this.missing = details.missing;
+  }
+}
+
+function storeRoot(dataDir) {
+  return path.join(String(dataDir == null ? '' : dataDir), 'agent-bundles');
+}
+
+function _invalid() {
+  return new AgentBundleError('agent_bundle_path_invalid', 422);
+}
+
+/** A blob hex, or `agent_bundle_path_invalid`. Never normalizes case: the name IS the hash. */
+function _requireHex(value) {
+  const hex = String(value == null ? '' : value).trim();
+  if (!HEX_RE.test(hex)) throw _invalid();
+  return hex;
+}
+
+/** `sha256:<64 hex>`, accepted URL-encoded (`sha256%3A…`) or raw, or `agent_bundle_path_invalid`. */
+function _requireTreeHash(value) {
+  const raw = String(value == null ? '' : value).trim();
+  let decoded = raw;
+  if (raw.includes('%')) {
+    try {
+      decoded = decodeURIComponent(raw);
+    } catch {
+      // expected: a malformed percent-escape is just an invalid tree hash, not a server fault
+      throw _invalid();
+    }
+  }
+  const match = TREE_HASH_RE.exec(decoded);
+  if (!match) throw _invalid();
+  return { treeHash: `sha256:${match[1]}`, hex: match[1] };
+}
+
+function _requireId(value) {
+  const id = String(value == null ? '' : value).trim();
+  if (!ID_RE.test(id)) throw _invalid();
+  return id;
+}
+
+function _blobPath(root, hex) {
+  return path.join(root, 'blobs', hex.slice(0, 2), hex);
+}
+
+async function _statOrNull(target) {
+  try {
+    return await fsp.stat(target);
+  } catch (error) {
+    if (error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) return null;
+    throw error;
+  }
+}
+
+async function _exists(target) {
+  return (await _statOrNull(target)) !== null;
+}
+
+async function _unlinkQuiet(target) {
+  try {
+    await fsp.unlink(target);
+  } catch {
+    /* expected: the temp file was never created, or the rename already consumed it */
+  }
+}
+
+async function _readJsonOrNull(target) {
+  let text;
+  try {
+    text = await fsp.readFile(target, 'utf8');
+  } catch (error) {
+    if (error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) return null;
+    throw error;
+  }
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    // expected: a torn/garbled pointer is a missing piece of information, not a reason to fail the
+    // spawn — D-7 keeps bundle work unable to block or fail a session.
+    return null;
+  }
+}
+
+/** D-5: a relative POSIX path under one of the three bundle roots, with no way to escape the tree. */
+function _validateEntryPath(value) {
+  if (typeof value !== 'string' || value.length === 0) throw _invalid();
+  if (value.startsWith('/')) throw _invalid();
+  if (value.includes('\\')) throw _invalid();
+  if (/[\u0000-\u001f]/.test(value)) throw _invalid();
+  const segments = value.split('/');
+  for (const segment of segments) {
+    if (segment === '' || segment === '.' || segment === '..') throw _invalid();
+  }
+  if (!PATH_PREFIXES.some((prefix) => value.startsWith(prefix))) throw _invalid();
+  return value;
+}
+
+function _normalizeEntries(manifest, canonicalTreeHash) {
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) throw _invalid();
+  if (manifest.schema !== 1) throw _invalid();
+  if (!Array.isArray(manifest.entries)) throw _invalid();
+  if (manifest.entries.length > MAX_ENTRIES) throw _invalid();
+  const seen = new Set();
+  const entries = [];
+  for (const raw of manifest.entries) {
+    if (!raw || typeof raw !== 'object') throw _invalid();
+    const rel = _validateEntryPath(raw.path);
+    if (seen.has(rel)) throw _invalid();
+    seen.add(rel);
+    if (!FILE_MODES.has(raw.mode)) throw _invalid();
+    if (!Number.isInteger(raw.size) || raw.size < 0) throw _invalid();
+    const sha256 = String(raw.sha256 == null ? '' : raw.sha256);
+    if (!HEX_RE.test(sha256)) throw _invalid();
+    entries.push({ path: rel, mode: raw.mode, sha256, size: raw.size });
+  }
+  if (computeTreeHash(entries) !== canonicalTreeHash) {
+    throw new AgentBundleError('agent_bundle_tree_hash_mismatch', 422);
+  }
+  return entries;
+}
+
+/** Every directory in a freshly written tree, the root included (breadth-first, unordered). */
+async function _collectDirs(rootDir) {
+  const dirs = [rootDir];
+  for (let index = 0; index < dirs.length; index += 1) {
+    const dirents = await fsp.readdir(dirs[index], { withFileTypes: true });
+    for (const dirent of dirents) {
+      if (dirent.isDirectory()) dirs.push(path.join(dirs[index], dirent.name));
+    }
+  }
+  return dirs;
+}
+
+/** Recursive remove that first drops read-only dirs back to writable (trees are 0555). */
+async function _removeTree(target) {
+  const stack = [target];
+  while (stack.length) {
+    const dir = stack.pop();
+    let dirents;
+    try {
+      dirents = await fsp.readdir(dir, { withFileTypes: true });
+    } catch (error) {
+      if (error && error.code === 'ENOENT') continue;
+      throw error;
+    }
+    try {
+      await fsp.chmod(dir, 0o700);
+    } catch (error) {
+      if (!error || error.code !== 'ENOENT') throw error;
+      /* expected: the dir vanished between readdir and chmod — the removal below is already done */
+    }
+    for (const dirent of dirents) {
+      if (dirent.isDirectory()) stack.push(path.join(dir, dirent.name));
+    }
+  }
+  await fsp.rm(target, { recursive: true, force: true });
+}
+
+/**
+ * §6.3: build `trees/<hex>` from the blobs. Copies (not hardlinks) so the 0444 inode is never a
+ * shared, mutable-looking object. The lock order is everything BELOW the temp root (0555,
+ * deepest-first) → `rename(tmp, treeDir)` → the published root itself (0555); see
+ * docs/agent-bundle-darwin-readonly-rename-2026-10-27.html D-1: Darwin's rename(2) needs write on
+ * `old/..`, so a 0555 temp ROOT makes the rename itself fail with EACCES on macOS ≤15, while the
+ * root stays owner-writable across the rename and is locked only once it is in its final place.
+ * A rename race (another request materialized the same tree first) is not an error: `materialized:false`.
+ */
+async function _materialize(root, hex, treeDir, entries) {
+  const tmp = path.join(root, 'trees', `.tmp-${hex}-${crypto.randomBytes(6).toString('hex')}`);
+  try {
+    await fsp.mkdir(tmp, { recursive: true });
+    for (const entry of entries) {
+      const target = path.join(tmp, ...entry.path.split('/'));
+      await fsp.mkdir(path.dirname(target), { recursive: true });
+      await fsp.copyFile(_blobPath(root, entry.sha256), target);
+      await fsp.chmod(target, entry.mode);
+    }
+    // D-5: EVERY directory in the tree is 0555, not just the entry folders — mkdir's defaults are
+    // whatever the umask says, and a writable intermediate would let a later spawn write into the
+    // store. Deepest-first so a parent is never locked while a child still needs creating.
+    // The temp ROOT is excluded (D-1, docs/agent-bundle-darwin-readonly-rename-2026-10-27.html): the
+    // rename below needs write on `old/..`, so the root is locked only after it is published.
+    const dirs = (await _collectDirs(tmp)).filter((dir) => dir !== tmp);
+    dirs.sort((a, b) => b.split(path.sep).length - a.split(path.sep).length);
+    for (const dir of dirs) await fsp.chmod(dir, DIR_MODE);
+    await fsp.rename(tmp, treeDir); // D-1: the root is still owner-writable here
+    await fsp.chmod(treeDir, DIR_MODE); // D-1: a throw here propagates; D-3 re-locks on the next PUT
+    return true;
+  } catch (error) {
+    await _removeTree(tmp);
+    if (error && (error.code === 'EEXIST' || error.code === 'ENOTEMPTY')) return false;
+    throw error; // RETHROW: a failed materialization must not be reported as "already present"
+  }
+}
+
+async function _writeHubPointer(root, peerInstanceId, treeHash) {
+  const dir = path.join(root, 'hubs');
+  await fsp.mkdir(dir, { recursive: true });
+  await atomicWriteFile(
+    path.join(dir, `${peerInstanceId}.json`),
+    JSON.stringify({ treeHash, at: Date.now() }),
+  );
+}
+
+/** §6.3: the hexes from `hashes` that this box does not hold, in input order, deduped. */
+async function missingBlobs(dataDir, hashes) {
+  const root = storeRoot(dataDir);
+  const unique = [];
+  const seen = new Set();
+  for (const value of Array.isArray(hashes) ? hashes : []) {
+    const hex = _requireHex(value);
+    if (seen.has(hex)) continue;
+    seen.add(hex);
+    unique.push(hex);
+  }
+  const missing = [];
+  for (const hex of unique) {
+    if (!(await _exists(_blobPath(root, hex)))) missing.push(hex);
+  }
+  return missing;
+}
+
+// gc.js's blob sweep rmdirs every shard it leaves empty, and it runs unawaited after a materializing
+// manifest PUT -- so a shard this write just created can vanish before the temp file is opened in it.
+// The writer owns recreating its directory (git's object writer does the same): mkdir and retry the
+// open on ENOENT. The recursive mkdir itself can throw ENOENT too -- it answers an existing shard with
+// EEXIST and then stats it, and the sweep can remove it in between. Once the temp file exists the
+// shard is non-empty and the sweep's rmdir cannot win.
+const SHARD_OPEN_ATTEMPTS = 3;
+
+async function _openInShard(dir, tmp) {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      await fsp.mkdir(dir, { recursive: true });
+      return await fsp.open(tmp, 'w', 0o600);
+    } catch (error) {
+      if (!error || error.code !== 'ENOENT' || attempt >= SHARD_OPEN_ATTEMPTS) throw error; // RETHROW
+      /* expected: a GC sweep removed the empty shard during mkdir or before open -- recreate it */
+    }
+  }
+}
+
+/**
+ * §6.2/AC-2a: store one blob. The hash is recomputed FIRST — a wrong-hash body stores nothing — and
+ * an existing blob is left untouched (`{ stored: false }`), which is what makes a re-push cheap.
+ */
+async function putBlob(dataDir, hex, buffer) {
+  const clean = _requireHex(hex);
+  const data = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer == null ? '' : buffer);
+  if (crypto.createHash('sha256').update(data).digest('hex') !== clean) {
+    throw new AgentBundleError('agent_bundle_blob_hash_mismatch', 422);
+  }
+  const root = storeRoot(dataDir);
+  const target = _blobPath(root, clean);
+  if (await _exists(target)) return { stored: false };
+  const dir = path.dirname(target);
+  const tmp = path.join(dir, `.${clean}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+  try {
+    const handle = await _openInShard(dir, tmp);
+    try {
+      await handle.writeFile(data);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await fsp.chmod(tmp, 0o444);
+    await fsp.rename(tmp, target);
+  } catch (error) {
+    await _unlinkQuiet(tmp);
+    throw error; // RETHROW: a failed write must not look like a stored blob
+  }
+  return { stored: true };
+}
+
+/**
+ * §6.2/D-5: accept a manifest and materialize its tree, then move this hub's pointer.
+ *
+ * The peer identity is required BEFORE any write: a box keys bundles by the AUTHENTICATED hub
+ * (`req.ctmAuth.peerInstanceId`), never by a field in the body, so an unidentified caller cannot
+ * create state on this machine.
+ *
+ * @returns {Promise<{treeHash: string, materialized: boolean}>}
+ */
+async function putManifest(dataDir, treeHash, manifest, options = {}) {
+  const peerRaw = String(options.peerInstanceId == null ? '' : options.peerInstanceId).trim();
+  if (!peerRaw) throw new AgentBundleError('agent_bundle_peer_unidentified', 403);
+  const peerInstanceId = _requireId(peerRaw);
+  const canonical = _requireTreeHash(treeHash);
+  const root = storeRoot(dataDir);
+  const entries = _normalizeEntries(manifest, canonical.treeHash);
+
+  const missing = new Set();
+  for (const entry of entries) {
+    if (!(await _exists(_blobPath(root, entry.sha256)))) missing.add(entry.sha256);
+  }
+  if (missing.size) {
+    throw new AgentBundleError('agent_bundle_blobs_missing', 409, { missing: [...missing].sort() });
+  }
+  // D-5: presence is not enough — the bytes on disk must be the size the manifest declares.
+  for (const entry of entries) {
+    const stat = await _statOrNull(_blobPath(root, entry.sha256));
+    if (stat && stat.size !== entry.size) {
+      throw new AgentBundleError('agent_bundle_tree_hash_mismatch', 422);
+    }
+  }
+
+  await fsp.mkdir(path.join(root, 'trees'), { recursive: true });
+  const treeDir = path.join(root, 'trees', canonical.hex);
+  const existing = await _statOrNull(treeDir);
+  const materialized = existing && existing.isDirectory()
+    // D-3 (docs/agent-bundle-darwin-readonly-rename-2026-10-27.html): re-lock a root a crash between
+    // D-1's rename and its chmod left writable — idempotent, and a throw here is a real 500.
+    ? (await fsp.chmod(treeDir, DIR_MODE), false)
+    : await _materialize(root, canonical.hex, treeDir, entries);
+
+  // WP-5: GC needs to know which blobs a tree still needs, so the manifest is copied next to the
+  // tree it names (the tree directory is the durable truth; nothing else remembers it). Written
+  // when the tree is created AND when it already exists without a copy — a tree materialized before
+  // this WP picks one up on the hub's next push of the same content.
+  const manifestCopy = path.join(root, 'trees', `${canonical.hex}.manifest.json`);
+  if (!(await _exists(manifestCopy))) {
+    await atomicWriteFile(manifestCopy, JSON.stringify({ schema: 1, treeHash: canonical.treeHash, entries }));
+  }
+
+  // AC-2e: the pointer moves even when the tree was already there — it names the hub's CURRENT
+  // bundle, not the one that happened to be materialized first.
+  await _writeHubPointer(root, peerInstanceId, canonical.treeHash);
+  return { treeHash: canonical.treeHash, materialized };
+}
+
+/** The hub pointer file this store keys by peer id — one read site for both callers below. */
+function _hubPointerPath(root, peerId) {
+  return path.join(root, 'hubs', `${peerId}.json`);
+}
+
+/**
+ * WP-3: the hub's CURRENT tree pointer for `peerInstanceId`, or null when that hub never pushed
+ * (or its pointer is unreadable). Used at create-record time so `sessions/<id>.json` carries the
+ * tree that was current then; `resolveSpawnBundle` re-reads the pointer at spawn regardless, so a
+ * null here costs nothing.
+ *
+ * @returns {Promise<string|null>} `sha256:<64 hex>` or null
+ */
+async function currentHubTree(dataDir, peerInstanceId) {
+  const peer = String(peerInstanceId == null ? '' : peerInstanceId).trim();
+  if (!ID_RE.test(peer)) return null;
+  const pointer = await _readJsonOrNull(_hubPointerPath(storeRoot(dataDir), peer));
+  if (!pointer) return null;
+  try {
+    return _requireTreeHash(pointer.treeHash).treeHash;
+  } catch (error) {
+    if (error instanceof AgentBundleError) return null;
+    throw error; // RETHROW: an unexpected read fault must not be reported as "no pointer"
+  }
+}
+
+/**
+ * §6.3: remember which hub started this session, and the tree hash as of that create.
+ *
+ * WP-3: `treeHash` may be NULL — that is the honest record for a hub that had not pushed yet at
+ * create time (D-7 reads the hub's CURRENT pointer at spawn, so the create-time value is
+ * bookkeeping). A non-null value is still validated into the canonical `sha256:<hex>` form.
+ */
+async function recordSessionHub(dataDir, ctmSessionId, hubPeerId, treeHash) {
+  const sessionId = _requireId(ctmSessionId);
+  const hubPeerIdClean = _requireId(hubPeerId);
+  const canonical = treeHash === null || treeHash === undefined || String(treeHash).trim() === ''
+    ? null
+    : _requireTreeHash(treeHash).treeHash;
+  const dir = path.join(storeRoot(dataDir), 'sessions');
+  await fsp.mkdir(dir, { recursive: true });
+  await atomicWriteFile(
+    path.join(dir, `${sessionId}.json`),
+    JSON.stringify({ hubPeerId: hubPeerIdClean, createdTreeHash: canonical, at: Date.now() }),
+  );
+}
+
+/**
+ * The pointer -> materialized-tree tail shared by both `resolveSpawnBundle` paths: read
+ * `hubs/<hubPeerId>.json`, canonicalize its tree hash, stat `trees/<hex>`. Returns null for every
+ * missing/unusable piece (no pointer, a torn pointer, a malformed hash, no tree directory) and
+ * rethrows an unexpected read fault. Factored out so the record path and the sole-hub path cannot
+ * drift apart (WP-5 step 4).
+ *
+ * @returns {Promise<null | {treeDir: string, treeHash: string, hubPeerId: string}>}
+ */
+async function _bundleForHub(root, hubPeerId) {
+  const hub = await _readJsonOrNull(_hubPointerPath(root, hubPeerId));
+  if (!hub) return null;
+  let hex;
+  try {
+    hex = _requireTreeHash(hub.treeHash).hex;
+  } catch (error) {
+    if (error instanceof AgentBundleError) return null;
+    throw error; // RETHROW: an unexpected read fault must not be reported as "no bundle"
+  }
+  const treeDir = path.join(root, 'trees', hex);
+  const stat = await _statOrNull(treeDir);
+  if (!stat || !stat.isDirectory()) return null;
+  return { treeDir, treeHash: `sha256:${hex}`, hubPeerId };
+}
+
+/**
+ * rev 3 D-10: the peer id of the box's ONLY hub, or null. A box with exactly one `hubs/<peer>.json`
+ * pointer has exactly one hub, so a session with no `sessions/<id>.json` record (created before the
+ * hub sent its peer id, or by a box-local path) is attributed to that hub. Several pointers (or none)
+ * stay null — the box cannot guess.
+ *
+ * Only `<peer>.json` names whose basename is a valid id count; temp files (`hubs/.tmp-*`) and anything
+ * else are ignored. ENOENT (no `hubs/` dir at all) is the honest "no hub" -> null; any other read
+ * fault is RETHROWN for the caller to REPORT (spawn.js turns it into `agent-bundle-resolve-failed`).
+ *
+ * @returns {Promise<string|null>}
+ */
+async function _soleHubPeerId(root) {
+  let names;
+  try {
+    names = await fsp.readdir(path.join(root, 'hubs'));
+  } catch (error) {
+    if (error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) return null;
+    throw error; // RETHROW: a store we cannot read is REPORTED, never silently "no hub"
+  }
+  const peers = [];
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    const peer = name.slice(0, -'.json'.length);
+    if (!ID_RE.test(peer)) continue;
+    peers.push(peer);
+  }
+  return peers.length === 1 ? peers[0] : null;
+}
+
+/**
+ * §6.3: the bundle this session should spawn with, read through the hub's CURRENT pointer so a skill
+ * edit on the hub applies at the next spawn (D-7's "session overlay", not a snapshot).
+ *
+ * rev 3 D-10: a `sessions/<id>.json` record still wins when present — resolution follows THAT record's
+ * hub pointer only, with no fallback even when the pointer is gone or its tree was GC'd. With no
+ * record, the box applies its single hub's bundle when it has exactly one hub pointer
+ * (`_soleHubPeerId`); zero or several pointers stay null, so the pre-fix hub-created sessions on a
+ * one-hub box (`hubs/ctm-…-3456-1a2c9c.json`) get the hub's skills where nothing else could tell them
+ * apart from box-local creates (docs/remote-skills-hub-peer-identity-2026-10-26.html rev 3 D-10).
+ *
+ * @returns {Promise<null | {treeDir: string, treeHash: string, hubPeerId: string}>}
+ */
+async function resolveSpawnBundle(dataDir, ctmSessionId) {
+  const sessionId = String(ctmSessionId == null ? '' : ctmSessionId).trim();
+  if (!ID_RE.test(sessionId)) return null;
+  const root = storeRoot(dataDir);
+  const session = await _readJsonOrNull(path.join(root, 'sessions', `${sessionId}.json`));
+  if (session) {
+    const hubPeerId = String(session.hubPeerId == null ? '' : session.hubPeerId).trim();
+    if (!ID_RE.test(hubPeerId)) return null;
+    // The record wins: no fallback to a sole hub, so 'sess-orphan' / 'sess-gc' keep resolving to null.
+    return _bundleForHub(root, hubPeerId);
+  }
+  // No record (D-10): the box's only hub, if it has exactly one.
+  const sole = await _soleHubPeerId(root);
+  if (!sole) return null;
+  return _bundleForHub(root, sole);
+}
+
+/**
+ * WP-4 (§6.4, AC-4e): the `sessions/<id>.json` record itself — "was this session created by a hub at
+ * all, and which one" — without following the hub's pointer.
+ *
+ * `resolveSpawnBundle` answers "what should this spawn load" (null covers both "no hub" and "no
+ * tree"); this answers "was there ever a hub", which is what tells a tree that vanished (report
+ * `agent-bundle-missing`) from a local create (report nothing).
+ *
+ * ENOENT → null (the honest "no record"); any other read fault is RETHROWN for the caller to REPORT —
+ * a bundle read never decides whether a session spawns (D-6/D-7).
+ *
+ * @returns {Promise<null | {hubPeerId: string, createdTreeHash: string|null}>}
+ */
+async function sessionHubRecord(dataDir, ctmSessionId) {
+  const sessionId = String(ctmSessionId == null ? '' : ctmSessionId).trim();
+  if (!ID_RE.test(sessionId)) return null;
+  const record = await _readJsonOrNull(path.join(storeRoot(dataDir), 'sessions', `${sessionId}.json`));
+  if (!record) return null;
+  const hubPeerId = String(record.hubPeerId == null ? '' : record.hubPeerId).trim();
+  if (!ID_RE.test(hubPeerId)) return null;
+  let createdTreeHash = null;
+  if (record.createdTreeHash !== null && record.createdTreeHash !== undefined) {
+    try {
+      createdTreeHash = _requireTreeHash(record.createdTreeHash).treeHash;
+    } catch (error) {
+      if (!(error instanceof AgentBundleError)) throw error; // RETHROW: a real read fault is not "no tree"
+      createdTreeHash = null;
+    }
+  }
+  return { hubPeerId, createdTreeHash };
+}
+
+module.exports = {
+  storeRoot,
+  missingBlobs,
+  putBlob,
+  putManifest,
+  recordSessionHub,
+  // WP-3: the hub's current pointer, read at create-record time (a null record is fine — the
+  // spawn-time resolver re-reads the pointer itself).
+  currentHubTree,
+  resolveSpawnBundle,
+  // WP-4: the raw session record, for the "hub-created but no tree" diagnostic (AC-4e).
+  sessionHubRecord,
+  // WP-5: the read-only-tree remover, exported so lib/agent-bundle/gc.js removes a tree the same
+  // way materialization's own failure path does (chmod 0700 down the tree, then rm -r) instead of
+  // growing a second copy of that chmod dance.
+  removeTree: _removeTree,
+  AgentBundleError,
+};