@nurix/nustack 0.18.1 → 0.19.1

package/dist/commands/doctor.js

@@ -8,6 +8,7 @@ import { readManagedValues } from "../lib/env_file.js";
 import { readProjectManifests, diagnoseManifests } from "../lib/onboarding/manifest_writer.js";
 import { fetchToolkitProfile, ToolkitProfileUnavailableError } from "../lib/etna/profile.js";
 import { toolkitCompatibility } from "../lib/etna/reconcile.js";
+import { readMountStateSync } from "../lib/harness/mount.js";
 import { openLocalStore } from "../lib/local_store/database.js";
 import { readDeviceState } from "../lib/local_store/device_state.js";
 import { getBindingByRepositoryRoot, listActiveBindings } from "../lib/local_store/bindings.js";
@@ -204,7 +205,7 @@ function addBindingRows(add, store, binding, cloud) {
         else
             add("sync", "Pending inbound", "warn", `${pending.length} pending (${technical.length} waiting, ${decisions.length} need a decision)`);
     }
-    const compatibility = toolkitCompatibility(binding, cloud);
+    const compatibility = toolkitCompatibility(readMountStateSync(binding.repositoryRoot), cloud);
     if (compatibility.blocksWrites)
         add("toolkit", "Compatibility gate", "error", `incompatible — ${compatibility.reason}; projection and sync writes are blocked`);
     else

package/dist/commands/harness.js

