@nurix/nustack 0.23.11 → 0.23.13

package/dist/lib/harness/legacyMount.js

@@ -0,0 +1,231 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, rename, rm, rmdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { HarnessError, HARNESS_CODES } from "./codes.js";
+export const LEGACY_MOUNT_RECORD_PATH = ".claude/state/legacy-mount.json";
+export const LEGACY_EXCLUDE_START = "# etna:mount:start";
+export const LEGACY_EXCLUDE_END = "# etna:mount:end";
+const SHA256 = /^[0-9a-f]{64}$/;
+const REQUEST_TIMEOUT_MS = 15_000;
+const FETCH_CONCURRENCY = 8;
+const sha256Of = (bytes) => createHash("sha256").update(bytes).digest("hex");
+export function isMountedPath(file) {
+    if (file.policy)
+        return file.policy === "mount";
+    const contract = ["CLAUDE.md", "AGENTS.md", ".claude/harness.json", ".claude/settings.json", ".claude/hooks/mount.mjs", ".codex/hooks.json"];
+    if (contract.includes(file.path))
+        return false;
+    return file.path.startsWith(".claude/") || file.path.startsWith(".agents/") || file.path.startsWith(".codex/");
+}
+function isSafePath(file) {
+    return file !== "" && !path.isAbsolute(file) && !file.split(/[\\/]/).includes("..") && !file.split("/").includes(".git") && !file.startsWith(".claude/state/");
+}
+async function readIfPresent(file) {
+    try {
+        return await readFile(file);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeAtomic(target, bytes) {
+    await mkdir(path.dirname(target), { recursive: true });
+    const staging = `${target}.mount-${process.pid}`;
+    await writeFile(staging, bytes);
+    await rename(staging, target);
+}
+async function fetchBytes(url) {
+    const response = await globalThis.fetch(url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    if (!response.ok)
+        throw new Error(`${url} answered ${response.status}`);
+    return Buffer.from(await response.arrayBuffer());
+}
+function objectUrlOf(manifestUrl, key) {
+    return `${new URL(manifestUrl).origin}/${key.replace(/^\/+/, "")}`;
+}
+function excludePathOf(root) {
+    try {
+        const relative = execFileSync("git", ["rev-parse", "--git-path", "info/exclude"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        return path.isAbsolute(relative) ? relative : path.join(root, relative);
+    }
+    catch {
+        return null;
+    }
+}
+function withoutLegacyBlock(held) {
+    const start = held.indexOf(LEGACY_EXCLUDE_START);
+    const end = held.indexOf(LEGACY_EXCLUDE_END);
+    if (start < 0 || end <= start)
+        return held;
+    return held.slice(0, start) + held.slice(end + LEGACY_EXCLUDE_END.length).replace(/^\n/, "");
+}
+function ignoredNamesOf(files) {
+    const names = new Set([".claude/state/"]);
+    for (const file of files) {
+        const parts = file.path.split("/");
+        if (parts[0] === ".agents")
+            names.add(".agents/skills/");
+        else if (parts[0] === ".codex")
+            names.add(parts.length > 2 ? `.codex/${parts[1]}/` : `.codex/${parts[1]}`);
+        else if (parts.length > 3)
+            names.add(`${parts.slice(0, 3).join("/")}/`);
+        else
+            names.add(file.path);
+    }
+    return [...names].sort();
+}
+async function writeLegacyExcludeBlock(root, files) {
+    const excludePath = excludePathOf(root);
+    if (!excludePath)
+        return;
+    const outside = withoutLegacyBlock((await readIfPresent(excludePath))?.toString("utf8") ?? "");
+    const block = [LEGACY_EXCLUDE_START, ...ignoredNamesOf(files), LEGACY_EXCLUDE_END].join("\n");
+    await writeAtomic(excludePath, `${outside.replace(/\n*$/, outside ? "\n" : "")}${block}\n`);
+}
+export async function removeLegacyExcludeBlock(root) {
+    const excludePath = excludePathOf(root);
+    if (!excludePath)
+        return;
+    const held = (await readIfPresent(excludePath))?.toString("utf8");
+    if (held === undefined || !held.includes(LEGACY_EXCLUDE_START))
+        return;
+    await writeAtomic(excludePath, withoutLegacyBlock(held));
+}
+function parseLegacyRecord(raw) {
+    if (raw === null)
+        return null;
+    try {
+        const parsed = JSON.parse(raw.toString());
+        if (typeof parsed.version !== "string" || typeof parsed.digest !== "string")
+            return null;
+        return {
+            version: parsed.version,
+            digest: parsed.digest,
+            mountedAt: typeof parsed.mountedAt === "string" ? parsed.mountedAt : "",
+            source: "legacy",
+            origin: typeof parsed.origin === "string" ? parsed.origin : null,
+            legacyFiles: Array.isArray(parsed.legacyFiles)
+                ? parsed.legacyFiles.filter((file) => typeof file?.path === "string" && typeof file?.sha256 === "string")
+                : [],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function readLegacyMountRecord(root) {
+    return parseLegacyRecord(await readIfPresent(path.join(root, LEGACY_MOUNT_RECORD_PATH)));
+}
+export function readLegacyMountRecordSync(root) {
+    const file = path.join(root, LEGACY_MOUNT_RECORD_PATH);
+    if (!existsSync(file))
+        return null;
+    try {
+        return parseLegacyRecord(readFileSync(file));
+    }
+    catch {
+        return null;
+    }
+}
+export async function mountLegacyManifest(root, manifestUrl, origin) {
+    const manifestBytes = await fetchBytes(manifestUrl);
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestBytes.toString("utf8"));
+    }
+    catch {
+        throw new HarnessError(HARNESS_CODES.HARNESS_MOUNT_FAILED, `the manifest at ${manifestUrl} is not JSON`);
+    }
+    if (!manifest || !Array.isArray(manifest.files))
+        throw new HarnessError(HARNESS_CODES.HARNESS_MOUNT_FAILED, `the manifest at ${manifestUrl} lists no files`);
+    const mounted = manifest.files.filter(isMountedPath);
+    for (const file of mounted) {
+        if (typeof file.sha256 !== "string" || !SHA256.test(file.sha256)) {
+            throw new HarnessError(HARNESS_CODES.HARNESS_DIGEST_MISMATCH, `the manifest entry ${String(file.path)} carries no verifiable sha256; nothing was written`);
+        }
+        if (typeof file.path !== "string" || !isSafePath(file.path) || typeof file.key !== "string") {
+            throw new HarnessError(HARNESS_CODES.HARNESS_MOUNT_FAILED, `the manifest names an unsafe path: ${String(file.path)}`);
+        }
+    }
+    const toWrite = [];
+    const kept = [];
+    const needed = [];
+    for (const file of mounted) {
+        const held = await readIfPresent(path.join(root, file.path));
+        if (held && sha256Of(held) === file.sha256)
+            kept.push(file.path);
+        else
+            needed.push(file);
+    }
+    const fetched = new Map();
+    let next = 0;
+    const worker = async () => {
+        while (next < needed.length) {
+            const file = needed[next++];
+            const bytes = await fetchBytes(objectUrlOf(manifestUrl, file.key));
+            if (sha256Of(bytes) !== file.sha256) {
+                throw new HarnessError(HARNESS_CODES.HARNESS_DIGEST_MISMATCH, `the object for ${file.path} does not match its sha256; nothing was written`);
+            }
+            fetched.set(file, bytes);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(FETCH_CONCURRENCY, needed.length) }, worker));
+    for (const file of needed)
+        toWrite.push({ file, bytes: fetched.get(file) });
+    for (const { file, bytes } of toWrite)
+        await writeAtomic(path.join(root, file.path), bytes);
+    await writeLegacyExcludeBlock(root, mounted);
+    const stateDir = path.join(root, ".claude", "state");
+    await mkdir(stateDir, { recursive: true });
+    if (!(await readIfPresent(path.join(stateDir, ".gitignore"))))
+        await writeFile(path.join(stateDir, ".gitignore"), "*\n");
+    const record = {
+        version: String(manifest.version ?? ""),
+        digest: sha256Of(manifestBytes),
+        mountedAt: new Date().toISOString(),
+        source: "legacy",
+        origin,
+        legacyFiles: mounted.map((file) => ({ path: file.path, sha256: file.sha256 })),
+    };
+    await writeAtomic(path.join(root, LEGACY_MOUNT_RECORD_PATH), `${JSON.stringify(record, null, 2)}\n`);
+    return { version: record.version, digest: record.digest, written: toWrite.map((item) => item.file.path), kept };
+}
+export async function handOverLegacyMount(root, keptByVersion) {
+    const record = await readLegacyMountRecord(root);
+    if (!record)
+        return null;
+    const removed = [];
+    const editedKept = [];
+    for (const file of record.legacyFiles) {
+        if (keptByVersion.has(file.path) || !isSafePath(file.path))
+            continue;
+        const target = path.join(root, file.path);
+        const held = await readIfPresent(target);
+        if (!held)
+            continue;
+        if (sha256Of(held) !== file.sha256) {
+            editedKept.push(file.path);
+            continue;
+        }
+        await rm(target, { force: true });
+        await removeEmptyParents(root, path.dirname(file.path));
+        removed.push(file.path);
+    }
+    await removeLegacyExcludeBlock(root);
+    await rm(path.join(root, LEGACY_MOUNT_RECORD_PATH), { force: true });
+    return { removed, editedKept };
+}
+async function removeEmptyParents(root, relativeDir) {
+    let dir = relativeDir;
+    while (dir && dir !== "." && dir !== "/") {
+        try {
+            await rmdir(path.join(root, dir));
+        }
+        catch {
+            return;
+        }
+        dir = path.dirname(dir);
+    }
+}

package/dist/lib/harness/mount.js

@@ -1,155 +1,223 @@
-import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { ensureAccessToken } from "../auth_grant.js";
+import { getProject, resolveNuStackOrigin } from "../nustack_client.js";
+import { isOriginMismatch } from "../origin_guard.js";
+import { resolveProjectId } from "../project_context.js";
+import { readProjectContract } from "../project_contract.js";
+import { hasEtnaMountHook } from "../onboarding/session_hook.js";
+import { HarnessError, HARNESS_CODES } from "./codes.js";
+import { handOverLegacyMount, mountLegacyManifest, readLegacyMountRecord, readLegacyMountRecordSync } from "./legacyMount.js";
+import { loadHarness } from "./vendor.js";
+import { fetchVersionManifest, fetchVersionObject, resolveProjectVersion, VersionsRouteError } from "./versionsClient.js";
 export const MOUNT_STATE_PATH = ".claude/state/mount.json";
-const IGNORE_START = "# etna:mount:start";
-const IGNORE_END = "# etna:mount:end";
-const ETNA_MOUNT_SPECIFIER = "@nurix/etna/mount";
-const sha256Of = (bytes) => createHash("sha256").update(bytes).digest("hex");
-export function defaultCacheDir(env = process.env) {
-    return env.ETNA_CACHE_DIR?.trim() || path.join(homedir(), ".etna", "cache");
-}
-export function isMountedPath(file) {
-    if (file.policy)
-        return file.policy === "mount";
-    const contract = ["CLAUDE.md", "AGENTS.md", ".claude/harness.json", ".claude/settings.json", ".claude/hooks/mount.mjs", ".codex/hooks.json"];
-    if (contract.includes(file.path))
-        return false;
-    return file.path.startsWith(".claude/") || file.path.startsWith(".agents/") || file.path.startsWith(".codex/");
-}
-async function readIfPresent(file) {
-    try {
-        return await readFile(file);
-    }
-    catch {
+const DIGEST_REFUSALS = new Set(["mount.digest_mismatch", "mount.expected_digest_mismatch", "mount.object_mismatch", "mount.cache_corrupt", "mount.bad_sha256"]);
+function stateOf(record) {
+    if (!record || typeof record.version !== "string" || typeof record.digest !== "string")
         return null;
-    }
+    const source = record.source === "network" || record.source === "cache" || record.source === "legacy" ? record.source : null;
+    return {
+        version: record.version,
+        digest: record.digest,
+        mountedAt: typeof record.mountedAt === "string" ? record.mountedAt : "",
+        source,
+        origin: typeof record.origin === "string" ? record.origin : null,
+    };
 }
 export async function readMountState(root) {
-    return parseMountState(await readIfPresent(path.join(root, MOUNT_STATE_PATH)));
+    const { readMountRecord } = await loadHarness("mount");
+    return stateOf(readMountRecord(root)) ?? stateOf((await readLegacyMountRecord(root)));
 }
 export function readMountStateSync(root) {
+    const file = path.join(root, MOUNT_STATE_PATH);
+    let record = null;
+    if (existsSync(file)) {
+        try {
+            const parsed = JSON.parse(readFileSync(file, "utf8"));
+            record = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+        }
+        catch {
+            record = null;
+        }
+    }
+    return stateOf(record) ?? stateOf(readLegacyMountRecordSync(root));
+}
+function coded(code, message) {
+    return Object.assign(new Error(message), { code });
+}
+export async function readSummary(root, projectId, globals) {
+    let baseUrl;
     try {
-        return parseMountState(readFileSync(path.join(root, MOUNT_STATE_PATH)));
+        baseUrl = resolveNuStackOrigin(globals, root).url;
     }
-    catch {
-        return null;
+    catch (error) {
+        if (isOriginMismatch(error))
+            return { kind: "offline", reason: error.message, guardRefusal: error, baseUrl: null };
+        throw error;
     }
-}
-function parseMountState(raw) {
-    if (!raw)
-        return null;
+    let token;
     try {
-        const parsed = JSON.parse(raw.toString("utf8"));
-        if (typeof parsed.version !== "string" || typeof parsed.digest !== "string")
-            return null;
-        return { version: parsed.version, digest: parsed.digest, mountedAt: typeof parsed.mountedAt === "string" ? parsed.mountedAt : "", ...(typeof parsed.manifestUrl === "string" ? { manifestUrl: parsed.manifestUrl } : {}) };
+        token = await ensureAccessToken(baseUrl);
     }
-    catch {
-        return null;
+    catch (error) {
+        if (isOriginMismatch(error))
+            return { kind: "offline", reason: error.message, guardRefusal: error, baseUrl };
+        return { kind: "offline", reason: "this machine's sign-in could not be read", guardRefusal: null, baseUrl };
+    }
+    if (!token)
+        return { kind: "offline", reason: "this machine is not signed in", guardRefusal: null, baseUrl };
+    try {
+        const summary = await getProject(baseUrl, token.accessToken, projectId);
+        return { kind: "summary", summary, baseUrl, accessToken: token.accessToken };
+    }
+    catch (error) {
+        if (isOriginMismatch(error))
+            return { kind: "offline", reason: error.message, guardRefusal: error, baseUrl };
+        const code = error.code;
+        if (typeof code === "string" && code !== "UNEXPECTED" && code !== "SIGNED_OUT")
+            throw error;
+        return { kind: "offline", reason: `the Project summary could not be read (${error instanceof Error ? error.message : String(error)})`, guardRefusal: null, baseUrl };
     }
 }
-async function fetchBytes(fetchImpl, url) {
-    const response = await fetchImpl(url);
-    if (!response.ok)
-        throw new Error(`${url} answered ${response.status}`);
-    return Buffer.from(await response.arrayBuffer());
-}
-function objectUrlOf(manifestUrl, key) {
-    return `${new URL(manifestUrl).origin}/${key.replace(/^\/+/, "")}`;
+export function isProjectVersionSummary(summary) {
+    return Boolean(summary.harness?.digest || summary.harness?.versionManifestPath);
 }
-async function writeAtomic(target, bytes) {
-    await mkdir(path.dirname(target), { recursive: true });
-    const staging = `${target}.mount-${process.pid}`;
-    await writeFile(staging, bytes);
-    await rename(staging, target);
+export async function projectOf(root, flag, contractProjectId) {
+    if (flag?.trim())
+        return flag.trim();
+    if (contractProjectId)
+        return contractProjectId;
+    const resolved = await resolveProjectId(root, {});
+    if (!resolved.ok)
+        throw coded("PROJECT_CONTEXT_MISSING", resolved.message);
+    return resolved.projectId;
 }
-function ignoredNamesOf(files) {
-    const names = new Set([".claude/state/"]);
-    for (const file of files) {
-        const parts = file.path.split("/");
-        if (parts[0] === ".agents")
-            names.add(".agents/skills/");
-        else if (parts[0] === ".codex")
-            names.add(parts.length > 2 ? `.codex/${parts[1]}/` : `.codex/${parts[1]}`);
-        else if (parts.length > 3)
-            names.add(`${parts.slice(0, 3).join("/")}/`);
-        else
-            names.add(file.path);
+function outcomeOf(projectId, result, lines, offlineCode) {
+    if (result.status === "mounted" || result.status === "current") {
+        const kept = result.findings.filter((finding) => finding.code === "mount.kept_edited" || finding.code === "mount.contract_edited");
+        return {
+            projectId,
+            status: result.status,
+            source: result.source ?? "network",
+            version: result.semver,
+            digest: result.digest,
+            runtime: result.runtime,
+            written: result.written,
+            kept: result.kept,
+            removed: result.removed,
+            lines: [...lines, result.line, ...kept.map((finding) => finding.message)],
+        };
     }
-    return [...names].sort();
+    const finding = result.findings[0];
+    if (result.status === "refused" && finding && DIGEST_REFUSALS.has(finding.code))
+        throw new HarnessError(HARNESS_CODES.HARNESS_DIGEST_MISMATCH, result.line);
+    if (result.status === "unavailable" && (!finding || finding.code === "mount.no_route"))
+        throw new HarnessError(offlineCode, result.line);
+    throw new HarnessError(HARNESS_CODES.HARNESS_MOUNT_FAILED, result.line);
 }
-async function writeExcludeBlock(root, files) {
-    let excludePath;
-    try {
-        excludePath = execFileSync("git", ["rev-parse", "--git-path", "info/exclude"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+async function recordedFiles(root, runtime) {
+    const { readMountRecord } = await loadHarness("mount");
+    return new Set((readMountRecord(root)?.runtimes?.[runtime]?.files ?? []).map((file) => file.path));
+}
+async function handOver(root, runtime, outcome) {
+    const handed = await handOverLegacyMount(root, await recordedFiles(root, runtime));
+    if (!handed)
+        return outcome;
+    const lines = [...outcome.lines, ...handed.editedKept.map((file) => `kept ${file}: the legacy harness wrote it and it has been edited since`)];
+    return { ...outcome, removed: [...outcome.removed, ...handed.removed], lines };
+}
+export async function mountProjectHarness(root, options) {
+    const log = options.log ?? ((line) => process.stderr.write(`${line}\n`));
+    const report = (outcome) => {
+        for (const line of outcome.lines)
+            log(line);
+        return outcome;
+    };
+    const runtime = options.runtime ?? "claude-code";
+    if (await hasEtnaMountHook(root)) {
+        throw new HarnessError(HARNESS_CODES.ETNA_MOUNT_PRESENT, "This checkout's .claude/settings.json runs etna's mount hook (.claude/hooks/mount.mjs), and two mounters on one checkout erase each other's record. Remove etna's SessionStart entry, then run `nustack init`.");
     }
-    catch {
-        return;
+    const contract = await readProjectContract(root);
+    const projectId = await projectOf(root, options.projectId, contract.projectId);
+    const lines = [];
+    let harness = contract.harness;
+    if (!harness) {
+        harness = { track: "latest" };
+        if (contract.contractPresent)
+            lines.push("This contract names no harness version, so the newest is mounted; run `nustack init` to record one.");
     }
-    const absolute = path.isAbsolute(excludePath) ? excludePath : path.join(root, excludePath);
-    const held = (await readIfPresent(absolute))?.toString("utf8") ?? "";
-    const start = held.indexOf(IGNORE_START);
-    const end = held.indexOf(IGNORE_END);
-    const outside = start >= 0 && end > start ? held.slice(0, start) + held.slice(end + IGNORE_END.length).replace(/^\n/, "") : held;
-    const block = [IGNORE_START, ...ignoredNamesOf(files), IGNORE_END].join("\n");
-    await writeAtomic(absolute, `${outside.replace(/\n*$/, outside ? "\n" : "")}${block}\n`);
-}
-export async function mountWithAdapter(root, manifestUrl, options = {}) {
-    const fetchImpl = options.fetchImpl ?? fetch;
-    const cacheDir = options.cacheDir ?? defaultCacheDir();
-    const manifestBytes = await fetchBytes(fetchImpl, manifestUrl);
-    const digest = sha256Of(manifestBytes);
-    const manifest = JSON.parse(manifestBytes.toString("utf8"));
-    if (!manifest || !Array.isArray(manifest.files))
-        throw new Error(`the manifest at ${manifestUrl} lists no files`);
-    const version = String(manifest.version ?? "");
-    const prior = await readMountState(root);
-    const mounted = manifest.files.filter(isMountedPath);
-    let written = 0;
-    let kept = 0;
-    for (const file of mounted) {
-        if (file.path.split("/").includes("..") || path.isAbsolute(file.path))
-            throw new Error(`the manifest names an unsafe path: ${file.path}`);
-        const target = path.join(root, file.path);
-        const held = await readIfPresent(target);
-        if (held && file.sha256 && sha256Of(held) === file.sha256) {
-            kept += 1;
-            continue;
-        }
-        const cached = file.sha256 ? await readIfPresent(path.join(cacheDir, "objects", file.sha256)) : null;
-        let bytes = cached && sha256Of(cached) === file.sha256 ? cached : null;
-        if (!bytes) {
-            bytes = await fetchBytes(fetchImpl, objectUrlOf(manifestUrl, file.key));
-            if (file.sha256 && sha256Of(bytes) !== file.sha256)
-                throw new Error(`the object for ${file.path} does not match its sha256`);
-            if (file.sha256)
-                await writeAtomic(path.join(cacheDir, "objects", file.sha256), bytes);
-        }
-        await writeAtomic(target, bytes);
-        written += 1;
+    const pinned = "digest" in harness ? harness : null;
+    const { mountVersion, defaultHarnessCacheDir } = await loadHarness("mount");
+    const common = { root, cacheDir: defaultHarnessCacheDir(), runtime, projectId, writeContract: options.writeContract };
+    const noFetch = async () => {
+        throw new Error("a cached mount fetches nothing");
+    };
+    const fromCache = async (reason, guardRefusal, origin) => {
+        const result = await mountVersion({ ...common, manifest: null, fetchObject: noFetch, expectedDigest: pinned?.digest ?? null, recordExtras: origin ? { origin } : {} });
+        if (guardRefusal && result.status !== "mounted" && result.status !== "current")
+            throw new HarnessError(HARNESS_CODES.ORIGIN_MISMATCH, guardRefusal.message);
+        const notice = guardRefusal ? `harness taken from the cache, the origin was refused: ${guardRefusal.message}` : `harness taken from the cache: ${reason}`;
+        return handOver(root, runtime, outcomeOf(projectId, result, [...lines, notice], HARNESS_CODES.HARNESS_OFFLINE_NO_CACHE));
+    };
+    const read = await readSummary(root, projectId, options.globals ?? {});
+    if (read.kind === "offline")
+        return report(await fromCache(read.reason, read.guardRefusal, read.baseUrl));
+    if (!isProjectVersionSummary(read.summary)) {
+        const manifestUrl = read.summary.harness?.manifestUrl ?? null;
+        if (!manifestUrl)
+            throw new HarnessError(HARNESS_CODES.HARNESS_UNAVAILABLE, `Project ${projectId} resolves no harness version to mount.`);
+        const legacy = await mountLegacyManifest(root, manifestUrl, read.baseUrl);
+        return report({
+            projectId,
+            status: legacy.written.length > 0 ? "mounted" : "current",
+            source: "legacy",
+            version: legacy.version,
+            digest: legacy.digest,
+            runtime,
+            written: legacy.written,
+            kept: legacy.kept,
+            removed: [],
+            lines: [...lines, `harness mounted: ${legacy.version} (legacy) from ${manifestUrl}`],
+        });
     }
-    await writeExcludeBlock(root, mounted);
-    await mkdir(path.join(root, ".claude", "state"), { recursive: true });
-    if (!(await readIfPresent(path.join(root, ".claude", "state", ".gitignore"))))
-        await writeFile(path.join(root, ".claude", "state", ".gitignore"), "*\n");
-    const state = { version, digest, mountedAt: new Date().toISOString(), manifestUrl };
-    if (!prior || prior.digest !== digest || prior.version !== version || written > 0)
-        await writeAtomic(path.join(root, MOUNT_STATE_PATH), `${JSON.stringify(state, null, 2)}\n`);
-    return { version, digest, written, kept, via: "adapter" };
-}
-export async function mountHarness(root, manifestUrl, options = {}) {
-    if (options.useEtna !== false) {
-        const specifier = ETNA_MOUNT_SPECIFIER;
-        const etna = (await import(specifier).catch(() => null));
-        if (etna && typeof etna.mount === "function") {
-            await etna.mount(root, manifestUrl);
-            const state = await readMountState(root);
-            return { version: state?.version ?? "", digest: state?.digest ?? "", written: 0, kept: 0, via: "etna" };
+    let resolved;
+    try {
+        resolved = await resolveProjectVersion(read.baseUrl, read.accessToken, projectId, pinned ? { digest: pinned.digest } : { track: "latest" });
+    }
+    catch (error) {
+        if (isOriginMismatch(error))
+            return report(await fromCache(error.message, error, read.baseUrl));
+        if (error instanceof VersionsRouteError && error.status === 404) {
+            if (error.code === "PROJECT_NOT_FOUND")
+                throw coded("PROJECT_NOT_FOUND", error.message);
+            if (error.code === "VALIDATION_FAILED" && pinned) {
+                const result = await mountVersion({ ...common, manifest: null, fetchObject: noFetch, expectedDigest: pinned.digest, recordExtras: { origin: read.baseUrl } });
+                if (result.status !== "mounted" && result.status !== "current") {
+                    throw new HarnessError(HARNESS_CODES.HARNESS_DIGEST_MISMATCH, `Project ${projectId} serves no version with the pinned digest ${pinned.digest}, and none is cached.`);
+                }
+                return report(await handOver(root, runtime, outcomeOf(projectId, result, lines, HARNESS_CODES.HARNESS_DIGEST_MISMATCH)));
+            }
+            throw new HarnessError(HARNESS_CODES.HARNESS_UNAVAILABLE, `Project ${projectId} serves no harness version yet: ${error.message}`);
         }
+        if (error instanceof VersionsRouteError && (error.status === 0 || error.status >= 500))
+            return report(await fromCache(error.message, null, read.baseUrl));
+        throw new HarnessError(HARNESS_CODES.HARNESS_MOUNT_FAILED, error instanceof Error ? error.message : String(error));
+    }
+    let manifest;
+    try {
+        manifest = await fetchVersionManifest(read.baseUrl, read.accessToken, projectId, resolved.semver);
+    }
+    catch (error) {
+        if (error instanceof VersionsRouteError && (error.status === 0 || error.status >= 500))
+            return report(await fromCache(error.message, null, read.baseUrl));
+        throw new HarnessError(HARNESS_CODES.HARNESS_MOUNT_FAILED, error instanceof Error ? error.message : String(error));
     }
-    return mountWithAdapter(root, manifestUrl, options);
+    const result = await mountVersion({
+        ...common,
+        manifest,
+        fetchObject: (entry) => fetchVersionObject(read.baseUrl, read.accessToken, projectId, resolved.semver, entry),
+        expectedDigest: pinned?.digest ?? resolved.digest,
+        recordExtras: { origin: read.baseUrl },
+    });
+    return report(await handOver(root, runtime, outcomeOf(projectId, result, lines, HARNESS_CODES.HARNESS_OFFLINE_NO_CACHE)));
 }

package/dist/lib/harness/storeWaivers.js

@@ -0,0 +1,43 @@
+import { openLocalStoreReadOnly } from "../local_store/database.js";
+const RECORDS_STORE_VERSION = 9;
+const NEVER_EXPIRES = "9999-12-31";
+const DISCHARGED_VERDICTS = new Set(["updated", "owes_nothing"]);
+export async function readStoreDocumentationWaivers(projectId, dbPath) {
+    if (!projectId)
+        return [];
+    const store = await openLocalStoreReadOnly(dbPath ? { dbPath } : {}).catch(() => null);
+    if (!store)
+        return [];
+    try {
+        if (store.version < RECORDS_STORE_VERSION)
+            return [];
+        const rows = store.db
+            .prepare("SELECT payload_json FROM records WHERE kind = 'obligation' AND project_id = ?")
+            .all(projectId);
+        const subjects = new Set();
+        for (const row of rows) {
+            let payload;
+            try {
+                payload = JSON.parse(row.payload_json);
+            }
+            catch {
+                continue;
+            }
+            if (payload.type !== "documentation" || payload.state !== "discharged" || typeof payload.subject !== "string")
+                continue;
+            if (typeof payload.outcome?.verdict !== "string" || !DISCHARGED_VERDICTS.has(payload.outcome.verdict))
+                continue;
+            subjects.add(payload.subject);
+        }
+        return [...subjects].sort().map((subject) => ({
+            kind: "waived",
+            body: `bookkeeping \`${subject}\` — its documentation obligation is discharged in the local store expires=${NEVER_EXPIRES}`,
+        }));
+    }
+    catch {
+        return [];
+    }
+    finally {
+        store.close();
+    }
+}