@nurix/etna 0.20.27 → 0.20.28

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,
+};

package/lib/install/plan.mjs

@@ -21,11 +21,13 @@
 //           project's living copy, never refreshed and never pruned.
 //   merge — folded into whatever the project already has, key by key. Only `.claude/settings.json`,
 //           which carries the user's own hooks and permissions beside the harness's.
+//   mount — the gitignored harness (`isMountedPath`), written here and at session start by `mount.mjs`.
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { buildCodexAdapter } from '../codex/agents-md.mjs';
 import { toCodexCommand } from '../codex/hooks.mjs';
+import { isMountedPath, hasWorkerConfig, DEFAULT_ORIGIN } from './mount.mjs';
 
 // Subfolders bundled inside each harness payload that map 1:1 onto <project>/.claude/<name>/.
 // Order matches Claude Code's own folder layout. hooks/ carries the hook scripts + lib/ (and
@@ -166,30 +168,7 @@ function codexHooks(bundleDir) {
 const CAPABILITY_RULES = { 'cloudflare.md': targetHasWorkerConfig };
 
 function targetHasWorkerConfig(targetDir) {
-  const names = ['wrangler.jsonc', 'wrangler.toml'];
-  if (names.some((n) => existsSync(join(targetDir, n)))) return true;
-  let entries = [];
-  try {
-    entries = readdirSync(targetDir, { withFileTypes: true });
-  } catch {
-    return false;
-  }
-  for (const e of entries) {
-    if (!e.isDirectory() || e.name === 'node_modules' || e.name.startsWith('.')) continue;
-    if (names.some((n) => existsSync(join(targetDir, e.name, n)))) return true;
-    // one more level: packages/*/wrangler.jsonc — the common monorepo shape
-    let sub = [];
-    try {
-      sub = readdirSync(join(targetDir, e.name), { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const s of sub) {
-      if (!s.isDirectory() || s.name === 'node_modules' || s.name.startsWith('.')) continue;
-      if (names.some((n) => existsSync(join(targetDir, e.name, s.name, n)))) return true;
-    }
-  }
-  return false;
+  return hasWorkerConfig(targetDir);
 }
 
 // A rule the target's capabilities exclude. No targetDir (payload verification, byte-identity
@@ -209,19 +188,32 @@ function ruleExcluded(sub, rel, targetDir) {
 //
 // Read from the target, never from the bundle. An absent or unreadable marker returns nothing and
 // the manifest default stands.
+// `mount.origin` and `mount.track` are consumer-owned the same way.
 function consumerOwnedMarkerKeys(targetDir) {
   if (!targetDir) return {};
   try {
     const prior = JSON.parse(readFileSync(join(targetDir, '.claude', 'harness.json'), 'utf8'));
-    return typeof prior.docsRoot === 'string' && prior.docsRoot.trim()
-      ? { docsRoot: prior.docsRoot.trim() }
-      : {};
+    const keys = {};
+    if (typeof prior.docsRoot === 'string' && prior.docsRoot.trim()) keys.docsRoot = prior.docsRoot.trim();
+    const mount = prior.mount && typeof prior.mount === 'object' ? prior.mount : {};
+    if (typeof mount.origin === 'string' && mount.origin.trim()) keys.origin = mount.origin.trim();
+    if (mount.track === 'latest' || mount.track === 'pinned') keys.track = mount.track;
+    return keys;
   } catch (e) {
     return {};
   }
 }
 
-export function planHarnessFiles(bundleDir, targetDir = null) {
+// The marker's `mount` block: the CLI's flags, else the consumer's value, else the bundle's, else the defaults.
+function markerMount(meta, prior, override = {}) {
+  const bundled = meta.mount && typeof meta.mount === 'object' ? meta.mount : {};
+  return {
+    origin: override.origin || prior.origin || bundled.origin || DEFAULT_ORIGIN,
+    track: override.track || prior.track || bundled.track || 'latest',
+  };
+}
+
+export function planHarnessFiles(bundleDir, targetDir = null, options = {}) {
   const claudeMdPath = join(bundleDir, 'CLAUDE.md');
   if (!existsSync(claudeMdPath)) {
     throw new Error(`Bundled CLAUDE.md missing at ${claudeMdPath}. Rebuild package data.`);
@@ -300,9 +292,11 @@ export function planHarnessFiles(bundleDir, targetDir = null) {
   const markerPath = join(bundleDir, 'harness.json');
   const meta = existsSync(markerPath) ? JSON.parse(readFileSync(markerPath, 'utf8')) : {};
   if (existsSync(markerPath)) {
+    const { origin, track, ...prior } = consumerOwnedMarkerKeys(targetDir);
+    const mount = markerMount(meta, { origin, track }, options.mount);
     files.push({
       path: '.claude/harness.json',
-      content: asJson({ ...meta, ...consumerOwnedMarkerKeys(targetDir), owned }),
+      content: asJson({ ...meta, ...prior, mount, owned }),
       policy: 'own',
     });
   }
@@ -318,6 +312,7 @@ export function planHarnessFiles(bundleDir, targetDir = null) {
   // Sorted so the plan is byte-stable across machines — readdir order is not guaranteed, and an
   // unstable order would make two identical builds look different to anything comparing them.
   files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  for (const file of files) if (file.policy === 'own' && isMountedPath(file.path)) file.policy = 'mount';
 
   const seen = new Set();
   for (const file of files) {

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@nurix/etna",
-  "version": "0.20.27",
-  "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
+  "version": "0.20.28",
+  "description": "Bootstrap a project with a Nurix harness — writes the committed contract (CLAUDE.md, AGENTS.md, .claude/harness.json, settings.json, the mount hook) and mounts the harness itself, gitignored, from a bundled payload; sessions keep it current from the CDN.",
   "type": "module",
   "bin": {
     "etna": "bin/etna.js"
   },
+  "exports": {
+    "./mount": "./lib/install/mount.mjs"
+  },
   "dependencies": {
     "@clack/prompts": "^0.11.0"
   },
@@ -43,5 +46,5 @@
     "agent",
     "plugin"
   ],
-  "etnaFingerprint": "aa072fd57bad"
+  "etnaFingerprint": "47047f5258d8"
 }