create-walle 0.10.2 → 0.10.3

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

@@ -0,0 +1,724 @@
+'use strict';
+
+/**
+ * WP-8 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-11/D-12/D-13, §6.2, §6.5, the WP-8 row
+ * AC-8a..AC-8d, P-5 "never overwrite the other side silently"): the ONE-SKILL transfers, and the
+ * per-machine plugin exclusion list.
+ *
+ * WP-7 answers "what does the box have that the hub does not?" and classifies it; this module is what
+ * happens when a human acts on that answer. Two directions, one file, because they are one exchange:
+ *
+ *   BOX  `exportBoxSkill({ homeDir, env, agent, name })`  the bytes of ONE item folder, hashed with
+ *        build.js's own walk so the hash IS a hub item hash. `retireBoxSkill({ …, expectHash })`
+ *        MOVES that folder under `<data dir>/agent-bundles/retired/<agent>/<name>-<ts>/` — D-13's
+ *        "moves, never deletes" — after re-hashing it and refusing a copy that changed since review.
+ *   HUB  `importBoxSkillToHub({ … })` fetches that export, verifies every byte, and writes the folder
+ *        into the hub's OWN skill root via stage-inside-root + rename (D-12), backing up any copy that
+ *        was already there FIRST (P-5), then asks the box to retire its shadowing copy.
+ *
+ * The two rules that shape every line here:
+ *   P-5  the hub NEVER writes over a folder it did not just verify a backup of, and the box NEVER
+ *        deletes. A failure anywhere leaves both sides exactly as they were.
+ *   Identity is a NAME, held to the store's own id shape. A name that could escape a root (a slash, a
+ *        `..`, a NUL) is refused before a path is ever built from it, on both sides.
+ *
+ * Everything filesystem-touching takes an injectable `homeDir` / `env` / `dataDir` / `now`, so a test
+ * never reads this machine's real `~/.claude`, `~/.agents` or CTM data dir, and never sleeps.
+ */
+
+const crypto = require('crypto');
+const fsp = require('fs/promises');
+const os = require('os');
+const path = require('path');
+
+const { atomicWriteFile } = require('../../atomic-write');
+const {
+  computeTreeHash, itemHashOfDir, walkItem, listClaudeSkillItems, listCodexSkillItems,
+} = require('./build');
+const inventory = require('./inventory');
+const store = require('./store');
+const codexInstall = require('./codex-install');
+const installer = require('../coding-cli-skill-installer');
+
+const { MANAGED_SKILLS } = installer;
+const { readMarker } = installer._internals;
+
+/** store.js's ID_RE — a name that is also a directory name, and nothing else. */
+const NAME_RE = /^[A-Za-z0-9._-]{1,128}$/;
+// WP-12 (AC-12c): `dsh` (the DeepSeek Harness) is a transfer target like Claude/Codex; its hub root is
+// $DSH_HOME/skills (default ~/.dsh/skills) and its box roots are $DSH_HOME/skills plus ~/.agents/skills.
+const AGENTS = Object.freeze(['claude', 'codex', 'dsh']);
+/** §6.2: the whole export must fit in one response body. */
+const MAX_EXPORT_BYTES = 25 * 1024 * 1024;
+
+/**
+ * WP-9 (§9 S-9, AC-9b): the DIFF SOURCE. A browser cannot call the box's own
+ * `GET /api/agent-skills/export` (peer-bearer auth), so the hub relays one preview per side.
+ *
+ * The two caps are different questions. TEXT is per FILE: past 256 KiB a file is reported as binary
+ * (the dialog never renders a wall of diff lines), and the SAME rule covers a file that is not valid
+ * UTF-8 — `text: null, binary: true` is one answer for "not lines we can diff". TOTAL is per
+ * RESPONSE: the hub refuses (413) rather than streaming megabytes through one JSON body.
+ */
+const MAX_PREVIEW_TEXT_BYTES = 256 * 1024;
+const MAX_PREVIEW_BYTES = 2 * 1024 * 1024;
+/** codex-install.js's marker `source` (an ON-DISK value, restated as data — see inventory.js). */
+const AGENT_BUNDLE_SOURCE = 'agent-bundle';
+
+/** The per-machine plugin exclusion store (§6.5). A DB column is out of scope for this WP: see below. */
+const EXCLUDE_FILE = 'agent-bundle-exclude-plugins.json';
+const EXCLUDE_SCHEMA = 1;
+const MAX_EXCLUDE_ENTRIES = 200;
+const MAX_EXCLUDE_ID_CHARS = 200;
+
+/**
+ * One typed failure, carrying the wire status. Both route modules map it by `status`/`code` alone, so
+ * the box's answer and the hub's relay of it are the same shape for the same fault.
+ */
+class AgentSkillError extends Error {
+  constructor(code, status, detail) {
+    super(code);
+    this.name = 'AgentSkillError';
+    this.code = code;
+    this.status = Number(status) || 500;
+    if (detail != null) this.detail = String(detail).slice(0, 200);
+  }
+}
+
+function sha256Hex(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+function _safeDetail(value) {
+  const text = value instanceof Error
+    ? String(value.message || value.name || 'error')
+    : String(value == null ? '' : value);
+  // Defensive: a transport message is caller-supplied text and the only secret on this path is the
+  // peer bearer, so redact the shape a bearer takes before it can escape into a response.
+  return text.replace(/bearer\s+[^\s,;]+/gi, 'bearer <redacted>').replace(/[\r\n\t]+/g, ' ').trim().slice(0, 200);
+}
+
+function _resolvedHome(homeDir) {
+  return String(homeDir == null ? '' : homeDir).replace(/\/+$/, '') || '/';
+}
+
+function _string(value, max = 1000) {
+  return String(value == null ? '' : value).trim().slice(0, max);
+}
+
+/** `20261026T120000000Z` — sortable, path-safe, and derived from an INJECTED clock. */
+function _compactTs(ms) {
+  return new Date(Number(ms) || Date.now()).toISOString().replace(/[-:.]/g, '');
+}
+
+async function _statOrNull(target) {
+  try {
+    return await fsp.stat(target);
+  } catch (error) {
+    if (error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) return null;
+    throw error; // RETHROW: a real stat fault is the caller's to REPORT
+  }
+}
+
+async function _realOrPlain(target) {
+  try {
+    return await fsp.realpath(target);
+  } catch (error) {
+    if (error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) return target;
+    throw error; // RETHROW: a real resolution fault is the caller's to REPORT
+  }
+}
+
+/**
+ * The two ref fields, validated. `agent` is one of exactly two CLIs and `name` is a directory name
+ * (never a path): everything downstream builds a path out of `name`, so this is the one gate.
+ */
+function validateSkillRef(agent, name) {
+  const resolvedAgent = _string(agent, 40);
+  const resolvedName = String(name == null ? '' : name).trim();
+  if (!AGENTS.includes(resolvedAgent) || !NAME_RE.test(resolvedName)) {
+    throw new AgentSkillError('agent_skill_invalid', 422);
+  }
+  // NAME_RE alone still admits the two directory self-names, and every path below is built by joining
+  // this name onto a root — so `.`/`..` would escape the root rather than name an item (`readdir` never
+  // returns either, so no real item is refused by this).
+  if (resolvedName === '.' || resolvedName === '..') throw new AgentSkillError('agent_skill_invalid', 422);
+  return { agent: resolvedAgent, name: resolvedName };
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * BOX side — locate / export / retire
+ * ---------------------------------------------------------------------------------------------- */
+
+/**
+ * The item folder for `(agent, name)` on THIS machine, or null. Deliberately the SAME enumeration
+ * `readBoxInventory` runs (build.js's listers, in build.js's order), so "the same skill" means the
+ * same folder for the inventory, the export and the retire — including Codex's first-root-wins rule.
+ */
+async function _locateBoxItem(agent, name, homeDir, env) {
+  const resolvedHome = _resolvedHome(homeDir);
+  const items = agent === 'claude'
+    ? await listClaudeSkillItems(inventory.claudeConfigDir(resolvedHome, env))
+    : agent === 'dsh'
+      // WP-12: dsh's box roots are <home>/.agents/skills AND $DSH_HOME/skills (default ~/.dsh/skills) --
+      // the same pair the codex lister walks, with $DSH_HOME standing in for $CODEX_HOME, so a copy
+      // under either dsh root is exportable.
+      ? await listCodexSkillItems(resolvedHome, { ...env, CODEX_HOME: env.DSH_HOME || path.join(resolvedHome, '.dsh') })
+      : await listCodexSkillItems(resolvedHome, env);
+  return items.find((item) => item.name === name) || null;
+}
+
+/**
+ * §6.2 `GET /api/agent-skills/export`: the bytes of ONE box-owned skill.
+ *
+ * `managed: 'ctm-managed'` is a 404 (`agent_skill_not_found`) rather than a 409: this release's own
+ * `delegate` copy is simply not an item that can be proposed for import, and saying "not found" keeps
+ * the hub from ever rendering it as one.
+ *
+ * @returns {Promise<{agent: string, name: string, itemHash: string, files: Array<object>}>}
+ */
+async function exportBoxSkill({ homeDir = os.homedir(), env = process.env, agent, name } = {}) {
+  const ref = validateSkillRef(agent, name);
+  const item = await _locateBoxItem(ref.agent, ref.name, homeDir, env);
+  if (!item) throw new AgentSkillError('agent_skill_not_found', 404);
+  if (await inventory.managedStateOf(item) === 'ctm-managed') {
+    throw new AgentSkillError('agent_skill_not_found', 404);
+  }
+  const realRoot = await _realOrPlain(item.rootDir);
+  const walked = await walkItem(realRoot);
+  if (walked.error) throw new AgentSkillError('agent_skill_not_found', 404);
+  const files = walked.files;
+  const total = files.reduce((sum, file) => sum + file.size, 0);
+  if (total > MAX_EXPORT_BYTES) throw new AgentSkillError('agent_skill_too_large', 413);
+
+  const out = [];
+  for (const file of files) {
+    const buffer = await fsp.readFile(file.abs);
+    out.push({
+      path: file.rel,
+      mode: file.mode,
+      size: buffer.length,
+      sha256: sha256Hex(buffer),
+      contentBase64: buffer.toString('base64'),
+    });
+  }
+  // The item hash is the canonical entry list build.js hashes — computed from the SAME bytes this
+  // response carries, so the hub's recomputation can only disagree if a byte changed in flight.
+  return { agent: ref.agent, name: ref.name, itemHash: computeTreeHash(out.map(_entryOf)), files: out };
+}
+
+/** The `{path, mode, sha256, size}` projection computeTreeHash folds (one shape, one place). */
+function _entryOf(file) {
+  return { path: file.path, mode: file.mode, sha256: file.sha256, size: file.size };
+}
+
+/** rename, or (across filesystems) copy-then-remove. NEVER a plain delete of the source. */
+async function _moveDir(src, dest) {
+  try {
+    await fsp.rename(src, dest);
+    return;
+  } catch (error) {
+    if (!error || error.code !== 'EXDEV') throw error; // RETHROW: only EXDEV has a fallback
+  }
+  await fsp.cp(src, dest, { recursive: true, force: true, verbatimSymlinks: true });
+  await fsp.rm(src, { recursive: true, force: true });
+}
+
+/**
+ * §6.2/§6.5 `POST /api/agent-skills/retire` — D-13's "moves, never deletes".
+ *
+ * The copy is re-hashed NOW and must still be the one the user reviewed (`expectHash`); a managed
+ * (`ctm-managed`) copy is refused outright. The folder is then MOVED under
+ * `<data dir>/agent-bundles/retired/<agent>/<name>-<compactTs>/` — never removed — so the box user can
+ * always recover it by hand.
+ *
+ * A folder carrying an `agent-bundle` marker (a WP-6 Codex install the box then edited) ALSO drops its
+ * root-record entry in `<homeDir>/.agents/skills`: without that, the hub's next push would read the
+ * missing target as a USER DELETION (`removed`) and never re-install the bundle copy, which is exactly
+ * the shadowing D-13 exists to end.
+ *
+ * @returns {Promise<{retiredTo: string}>}
+ */
+async function retireBoxSkill({
+  homeDir = os.homedir(), env = process.env, dataDir = null, agent, name, expectHash = null, now = Date.now,
+} = {}) {
+  const ref = validateSkillRef(agent, name);
+  if (!dataDir) throw new Error('retireBoxSkill: a data dir is required');
+  const item = await _locateBoxItem(ref.agent, ref.name, homeDir, env);
+  if (!item) throw new AgentSkillError('agent_skill_not_found', 404);
+  if (await inventory.managedStateOf(item) === 'ctm-managed') {
+    throw new AgentSkillError('agent_skill_managed', 409);
+  }
+  const itemHash = await itemHashOfDir(item.rootDir);
+  if (itemHash === null) throw new AgentSkillError('agent_skill_not_found', 404);
+  const expected = String(expectHash == null ? '' : expectHash).trim();
+  if (!expected || itemHash !== expected) {
+    throw new AgentSkillError('agent_skill_changed_since_review', 409);
+  }
+  // Read the marker BEFORE the move: after it, the folder is at the retired path.
+  const marker = await readMarker(item.rootDir, ref.name);
+  const retiredTo = path.join(store.storeRoot(dataDir), 'retired', ref.agent, `${ref.name}-${_compactTs(now)}`);
+  await fsp.mkdir(path.dirname(retiredTo), { recursive: true });
+  await _moveDir(item.rootDir, retiredTo);
+  if (marker && marker.source === AGENT_BUNDLE_SOURCE) {
+    await codexInstall.dropRecordEntry(codexInstall.skillsRoot(_resolvedHome(homeDir)), ref.name);
+  }
+  return { retiredTo };
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * HUB side — the hub's own skill root, the export verification, the backup + stage + rename write
+ * ---------------------------------------------------------------------------------------------- */
+
+/** The hub's skill root for one agent: `<CLAUDE_CONFIG_DIR|~/.claude>/skills`, `~/.agents/skills`, or
+ *  (WP-12) `$DSH_HOME/skills` (default `~/.dsh/skills`) for dsh. */
+async function resolveHubSkillsRoot(agent, homeDir = os.homedir(), env = process.env) {
+  const resolvedHome = _resolvedHome(homeDir);
+  const plain = agent === 'claude'
+    ? path.join(inventory.claudeConfigDir(resolvedHome, env), 'skills')
+    : agent === 'dsh'
+      ? path.join(env.DSH_HOME ? _resolvedHome(env.DSH_HOME) : path.join(resolvedHome, '.dsh'), 'skills')
+      : path.join(resolvedHome, '.agents', 'skills');
+  // AC-8a: a Dropbox/`~/.claude`-symlinked root is the observed real shape, so the write target is the
+  // RESOLVED directory — writing through the symlink would still work, but the backup and the replace
+  // would then straddle two paths for one folder.
+  return _realOrPlain(plain);
+}
+
+/**
+ * §6.2/§6.5 step 2: every file's `sha256` is recomputed from its decoded bytes, and the item hash is
+ * recomputed from those bytes — an export that disagrees with ITSELF (`agent_skill_export_corrupt`,
+ * 502) is a different fault from an export that disagrees with what the user reviewed
+ * (`agent_skill_changed_since_review`, 409, AC-8c).
+ *
+ * @returns {Array<{path: string, mode: number, sha256: string, size: number, contentBase64: string}>}
+ */
+function verifyExport(body, agent, name) {
+  const corrupt = () => new AgentSkillError('agent_skill_export_corrupt', 502);
+  if (!body || typeof body !== 'object' || Array.isArray(body)) throw corrupt();
+  if (String(body.agent) !== agent || String(body.name) !== name) throw corrupt();
+  if (!Array.isArray(body.files) || typeof body.itemHash !== 'string') throw corrupt();
+  const files = [];
+  for (const raw of body.files) {
+    if (!raw || typeof raw !== 'object') throw corrupt();
+    const rel = String(raw.path == null ? '' : raw.path);
+    if (!rel || rel.startsWith('/') || rel.includes('\\') || rel.split('/').some((part) => !part || part === '.' || part === '..')) {
+      throw corrupt();
+    }
+    const sha = String(raw.sha256 == null ? '' : raw.sha256);
+    if (!/^[0-9a-f]{64}$/.test(sha)) throw corrupt();
+    const mode = Number(raw.mode);
+    if (mode !== 0o444 && mode !== 0o555) throw corrupt();
+    const size = Number(raw.size);
+    if (!Number.isInteger(size) || size < 0) throw corrupt();
+    const contentBase64 = String(raw.contentBase64 == null ? '' : raw.contentBase64);
+    const buffer = Buffer.from(contentBase64, 'base64');
+    if (buffer.length !== size || sha256Hex(buffer) !== sha) throw corrupt();
+    files.push({ path: rel, mode, sha256: sha, size, contentBase64 });
+  }
+  if (_itemHashOfFiles(files) !== body.itemHash) throw corrupt();
+  return files;
+}
+
+/** The item hash of a verified file list — build.js's canonical list, byte for byte. */
+function _itemHashOfFiles(files) {
+  return computeTreeHash(files.map(_entryOf));
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * WP-9 PREVIEW (§9 S-9, AC-9b) — the read-only diff source both sides of the Review dialog use
+ * ---------------------------------------------------------------------------------------------- */
+
+/**
+ * One preview entry from the bytes on disk. `text` is the file's lines only when the bytes are valid
+ * UTF-8 AND at most MAX_PREVIEW_TEXT_BYTES; everything else is `{text: null, binary: true}` with the
+ * real size, so the dialog can say "binary file, <size>" without ever guessing.
+ *
+ * The validity test is the round trip plus the encoded form's NUL scan: a decoder that substituted
+ * U+FFFD lost information (the file is not UTF-8 text), and a NUL is the classic payload signature.
+ */
+function _previewEntryOf(filePath, buffer) {
+  const size = buffer.length;
+  const binary = size > MAX_PREVIEW_TEXT_BYTES || buffer.includes(0);
+  let text = null;
+  if (!binary) {
+    const decoded = buffer.toString('utf8');
+    text = (decoded.includes('�') || Buffer.byteLength(decoded, 'utf8') !== size) ? null : decoded;
+  }
+  return { path: filePath, text: text === null ? null : text, binary: text === null, size };
+}
+
+/**
+ * The HUB's own copy of `(agent, name)` — the folder `_writeIntoHubRoot` writes to, read with async
+ * fs. `null` when the hub holds no such folder (the "new on <machine>" case: there is nothing to diff
+ * against). An unreadable folder is also `null`: a preview is a read, never a failure the user acts on.
+ *
+ * @returns {Promise<{files: Array<{path: string, text: string|null, binary: boolean, size: number}>}|null>}
+ */
+async function readHubSkillFiles({ agent, name, hubHomeDir = os.homedir(), hubEnv = process.env } = {}) {
+  const ref = validateSkillRef(agent, name);
+  const root = await resolveHubSkillsRoot(ref.agent, hubHomeDir, hubEnv);
+  const dir = path.join(root, ref.name);
+  const stat = await _statOrNull(dir);
+  if (!stat || !stat.isDirectory()) return null;
+  const walked = await walkItem(await _realOrPlain(dir));
+  if (walked.error) return null;
+  const files = [];
+  for (const file of walked.files) {
+    let buffer;
+    try {
+      buffer = await fsp.readFile(file.abs);
+    } catch {
+      // HANDLE: one unreadable file is reported as a binary entry — the preview still shows the rest.
+      files.push({ path: file.rel, text: null, binary: true, size: Number(file.size) || 0 });
+      continue;
+    }
+    files.push(_previewEntryOf(file.rel, buffer));
+  }
+  return { files };
+}
+
+/**
+ * WP-9 (§9 S-9, AC-9b/AC-9c): `GET /api/machines/:id/skills/preview?agent=&name=`.
+ *
+ * The box's half rides the SAME fetch + verification as an import (validateSkillRef, `verifyExport`,
+ * the item hash recomputed from the bytes) — so a preview can never show a folder the import would
+ * then refuse. The hub's half is its own copy, or null. NOTHING is written on either side, and no
+ * backup/retire leg runs: this is the read the Review dialog renders diffs from.
+ *
+ * @returns {Promise<{agent: string, name: string, boxHash: string,
+ *   box: {files: Array<object>}, hub: {files: Array<object>}|null}>}
+ */
+async function previewBoxSkill({ agent, name, hubHomeDir = os.homedir(), hubEnv = process.env, fetchExport } = {}) {
+  const ref = validateSkillRef(agent, name);
+  if (typeof fetchExport !== 'function') throw new AgentSkillError('agent_skill_box_unreachable', 502);
+  let response;
+  try {
+    response = await fetchExport({ agent: ref.agent, name: ref.name });
+  } catch (error) {
+    throw new AgentSkillError('agent_skill_box_unreachable', 502, _safeDetail(error));
+  }
+  const status = Number(response && response.status);
+  if (!Number.isFinite(status) || status === 0) throw new AgentSkillError('agent_skill_box_unreachable', 502, 'the box did not answer');
+  if (status === 404) throw new AgentSkillError('agent_skill_not_found', 404);
+  if (status !== 200 || !response.body) {
+    throw new AgentSkillError('agent_skill_box_unreachable', 502, `the box answered ${status}`);
+  }
+
+  // Same verification the import runs, so "what the dialog showed" and "what an import would write"
+  // are the same bytes (and the same hash the Import button sends back as `expectBoxHash`).
+  const files = verifyExport(response.body, ref.agent, ref.name);
+  const boxHash = String(response.body.itemHash);
+  const box = {
+    files: files.map((file) => _previewEntryOf(file.path, Buffer.from(file.contentBase64, 'base64'))),
+  };
+  const hub = await readHubSkillFiles({
+    agent: ref.agent, name: ref.name, hubHomeDir, hubEnv,
+  });
+
+  const totalBytes = box.files.reduce((sum, file) => sum + file.size, 0)
+    + (hub ? hub.files.reduce((sum, file) => sum + file.size, 0) : 0);
+  if (totalBytes > MAX_PREVIEW_BYTES) throw new AgentSkillError('agent_skill_preview_too_large', 413);
+
+  return { agent: ref.agent, name: ref.name, boxHash, box, hub };
+}
+
+/** Recursive copy that preserves the exec bit and reproduces neither the tree's nor the source's
+ *  read-only dir modes (the hub's skill root is user-editable, P-5's whole point). */
+async function _copyDirTree(srcDir, destDir) {
+  await fsp.mkdir(destDir, { recursive: true });
+  await fsp.chmod(destDir, 0o755);
+  for (const dirent of await fsp.readdir(srcDir, { withFileTypes: true })) {
+    const src = path.join(srcDir, dirent.name);
+    const dest = path.join(destDir, dirent.name);
+    if (dirent.isDirectory()) {
+      await _copyDirTree(src, dest);
+      continue;
+    }
+    if (!dirent.isFile()) continue; // symlinks are never followed out of the folder
+    const stat = await fsp.lstat(src);
+    await fsp.copyFile(src, dest);
+    await fsp.chmod(dest, (stat.mode & 0o111) !== 0 ? 0o755 : 0o644);
+  }
+}
+
+/** Write the verified files into `destDir` (staging): files 0644, exec bit preserved as 0755, dirs
+ *  0755 — the user edits these copies, so no 0444 can survive the import. */
+async function _writeFiles(destDir, files) {
+  await fsp.mkdir(destDir, { recursive: true });
+  await fsp.chmod(destDir, 0o755);
+  const dirs = new Set([destDir]);
+  for (const file of files) {
+    const target = path.join(destDir, ...file.path.split('/'));
+    const dir = path.dirname(target);
+    await fsp.mkdir(dir, { recursive: true });
+    dirs.add(dir);
+    await fsp.writeFile(target, Buffer.from(file.contentBase64, 'base64'));
+    await fsp.chmod(target, (file.mode & 0o111) !== 0 ? 0o755 : 0o644);
+  }
+  for (const dir of dirs) await fsp.chmod(dir, 0o755);
+}
+
+/**
+ * D-12: back up any existing hub copy FIRST, then stage inside the root and rename.
+ *
+ * ORDER IS LOAD-BEARING (P-5): the backup is written and VERIFIED (same item hash as the folder it
+ * came from) before a single byte of the live copy is touched, so the only way to lose the old copy is
+ * to fail while the new one is already in place — and even then the replaced folder is still on disk
+ * until the swap is complete.
+ *
+ * @returns {Promise<{importedTo: string, backupDir: string|null}>}
+ */
+async function _writeIntoHubRoot({ agent, name, files, dataDir, hubHomeDir, hubEnv, now }) {
+  const root = await resolveHubSkillsRoot(agent, hubHomeDir, hubEnv);
+  await fsp.mkdir(root, { recursive: true });
+  const targetDir = path.join(root, name);
+  const existing = await _statOrNull(targetDir);
+
+  let backupDir = null;
+  if (existing && existing.isDirectory()) {
+    backupDir = path.join(String(dataDir), 'skill-import-backups', agent, `${name}-${_compactTs(now)}`);
+    await fsp.mkdir(path.dirname(backupDir), { recursive: true });
+    await _copyDirTree(targetDir, backupDir);
+    const [beforeHash, backupHash] = await Promise.all([itemHashOfDir(targetDir), itemHashOfDir(backupDir)]);
+    if (beforeHash === null || beforeHash !== backupHash) {
+      throw new AgentSkillError('agent_skill_backup_failed', 500);
+    }
+  }
+
+  const rand = crypto.randomBytes(6).toString('hex');
+  const staging = path.join(root, `.${name}.ctm-import-${rand}`);
+  const replaced = path.join(root, `.${name}.ctm-replaced-${rand}`);
+  try {
+    await _writeFiles(staging, files);
+    let moved = false;
+    if (existing) {
+      await fsp.rename(targetDir, replaced);
+      moved = true;
+    }
+    try {
+      await fsp.rename(staging, targetDir);
+    } catch (error) {
+      // RETHROW: the swap failed, so put the original back before the staging dir is cleaned up.
+      if (moved) await fsp.rename(replaced, targetDir);
+      throw error;
+    }
+    if (moved) await fsp.rm(replaced, { recursive: true, force: true });
+  } catch (error) {
+    await fsp.rm(staging, { recursive: true, force: true });
+    throw error; // RETHROW: the caller maps it; the original folder is still in place
+  }
+  return { importedTo: targetDir, backupDir };
+}
+
+/**
+ * §6.5 `POST /api/machines/:instanceId/skills/import`.
+ *
+ * `fetchExport` / `retire` are the caller's transport (lib/api/machines.js builds them from the peer
+ * bearer + the row's dial list), so this module owns the policy and the route owns the socket. A
+ * retire failure NEVER undoes the import (the bytes are already the hub's), so the result carries
+ * `retired: false` plus the code instead of throwing.
+ *
+ * @returns {Promise<{importedTo: string, backupDir: string|null, retired: boolean,
+ *                    retiredTo: string|null, retireError: string|null}>}
+ */
+async function importBoxSkillToHub({
+  agent, name, expectBoxHash = null, dataDir,
+  hubHomeDir = os.homedir(), hubEnv = process.env,
+  fetchExport, retire = null, now = Date.now,
+} = {}) {
+  const ref = validateSkillRef(agent, name);
+  if (!dataDir) throw new Error('importBoxSkillToHub: a data dir is required');
+  if (Object.hasOwn(MANAGED_SKILLS, ref.name)) {
+    throw new AgentSkillError('agent_skill_managed', 409);
+  }
+
+  let response;
+  try {
+    response = await fetchExport({ agent: ref.agent, name: ref.name });
+  } catch (error) {
+    throw new AgentSkillError('agent_skill_box_unreachable', 502, _safeDetail(error));
+  }
+  const status = Number(response && response.status);
+  if (!Number.isFinite(status) || status === 0) {
+    throw new AgentSkillError('agent_skill_box_unreachable', 502, 'the box did not answer');
+  }
+  if (status === 404) throw new AgentSkillError('agent_skill_not_found', 404);
+  if (status !== 200 || !response.body) {
+    throw new AgentSkillError('agent_skill_box_unreachable', 502, `the box answered ${status}`);
+  }
+
+  const files = verifyExport(response.body, ref.agent, ref.name);
+  const boxHash = String(response.body.itemHash);
+  const expected = String(expectBoxHash == null ? '' : expectBoxHash).trim();
+  if (boxHash !== expected) throw new AgentSkillError('agent_skill_changed_since_review', 409);
+
+  const written = await _writeIntoHubRoot({
+    agent: ref.agent, name: ref.name, files, dataDir, hubHomeDir, hubEnv, now,
+  });
+
+  let retired = false;
+  let retiredTo = null;
+  let retireError = null;
+  if (typeof retire === 'function') {
+    try {
+      const answer = await retire({ agent: ref.agent, name: ref.name, expectHash: boxHash });
+      const retireStatus = Number(answer && answer.status);
+      if (retireStatus === 200 && answer.body && typeof answer.body.retiredTo === 'string') {
+        retired = true;
+        retiredTo = answer.body.retiredTo;
+      } else {
+        retireError = _string(answer && answer.body && answer.body.code, 80)
+          || (retireStatus ? `agent_skill_box_http_${retireStatus}` : 'agent_skill_box_unreachable');
+      }
+    } catch (error) {
+      // REPORT: the import already succeeded; a dead box on the retire leg is a partial outcome the
+      // caller surfaces, never a rollback of bytes that are already correct.
+      retireError = 'agent_skill_box_unreachable';
+    }
+  } else {
+    retireError = 'agent_skill_retire_skipped';
+  }
+
+  return { importedTo: written.importedTo, backupDir: written.backupDir, retired, retiredTo, retireError };
+}
+
+/**
+ * §6.5 `POST /api/machines/:instanceId/skills/retire` — "use the laptop's copy", or a redundant `same`
+ * copy: the box's folder moves aside, and NOTHING is written on the hub. Same error mapping as the
+ * import leg, minus the write.
+ *
+ * @returns {Promise<{retiredTo: string}>}
+ */
+async function retireBoxSkillFromHub({ agent, name, expectBoxHash = null, retire } = {}) {
+  const ref = validateSkillRef(agent, name);
+  if (typeof retire !== 'function') throw new AgentSkillError('agent_skill_box_unreachable', 502);
+  let response;
+  try {
+    response = await retire({ agent: ref.agent, name: ref.name, expectHash: expectBoxHash });
+  } catch (error) {
+    throw new AgentSkillError('agent_skill_box_unreachable', 502, _safeDetail(error));
+  }
+  const status = Number(response && response.status);
+  const code = _string(response && response.body && response.body.code, 80);
+  if (!Number.isFinite(status) || status === 0) throw new AgentSkillError('agent_skill_box_unreachable', 502);
+  if (status === 200 && response.body && typeof response.body.retiredTo === 'string') {
+    return { retiredTo: response.body.retiredTo };
+  }
+  if (status === 404) throw new AgentSkillError('agent_skill_not_found', 404);
+  if (status === 409) throw new AgentSkillError(code || 'agent_skill_changed_since_review', 409);
+  if (status === 422) throw new AgentSkillError(code || 'agent_skill_invalid', 422);
+  throw new AgentSkillError('agent_skill_box_unreachable', 502, `the box answered ${status}`);
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * Per-machine plugin exclusions (§6.5)
+ *
+ * ONE hub-side JSON file, `<hub data dir>/agent-bundle-exclude-plugins.json`, shaped
+ * `{ schema: 1, machines: { <instanceId>: [<plugin id>…] } }`. A DB column is deliberately OUT of
+ * scope for this WP (it would mean a migration plus a db.js writer for a list that is read on the
+ * create path and written from one settings row); the file is atomic and the read below is cached in
+ * memory, re-read on write.
+ * ---------------------------------------------------------------------------------------------- */
+
+let _excludeCache = null; // { dataDir, machines }
+
+function _excludePath(dataDir) {
+  return path.join(String(dataDir == null ? '' : dataDir), EXCLUDE_FILE);
+}
+
+/**
+ * Load the store for `dataDir` into the in-memory cache (async — no sync fs on the main thread). A
+ * missing/garbled file is an empty list. Callers that need the list (the Machines list handler, the
+ * push path) await this first; `excludePluginsFor` then reads the cache synchronously.
+ */
+async function loadExcludePlugins(dataDir) {
+  const dir = String(dataDir == null ? '' : dataDir);
+  if (_excludeCache && _excludeCache.dataDir === dir) return _excludeCache.machines;
+  let machines = {};
+  try {
+    const parsed = JSON.parse(await fsp.readFile(path.join(dir, EXCLUDE_FILE), 'utf8'));
+    if (parsed && typeof parsed === 'object' && parsed.machines && typeof parsed.machines === 'object'
+      && !Array.isArray(parsed.machines)) {
+      machines = parsed.machines;
+    }
+  } catch {
+    /* expected: no file yet, or a torn copy — both mean "nothing excluded", never a create failure */
+  }
+  _excludeCache = { dataDir: dir, machines };
+  return machines;
+}
+
+/** The plugin ids excluded for ONE machine, or `[]`, from the cache `loadExcludePlugins` filled
+ *  (a store never loaded for this dir reads as nothing excluded). */
+function excludePluginsFor(dataDir, instanceId) {
+  const id = _string(instanceId, 160);
+  if (!id) return [];
+  const dir = String(dataDir == null ? '' : dataDir);
+  const machines = _excludeCache && _excludeCache.dataDir === dir ? _excludeCache.machines : {};
+  const list = machines[id];
+  return Array.isArray(list) ? list.slice() : [];
+}
+
+/**
+ * §6.5 `PUT /api/machines/:instanceId/skills/exclude-plugins`: replace one machine's list. Ids are
+ * strings of at most 200 chars, deduped and sorted; at most 200 of them (the plugin count a hub can
+ * plausibly carry, and the bound that keeps the file small).
+ *
+ * @returns {Promise<string[]>} the stored list
+ */
+async function setExcludePlugins(dataDir, instanceId, plugins) {
+  const id = _string(instanceId, 160);
+  if (!id) throw new AgentSkillError('agent_skill_invalid', 422);
+  if (!Array.isArray(plugins)) throw new AgentSkillError('exclude_plugins_invalid', 422);
+  const unique = new Set();
+  for (const value of plugins) {
+    if (typeof value !== 'string') throw new AgentSkillError('exclude_plugins_invalid', 422);
+    const pluginId = value.trim();
+    if (!pluginId || pluginId.length > MAX_EXCLUDE_ID_CHARS) throw new AgentSkillError('exclude_plugins_invalid', 422);
+    unique.add(pluginId);
+  }
+  if (unique.size > MAX_EXCLUDE_ENTRIES) throw new AgentSkillError('exclude_plugins_invalid', 422);
+  const list = [...unique].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  const dir = String(dataDir == null ? '' : dataDir);
+  const machines = { ...(await loadExcludePlugins(dir)), [id]: list };
+  const next = { schema: EXCLUDE_SCHEMA, machines };
+  await fsp.mkdir(dir, { recursive: true });
+  await atomicWriteFile(_excludePath(dir), JSON.stringify(next, null, 2) + '\n');
+  // Re-read on write: the cache IS the file's parsed content, so a write refreshes it in place.
+  _excludeCache = { dataDir: dir, machines };
+  return list;
+}
+
+/**
+ * Test-only: drop the in-memory cache so each test observes its own file. Module state, like every
+ * other cache in this tree.
+ */
+function _resetExcludePluginsCacheForTests() {
+  _excludeCache = null;
+}
+
+module.exports = {
+  AgentSkillError,
+  // box
+  validateSkillRef,
+  exportBoxSkill,
+  retireBoxSkill,
+  // hub
+  resolveHubSkillsRoot,
+  verifyExport,
+  importBoxSkillToHub,
+  retireBoxSkillFromHub,
+  // WP-9: the review dialog's diff source.
+  readHubSkillFiles,
+  previewBoxSkill,
+  // per-machine plugin exclusions
+  loadExcludePlugins,
+  excludePluginsFor,
+  setExcludePlugins,
+  _resetExcludePluginsCacheForTests,
+  EXCLUDE_FILE,
+  MAX_EXPORT_BYTES,
+  MAX_PREVIEW_BYTES,
+  MAX_PREVIEW_TEXT_BYTES,
+};