@nurix/nustack 0.23.12 → 0.23.14

package/dist/program.js

@@ -30,6 +30,7 @@ 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 { runCheck } from "./commands/check.js";
 import { runSessionsList, runSessionsPrune, runSessionsRecord, runSessionsServe, } from "./commands/sessions.js";
 import { registerReviewCommands } from "./commands/review.js";
 import { registerRecordsCommands, startDrainIfDue } from "./commands/records.js";
@@ -38,6 +39,7 @@ import { RECORD_ALIAS_GROUPS, registerRecordAliases } from "./commands/recordAli
 import { runAgentContext, runAgentHookInstall, runAgentHookRemove } from "./commands/agent.js";
 import { runCensus } from "./commands/census.js";
 import { runGateInstall, runGateRemove, runGateStatus } from "./commands/gate.js";
+import { parseBudgetMs, parseLineWindow, runReadBulk } from "./commands/read.js";
 import { HOOK_SUBCOMMANDS } from "./lib/gate/subcommands.js";
 import { printJsonError } from "./lib/json_output.js";
 import { setCliVersion } from "./lib/auth_grant.js";
@@ -68,7 +70,9 @@ program
     .command("init")
     .description("Onboard this folder: sign in, then bind it to a Project (the onboarding router)")
     .option("--organization <id>", "the Organization to create or select the Project in")
+    .option("--project <id>", "the Project to bind (with --yes and --organization: the unattended path)")
     .option("--yes", "pre-confirm the populated-folder onboarding guard")
+    .option("--json", "emit the versioned machine envelope (unattended path only)")
     .action(async (options) => runInit({ ...program.opts(), ...options }));
 program
     .command("add [service]")
@@ -244,8 +248,8 @@ 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());
 registerRecordAliases(program, () => program.opts());
-const LOCAL_ONLY_COMMANDS = ["census"];
-const UNDRAINED_GROUPS = ["records", "gate", ...RECORD_ALIAS_GROUPS];
+const LOCAL_ONLY_COMMANDS = ["census", "check"];
+const UNDRAINED_GROUPS = ["records", "gate", "read", ...RECORD_ALIAS_GROUPS];
 program.hook("preAction", async (_program, action) => {
     if (program.opts().nonInteractive)
         process.env[NON_INTERACTIVE_VARIABLE] = "1";
@@ -257,6 +261,13 @@ program.hook("preAction", async (_program, action) => {
     if (action.name() !== "telemetry" && isPartCheckStale())
         startTelemetryReconcile({ nustackUrl: program.opts().nustackUrl });
 });
+program
+    .command("check [rule]")
+    .description("Run one harness rule over this checkout; exits 0 pass, 1 block or flag, 2 when it cannot run")
+    .option("--json", "emit the versioned machine envelope")
+    .option("--hook <event>", "payload mode for the seed's thin hooks: pre-tool-use or stop (reads the hook payload on stdin)")
+    .option("--protection", "with --hook: the Protection wall's entry (block-rung Protection rows only)")
+    .action(async (rule, options) => runCheck(rule, options));
 const docs = program.command("docs").description("Work with a Project's Documents");
 docs
     .command("list")
@@ -321,12 +332,13 @@ 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("--runtime <runtime>", "the runtime whose half of the version is mounted (claude-code, codex, opencode, copilot-cli)")
+    .option("--write-contract <mode>", "whether the mount may write CLAUDE.md / AGENTS.md (never, when-unmodified)")
     .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")
+    .description("Print the mounted harness against the expected version; exits 1 when they differ, 2 when unreachable")
     .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()));
@@ -385,6 +397,17 @@ gate.command("status")
     .description("Report the gate's hooks, the Local Reader switch, the threshold, the outline and the store version")
     .option("--json", "emit the versioned machine envelope")
     .action(async (options) => runGateStatus(options));
