@nurix/nustack 0.23.11 → 0.23.13

package/dist/vendor/harness/mount/cache.js

@@ -0,0 +1,65 @@
+// packages/harness/src/mount/cache.ts - The machine's digest-keyed harness cache: `<cacheDir>/<digest>/files/<prefixed
+// path>` plus `<cacheDir>/<digest>/manifest.json`, written last as the completeness mark. Every read is verified;
+// a folder that fails is evicted. docs/architecture/systems/harness-records.md speaks for it (Offline mount).
+import { homedir } from 'node:os';
+import { readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { readBytes, writeAtomic } from './files.js';
+export const HARNESS_CACHE_DIR_ENV = 'NUSTACK_HARNESS_CACHE_DIR';
+const DIGEST_NAME = /^[0-9a-f]{64}$/;
+/** The machine cache every repository shares: NUSTACK_HARNESS_CACHE_DIR, else ~/.nustack/cache/harness. The only reader of the variable. */
+export function defaultHarnessCacheDir(env = process.env) {
+    return env[HARNESS_CACHE_DIR_ENV]?.trim() || join(homedir(), '.nustack', 'cache', 'harness');
+}
+export const cacheFolder = (cacheDir, digest) => join(cacheDir, digest);
+const manifestFile = (cacheDir, digest) => join(cacheFolder(cacheDir, digest), 'manifest.json');
+const objectFile = (cacheDir, digest, entry) => join(cacheFolder(cacheDir, digest), 'files', ...entry.path.split('/'));
+/** The folder's manifest, or null when the folder is half-written (no manifest) or the file does not parse. */
+export function readCachedManifest(cacheDir, digest) {
+    const bytes = readBytes(manifestFile(cacheDir, digest));
+    if (!bytes)
+        return null;
+    try {
+        const parsed = JSON.parse(bytes.toString('utf8'));
+        return parsed && typeof parsed === 'object' && Array.isArray(parsed.files) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A cached object's bytes, unverified; null when the folder lacks it. */
+export const readCachedObject = (cacheDir, digest, entry) => readBytes(objectFile(cacheDir, digest, entry));
+export function writeCachedObject(cacheDir, digest, entry, bytes) {
+    writeAtomic(objectFile(cacheDir, digest, entry), bytes);
+}
+/** Writes the completeness mark last, keeping the first `cachedAt` and the union of cached runtimes. */
+export function writeCachedManifest(cacheDir, manifest, runtime) {
+    const prior = readCachedManifest(cacheDir, manifest.digest);
+    const cachedRuntimes = [...new Set([...(prior?.cachedRuntimes ?? []), runtime])].sort();
+    const body = { ...manifest, cachedAt: prior?.cachedAt ?? new Date().toISOString(), cachedRuntimes };
+    writeAtomic(manifestFile(cacheDir, manifest.digest), `${JSON.stringify(body, null, 2)}\n`);
+}
+export function evictCacheFolder(cacheDir, digest) {
+    rmSync(cacheFolder(cacheDir, digest), { recursive: true, force: true });
+}
+/** The newest cached version for a project: 64-hex folders holding a complete manifest of that project, latest cachedAt. */
+export function newestCachedDigest(cacheDir, projectId) {
+    let names;
+    try {
+        names = readdirSync(cacheDir);
+    }
+    catch {
+        return null;
+    }
+    let best = null;
+    for (const name of names) {
+        if (!DIGEST_NAME.test(name))
+            continue;
+        const manifest = readCachedManifest(cacheDir, name);
+        if (!manifest || manifest.projectId !== projectId || typeof manifest.cachedAt !== 'string')
+            continue;
+        if (!best || manifest.cachedAt > best.cachedAt)
+            best = { digest: name, semver: String(manifest.semver ?? ''), cachedAt: manifest.cachedAt };
+    }
+    return best ? { digest: best.digest, semver: best.semver } : null;
+}

package/dist/vendor/harness/mount/exclude.js

@@ -0,0 +1,77 @@
+// packages/harness/src/mount/exclude.ts - Keeps the mounted harness out of git without editing a tracked file: the
+// managed block in the repository's info/exclude (the git directory followed through a worktree's gitdir and
+// commondir), and the one git call that tells a tracked merge target from an untracked one.
+// docs/architecture/systems/harness-records.md speaks for it (Harness mount).
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { writeAtomic } from './files.js';
+export const MOUNT_EXCLUDE_START = '# nustack:mount:start';
+export const MOUNT_EXCLUDE_END = '# nustack:mount:end';
+/** The repository's git directory and its common directory (the same folder outside a worktree); null outside git. */
+export function resolveGitDirs(root) {
+    const dotGit = join(root, '.git');
+    let gitDir;
+    try {
+        if (statSync(dotGit).isDirectory())
+            gitDir = dotGit;
+        else {
+            const pointer = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGit, 'utf8'));
+            if (!pointer)
+                return null;
+            gitDir = resolve(root, pointer[1].trim());
+        }
+    }
+    catch {
+        return null;
+    }
+    let commonDir = gitDir;
+    try {
+        const common = readFileSync(join(gitDir, 'commondir'), 'utf8').trim();
+        if (common)
+            commonDir = isAbsolute(common) ? common : resolve(gitDir, common);
+    }
+    catch {
+        /* no commondir: not a linked worktree */
+    }
+    return { gitDir, commonDir };
+}
+/** The block's lines: a folder per skill or hook library, a file per agent, rule or merge target. */
+export function excludeBlockLines(paths) {
+    const names = new Set();
+    for (const path of paths) {
+        const parts = path.split('/');
+        names.add(parts.length > 3 ? `${parts.slice(0, 3).join('/')}/` : path);
+    }
+    return [MOUNT_EXCLUDE_START, '# Managed by nustack: the mounted harness, rewritten on every mount. Edit outside this block.', ...[...names].sort(), MOUNT_EXCLUDE_END];
+}
+/** Rewrites the managed block in place (appended when absent), leaving every line outside it untouched. False outside git. */
+export function writeExcludeBlock(root, paths) {
+    const dirs = resolveGitDirs(root);
+    if (!dirs)
+        return false;
+    const file = join(dirs.commonDir, 'info', 'exclude');
+    const before = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    const lines = before === '' ? [] : before.replace(/\n$/, '').split('\n');
+    const start = lines.findIndex((line) => line.trim() === MOUNT_EXCLUDE_START);
+    const end = start >= 0 ? lines.findIndex((line, index) => index > start && line.trim() === MOUNT_EXCLUDE_END) : -1;
+    const block = excludeBlockLines(paths);
+    const next = start >= 0 && end > start ? [...lines.slice(0, start), ...block, ...lines.slice(end + 1)] : [...lines, ...block];
+    const after = `${next.join('\n')}\n`;
+    if (after === before)
+        return true;
+    writeAtomic(file, after);
+    return true;
+}
+/** The merge targets git tracks, by one `git ls-files` call; a failed call counts every target as tracked. */
+export function trackedMergeTargets(root, targets) {
+    if (targets.length === 0)
+        return new Set();
+    try {
+        const out = execFileSync('git', ['ls-files', '-z', '--', ...targets], { cwd: root, encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'] });
+        return new Set(out.split('\0').filter(Boolean));
+    }
+    catch {
+        return new Set(targets);
+    }
+}

package/dist/vendor/harness/mount/files.js

@@ -0,0 +1,38 @@
+// packages/harness/src/mount/files.ts - The mount's filesystem floor: atomic writes, byte reads and hashes, and the
+// removal of folders a prune empties. docs/architecture/systems/harness-records.md speaks for it (Harness mount).
+import { createHash } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+export const sha256Of = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export function readBytes(file) {
+    try {
+        return readFileSync(file);
+    }
+    catch {
+        return null;
+    }
+}
+let sequence = 0;
+/** Temp file then rename, so a concurrent reader sees the old file or the new one, never a torn one. */
+export function writeAtomic(file, bytes) {
+    mkdirSync(dirname(file), { recursive: true });
+    sequence += 1;
+    const temp = join(dirname(file), `.${basename(file)}.mount-${process.pid}-${sequence}`);
+    writeFileSync(temp, bytes);
+    renameSync(temp, file);
+}
+/** Removes the now-empty folders above a deleted repository path, never a top-level folder or its first child. */
+export function removeEmptyParents(root, relPath) {
+    let dir = dirname(relPath);
+    while (dir !== '.' && dir.split('/').length > 2) {
+        try {
+            if (readdirSync(join(root, dir)).length > 0)
+                return;
+            rmdirSync(join(root, dir));
+        }
+        catch {
+            return;
+        }
+        dir = dirname(dir);
+    }
+}

package/dist/vendor/harness/mount/index.js

@@ -0,0 +1,352 @@
+// packages/harness/src/mount/index.ts - Mounts one runtime's half of a harness version into a repository: the digest
+// verified over the whole manifest, every object verified (fetched or cached) before the first write, writes deepest
+// path first, contract and seed files kept when a person owns them, merge targets folded, the unmodified files a
+// version drops pruned, the mounted paths kept out of git, and the mount record written by its one writer.
+// Ported from etna packages/cli/lib/install/mount.mjs and packages/cli/src/lib/harness/mount.ts.
+// docs/architecture/systems/harness-records.md speaks for it (Harness mount).
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DOCS_ROOT_TOKEN, INSTRUCTION_FILE_OF, isRuntime, MERGE_TARGET_OF, splitRuntimePath } from '../assemble/runtimes.js';
+import { mergeClaudeSettings, mergeCodexHooks, mergeMcpServers } from '../assemble/settingsMerge.js';
+import { contentDigest } from '../digest/index.js';
+import { depthOf, isSafeRelativePath } from '../lib/paths.js';
+import { resolveDocsRoot } from '../rules/docsRoot.js';
+import { defaultHarnessCacheDir, evictCacheFolder, newestCachedDigest, readCachedManifest, readCachedObject, writeCachedManifest, writeCachedObject, } from './cache.js';
+import { trackedMergeTargets, writeExcludeBlock } from './exclude.js';
+import { readBytes, removeEmptyParents, sha256Of, writeAtomic } from './files.js';
+export { FINDING_CODES } from '../lib/findings.js';
+export { defaultHarnessCacheDir, newestCachedDigest, HARNESS_CACHE_DIR_ENV } from './cache.js';
+export { MOUNT_EXCLUDE_START, MOUNT_EXCLUDE_END, resolveGitDirs, excludeBlockLines } from './exclude.js';
+export const MOUNT_RECORD_PATH = '.claude/state/mount.json';
+export const NO_ROUTE_LINE = 'harness not mounted: no route to NuStack and no cached version';
+const SHA256 = /^[0-9a-f]{64}$/;
+const FETCH_CONCURRENCY = 8;
+const MERGE_OF = { 'claude-settings': mergeClaudeSettings, 'codex-hooks': mergeCodexHooks, 'mcp-servers': mergeMcpServers };
+/** The mount record, or null when none parses; an older record parses as one with no `runtimes`. */
+export function readMountRecord(root) {
+    const bytes = readBytes(join(root, MOUNT_RECORD_PATH));
+    if (!bytes)
+        return null;
+    try {
+        const parsed = JSON.parse(bytes.toString('utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A repository path the mount may write: safe, outside `.git` and outside the mount's own state folder. */
+function isWritablePath(path) {
+    return isSafeRelativePath(path) && !path.split('/').includes('.git') && !path.startsWith('.claude/state/');
+}
+/** The first reason the manifest must be refused, before anything is fetched or written. */
+function manifestProblem(manifest, expectedDigest) {
+    if (!manifest || typeof manifest !== 'object' || manifest.schemaVersion !== 1)
+        return { code: 'mount.schema_unknown', message: `schemaVersion ${String(manifest?.schemaVersion)} is not 1` };
+    if (!Array.isArray(manifest.files))
+        return { code: 'mount.schema_unknown', message: 'the manifest lists no files' };
+    for (const entry of manifest.files) {
+        if (typeof entry?.sha256 !== 'string' || !SHA256.test(entry.sha256))
+            return { code: 'mount.bad_sha256', message: `${String(entry?.path)}: sha256 is not 64 lowercase hex`, path: String(entry?.path) };
+        const split = typeof entry.path === 'string' && isSafeRelativePath(entry.path) ? splitRuntimePath(entry.path) : null;
+        if (!split)
+            return { code: 'mount.unsafe_path', message: `${String(entry.path)}: not a safe <runtime>/<path>`, path: String(entry.path) };
+        const placed = entry.policy === 'seed' ? (split.path.startsWith(`${DOCS_ROOT_TOKEN}/`) ? split.path.slice(DOCS_ROOT_TOKEN.length + 1) : '') : split.path;
+        if (!isWritablePath(placed) || (entry.policy !== 'seed' && placed.startsWith('@')))
+            return { code: 'mount.unsafe_path', message: `${entry.path}: unsafe repository path`, path: entry.path };
+        if (entry.policy === 'contract' && split.path !== INSTRUCTION_FILE_OF[split.runtime])
+            return { code: 'mount.contract_outside', message: `${entry.path}: a contract entry outside ${split.runtime}'s instruction file`, path: entry.path };
+        if (entry.policy !== 'mount' && entry.policy !== 'contract' && entry.policy !== 'seed')
+            return { code: 'mount.schema_unknown', message: `${entry.path}: unknown policy ${String(entry.policy)}`, path: entry.path };
+        if (entry.merge !== undefined && (entry.policy !== 'mount' || MERGE_TARGET_OF[entry.merge] !== split.path))
+            return { code: 'mount.unsafe_path', message: `${entry.path}: merge ${String(entry.merge)} at the wrong path`, path: entry.path };
+    }
+    if (contentDigest(manifest.files) !== manifest.digest)
+        return { code: 'mount.digest_mismatch', message: 'the manifest digest does not match its files' };
+    if (expectedDigest && manifest.digest !== expectedDigest)
+        return { code: 'mount.expected_digest_mismatch', message: `the manifest digest ${manifest.digest} is not the expected ${expectedDigest}` };
+    return null;
+}
+/** Runs task over items with at most `limit` in flight. */
+async function eachLimited(items, limit, 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(limit, items.length) }, worker));
+}
+export async function mountVersion(options) {
+    const runtime = (options.runtime ?? 'claude-code');
+    const root = options.root;
+    const cacheDir = options.cacheDir ?? defaultHarnessCacheDir();
+    const writeContract = options.writeContract ?? 'when-unmodified';
+    const result = { status: 'unavailable', digest: null, semver: null, runtime, source: null, written: [], kept: [], removed: [], contractDrift: [], findings: [], line: '' };
+    const finish = (status, line, finding) => {
+        if (finding)
+            result.findings.push({ code: finding.code, message: finding.message, ...(finding.path ? { path: finding.path } : {}) });
+        return { ...result, status, line };
+    };
+    const refuse = (finding) => finish('refused', `harness not mounted: ${finding.message}`, finding);
+    if (!isRuntime(runtime))
+        return refuse({ code: 'mount.runtime_unknown', message: `unknown runtime ${String(runtime)}` });
+    // The manifest: the caller's, verified; else the cache entry the expected digest or the project's newest names.
+    let manifest;
+    let source;
+    if (options.manifest) {
+        const problem = manifestProblem(options.manifest, options.expectedDigest);
+        if (problem)
+            return refuse(problem);
+        manifest = options.manifest;
+        source = 'network';
+    }
+    else {
+        const projectId = options.projectId;
+        let digest = options.expectedDigest;
+        if (!digest) {
+            if (!projectId)
+                return refuse({ code: 'mount.project_unknown', message: 'no manifest, no expected digest and no projectId to find a cached version by' });
+            digest = newestCachedDigest(cacheDir, projectId)?.digest ?? null;
+        }
+        const cached = digest ? readCachedManifest(cacheDir, digest) : null;
+        if (!digest || !cached)
+            return finish('unavailable', NO_ROUTE_LINE, { code: 'mount.no_route', message: NO_ROUTE_LINE });
+        const problem = manifestProblem(cached, digest);
+        if (problem || cached.digest !== digest) {
+            evictCacheFolder(cacheDir, digest);
+            return refuse({ code: 'mount.cache_corrupt', message: `the cached version ${digest} failed verification (${problem?.message ?? 'its digest is not its folder'}) and was evicted` });
+        }
+        manifest = cached;
+        source = 'cache';
+    }
+    result.digest = manifest.digest;
+    result.semver = manifest.semver;
+    result.source = source;
+    const planned = manifest.files.flatMap((entry) => {
+        const split = splitRuntimePath(entry.path);
+        return split && split.runtime === runtime ? [{ entry, path: split.path }] : [];
+    });
+    const record = readMountRecord(root) ?? {};
+    const prior = record.runtimes?.[runtime];
+    // Current: the record names this digest for this runtime and every recorded file still matches.
+    if (prior && prior.digest === manifest.digest && Array.isArray(prior.files) && prior.files.every((file) => sha256Of(readBytes(join(root, file.path)) ?? '\0missing') === file.sha256)) {
+        result.kept = prior.files.map((file) => file.path);
+        return finish('current', `harness current: ${manifest.semver} (${manifest.digest.slice(0, 12)}) for ${runtime}`);
+    }
+    const docsRoot = resolveDocsRoot({ read: (path) => readBytes(join(root, path))?.toString('utf8') ?? null });
+    const placedPath = (item) => (item.entry.policy === 'seed' ? `${docsRoot}/${item.path.slice(DOCS_ROOT_TOKEN.length + 1)}` : item.path);
+    const onDisk = new Map();
+    const disk = (path) => {
+        if (!onDisk.has(path))
+            onDisk.set(path, readBytes(join(root, path)));
+        return onDisk.get(path);
+    };
+    const priorSha = new Map((prior?.files ?? []).map((file) => [file.path, file.sha256]));
+    // Decide what each entry needs before fetching anything: only the bytes a write uses are fetched.
+    const needed = [];
+    const unchanged = [];
+    for (const item of planned) {
+        const target = placedPath(item);
+        const held = disk(target);
+        const heldSha = held ? sha256Of(held) : null;
+        if (item.entry.merge)
+            needed.push(item);
+        else if (item.entry.policy === 'mount') {
+            if (heldSha === item.entry.sha256)
+                unchanged.push(target);
+            else
+                needed.push(item);
+        }
+        else if (item.entry.policy === 'seed') {
+            if (held)
+                result.kept.push(target);
+            else if (writeContract !== 'never')
+                needed.push(item);
+        }
+        else if (heldSha === item.entry.sha256)
+            unchanged.push(target);
+        else if (writeContract === 'never') {
+            if (held)
+                result.kept.push(target);
+        }
+        else if (!held || writeContract === 'always' || priorSha.get(target) === heldSha)
+            needed.push(item);
+        else {
+            result.kept.push(target);
+            result.contractDrift.push(target);
+            result.findings.push({ code: 'mount.contract_edited', message: `${target} differs from what the last mount wrote; left as edited`, path: target });
+        }
+    }
+    // Every needed object, from the cache (verified) or fetched (verified), before the first write.
+    const bytesOf = new Map();
+    const fetched = [];
+    for (const item of needed) {
+        const cached = readCachedObject(cacheDir, manifest.digest, item.entry);
+        if (cached && sha256Of(cached) === item.entry.sha256)
+            bytesOf.set(item.entry.path, cached);
+        else if (source === 'cache') {
+            if (cached) {
+                evictCacheFolder(cacheDir, manifest.digest);
+                return refuse({ code: 'mount.cache_corrupt', message: `the cached ${item.entry.path} does not match its entry; the cached version was evicted`, path: item.entry.path });
+            }
+            return finish('unavailable', `harness not mounted: no route to NuStack and the cached version lacks ${item.entry.path}`, { code: 'mount.no_route', message: `the cached version lacks ${item.entry.path}`, path: item.entry.path });
+        }
+        else
+            fetched.push(item);
+    }
+    let failure = null;
+    await eachLimited(fetched, FETCH_CONCURRENCY, async (item) => {
+        if (failure)
+            return;
+        try {
+            const bytes = await options.fetchObject(item.entry);
+            if (sha256Of(bytes) !== item.entry.sha256)
+                failure ??= { code: 'mount.object_mismatch', message: `${item.entry.path}: the object does not match its sha256`, path: item.entry.path };
+            else
+                bytesOf.set(item.entry.path, bytes);
+        }
+        catch (error) {
+            failure ??= { code: 'mount.fetch_failed', message: `fetching ${item.entry.path} failed: ${error instanceof Error ? error.message : String(error)}`, path: item.entry.path };
+        }
+    });
+    if (failure) {
+        const found = failure;
+        return found.code === 'mount.fetch_failed' ? finish('unavailable', `harness not mounted: ${found.message}`, found) : refuse(found);
+    }
+    // The cache: fetched objects, then the manifest last as the completeness mark.
+    for (const item of fetched)
+        writeCachedObject(cacheDir, manifest.digest, item.entry, bytesOf.get(item.entry.path));
+    if (source === 'network')
+        writeCachedManifest(cacheDir, manifest, runtime);
+    // Merge targets: tracked ones are left alone; an unparsable one is left alone; the rest fold the fragment in.
+    const merges = needed.filter((item) => item.entry.merge);
+    const mergeTargets = [...new Set([...merges.map((item) => item.path), ...Object.keys(prior?.managed ?? {})])];
+    const tracked = trackedMergeTargets(root, mergeTargets);
+    const managed = {};
+    const createdMergeTargets = new Set((prior?.createdMergeTargets ?? []).filter((path) => existsSync(join(root, path))));
+    const mergeWrites = [];
+    for (const target of mergeTargets) {
+        const item = merges.find((candidate) => candidate.path === target);
+        const kind = (item?.entry.merge ?? Object.entries(MERGE_TARGET_OF).find(([, path]) => path === target)?.[0]);
+        if (!kind)
+            continue;
+        if (tracked.has(target)) {
+            result.findings.push({ code: 'mount.merge_target_tracked', message: `${target} is tracked by git; left untouched`, path: target });
+            continue;
+        }
+        const held = disk(target);
+        let existing = null;
+        if (held) {
+            try {
+                const parsed = JSON.parse(held.toString('utf8'));
+                if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                    throw new Error('not an object');
+                existing = parsed;
+            }
+            catch {
+                result.findings.push({ code: 'mount.merge_target_unparsable', message: `${target} does not parse as a JSON object; left untouched`, path: target });
+                continue;
+            }
+        }
+        let fragment = {};
+        if (item) {
+            try {
+                fragment = JSON.parse(Buffer.from(bytesOf.get(item.entry.path)).toString('utf8'));
+            }
+            catch {
+                return refuse({ code: 'mount.object_mismatch', message: `${item.entry.path}: the merge fragment is not JSON`, path: item.entry.path });
+            }
+        }
+        const merged = MERGE_OF[kind](existing, fragment, prior?.managed?.[target]);
+        if (Object.keys(merged.managed).length > 0)
+            managed[target] = merged.managed;
+        const content = `${JSON.stringify(merged.merged, null, 2)}\n`;
+        if (held && held.toString('utf8') === content)
+            continue;
+        if (!held) {
+            if (!item)
+                continue;
+            createdMergeTargets.add(target);
+        }
+        mergeWrites.push({ target, content });
+    }
+    // All writes, deepest path first, so a module lands before the file importing it.
+    const writes = needed.filter((item) => !item.entry.merge).map((item) => ({ target: placedPath(item), bytes: bytesOf.get(item.entry.path) }));
+    writes.sort((a, b) => depthOf(b.target) - depthOf(a.target) || (a.target < b.target ? -1 : a.target > b.target ? 1 : 0));
+    for (const write of writes) {
+        writeAtomic(join(root, write.target), write.bytes);
+        result.written.push(write.target);
+    }
+    for (const write of mergeWrites) {
+        writeAtomic(join(root, write.target), write.content);
+        result.written.push(write.target);
+    }
+    result.kept.push(...unchanged);
+    // What this runtime now holds: mount and contract files whose bytes equal their entry.
+    const files = [];
+    for (const item of planned) {
+        if (item.entry.merge || item.entry.policy === 'seed')
+            continue;
+        const target = placedPath(item);
+        const held = result.written.includes(target) ? item.entry.sha256 : sha256Of(disk(target) ?? '\0missing');
+        if (held === item.entry.sha256)
+            files.push({ path: target, sha256: item.entry.sha256, policy: item.entry.policy });
+    }
+    // Prune: a file the previous mount of this runtime recorded and this version omits, still unmodified, and no
+    // other runtime's record listing it.
+    const now = new Set(files.map((file) => file.path));
+    const otherRuntimes = Object.entries(record.runtimes ?? {}).filter(([name]) => name !== runtime);
+    const listedElsewhere = (path) => otherRuntimes.some(([, other]) => (other?.files ?? []).some((file) => file.path === path));
+    for (const old of prior?.files ?? []) {
+        if (old.policy !== 'mount' || now.has(old.path) || planned.some((item) => placedPath(item) === old.path))
+            continue;
+        const held = readBytes(join(root, old.path));
+        if (!held)
+            continue;
+        if (sha256Of(held) !== old.sha256) {
+            result.kept.push(old.path);
+            result.findings.push({ code: 'mount.kept_edited', message: `${old.path} was dropped by this version but edited since the last mount; left in place`, path: old.path });
+            continue;
+        }
+        if (listedElsewhere(old.path))
+            continue;
+        rmSync(join(root, old.path), { force: true });
+        removeEmptyParents(root, old.path);
+        result.removed.push(old.path);
+    }
+    // Out of git: every runtime's mounted files and the merge targets a mount created.
+    const runtimes = { ...(record.runtimes ?? {}) };
+    const mountedAt = new Date().toISOString();
+    runtimes[runtime] = {
+        digest: manifest.digest,
+        treeDigest: contentDigest(planned.filter((item) => !item.entry.merge && item.entry.policy !== 'seed').map((item) => ({ path: placedPath(item), sha256: item.entry.sha256 }))),
+        semver: manifest.semver,
+        source,
+        mountedAt,
+        files,
+        managed,
+        createdMergeTargets: [...createdMergeTargets].sort(),
+    };
+    const excluded = Object.values(runtimes).flatMap((entry) => [...(entry?.files ?? []).filter((file) => file.policy === 'mount').map((file) => file.path), ...(entry?.createdMergeTargets ?? [])]);
+    writeExcludeBlock(root, excluded);
+    // The record, by its one writer: unknown top-level keys kept, the caller's extras beside the owned keys.
+    const stateDir = join(root, '.claude', 'state');
+    mkdirSync(stateDir, { recursive: true });
+    if (!existsSync(join(stateDir, '.gitignore')))
+        writeFileSync(join(stateDir, '.gitignore'), '*\n');
+    const body = {
+        ...record,
+        ...(options.recordExtras ?? {}),
+        version: manifest.semver,
+        digest: manifest.digest,
+        mountedAt,
+        projectId: options.projectId ?? manifest.projectId,
+        source,
+        runtimes,
+    };
+    writeAtomic(join(root, MOUNT_RECORD_PATH), `${JSON.stringify(body, null, 2)}\n`);
+    return finish('mounted', `harness mounted: ${manifest.semver} (${manifest.digest.slice(0, 12)}) for ${runtime} from ${source}`);
+}