@@ -0,0 +1,90 @@
+import path from "node:path";
+import { getProject, resolveNuStackUrl } from "../lib/nustack_client.js";
+import { ensureAuthWithRecovery, lastAuthFailure } from "../lib/auth_recovery.js";
+import { resolveProjectId } from "../lib/project_context.js";
+import { resolveRepository } from "../lib/git-sync/core/repository.js";
+import { mountHarness, readMountState } from "../lib/harness/mount.js";
+import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
+function emitFail(command, json, code, message) {
+    if (json)
+        printJsonError(command, { code, message });
+    else {
+        console.error(message);
+        process.exitCode = 1;
+    }
+}
+function rootOf(dir) {
+    try {
+        return resolveRepository(dir).repositoryRoot;
+    }
+    catch {
+        return dir;
+    }
+}
+async function cloudHarness(command, json, root, options, globals) {
+    const project = await resolveProjectId(root, options);
+    if (!project.ok) {
+        emitFail(command, json, "PROJECT_CONTEXT_MISSING", project.message);
+        return null;
+    }
+    const baseUrl = resolveNuStackUrl(globals);
+    const auth = await ensureAuthWithRecovery(baseUrl, json);
+    if (!auth) {
+        const failure = lastAuthFailure();
+        emitFail(command, json, failure.code, failure.message);
+        return null;
+    }
+    const summary = await getProject(baseUrl, auth.accessToken, project.projectId);
+    return { projectId: project.projectId, harness: summary.harness ?? null };
+}
+export async function runHarnessMount(target, options, globals) {
+    const json = options.json === true;
+    const root = rootOf(path.resolve(target ?? process.cwd()));
+    let manifestUrl = options.manifest ?? null;
+    let projectId = null;
+    if (!manifestUrl) {
+        const cloud = await cloudHarness("harness mount", json, root, options, globals);
+        if (!cloud)
+            return;
+        projectId = cloud.projectId;
+        manifestUrl = cloud.harness?.manifestUrl ?? null;
+        if (!manifestUrl) {
+            emitFail("harness mount", json, "HARNESS_UNAVAILABLE", `Project ${cloud.projectId} resolves no harness version with an uploaded manifest.`);
+            return;
+        }
+    }
+    let mounted;
+    try {
+        mounted = await mountHarness(root, manifestUrl);
+    }
+    catch (error) {
+        emitFail("harness mount", json, "HARNESS_MOUNT_FAILED", `The harness mount failed: ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    if (json) {
+        printJsonSuccess("harness mount", { projectId, root, manifestUrl, ...mounted });
+        return;
+    }
+    console.log(`Mounted harness ${mounted.version} into ${root} (${mounted.written} written, ${mounted.kept} unchanged, digest ${mounted.digest.slice(0, 12)})`);
+}
+export async function runHarnessStatus(options, globals) {
+    const json = options.json === true;
+    const root = rootOf(process.cwd());
+    const cloud = await cloudHarness("harness status", json, root, options, globals);
+    if (!cloud)
+        return;
+    const mounted = await readMountState(root);
+    const pinned = cloud.harness?.version ?? null;
+    const inStep = pinned === null || mounted?.version === pinned;
+    if (json) {
+        printJsonSuccess("harness status", { projectId: cloud.projectId, mounted, cloud: cloud.harness, inStep });
+    }
+    else {
+        console.log(`Harness for Project ${cloud.projectId}`);
+        console.log(`  mounted:   ${mounted ? `${mounted.version} (digest ${mounted.digest.slice(0, 12)})` : "(nothing mounted)"}`);
+        console.log(`  cloud pin: ${cloud.harness ? `${cloud.harness.slug} ${cloud.harness.version}` : "(none)"}`);
+        console.log(`  verdict:   ${inStep ? "in step" : "DIFFERS — run `nustack harness mount`"}`);
+    }
+    if (!inStep)
+        process.exitCode = 1;
+}

package/dist/commands/project.js

@@ -16,6 +16,7 @@ import { resolveRepository } from "../lib/git-sync/core/repository.js";
 import { readProjectManifests } from "../lib/onboarding/manifest_writer.js";
 import { hasManifest, scaffoldManifest } from "../lib/manifest.js";
 import { toolkitCompatibility } from "../lib/etna/reconcile.js";
+import { readMountStateSync } from "../lib/harness/mount.js";
 import { attachExistingGit } from "../lib/onboarding/attach_existing_git.js";
 import { webFirstAttach } from "../lib/onboarding/web_first_attach.js";
 import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
@@ -183,6 +184,7 @@ export async function runProjectStatus(options, globals) {
                     rendererVersion: cloudProject.toolkit.rendererVersion,
                     placementMapVersion: cloudProject.toolkit.placementMapVersion,
                     catalogVersionId: null,
+                    harnessVersion: cloudProject.harness?.version ?? null,
                 };
             }
         }
@@ -190,7 +192,7 @@ export async function runProjectStatus(options, globals) {
             cloudProject = null;
         }
     }
-    const compatibility = toolkitCompatibility(binding ?? { etnaProfileJson: null }, cloud);
+    const compatibility = toolkitCompatibility(readMountStateSync(binding?.repositoryRoot ?? cwd), cloud);
     if (json) {
         printJsonSuccess("project status", {
             projectId: project.projectId,

package/dist/commands/records.js

@@ -0,0 +1,150 @@
+import { existsSync } from "node:fs";
+import { openLocalStore } from "../lib/local_store/database.js";
+import { stateDbPath } from "../lib/local_store/paths.js";
+import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
+import { RECORDS_BATCH_CAP, drainOutbox, drainStore, emitRecords, isRecordKind, listOutbox, listStored, resolveDoor, } from "../lib/records/door.js";
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+function parseRows(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const list = Array.isArray(parsed) ? parsed : [parsed];
+    const rows = list.filter((row) => !!row && typeof row === "object" && typeof row.anchor === "string" && row.anchor.trim() !== "");
+    return rows.length === list.length ? rows : null;
+}
+function emitLine(outcome) {
+    if (outcome.rung === 1)
+        return `records emit: landed ${outcome.landed} on NuStack (${outcome.projectId})\n`;
+    if (outcome.rung === 2)
+        return `records emit: the door refused (${outcome.error}); ${outcome.keys.length} row(s) wait in the outbox\n`;
+    return `records emit: ${outcome.reason}; ${outcome.keys.length} row(s) kept in the local store\n`;
+}
+export async function runRecordsEmit(options, globals) {
+    const json = options.json === true;
+    const refuse = (message) => {
+        if (json)
+            printJsonError("records emit", { code: "VALIDATION_FAILED", message });
+        else {
+            process.stderr.write(`records emit: ${message}\n`);
+            process.exitCode = 1;
+        }
+    };
+    if (!isRecordKind(options.kind))
+        return refuse("--kind must be backlog, backlog.remove, bookkeeping or gate_event");
+    const rows = parseRows(options.row ?? (await readStdin()));
+    if (!rows || rows.length === 0)
+        return refuse("the rows must be JSON — one object or an array — each with an anchor");
+    const root = options.root ?? process.cwd();
+    const resolution = await resolveDoor(root, globals, options.project);
+    const store = await openLocalStore();
+    try {
+        const outcomes = [];
+        for (let start = 0; start < rows.length; start += RECORDS_BATCH_CAP) {
+            outcomes.push(await emitRecords(store, resolution, options.kind, rows.slice(start, start + RECORDS_BATCH_CAP)));
+        }
+        if (outcomes.every((outcome) => outcome.rung === 1))
+            await drainOutbox(store, globals, { dueOnly: true });
+        const last = outcomes[outcomes.length - 1];
+        const keys = outcomes.flatMap((outcome) => outcome.keys);
+        if (json)
+            printJsonSuccess("records emit", { ...last, keys });
+        else
+            process.stdout.write(emitLine({ ...last, keys }));
+    }
+    finally {
+        store.close();
+    }
+}
+export async function runRecordsSync(options, globals) {
+    const store = await openLocalStore();
+    try {
+        const outbox = await drainOutbox(store, globals);
+        const stored = await drainStore(store, globals);
+        const result = {
+            sent: outbox.sent + stored.sent,
+            waiting: listOutbox(store).length,
+            stored: listStored(store).length,
+            lastError: outbox.lastError ?? stored.lastError,
+        };
+        if (options.json)
+            printJsonSuccess("records sync", result);
+        else
+            process.stdout.write(`records sync: sent ${result.sent}; ${result.waiting} wait in the outbox, ${result.stored} kept locally\n`);
+    }
+    finally {
+        store.close();
+    }
+}
+export async function runRecordsList(options) {
+    const store = await openLocalStore();
+    try {
+        const outbox = listOutbox(store, options.project);
+        const stored = listStored(store, options.project ? { projectId: options.project } : {});
+        const newest = [...outbox].sort((a, b) => b.createdAtMs - a.createdAtMs).find((row) => row.lastError !== null);
+        const data = {
+            outboxCount: outbox.length,
+            storeCount: stored.length,
+            lastError: newest?.lastError ?? null,
+            outbox,
+            store: stored,
+        };
+        if (options.json)
+            printJsonSuccess("records list", data);
+        else {
+            process.stdout.write(`records list: ${data.outboxCount} in the outbox, ${data.storeCount} kept locally\n`);
+            if (data.lastError)
+                process.stdout.write(`  last error: ${data.lastError}\n`);
+        }
+    }
+    finally {
+        store.close();
+    }
+}
+export async function drainBeforeCommand(globals) {
+    if (!existsSync(stateDbPath()))
+        return;
+    try {
+        const store = await openLocalStore();
+        try {
+            await drainOutbox(store, globals, { dueOnly: true, limit: 20 });
+        }
+        finally {
+            store.close();
+        }
+    }
+    catch {
+    }
+}
+export function registerRecordsCommands(recordsCommand, getGlobalOptions) {
+    recordsCommand
+        .command("emit")
+        .description("Land records on NuStack, else park them in the outbox, else keep them locally")
+        .option("--kind <kind>", "backlog, backlog.remove, bookkeeping or gate_event")
+        .option("--row <json>", "the row, or an array of rows, as JSON (default: read from stdin)")
+        .option("--root <dir>", "the folder the records are about (default: the current directory)")
+        .option("--project <id>", "the Project, when the folder carries no binding marker")
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (options) => runRecordsEmit(options, getGlobalOptions()));
+    recordsCommand
+        .command("sync")
+        .description("Send every outbox row, and stored rows whose folder now has a door")
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (options) => runRecordsSync(options, getGlobalOptions()));
+    recordsCommand
+        .command("list")
+        .description("Show the rows that have not reached NuStack: the outbox and the local store")
+        .option("--project <id>", "only this Project's rows")
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (options) => runRecordsList(options));
+}

package/dist/commands/toolkit.js

@@ -9,6 +9,7 @@ import { resolveRepository } from "../lib/git-sync/core/repository.js";
 import { readProjectManifests, diagnoseManifests } from "../lib/onboarding/manifest_writer.js";
 import { fetchToolkitProfile, ToolkitProfileUnavailableError } from "../lib/etna/profile.js";
 import { buildReconcilePlan, applyReconcile, toolkitCompatibility } from "../lib/etna/reconcile.js";
+import { readMountStateSync } from "../lib/harness/mount.js";
 import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
 function emitFail(command, json, code, message) {
     if (json)
@@ -59,8 +60,7 @@ export async function runToolkitStatus(options, globals) {
     }
     const manifests = await readProjectManifests(ctx.root);
     const diagnosis = diagnoseManifests({ name: cloud.name, version: cloud.version }, manifests.projectManifest?.toolkit ?? null, manifests.serviceToolkit);
-    const binding = await withStore((store) => getBindingByRepositoryRoot(store, ctx.root));
-    const compatibility = toolkitCompatibility(binding ?? { etnaProfileJson: null }, cloud);
+    const compatibility = toolkitCompatibility(readMountStateSync(ctx.root), cloud);
     if (json) {
         printJsonSuccess("toolkit status", {
             projectId: ctx.projectId,

package/dist/index.js

@@ -24,8 +24,10 @@ import { runOrganizationList, runOrganizationCreate, runOrganizationUse } from "
 import { runDocsList, runDocsShow, runDocsStatus } from "./commands/docs.js";
 import { runHandoffList, runHandoffShow } from "./commands/handoff.js";
 import { runToolkitStatus, runToolkitReconcile } from "./commands/toolkit.js";
+import { runHarnessMount, runHarnessStatus } from "./commands/harness.js";
 import { runSessionsList, runSessionsPrune, runSessionsRecord, runSessionsServe, } from "./commands/sessions.js";
 import { registerReviewCommands } from "./commands/review.js";
+import { drainBeforeCommand, registerRecordsCommands } from "./commands/records.js";
 import { runAgentContext, runAgentHookInstall, runAgentHookRemove } from "./commands/agent.js";
 import { printJsonError } from "./lib/json_output.js";
 import { setCliVersion } from "./lib/auth_grant.js";
@@ -216,6 +218,11 @@ const project = program.command("project").description("Work with NuStack Projec
 registerProjectCommands(project, () => program.opts());
 registerProjectSyncCommands(project, () => program.opts());
 registerReviewCommands(program.command("review").description("Read and mirror NuStack Review items"), () => program.opts());
+registerRecordsCommands(program.command("records").description("Emit, send and list harness records"), () => program.opts());
+program.hook("preAction", async (_program, action) => {
+    if (action.parent?.name() !== "records")
+        await drainBeforeCommand(program.opts());
+});
 const docs = program.command("docs").description("Work with a Project's Documents");
 docs
     .command("list")
@@ -275,6 +282,20 @@ sessions
     .option("--force", "also reclaim an unmerged or dirty session — never one whose engine is running")
     .option("--json", "emit the versioned machine envelope")
     .action(async (options) => runSessionsPrune(options));
+const harness = program.command("harness").description("Mount the Project's harness and compare it with the cloud pin");
+harness
+    .command("mount [path]")
+    .description("Mount the resolved harness version into a checkout (default: the current repository)")
+    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
+    .option("--manifest <url>", "mount this manifest instead of the one the Project resolves")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (target, options) => runHarnessMount(target, options, program.opts()));
+harness
+    .command("status")
+    .description("Print the mounted harness against the cloud pin; exits 1 when they differ")
+    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runHarnessStatus(options, program.opts()));
 const toolkit = program.command("toolkit").description("Inspect and reconcile the Project's toolkit pin");
 toolkit
     .command("status")

package/dist/lib/etna/manager.js

@@ -2,6 +2,7 @@ import { detectPackageManager, installPackage } from "../package_manager.js";
 import { assertSafePackageName } from "../guards.js";
 import { updateBindingEtnaProfile } from "../local_store/bindings.js";
 import { serializeProfileForBinding } from "./profile.js";
+import { mountHarness } from "../harness/mount.js";
 export function toolkitPackageName(profile) {
     if (!profile.name.startsWith("@"))
         return null;
@@ -15,7 +16,17 @@ export function toolkitPackageName(profile) {
 export async function installToolkit(store, bindingId, profile, cwd, deps = {}) {
     const packageName = toolkitPackageName(profile);
     let result;
-    if (!packageName) {
+    const manifestUrl = deps.manifestUrl ?? profile.manifestUrl ?? null;
+    if (manifestUrl) {
+        try {
+            await (deps.mount ?? mountHarness)(cwd, manifestUrl);
+            result = { ok: true, installed: true, skipped: false, reason: "mounted" };
+        }
+        catch (error) {
+            result = { ok: false, installed: false, skipped: false, reason: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    else if (!packageName) {
         result = { ok: true, installed: false, skipped: true, reason: "device_level_toolkit" };
     }
     else {

package/dist/lib/etna/profile.js

@@ -19,6 +19,8 @@ export async function fetchToolkitProfile(baseUrl, accessToken, projectId) {
         rendererVersion: typeof toolkit.rendererVersion === "string" ? toolkit.rendererVersion : "",
         placementMapVersion: typeof toolkit.placementMapVersion === "string" ? toolkit.placementMapVersion : "",
         catalogVersionId: null,
+        harnessVersion: project.harness?.version ?? null,
+        manifestUrl: project.harness?.manifestUrl ?? null,
     };
 }
 export function toolkitProfileFromManifest(manifest) {

package/dist/lib/etna/reconcile.js

@@ -19,18 +19,12 @@ export function parseRecordedToolkit(binding) {
         return null;
     }
 }
-export function toolkitCompatibility(binding, cloud) {
-    const recorded = parseRecordedToolkit(binding);
-    if (!recorded || !cloud)
+export function toolkitCompatibility(mounted, cloud) {
+    if (!mounted || !cloud)
         return { compatible: true, blocksWrites: false, reason: null };
-    if (recorded.name !== cloud.name) {
-        return { compatible: false, blocksWrites: true, reason: `toolkit name diverges (local ${recorded.name} vs cloud ${cloud.name})` };
-    }
-    if (recorded.version !== cloud.version) {
-        return { compatible: false, blocksWrites: true, reason: `toolkit version diverges (local ${recorded.version} vs cloud ${cloud.version})` };
-    }
-    if (cloud.rendererVersion && recorded.rendererVersion && recorded.rendererVersion !== cloud.rendererVersion) {
-        return { compatible: false, blocksWrites: true, reason: `renderer version diverges (local ${recorded.rendererVersion} vs cloud ${cloud.rendererVersion})` };
+    const pinned = cloud.harnessVersion ?? cloud.version;
+    if (mounted.version !== pinned) {
+        return { compatible: false, blocksWrites: true, reason: `mounted harness ${mounted.version} differs from the cloud pin ${pinned}` };
     }
     return { compatible: true, blocksWrites: false, reason: null };
 }

package/dist/lib/harness/mount.js

@@ -0,0 +1,155 @@
+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 path from "node:path";
+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 {
+        return null;
+    }
+}
+export async function readMountState(root) {
+    return parseMountState(await readIfPresent(path.join(root, MOUNT_STATE_PATH)));
+}
+export function readMountStateSync(root) {
+    try {
+        return parseMountState(readFileSync(path.join(root, MOUNT_STATE_PATH)));
+    }
+    catch {
+        return null;
+    }
+}
+function parseMountState(raw) {
+    if (!raw)
+        return null;
+    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 } : {}) };
+    }
+    catch {
+        return null;
+    }
+}
+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(/^\/+/, "")}`;
+}
+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);
+}
+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 writeExcludeBlock(root, files) {
+    let excludePath;
+    try {
+        excludePath = execFileSync("git", ["rev-parse", "--git-path", "info/exclude"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return;
+    }
+    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;
+    }
+    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" };
+        }
+    }
+    return mountWithAdapter(root, manifestUrl, options);
+}

