@nurix/etna 0.20.26 → 0.20.28

package/data/harnesses/kb-agi/harness.json

@@ -10,5 +10,9 @@
   "seeds": [],
   "tools": [],
   "docsRoot": "docs",
+  "mount": {
+    "origin": "https://cdn.nustack.io",
+    "track": "latest"
+  },
   "digest": "b9b62b069087"
 }

package/lib/install/materialize.mjs

@@ -21,7 +21,9 @@ import {
   rmSync,
 } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { planHarnessFiles, PRUNABLE_SUBDIRS, CODEX_REBUILT_DIRS } from './plan.mjs';
+import { writeIgnoreBlock, recordMount, ignoreBlockLines } from './mount.mjs';
 import { projectSkills } from '../codex/skills.mjs';
 
 // Hook scripts shipped by earlier harness versions (the legacy memory-ledger tier) and since retired.
@@ -121,25 +123,23 @@ function retireOldHooks(targetDir, bundledHarnessDir) {
   return removed;
 }
 
-// Artifacts a prior install leaves behind, in the order they are cheapest to trust. `.claude/` is
-// deliberately NOT the only one: a repo that gitignores it never commits `harness.json`, so a fresh
-// CI checkout of an already-harnessed repo carries no marker there and would read as first contact
-// on EVERY roll — which seeds pristine scaffolds over the project's real docs, backs the originals
-// up as .bkp, and does it again next time, since the gitignore is what stops the marker persisting.
-// The Codex artifacts and AGENTS.md are written by the same install and are conventionally tracked,
-// so any one of them present is proof this repo has been harnessed before.
-const PRIOR_INSTALL_MARKERS = [
-  join('.claude', 'harness.json'),
-  join('.codex', 'hooks.json'),
-  join('.agents', 'skills'),
-  'AGENTS.md',
-];
-
 // First contact means "this repo has never been harnessed", which is what licenses the installer to
-// move a colliding file aside as .bkp and write the pristine seed over it. Getting it wrong in the
-// permissive direction is destructive, so any evidence of a prior install settles it.
+// move a colliding file aside as .bkp and write the pristine seed over it. `.claude/harness.json` is
+// always committed (the ignore block negates it), so its absence alone decides.
 function isFirstContact(targetDir) {
-  return !PRIOR_INSTALL_MARKERS.some((rel) => existsSync(join(targetDir, rel)));
+  return !existsSync(join(targetDir, '.claude', 'harness.json'));
+}
+
+// The ignore-block names a repository still tracks — what adopting the mount has to untrack. A
+// read-only `git ls-files`; the installer never runs a git command that changes anything.
+export function trackedMountedPaths(targetDir, mountedPaths) {
+  const listed = spawnSync('git', ['ls-files', '-z'], { cwd: targetDir, encoding: 'utf8' });
+  if (listed.status !== 0) return [];
+  const tracked = (listed.stdout || '').split('\0').filter(Boolean);
+  return ignoreBlockLines(mountedPaths)
+    .filter((line) => line.startsWith('.') && line !== '.claude/state/')
+    .filter((name) => tracked.some((file) => (name.endsWith('/') ? file.startsWith(name) : file === name)))
+    .map((name) => name.replace(/\/$/, ''));
 }
 
 // Read the `owned` manifest the PREVIOUS install recorded in the project's harness.json.
@@ -230,12 +230,14 @@ function hookScript(command) {
 // "hooks", preserving every existing key. Idempotent: for each event, an incoming entry
 // merges into the matcher-group of the same matcher, skipping any hook whose command
 // already exists there; a hook already registered for the same script under an older command
-// shape is replaced in place, never doubled; a new matcher creates a new group. Returns the
-// count of hooks added or replaced.
+// shape is replaced in place, never doubled, and so is a harness script the incoming group no
+// longer registers; a new matcher creates a new group. Returns the count of hooks changed.
 function mergeHooks(targetDir, bundledHooksJson) {
   if (!existsSync(bundledHooksJson)) return 0;
   const bundled = readJson(bundledHooksJson);
   const incoming = bundled.hooks || {};
+  const hooksDir = dirname(bundledHooksJson);
+  const shipped = new Set(readdirSync(hooksDir).filter((name) => /\.m?js$/.test(name)));
   const settingsPath = join(targetDir, '.claude', 'settings.json');
   const settings = readJson(settingsPath);
   settings.hooks = settings.hooks || {};
@@ -260,14 +262,23 @@ function mergeHooks(targetDir, bundledHooksJson) {
         continue;
       }
       match.hooks = match.hooks || [];
+      const registered = new Set((group.hooks || []).map((h) => hookScript(h.command)).filter(Boolean));
+      const isRetiredHere = (h) => {
+        const script = hookScript(h.command);
+        return !!script && shipped.has(script) && !registered.has(script);
+      };
       for (const hook of group.hooks || []) {
         if (groupHasCommand(match, hook.command)) continue;
         const script = hookScript(hook.command);
-        const staleIndex = script ? match.hooks.findIndex((h) => hookScript(h.command) === script) : -1;
+        let staleIndex = script ? match.hooks.findIndex((h) => hookScript(h.command) === script) : -1;
+        if (staleIndex === -1) staleIndex = match.hooks.findIndex(isRetiredHere);
         if (staleIndex === -1) match.hooks.push(hook);
         else match.hooks[staleIndex] = hook;
         added += 1;
       }
+      const before = match.hooks.length;
+      match.hooks = match.hooks.filter((h) => !isRetiredHere(h));
+      added += before - match.hooks.length;
     }
   }
   if (added > 0) writeJson(settingsPath, settings);