+const read = program.command("read").description("Ask the local model about large files through the running NuStack desktop");
+read.command("bulk")
+    .description("Ask the local model one question about a few large files; a digest that fails its check is never printed")
+    .requiredOption("--paths <path...>", "the files to read, at most eight, inside one NuStack project")
+    .requiredOption("--question <text>", "what to answer about those files")
+    .option("--session <id>", "the Claude Code session this read belongs to (its latch and label rows); omitted, the read runs as `direct`")
+    .option("--agent-type <type>", "the sub-agent type the label rows name (default `main`)")
+    .option("--lines <n>", "line window per model turn (the desktop's default 400)", parseLineWindow)
+    .option("--budget-ms <n>", "the whole call's wall-time budget, 5000 to 300000 ms (default: NUSTACK_READ_BULK_BUDGET_MS, the desktop setting, then the desktop's own)", parseBudgetMs)
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runReadBulk(options));
 function describeError(error) {
     const directCode = error?.code;
     if (directCode === "PROJECT_CONTEXT_MISSING") {

package/dist/vendor/harness/assemble/runtimes.js

@@ -0,0 +1,32 @@
+// packages/harness/src/assemble/runtimes.ts - The four runtimes, each one's instruction file and merge targets, the
+// docs-root token and the `<runtime>/<repository path>` manifest convention. Imports nothing at runtime, so the
+// mount's vendored closure can carry it. docs/architecture/systems/harness-compiler.md speaks for it (Compile).
+export const RUNTIMES = ['claude-code', 'codex', 'opencode', 'copilot-cli'];
+export const isRuntime = (value) => RUNTIMES.includes(value);
+/** The contract path of each runtime: its instruction file, the only file a mount treats as committed policy. */
+export const INSTRUCTION_FILE_OF = {
+    'claude-code': 'CLAUDE.md',
+    codex: 'AGENTS.md',
+    opencode: 'AGENTS.md',
+    'copilot-cli': '.github/copilot-instructions.md',
+};
+/** The repository file each merge kind folds into. */
+export const MERGE_TARGET_OF = {
+    'claude-settings': '.claude/settings.local.json',
+    'codex-hooks': '.codex/hooks.json',
+    'mcp-servers': '.mcp.json',
+};
+/** A `seed` path is `@docs/<path>`, relative to the repository's docs root, which the mount resolves. */
+export const DOCS_ROOT_TOKEN = '@docs';
+export function prefixRuntime(runtime, files) {
+    return files.map((file) => ({ ...file, path: `${runtime}/${file.path}` }));
+}
+/** `<runtime>/<path>` split into its two halves; null when the first segment is not a runtime. */
+export function splitRuntimePath(path) {
+    const slash = path.indexOf('/');
+    if (slash <= 0)
+        return null;
+    const runtime = path.slice(0, slash);
+    const rest = path.slice(slash + 1);
+    return isRuntime(runtime) && rest.length > 0 ? { runtime, path: rest } : null;
+}

package/dist/vendor/harness/assemble/settingsMerge.js

@@ -0,0 +1,136 @@
+const clone = (value) => (value === undefined ? value : JSON.parse(JSON.stringify(value)));
+/** Structural equality over JSON values, key order ignored. */
+export function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a))
+        return a.length === b.length && a.every((item, index) => jsonEqual(item, b[index]));
+    const left = Object.keys(a);
+    const right = Object.keys(b);
+    return left.length === right.length && left.every((key) => jsonEqual(a[key], b[key]));
+}
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const matcherOf = (group) => (typeof group.matcher === 'string' ? group.matcher : null);
+function removeManagedHooks(hooks, managed) {
+    for (const entry of managed) {
+        const groups = hooks[entry.event];
+        if (!Array.isArray(groups))
+            continue;
+        const group = groups.find((candidate) => matcherOf(candidate) === entry.matcher);
+        if (!group || !Array.isArray(group.hooks))
+            continue;
+        const index = group.hooks.findIndex((hook) => jsonEqual(hook, entry.hook));
+        if (index >= 0)
+            group.hooks.splice(index, 1);
+    }
+    for (const [event, groups] of Object.entries(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        hooks[event] = groups.filter((group) => !Array.isArray(group.hooks) || group.hooks.length > 0 || Object.keys(group).some((key) => key !== 'hooks' && key !== 'matcher'));
+        if (hooks[event].length === 0)
+            delete hooks[event];
+    }
+}
+function addHooks(hooks, incoming) {
+    const added = [];
+    for (const [event, groups] of Object.entries(incoming)) {
+        const existing = (hooks[event] = Array.isArray(hooks[event]) ? hooks[event] : []);
+        for (const group of groups) {
+            const matcher = matcherOf(group);
+            let target = existing.find((candidate) => matcherOf(candidate) === matcher);
+            if (!target) {
+                target = { ...clone(group), hooks: [] };
+                existing.push(target);
+            }
+            target.hooks = Array.isArray(target.hooks) ? target.hooks : [];
+            for (const hook of group.hooks ?? []) {
+                if (target.hooks.some((held) => jsonEqual(held, hook)))
+                    continue;
+                target.hooks.push(clone(hook));
+                added.push({ event, matcher, hook: clone(hook) });
+            }
+        }
+    }
+    return added;
+}
+function mergeHookFile(existing, fragment, priorManaged) {
+    const merged = clone(existing ?? {});
+    const hooks = isObject(merged.hooks) ? merged.hooks : {};
+    removeManagedHooks(hooks, priorManaged?.hooks ?? []);
+    const added = addHooks(hooks, isObject(fragment.hooks) ? fragment.hooks : {});
+    if (Object.keys(hooks).length > 0 || isObject(merged.hooks))
+        merged.hooks = hooks;
+    return { merged, hooks: added };
+}
+/** `.claude/settings.local.json`: hooks by event and matcher, permission rules by list, any other top-level key set only when absent. */
+export function mergeClaudeSettings(existing, fragment, priorManaged) {
+    const { merged, hooks } = mergeHookFile(existing, fragment, priorManaged);
+    const permissions = [];
+    const held = isObject(merged.permissions) ? merged.permissions : null;
+    if (held) {
+        for (const { list, rule } of priorManaged?.permissions ?? []) {
+            const rules = held[list];
+            if (Array.isArray(rules))
+                held[list] = rules.filter((candidate) => candidate !== rule);
+        }
+    }
+    const incoming = isObject(fragment.permissions) ? fragment.permissions : {};
+    for (const [list, rules] of Object.entries(incoming)) {
+        if (!Array.isArray(rules))
+            continue;
+        const target = (merged.permissions = isObject(merged.permissions) ? merged.permissions : {});
+        const current = (target[list] = Array.isArray(target[list]) ? target[list] : []);
+        for (const rule of rules) {
+            if (typeof rule !== 'string' || current.includes(rule))
+                continue;
+            current.push(rule);
+            permissions.push({ list, rule });
+        }
+    }
+    if (isObject(merged.permissions)) {
+        const target = merged.permissions;
+        for (const [list, rules] of Object.entries(target))
+            if (Array.isArray(rules) && rules.length === 0 && !(existing && isObject(existing.permissions) && Array.isArray(existing.permissions[list])))
+                delete target[list];
+        if (Object.keys(target).length === 0 && !(existing && isObject(existing.permissions)))
+            delete merged.permissions;
+    }
+    const keys = [];
+    for (const { key, value } of priorManaged?.keys ?? [])
+        if (key in merged && jsonEqual(merged[key], value))
+            delete merged[key];
+    for (const [key, value] of Object.entries(fragment)) {
+        if (key === 'hooks' || key === 'permissions' || key in merged)
+            continue;
+        merged[key] = clone(value);
+        keys.push({ key, value: clone(value) });
+    }
+    return { merged, managed: { ...(hooks.length ? { hooks } : {}), ...(permissions.length ? { permissions } : {}), ...(keys.length ? { keys } : {}) } };
+}
+/** `.codex/hooks.json`: hooks by event and matcher, every other key left as the person wrote it. */
+export function mergeCodexHooks(existing, fragment, priorManaged) {
+    const { merged, hooks } = mergeHookFile(existing, fragment, priorManaged);
+    return { merged, managed: hooks.length ? { hooks } : {} };
+}
+/** `.mcp.json`: servers by name; a name the person holds is theirs, and a server the previous mount added is replaced. */
+export function mergeMcpServers(existing, fragment, priorManaged) {
+    const merged = clone(existing ?? {});
+    const servers = (isObject(merged.mcpServers) ? merged.mcpServers : {});
+    for (const { name, value } of priorManaged?.mcpServers ?? [])
+        if (name in servers && jsonEqual(servers[name], value))
+            delete servers[name];
+    const added = [];
+    for (const [name, value] of Object.entries(isObject(fragment.mcpServers) ? fragment.mcpServers : {})) {
+        if (name in servers)
+            continue;
+        servers[name] = clone(value);
+        added.push({ name, value: clone(value) });
+    }
+    if (Object.keys(servers).length > 0 || isObject(merged.mcpServers))
+        merged.mcpServers = servers;
+    return { merged, managed: added.length ? { mcpServers: added } : {} };
+}

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

@@ -0,0 +1,38 @@
+// packages/harness/src/digest/index.ts - The one content digest a harness version is identified by, its test
+// vectors, and the version manifest. Imports only node:crypto, which the Worker's nodejs_compat flag provides.
+// docs/architecture/systems/harness-compiler.md speaks for it (Versions).
+import { createHash } from 'node:crypto';
+import { byPath } from '../lib/paths.js';
+export { FINDING_CODES } from '../lib/findings.js';
+export const sha256Hex = (content) => createHash('sha256').update(content).digest('hex');
+const shaOf = (file) => ('sha256' in file && typeof file.sha256 === 'string' ? file.sha256 : sha256Hex(file.content));
+/** sha256 hex of JSON.stringify of [{path, sha256}] sorted by path in code-unit order, each sha256 over the file's UTF-8 bytes. */
+export function contentDigest(files) {
+    const entries = files.map((file) => ({ path: file.path, sha256: shaOf(file) })).sort(byPath);
+    return sha256Hex(JSON.stringify(entries));
+}
+/** The two vectors every copy of the digest definition pins against. */
+export const CONTENT_DIGEST_VECTORS = [
+    { files: [], digest: '4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945' },
+    { files: [{ path: 'a', content: 'x' }], digest: 'd19d4b514b0cbad688ef3d00ee838c4db50655f1306c93c9ce84354b96e1a752' },
+];
+const byteLength = (content) => (typeof content === 'string' ? new TextEncoder().encode(content).byteLength : content.byteLength);
+/** The manifest of one version: prefixed entries sorted by path, totals, and the digest over its own entries. */
+export function versionManifest(files, meta) {
+    const entries = files
+        .map((file) => ({ path: file.path, sha256: sha256Hex(file.content), byteSize: byteLength(file.content), policy: file.policy, ...(file.merge ? { merge: file.merge } : {}) }))
+        .sort(byPath);
+    return {
+        schemaVersion: 1,
+        digest: contentDigest(entries),
+        semver: meta.semver,
+        projectId: meta.projectId,
+        catalogVersion: meta.catalogVersion,
+        compileMode: meta.compileMode,
+        runtimes: [...meta.runtimes],
+        unsupported: meta.unsupported,
+        fileCount: entries.length,
+        byteSize: entries.reduce((total, entry) => total + entry.byteSize, 0),
+        files: entries,
+    };
+}

package/dist/vendor/harness/lib/findings.js

@@ -0,0 +1,32 @@
+// packages/harness/src/lib/findings.ts - FINDING_CODES: every mount.*, compile.* and assemble.* finding code, in one
+// list each subpath re-exports. docs/architecture/systems/harness-compiler.md and harness-records.md speak for it.
+export const FINDING_CODES = [
+    'assemble.unknown_kind',
+    'assemble.unsafe_path',
+    'assemble.missing_primary',
+    'assemble.missing_component',
+    'assemble.duplicate_path',
+    'assemble.unparsable_json',
+    'compile.no_model',
+    'compile.model_failed',
+    'compile.anchor_missing',
+    'compile.frontmatter_changed',
+    'compile.policy_over_budget',
+    'compile.skill_catalog_over_budget',
+    'mount.schema_unknown',
+    'mount.runtime_unknown',
+    'mount.bad_sha256',
+    'mount.unsafe_path',
+    'mount.contract_outside',
+    'mount.digest_mismatch',
+    'mount.expected_digest_mismatch',
+    'mount.object_mismatch',
+    'mount.cache_corrupt',
+    'mount.fetch_failed',
+    'mount.no_route',
+    'mount.project_unknown',
+    'mount.contract_edited',
+    'mount.kept_edited',
+    'mount.merge_target_tracked',
+    'mount.merge_target_unparsable',
+];

package/dist/vendor/harness/lib/frontmatter.js

@@ -0,0 +1,79 @@
+// packages/harness/src/lib/frontmatter.ts - The leading frontmatter block and one key's value, ported from etna
+// harness/code/hooks/lib/ownership.mjs (frontmatter, unquote, cleanItem, field, asList). Pure, so the Worker runs it.
+// docs/architecture/systems/harness-records.md speaks for it.
+/** The leading `--- … ---` frontmatter block's body; "" when the text has none. */
+export function frontmatter(text) {
+    const match = /^?---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    return match ? match[1] : '';
+}
+/** The frontmatter block with its fences and the line break after them, byte for byte; "" when there is none. */
+export function frontmatterBlock(text) {
+    const match = /^?---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/.exec(text);
+    return match ? match[0] : '';
+}
+/** The text after the frontmatter block. */
+export const bodyOf = (text) => text.slice(frontmatterBlock(text).length);
+export function unquote(value) {
+    return String(value).trim().replace(/^["']|["']$/g, '').trim();
+}
+/** One YAML list item: a quoted item ends at its closing quote; an unquoted one ends at ` #`. */
+export function cleanItem(value) {
+    const text = String(value).trim();
+    const quote = text[0];
+    if (quote === '"' || quote === "'") {
+        const end = text.indexOf(quote, 1);
+        if (end > 0)
+            return text.slice(1, end).trim();
+    }
+    const hash = text.search(/\s#/);
+    return unquote(hash >= 0 ? text.slice(0, hash) : text);
+}
+function parseInlineArray(raw) {
+    const end = raw.indexOf(']');
+    const body = (end >= 0 ? raw.slice(0, end) : raw).replace(/^\[/, '');
+    return body
+        .split(',')
+        .map((item) => cleanItem(item))
+        .filter(Boolean);
+}
+/** One frontmatter key: a scalar, an inline array, or a following `- item` block; undefined when absent. */
+export function field(block, key) {
+    const lines = block.split(/\r?\n/);
+    const head = new RegExp(`^${key}\\s*:\\s*(.*)$`);
+    for (let i = 0; i < lines.length; i++) {
+        const match = head.exec(lines[i]);
+        if (!match)
+            continue;
+        const raw = match[1].trim();
+        if (raw === '') {
+            const next = (lines[i + 1] ?? '').trim();
+            if (next.startsWith('[')) {
+                let joined = '';
+                for (let j = i + 1; j < lines.length; j++) {
+                    joined += (joined ? ' ' : '') + lines[j].trim();
+                    if (lines[j].includes(']'))
+                        break;
+                }
+                return parseInlineArray(joined);
+            }
+            const items = [];
+            for (let j = i + 1; j < lines.length; j++) {
+                const item = /^\s*-\s+(.*)$/.exec(lines[j]);
+                if (!item)
+                    break;
+                items.push(cleanItem(item[1]));
+            }
+            return items;
+        }
+        if (raw.startsWith('['))
+            return parseInlineArray(raw);
+        return unquote(raw);
+    }
+    return undefined;
+}
+/** A scalar, list or absent field as a clean string list. */
+export function asList(value) {
+    if (value == null)
+        return [];
+    return (Array.isArray(value) ? value : [value]).map((item) => String(item).trim()).filter(Boolean);
+}

package/dist/vendor/harness/lib/paths.js

@@ -0,0 +1,31 @@
+// packages/harness/src/lib/paths.ts - The one spelling of a relative path the package accepts, and the posix
+// helpers the Worker-safe modules use instead of node:path. docs/architecture/systems/harness-compiler.md speaks for it.
+/** True for a non-empty `/`-joined relative path: no leading slash, drive letter or backslash, no `.`, `..` or empty segment. */
+export function isSafeRelativePath(path) {
+    if (typeof path !== 'string' || path.length === 0 || path.length > 1024)
+        return false;
+    if (path.includes('\\') || path.includes('\0') || path.startsWith('/') || /^[A-Za-z]:/.test(path))
+        return false;
+    return path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}
+/** Resolves `relative` against the folder `base` (both `/`-joined, repository-relative); null when it climbs out. */
+export function joinPosix(base, relative) {
+    const parts = base === '' ? [] : base.split('/');
+    for (const segment of relative.split('/')) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..') {
+            if (parts.length === 0)
+                return null;
+            parts.pop();
+        }
+        else
+            parts.push(segment);
+    }
+    return parts.join('/');
+}
+export const dirnamePosix = (path) => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '');
+export const basenamePosix = (path) => path.slice(path.lastIndexOf('/') + 1);
+export const depthOf = (path) => path.split('/').length;
+/** Sorts by path in code-unit order, the order the content digest is defined over. */
+export const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);

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