package/dist/lib/local_store/migrations.js

@@ -205,6 +205,36 @@ const MIGRATION_V7 = {
         `CREATE INDEX local_bindings_project_idx ON local_bindings (project_id)`,
     ],
 };
+const MIGRATION_V8 = {
+    version: 8,
+    statements: [
+        `CREATE TABLE record_outbox (
+            id TEXT PRIMARY KEY,
+            project_id TEXT NOT NULL,
+            kind TEXT NOT NULL CHECK (kind IN ('backlog','backlog.remove','bookkeeping','gate_event')),
+            idempotency_key TEXT NOT NULL,
+            door_url TEXT NOT NULL,
+            row_json TEXT NOT NULL CHECK (json_valid(row_json)),
+            attempts INTEGER NOT NULL DEFAULT 0,
+            next_retry_at_ms INTEGER,
+            last_error TEXT,
+            created_at_ms INTEGER NOT NULL,
+            updated_at_ms INTEGER NOT NULL
+        )`,
+        `CREATE UNIQUE INDEX record_outbox_idempotency_key_unique ON record_outbox (idempotency_key)`,
+        `CREATE TABLE record_store (
+            id TEXT PRIMARY KEY,
+            project_id TEXT,
+            repository_root TEXT NOT NULL,
+            kind TEXT NOT NULL CHECK (kind IN ('backlog','backlog.remove','bookkeeping','gate_event')),
+            idempotency_key TEXT NOT NULL,
+            row_json TEXT NOT NULL CHECK (json_valid(row_json)),
+            created_at_ms INTEGER NOT NULL,
+            updated_at_ms INTEGER NOT NULL
+        )`,
+        `CREATE UNIQUE INDEX record_store_idempotency_key_unique ON record_store (idempotency_key)`,
+    ],
+};
 export const MIGRATIONS = [
     MIGRATION_V1,
     MIGRATION_V2,
@@ -213,6 +243,7 @@ export const MIGRATIONS = [
     MIGRATION_V5,
     MIGRATION_V6,
     MIGRATION_V7,
+    MIGRATION_V8,
 ];
 export const LATEST_SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;
 export class LocalSchemaTooNewError extends Error {

package/dist/lib/records/door.js

@@ -0,0 +1,223 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { ensureAccessToken } from "../auth_grant.js";
+import { resolveNuStackUrl } from "../nustack_client.js";
+import { resolveProjectId } from "../project_context.js";
+export const RECORD_KINDS = ["backlog", "backlog.remove", "bookkeeping", "gate_event"];
+export const RECORDS_BATCH_CAP = 200;
+const REQUEST_TIMEOUT_MS = 10_000;
+const RETRY_BASE_MS = 30_000;
+const RETRY_CEILING_MS = 60 * 60 * 1000;
+export function isRecordKind(value) {
+    return typeof value === "string" && RECORD_KINDS.includes(value);
+}
+export function idempotencyKeyOf(project, kind, anchor) {
+    return `${project}:${kind}:${anchor}`;
+}
+async function readMountDoor(root) {
+    const manifest = path.join(root, ".claude", "harness.json");
+    if (!existsSync(manifest))
+        return undefined;
+    try {
+        const parsed = JSON.parse(await readFile(manifest, "utf8"));
+        if (!parsed.mount || !("door" in parsed.mount))
+            return undefined;
+        const door = parsed.mount.door;
+        return typeof door === "string" && door.trim() !== "" ? door.trim().replace(/\/+$/, "") : null;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function resolveDoor(root, globals, projectFlag) {
+    const project = await resolveProjectId(root, projectFlag ? { project: projectFlag } : {});
+    if (!project.ok)
+        return { kind: "store", projectId: null, root, reason: "this folder is not bound to a Project" };
+    const door = await readMountDoor(root);
+    if (door === null)
+        return { kind: "store", projectId: project.projectId, root, reason: "the harness manifest configures no door" };
+    return { kind: "door", projectId: project.projectId, doorUrl: door ?? resolveNuStackUrl(globals), isPlatformDefault: door === undefined, root };
+}
+export class DoorRefusedError extends Error {
+}
+export async function postRecords(doorUrl, projectId, kind, rows) {
+    const auth = await ensureAccessToken(doorUrl).catch(() => null);
+    if (!auth)
+        throw new DoorRefusedError("this device is signed out");
+    let response;
+    try {
+        response = await fetch(`${doorUrl}/api/v2/projects/${encodeURIComponent(projectId)}/records`, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${auth.accessToken}` },
+            body: JSON.stringify({ kind, rows }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw new DoorRefusedError(`the door did not answer: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok) {
+        const detail = payload?.error?.message ?? `HTTP ${response.status}`;
+        throw new DoorRefusedError(`${payload?.error?.code ?? `HTTP ${response.status}`}: ${detail}`);
+    }
+    return { landed: payload?.data?.landed ?? 0, skipped: payload?.data?.skipped ?? 0 };
+}
+function outboxOf(row) {
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        kind: row.kind,
+        idempotencyKey: row.idempotency_key,
+        doorUrl: row.door_url,
+        row: JSON.parse(row.row_json),
+        attempts: row.attempts,
+        nextRetryAtMs: row.next_retry_at_ms ?? null,
+        lastError: row.last_error ?? null,
+        createdAtMs: row.created_at_ms,
+    };
+}
+function storedOf(row) {
+    return {
+        id: row.id,
+        projectId: row.project_id ?? null,
+        repositoryRoot: row.repository_root,
+        kind: row.kind,
+        idempotencyKey: row.idempotency_key,
+        row: JSON.parse(row.row_json),
+        createdAtMs: row.created_at_ms,
+    };
+}
+export function retryDelayMs(attempts) {
+    return Math.min(RETRY_BASE_MS * 2 ** Math.max(0, attempts - 1), RETRY_CEILING_MS);
+}
+export function enqueueOutbox(store, input) {
+    const now = Date.now();
+    const key = idempotencyKeyOf(input.projectId, input.kind, input.row.anchor);
+    store.db
+        .prepare(`INSERT INTO record_outbox (id, project_id, kind, idempotency_key, door_url, row_json, attempts,
+                next_retry_at_ms, last_error, created_at_ms, updated_at_ms)
+             VALUES (:id, :project_id, :kind, :key, :door_url, :row_json, 1, :next_retry_at_ms, :last_error, :now, :now)
+             ON CONFLICT(idempotency_key) DO UPDATE SET
+                row_json = excluded.row_json, door_url = excluded.door_url, attempts = 1,
+                next_retry_at_ms = excluded.next_retry_at_ms, last_error = excluded.last_error,
+                created_at_ms = excluded.created_at_ms, updated_at_ms = excluded.updated_at_ms`)
+        .run({
+        id: randomUUID(),
+        project_id: input.projectId,
+        kind: input.kind,
+        key,
+        door_url: input.doorUrl,
+        row_json: JSON.stringify({ ...input.row, idempotencyKey: key }),
+        next_retry_at_ms: now + retryDelayMs(1),
+        last_error: input.error,
+        now,
+    });
+    return outboxOf(store.db.prepare("SELECT * FROM record_outbox WHERE idempotency_key = ?").get(key));
+}
+export function keepInStore(store, input) {
+    const now = Date.now();
+    const key = idempotencyKeyOf(input.projectId ?? input.root, input.kind, input.row.anchor);
+    store.db
+        .prepare(`INSERT INTO record_store (id, project_id, repository_root, kind, idempotency_key, row_json, created_at_ms, updated_at_ms)
+             VALUES (:id, :project_id, :root, :kind, :key, :row_json, :now, :now)
+             ON CONFLICT(idempotency_key) DO UPDATE SET row_json = excluded.row_json, created_at_ms = excluded.created_at_ms,
+                updated_at_ms = excluded.updated_at_ms`)
+        .run({
+        id: randomUUID(),
+        project_id: input.projectId,
+        root: input.root,
+        kind: input.kind,
+        key,
+        row_json: JSON.stringify({ ...input.row, idempotencyKey: key }),
+        now,
+    });
+    return storedOf(store.db.prepare("SELECT * FROM record_store WHERE idempotency_key = ?").get(key));
+}
+export function listOutbox(store, projectId) {
+    const rows = projectId
+        ? store.db.prepare("SELECT * FROM record_outbox WHERE project_id = ? ORDER BY created_at_ms ASC, rowid ASC").all(projectId)
+        : store.db.prepare("SELECT * FROM record_outbox ORDER BY created_at_ms ASC, rowid ASC").all();
+    return rows.map(outboxOf);
+}
+export function listStored(store, filter = {}) {
+    const rows = store.db.prepare("SELECT * FROM record_store ORDER BY created_at_ms ASC, rowid ASC").all();
+    return rows
+        .map(storedOf)
+        .filter((row) => (!filter.projectId || row.projectId === filter.projectId) && (!filter.root || row.repositoryRoot === filter.root));
+}
+export async function emitRecords(store, resolution, kind, rows) {
+    if (resolution.kind === "store") {
+        const kept = rows.map((row) => keepInStore(store, { projectId: resolution.projectId, root: resolution.root, kind, row }));
+        return { rung: 3, projectId: resolution.projectId, keys: kept.map((row) => row.idempotencyKey), reason: resolution.reason };
+    }
+    const { projectId, doorUrl } = resolution;
+    const parkedDoor = resolution.isPlatformDefault ? "" : doorUrl;
+    const keyed = rows.map((row) => ({ ...row, idempotencyKey: idempotencyKeyOf(projectId, kind, row.anchor) }));
+    const keys = keyed.map((row) => row.idempotencyKey);
+    try {
+        const result = await postRecords(doorUrl, projectId, kind, keyed);
+        return { rung: 1, projectId, keys, ...result };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        for (const row of rows)
+            enqueueOutbox(store, { projectId, kind, doorUrl: parkedDoor, row, error: message });
+        return { rung: 2, projectId, keys, error: message };
+    }
+}
+export async function drainOutbox(store, globals, options = {}) {
+    const now = Date.now();
+    let rows = listOutbox(store);
+    if (options.dueOnly)
+        rows = rows.filter((row) => row.nextRetryAtMs === null || row.nextRetryAtMs <= now);
+    if (options.limit !== undefined)
+        rows = rows.slice(0, options.limit);
+    let sent = 0;
+    let kept = 0;
+    let lastError = null;
+    for (const row of rows) {
+        try {
+            await postRecords(row.doorUrl || resolveNuStackUrl(globals), row.projectId, row.kind, [row.row]);
+            store.db.prepare("DELETE FROM record_outbox WHERE id = ?").run(row.id);
+            sent += 1;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+            store.db
+                .prepare(`UPDATE record_outbox SET attempts = attempts + 1, next_retry_at_ms = ?, last_error = ?, updated_at_ms = ? WHERE id = ?`)
+                .run(Date.now() + retryDelayMs(row.attempts + 1), lastError, Date.now(), row.id);
+            kept += 1;
+        }
+    }
+    return { sent, kept, lastError };
+}
+export async function drainStore(store, globals) {
+    let sent = 0;
+    let kept = 0;
+    let lastError = null;
+    for (const row of listStored(store)) {
+        if (!existsSync(row.repositoryRoot)) {
+            kept += 1;
+            continue;
+        }
+        const door = await resolveDoor(row.repositoryRoot, globals);
+        if (door.kind !== "door") {
+            kept += 1;
+            continue;
+        }
+        const keyed = { ...row.row, idempotencyKey: idempotencyKeyOf(door.projectId, row.kind, row.row.anchor) };
+        try {
+            await postRecords(door.doorUrl, door.projectId, row.kind, [keyed]);
+            store.db.prepare("DELETE FROM record_store WHERE id = ?").run(row.id);
+            sent += 1;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+            kept += 1;
+        }
+    }
+    return { sent, kept, lastError };
+}

package/dist/lib/session-engine/supervisor.js

@@ -7,6 +7,7 @@ import { FRAME_VERSION, parseInboundFrame, serializeFrame, } from "./frames.js";
 import { inspectSession, reclaimSession } from "./prune.js";
 import { sessionRegistryPath, readSessionRegistry, updateSessionRegistry } from "./registry.js";
 import { createSessionWorktree } from "./worktree.js";
+import { mountHarness } from "../harness/mount.js";
 function defaultProbeClaude(env) {
     return new Promise((resolve) => {
         execFile("claude", ["--version"], { env, timeout: 5_000 }, (error, stdout) => {
@@ -131,6 +132,21 @@ export class SessionSupervisor {
                 return;
         }
     }
+    async mountInto(sessionId, root, projectId) {
+        const lookup = this.options.sessions?.harnessManifestUrl;
+        if (!lookup)
+            return;
+        try {
+            const manifestUrl = await lookup.call(this.options.sessions, projectId);
+            if (!manifestUrl)
+                return;
+            await (this.options.mountHarness ?? mountHarness)(root, manifestUrl);
+        }
+        catch (error) {
+            const log = this.options.log ?? ((line) => process.stderr.write(`${line}\n`));
+            log(`nustack: harness mount skipped for session ${sessionId} - ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     async openSession(sessionId, projectPath, permissionMode, isolated, resumeSessionId, commit) {
         if (this.sessions.has(sessionId))
             return this.error(sessionId, "SESSION_ALREADY_OPEN", `session ${sessionId} is already open`);
@@ -158,6 +174,8 @@ export class SessionSupervisor {
             enginePid: process.pid,
             closedAt: null,
         };
+        if (record.projectId)
+            await this.mountInto(sessionId, worktree.worktreePath, record.projectId);
         const adapterOptions = {
             cwd: worktree.worktreePath,
             permissionMode,

package/dist/lib/sessions/client.js

@@ -37,6 +37,18 @@ export function makeSessionsClient(baseUrl, accessToken) {
         async setVendorSessionId(projectId, sessionId, vendorSessionId) {
             return this.transitionSession(projectId, sessionId, "running", { vendorSessionId });
         },
+        async harnessManifestUrl(projectId) {
+            const safeId = assertSafeOpaqueId("The Project id", projectId);
+            const response = await globalThis.fetch(`${baseUrl}/api/v2/projects/${encodeURIComponent(safeId)}`, {
+                headers,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const payload = (await response.json().catch(() => null));
+            if (!response.ok)
+                throw new Error(`project summary fetch failed: HTTP ${response.status}`);
+            const url = payload?.data?.harness?.manifestUrl;
+            return typeof url === "string" && url ? url : null;
+        },
     };
 }
 export function sessionsClientFromEnv(env = process.env) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/nustack",
-  "version": "0.18.1",
+  "version": "0.19.1",
   "description": "The nustack CLI — bootstrap NuStack services into a repo via the NuStack discovery plane.",
   "type": "module",
   "private": false,
@@ -21,6 +21,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
+    "@nurix/etna": "0.20.25",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "commander": "^14.0.0"