@@ -290,8 +301,8 @@ function mergeHooks(targetDir, bundledHooksJson) {
  * Returns the accounting the caller renders: `installed`, `notices`, `warnings`, plus `owned` (the
  * manifest written into `.claude/harness.json`) and `meta` (the bundle marker).
  */
-export function materializeHarness({ bundledHarnessDir, targetDir }) {
-  const { files, owned, meta, capabilityNotes } = planHarnessFiles(bundledHarnessDir, targetDir);
+export function materializeHarness({ bundledHarnessDir, targetDir, mount }) {
+  const { files, owned, meta, capabilityNotes } = planHarnessFiles(bundledHarnessDir, targetDir, { mount });
 
   const installed = [];
   const notices = [...(capabilityNotes || [])];
@@ -403,6 +414,23 @@ export function materializeHarness({ bundledHarnessDir, targetDir }) {
   const added = mergeHooks(targetDir, join(bundledHarnessDir, 'hooks', 'hooks.json'));
   if (added > 0) installed.push(`${added} hook(s) → .claude/settings.json`);
 
+  // The mount's bookkeeping, the same the session-start hook does: the managed ignore block names
+  // what is mounted, and the mount record lets that hook see this version is already on disk.
+  // Named from the ungated plan — the same set the version manifest lists — so the block the
+  // installer writes and the block a session's mount writes are byte-identical.
+  const mountedPaths = planHarnessFiles(bundledHarnessDir)
+    .files.filter((file) => file.policy === 'mount')
+    .map((file) => file.path);
+  if (writeIgnoreBlock(targetDir, mountedPaths)) installed.push('mount block → .gitignore');
+  if (meta.version) recordMount(targetDir, { version: meta.version, digest: meta.digest || null, owned });
+  const adoption = trackedMountedPaths(targetDir, mountedPaths);
+  if (adoption.length) {
+    notices.push(
+      'This repository still tracks mounted harness paths. To adopt the mount, untrack them ' +
+        '(the files stay on disk) and commit:\n' +
+        `  git rm -r --cached -- ${adoption.join(' ')}`,
+    );
+  }
 
-  return { installed, notices, warnings, owned, meta };
+  return { installed, notices, warnings, owned, meta, mountedPaths, adoption };
 }

package/lib/install/mount.mjs

@@ -0,0 +1,448 @@
+// packages/cli/lib/install/mount.mjs
+// The mount: a harness version's mounted files materialised from a version-keyed manifest and
+// the machine's content-addressed cache, plus the managed `.gitignore` block and the mount record.
+// The region between the shared-core markers is copied byte-for-byte into
+// harness/code/hooks/mount.mjs (a bare clone has no lib/ to import); a test pins the two equal.
+// Fuller account: docs/packages/cli.md § The mount.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+
+// --- shared mount core: start ---
+const DEFAULT_ORIGIN = 'https://cdn.nustack.io';
+const MOUNT_BLOCK_START = '# etna:mount:start';
+const MOUNT_BLOCK_END = '# etna:mount:end';
+const MOUNTED_CLAUDE_SUBDIRS = ['skills', 'agents', 'rules', 'scripts', 'hooks'];
+const CONTRACT_NEGATIONS = [
+  '!.claude/harness.json',
+  '!.claude/settings.json',
+  '!.claude/hooks/',
+  '!.claude/hooks/mount.mjs',
+  '!.codex/hooks.json',
+];
+const FETCH_CONCURRENCY = 8;
+const CAPABILITY_GATES = { '.claude/rules/cloudflare.md': 'worker' };
+
+function sha256Of(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+// The machine cache every repository on the machine shares; ETNA_CACHE_DIR relocates it.
+function cacheRoot(env = process.env) {
+  return env.ETNA_CACHE_DIR || join(homedir(), '.etna', 'cache');
+}
+
+// True for a path the mount owns; the contract layer (the committed half) answers false.
+function isMountedPath(path) {
+  if (path === '.claude/hooks/mount.mjs' || path === '.codex/hooks.json') return false;
+  const parts = path.split('/');
+  if (parts[0] === '.claude') return parts.length > 2 && MOUNTED_CLAUDE_SUBDIRS.includes(parts[1]);
+  return (parts[0] === '.agents' || parts[0] === '.codex') && parts.length > 1;
+}
+
+// Numeric dotted-version order: negative, zero or positive, like a sort comparator.
+function compareVersions(a, b) {
+  const left = String(a).split('.').map((part) => parseInt(part, 10) || 0);
+  const right = String(b).split('.').map((part) => parseInt(part, 10) || 0);
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    const diff = (left[i] || 0) - (right[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+function readJsonFile(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Temp file then rename, so a concurrent reader sees the old file or the new one, never a torn one.
+function writeAtomic(file, bytes) {
+  mkdirSync(dirname(file), { recursive: true });
+  const temp = join(dirname(file), `.${basename(file)}.mount-${process.pid}`);
+  writeFileSync(temp, bytes);
+  renameSync(temp, file);
+}
+
+async function fetchBytes(url, fetchImpl, timeoutMs) {
+  const response = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) });
+  if (!response.ok) throw new Error(`GET ${url} answered ${response.status}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+// Runs task over items with a bounded number in flight.
+async function eachLimited(items, task) {
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const item = items[next];
+      next += 1;
+      await task(item);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(FETCH_CONCURRENCY, items.length) }, worker));
+}
+
+// The version manifest, from the machine cache when present, else fetched and cached.
+async function resolveManifest({ origin, slug, version, cacheDir, fetchImpl, timeoutMs }) {
+  const cached = join(cacheDir, slug, version, 'manifest.json');
+  if (existsSync(cached)) return { manifest: JSON.parse(readFileSync(cached, 'utf8')), source: 'cache' };
+  const bytes = await fetchBytes(`${origin}/harness/${slug}/${version}/manifest.json`, fetchImpl, timeoutMs);
+  const manifest = JSON.parse(bytes.toString('utf8'));
+  writeAtomic(cached, bytes);
+  return { manifest, source: 'origin' };
+}
+
+// One file's bytes by sha256: the object cache first, else fetched, verified, and cached.
+async function readObject({ origin, entry, cacheDir, fetchImpl, timeoutMs }) {
+  const file = join(cacheDir, 'objects', entry.sha256);
+  if (existsSync(file)) {
+    const bytes = readFileSync(file);
+    if (sha256Of(bytes) === entry.sha256) return bytes;
+  }
+  const bytes = await fetchBytes(`${origin}/${entry.key}`, fetchImpl, timeoutMs);
+  if (sha256Of(bytes) !== entry.sha256) throw new Error(`${entry.path}: fetched bytes do not match the manifest`);
+  writeAtomic(file, bytes);
+  return bytes;
+}
+
+function mountedEntries(manifest) {
+  return (manifest.files || []).filter(
+    (entry) => (entry.policy === undefined || entry.policy === 'mount') && isMountedPath(entry.path),
+  );
+}
+
+// A Worker's config at the root, or one or two directory levels down (node_modules and dot dirs skipped).
+function hasWorkerConfig(projectDir) {
+  const names = ['wrangler.jsonc', 'wrangler.toml'];
+  const search = (dir, depth) => {
+    if (names.some((name) => existsSync(join(dir, name)))) return true;
+    if (depth === 0) return false;
+    let entries = [];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return false;
+    }
+    return entries.some(
+      (entry) => entry.isDirectory() && entry.name !== 'node_modules' && !entry.name.startsWith('.') && search(join(dir, entry.name), depth - 1),
+    );
+  };
+  return search(projectDir, 2);
+}
+
+// The mounted entries this project's capabilities admit; a gated rule mounts only where its capability is.
+function admittedEntries(projectDir, entries) {
+  const capabilities = { worker: null };
+  return entries.filter((entry) => {
+    const gate = entry.requires || CAPABILITY_GATES[entry.path];
+    if (!gate) return true;
+    if (capabilities[gate] === null) capabilities[gate] = gate === 'worker' ? hasWorkerConfig(projectDir) : false;
+    return capabilities[gate] === true;
+  });
+}
+
+function filesBelow(root, rel) {
+  const full = join(root, rel);
+  let stat;
+  try {
+    stat = statSync(full);
+  } catch {
+    return [];
+  }
+  if (!stat.isDirectory()) return [rel];
+  return readdirSync(full).flatMap((name) => filesBelow(root, `${rel}/${name}`));
+}
+
+// On-disk files the mount may delete: inside owned component names, and the hooks tree bar mount.mjs.
+function prunableFiles(projectDir, owned) {
+  const out = [];
+  for (const sub of ['skills', 'agents', 'rules', 'scripts']) {
+    for (const name of owned[sub] || []) out.push(...filesBelow(projectDir, `.claude/${sub}/${name}`));
+  }
+  for (const rel of filesBelow(projectDir, '.claude/hooks')) if (rel !== '.claude/hooks/mount.mjs') out.push(rel);
+  for (const name of owned.skills || []) out.push(...filesBelow(projectDir, `.agents/skills/${name}`));
+  for (const name of owned.agents || []) {
+    out.push(...filesBelow(projectDir, `.codex/agents/${name.replace(/\.md$/, '')}.toml`));
+  }
+  return out.filter((rel) => rel !== '.claude/hooks');
+}
+
+function unionOwned(...maps) {
+  const out = {};
+  for (const map of maps) {
+    for (const [sub, names] of Object.entries(map || {})) out[sub] = [...new Set([...(out[sub] || []), ...names])];
+  }
+  return out;
+}
+
+function removeEmptyParents(projectDir, rel) {
+  let dir = dirname(rel);
+  while (dir.split('/').length > 2) {
+    const full = join(projectDir, dir);
+    try {
+      if (readdirSync(full).length > 0) return;
+      rmSync(full, { recursive: true, force: true });
+    } catch {
+      return;
+    }
+    dir = dirname(dir);
+  }
+}
+
+// Writes the manifest's mounted files that differ on disk, then deletes owned names the manifest omits.
+async function mountFromManifest({ projectDir, manifest, origin, cacheDir, fetchImpl, timeoutMs, priorOwned }) {
+  const all = mountedEntries(manifest);
+  const entries = admittedEntries(projectDir, all);
+  const listed = new Set(entries.map((entry) => entry.path));
+  const written = [];
+  const failed = [];
+  const removed = [];
+  const stale = entries.filter((entry) => {
+    const dest = join(projectDir, entry.path);
+    return !(existsSync(dest) && sha256Of(readFileSync(dest)) === entry.sha256);
+  });
+  await eachLimited(stale, async (entry) => {
+    try {
+      writeAtomic(join(projectDir, entry.path), await readObject({ origin, entry, cacheDir, fetchImpl, timeoutMs }));
+      written.push(entry.path);
+    } catch {
+      failed.push(entry.path);
+    }
+  });
+  for (const rel of prunableFiles(projectDir, unionOwned(manifest.owned, priorOwned))) {
+    if (listed.has(rel)) continue;
+    rmSync(join(projectDir, rel), { force: true });
+    removeEmptyParents(projectDir, rel);
+    removed.push(rel);
+  }
+  return { written: written.sort(), failed: failed.sort(), removed, mountedPaths: all.map((entry) => entry.path) };
+}
+
+// The block's lines: contract negations, then the mounted top-level names and the state folder.
+function ignoreBlockLines(mountedPaths) {
+  const names = new Set(['.claude/state/']);
+  for (const path of mountedPaths) {
+    const parts = path.split('/');
+    if (parts[0] === '.claude') names.add(parts.length > 3 ? `${parts.slice(0, 3).join('/')}/` : path);
+    else names.add(parts.length > 2 ? `${parts[0]}/${parts[1]}/` : path);
+  }
+  return [
+    MOUNT_BLOCK_START,
+    '# Managed by etna: the mounted harness, rewritten on every mount. Edit outside this block.',
+    ...CONTRACT_NEGATIONS,
+    ...[...names].sort(),
+    MOUNT_BLOCK_END,
+  ];
+}
+
+// Rewrites the managed block at the end of .gitignore; a bare `.claude` line becomes `.claude/*`.
+function writeIgnoreBlock(projectDir, mountedPaths) {
+  const file = join(projectDir, '.gitignore');
+  const before = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  const kept = [];
+  let inBlock = false;
+  for (const line of before.split('\n')) {
+    if (line.trim() === MOUNT_BLOCK_START) inBlock = true;
+    else if (inBlock) inBlock = line.trim() !== MOUNT_BLOCK_END;
+    else {
+      const bare = /^(\/?)\.claude\/?\s*$/.exec(line);
+      kept.push(bare ? `${bare[1]}.claude/*` : line);
+    }
+  }
+  while (kept.length && kept[kept.length - 1].trim() === '') kept.pop();
+  const block = ignoreBlockLines(mountedPaths).join('\n');
+  const after = (kept.length ? `${kept.join('\n')}\n\n` : '') + `${block}\n`;
+  if (after === before) return false;
+  writeAtomic(file, after);
+  return true;
+}
+
+// Records what is mounted, beside the folder's self-ignoring `*` .gitignore.
+function recordMount(projectDir, record) {
+  const dir = join(projectDir, '.claude', 'state');
+  mkdirSync(dir, { recursive: true });
+  if (!existsSync(join(dir, '.gitignore'))) writeFileSync(join(dir, '.gitignore'), '*\n');
+  const body = { ...record, mountedAt: new Date().toISOString() };
+  writeAtomic(join(dir, 'mount.json'), `${JSON.stringify(body, null, 2)}\n`);
+}
+
+function mountSettings(marker) {
+  const mount = (marker && marker.mount) || {};
+  return {
+    origin: String(mount.origin || DEFAULT_ORIGIN).replace(/\/+$/, ''),
+    track: mount.track === 'pinned' ? 'pinned' : 'latest',
+  };
+}
+
+// Mounts the pinned version unless the mount record already names it.
+async function mountHarness({ projectDir, cacheDir = cacheRoot(), fetchImpl = globalThis.fetch, timeoutMs = 5000, force = false }) {
+  const marker = readJsonFile(join(projectDir, '.claude', 'harness.json'));
+  if (!marker || !marker.harness || !marker.version) return { status: 'unmarked' };
+  const { origin } = mountSettings(marker);
+  const slug = marker.harness;
+  const version = marker.version;
+  const prior = readJsonFile(join(projectDir, '.claude', 'state', 'mount.json'));
+  if (!force && prior && prior.version === version) return { status: 'current', slug, version, digest: prior.digest };
+  let resolved;
+  try {
+    resolved = await resolveManifest({ origin, slug, version, cacheDir, fetchImpl, timeoutMs });
+  } catch (error) {
+    return { status: 'unavailable', slug, version, origin, reason: error.message };
+  }
+  const { manifest, source } = resolved;
+  const result = await mountFromManifest({
+    projectDir,
+    manifest,
+    origin,
+    cacheDir,
+    fetchImpl,
+    timeoutMs,
+    priorOwned: prior && prior.owned,
+  });
+  writeIgnoreBlock(projectDir, result.mountedPaths);
+  if (result.failed.length === 0) {
+    recordMount(projectDir, { version, digest: manifest.digest || null, owned: manifest.owned || null });
+  }
+  return { status: result.failed.length ? 'partial' : 'mounted', slug, version, source, ...result };
+}
+
+async function readLatest({ origin, slug, fetchImpl, timeoutMs }) {
+  return JSON.parse((await fetchBytes(`${origin}/harness/${slug}/latest.json`, fetchImpl, timeoutMs)).toString('utf8'));
+}
+
+// Stages a version into the cache, the manifest verified against the pointer and written last.
+async function stageVersion({ origin, slug, latest, cacheDir, fetchImpl, timeoutMs }) {
+  const bytes = await fetchBytes(`${origin}/${latest.manifest}`, fetchImpl, timeoutMs);
+  if (sha256Of(bytes) !== latest.manifestSha256) {
+    throw new Error(`the ${slug} ${latest.version} manifest does not match latest.json's manifestSha256 — nothing staged`);
+  }
+  const manifest = JSON.parse(bytes.toString('utf8'));
+  await eachLimited(mountedEntries(manifest), (entry) => readObject({ origin, entry, cacheDir, fetchImpl, timeoutMs }));
+  writeAtomic(join(cacheDir, slug, latest.version, 'manifest.json'), bytes);
+  return manifest;
+}
+
+// Asks latest.json for a newer version; stages it, and on track latest moves the pin.
+async function checkForUpdate({ projectDir, cacheDir = cacheRoot(), fetchImpl = globalThis.fetch, timeoutMs = 2000 }) {
+  const markerFile = join(projectDir, '.claude', 'harness.json');
+  const marker = readJsonFile(markerFile);
+  if (!marker || !marker.harness || !marker.version) return { status: 'unmarked' };
+  const { origin, track } = mountSettings(marker);
+  const slug = marker.harness;
+  let latest;
+  try {
+    latest = await readLatest({ origin, slug, fetchImpl, timeoutMs });
+  } catch (error) {
+    return { status: 'unreachable', reason: error.message };
+  }
+  if (!latest || !latest.version || compareVersions(latest.version, marker.version) <= 0) return { status: 'current' };
+  if (!existsSync(join(cacheDir, slug, latest.version, 'manifest.json'))) {
+    try {
+      await stageVersion({ origin, slug, latest, cacheDir, fetchImpl, timeoutMs: Math.max(timeoutMs, 5000) });
+    } catch (error) {
+      return { status: 'refused', reason: error.message, notice: `Harness update not staged: ${error.message}` };
+    }
+  }
+  const mounted = marker.version;
+  if (track === 'latest') writeAtomic(markerFile, `${JSON.stringify({ ...marker, version: latest.version }, null, 2)}\n`);
+  const tail = track === 'pinned' ? ' (track: pinned — bump `version` in .claude/harness.json to take it)' : '';
+  return {
+    status: 'staged',
+    from: mounted,
+    to: latest.version,
+    track,
+    notice: `Harness ${slug} ${latest.version} is ready (mounted ${mounted}); restart the session to run on it${tail}`,
+  };
+}
+// --- shared mount core: end ---
+
+// The manifest describing one version prefix: every planned file keyed under
+// `harness/<slug>/<version>/`, with its sha256, byte size, and whether the mount or the contract owns it.
+export function buildManifest(files, { slug, version, digest, placementVersion, owned }) {
+  const prefix = `harness/${slug}/${version}/`;
+  const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const entries = sorted.map((file) => ({
+    path: file.path,
+    key: prefix + file.path,
+    sha256: sha256Of(file.content),
+    byteSize: Buffer.byteLength(file.content),
+    policy: isMountedPath(file.path) ? 'mount' : 'contract',
+    ...(CAPABILITY_GATES[file.path] ? { requires: CAPABILITY_GATES[file.path] } : {}),
+  }));
+  const fingerprint = createHash('sha256');
+  for (const file of sorted) fingerprint.update(`${file.path}:${sha256Of(file.content)}\n`);
+  return {
+    slug,
+    version,
+    harnessVersion: version,
+    placementVersion,
+    digest,
+    fingerprint: fingerprint.digest('hex').slice(0, 12),
+    prefix,
+    fileCount: entries.length,
+    byteSize: entries.reduce((total, entry) => total + entry.byteSize, 0),
+    ...(owned ? { owned } : {}),
+    files: entries,
+  };
+}
+
+// Seeds the machine cache from a planned file list, so a later session mounts this version offline.
+export function warmCacheFromPlan({ files, manifest, cacheDir = cacheRoot() }) {
+  for (const file of files) {
+    if (!isMountedPath(file.path)) continue;
+    const object = join(cacheDir, 'objects', sha256Of(file.content));
+    if (!existsSync(object)) writeAtomic(object, file.content);
+  }
+  const manifestFile = join(cacheDir, manifest.slug, manifest.version, 'manifest.json');
+  if (!existsSync(manifestFile)) writeAtomic(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+// Whether the origin serves this version's manifest: 'published', 'unpublished', or 'unreachable'.
+export async function probeOrigin({ origin, slug, version, fetchImpl = globalThis.fetch, timeoutMs = 3000 }) {
+  try {
+    const response = await fetchImpl(`${origin}/harness/${slug}/${version}/manifest.json`, {
+      method: 'HEAD',
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return response.ok ? 'published' : 'unpublished';
+  } catch {
+    return 'unreachable';
+  }
+}
+
+export {
+  DEFAULT_ORIGIN,
+  MOUNT_BLOCK_START,
+  MOUNT_BLOCK_END,
+  sha256Of,
+  cacheRoot,
+  isMountedPath,
+  hasWorkerConfig,
+  compareVersions,
+  mountSettings,
+  resolveManifest,
+  readObject,
+  mountFromManifest,
+  ignoreBlockLines,
+  writeIgnoreBlock,
+  recordMount,
+  mountHarness,
+  readLatest,
+  stageVersion,
+  checkForUpdate,
+};