@nurix/nustack 0.23.9 → 0.23.10

package/dist/lib/local_store/routing.js

@@ -0,0 +1,137 @@
+export const ROUTING_LATCH_LIMIT = 2;
+export const ROUTING_JOB_KINDS = ["read.bulk", "lane.subagent"];
+export const LABEL_ROW_HANDLERS = [
+    "outline",
+    "bypass",
+    "digest",
+    "full_read",
+    "local_model",
+    "redirect",
+    "pack_hit",
+    "pack_miss",
+];
+export const LABEL_ROW_CHECK_RESULTS = ["pass", "fail", "budget", "unavailable", "latched"];
+export const LABEL_ROW_ID_MAX = 128;
+export const LABEL_ROW_PATH_MAX = 512;
+export const LABEL_ROW_SYNC_STATES = ["pending", "synced", "refused", "local"];
+export const GATED_PATH_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
+export class LabelRowRefusedError extends Error {
+    code = "LABEL_ROW_REFUSED";
+    constructor(message) {
+        super(message);
+        this.name = "LabelRowRefusedError";
+    }
+}
+function isOneOf(values, value) {
+    return typeof value === "string" && values.includes(value);
+}
+function requireIdentifier(field, value) {
+    if (typeof value !== "string" || value.length < 1 || value.length > LABEL_ROW_ID_MAX) {
+        throw new LabelRowRefusedError(`${field} must be 1-${LABEL_ROW_ID_MAX} characters`);
+    }
+}
+function requireInteger(field, value, isSigned) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || (!isSigned && value < 0)) {
+        throw new LabelRowRefusedError(`${field} must be a${isSigned ? "n" : " non-negative"} integer`);
+    }
+}
+export function clipLabelRowPath(path) {
+    return path.length <= LABEL_ROW_PATH_MAX ? path : `…${path.slice(path.length - (LABEL_ROW_PATH_MAX - 1))}`;
+}
+export function insertLabelRow(store, row, syncState = "pending") {
+    requireIdentifier("id", row.id);
+    requireIdentifier("session_id", row.session_id);
+    requireIdentifier("agent_type", row.agent_type);
+    if (!isOneOf(LABEL_ROW_HANDLERS, row.handler))
+        throw new LabelRowRefusedError(`unknown handler "${String(row.handler)}"`);
+    if (row.check_result !== null && !isOneOf(LABEL_ROW_CHECK_RESULTS, row.check_result)) {
+        throw new LabelRowRefusedError(`unknown check result "${String(row.check_result)}"`);
+    }
+    if (!isOneOf(LABEL_ROW_SYNC_STATES, syncState))
+        throw new LabelRowRefusedError(`unknown sync state "${String(syncState)}"`);
+    if (row.bypass_used !== 0 && row.bypass_used !== 1)
+        throw new LabelRowRefusedError("bypass_used must be 0 or 1");
+    if (row.path !== null && typeof row.path !== "string")
+        throw new LabelRowRefusedError("path must be a string or null");
+    requireInteger("estimated_tokens", row.estimated_tokens, false);
+    requireInteger("returned_tokens", row.returned_tokens, false);
+    requireInteger("latency_ms", row.latency_ms, false);
+    requireInteger("tokens_kept_out", row.tokens_kept_out, true);
+    requireInteger("created_at", row.created_at, false);
+    store.db
+        .prepare(`INSERT INTO label_rows (id, session_id, agent_type, path, estimated_tokens, returned_tokens, handler,
+                check_result, bypass_used, latency_ms, tokens_kept_out, created_at, sync_state)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(row.id, row.session_id, row.agent_type, row.path === null ? null : clipLabelRowPath(row.path), row.estimated_tokens, row.returned_tokens, row.handler, row.check_result, row.bypass_used, row.latency_ms, row.tokens_kept_out, row.created_at, syncState);
+}
+export function labelRowWire(record) {
+    return {
+        id: record.id,
+        sessionId: record.session_id,
+        agentType: record.agent_type,
+        path: record.path,
+        estimatedTokens: record.estimated_tokens,
+        returnedTokens: record.returned_tokens,
+        handler: record.handler,
+        checkResult: record.check_result,
+        isBypassUsed: record.bypass_used === 1,
+        latencyMs: record.latency_ms,
+        tokensKeptOut: record.tokens_kept_out,
+        createdAt: record.created_at,
+    };
+}
+export function listPendingLabelRows(store, limit) {
+    return store.db
+        .prepare("SELECT * FROM label_rows WHERE sync_state = 'pending' ORDER BY created_at, id LIMIT ?")
+        .all(limit);
+}
+function markPending(store, ids, state) {
+    if (ids.length === 0)
+        return 0;
+    const placeholders = ids.map(() => "?").join(", ");
+    const result = store.db
+        .prepare(`UPDATE label_rows SET sync_state = ? WHERE sync_state = 'pending' AND id IN (${placeholders})`)
+        .run(state, ...ids);
+    return Number(result.changes);
+}
+export function markLabelRowsSynced(store, ids) {
+    return markPending(store, ids, "synced");
+}
+export function markLabelRowsRefused(store, ids) {
+    return markPending(store, ids, "refused");
+}
+export function isLatched(store, sessionId, jobKind) {
+    const row = store.db
+        .prepare("SELECT latched_at FROM routing_latch WHERE session_id = ? AND job_kind = ?")
+        .get(sessionId, jobKind);
+    return row?.latched_at != null;
+}
+export function recordRoutingMiss(store, sessionId, jobKind, miss, now = Date.now()) {
+    if (!isOneOf(ROUTING_JOB_KINDS, jobKind))
+        throw new Error(`unknown routing job kind "${String(jobKind)}"`);
+    const failures = miss === "failure" ? 1 : 0;
+    const budgetMisses = miss === "budget" ? 1 : 0;
+    store.db
+        .prepare(`INSERT INTO routing_latch (session_id, job_kind, failures, budget_misses, latched_at)
+             VALUES (?, ?, ?, ?, NULL)
+             ON CONFLICT (session_id, job_kind) DO UPDATE SET
+                failures = failures + excluded.failures,
+                budget_misses = budget_misses + excluded.budget_misses`)
+        .run(sessionId, jobKind, failures, budgetMisses);
+    store.db
+        .prepare(`UPDATE routing_latch SET latched_at = ?
+             WHERE session_id = ? AND job_kind = ? AND latched_at IS NULL AND failures + budget_misses >= ?`)
+        .run(now, sessionId, jobKind, ROUTING_LATCH_LIMIT);
+}
+export function isPathGated(store, sessionId, path) {
+    return store.db.prepare("SELECT 1 FROM gated_paths WHERE session_id = ? AND path = ?").get(sessionId, path) !== undefined;
+}
+export function gatePathOnce(store, sessionId, path, now = Date.now()) {
+    const result = store.db
+        .prepare("INSERT INTO gated_paths (session_id, path, gated_at) VALUES (?, ?, ?) ON CONFLICT (session_id, path) DO NOTHING")
+        .run(sessionId, path, now);
+    const isInserted = Number(result.changes) === 1;
+    if (isInserted)
+        store.db.prepare("DELETE FROM gated_paths WHERE gated_at < ?").run(now - GATED_PATH_RETENTION_MS);
+    return isInserted;
+}

package/dist/program.js

@@ -0,0 +1,491 @@
+import { readFileSync } from "node:fs";
+import { Command } from "commander";
+import { runLogin } from "./commands/login.js";
+import { runInit } from "./commands/init.js";
+import { runAdd } from "./commands/add.js";
+import { runList } from "./commands/list.js";
+import { runSync } from "./commands/sync.js";
+import { runDescribe } from "./commands/describe.js";
+import { runValidate } from "./commands/validate.js";
+import { runGraph } from "./commands/graph.js";
+import { runLogscope } from "./commands/logscope.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runTokenCreate, runTokenList, runTokenRevoke } from "./commands/token.js";
+import { runOpen } from "./commands/open.js";
+import { runBootstrap } from "./commands/bootstrap.js";
+import { runLogout } from "./commands/logout.js";
+import { runTelemetry } from "./commands/telemetry.js";
+import { runSearch, runSearchServices } from "./commands/search.js";
+import { runDeviceList, runDeviceRevoke, runDeviceStatus } from "./commands/device.js";
+import { registerProjectSyncCommands } from "./commands/project-sync.js";
+import { registerProjectCommands } from "./commands/project.js";
+import { registerDeployCommands, registerLogsCommand, registerProjectSetCommand } from "./commands/deploy.js";
+import { registerActivityCommand } from "./commands/activity.js";
+import { registerWhoamiCommand } from "./commands/whoami.js";
+import { registerApiCommand } from "./commands/api.js";
+import { registerMcpCommands } from "./commands/mcp.js";
+import { NON_INTERACTIVE_VARIABLE } from "./lib/interactive.js";
+import { runOrganizationList, runOrganizationCreate, runOrganizationUse } from "./commands/organization.js";
+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 { registerRecordsCommands, startDrainIfDue } from "./commands/records.js";
+import { isPartCheckStale, startTelemetryReconcile } from "./lib/telemetry/part_state.js";
+import { RECORD_ALIAS_GROUPS, registerRecordAliases } from "./commands/recordAliases.js";
+import { runAgentContext, runAgentHookInstall, runAgentHookRemove } from "./commands/agent.js";
+import { runCensus } from "./commands/census.js";
+import { runGateInstall, runGateRemove, runGateStatus } from "./commands/gate.js";
+import { HOOK_SUBCOMMANDS } from "./lib/gate/subcommands.js";
+import { printJsonError } from "./lib/json_output.js";
+import { setCliVersion } from "./lib/auth_grant.js";
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+setCliVersion(version);
+const program = new Command();
+program
+    .name("nustack")
+    .description("Bootstrap NuStack services into your repo via the NuStack discovery plane.")
+    .version(version)
+    .option("--nustack-url <url>", "NuStack base URL (defaults to $NUSTACK_URL, then the hosted instance)")
+    .option("--non-interactive", `never prompt — take the default or refuse with a coded error (also $${NON_INTERACTIVE_VARIABLE}=1)`)
+    .action(async () => runBootstrap(program.opts()));
+program.addHelpText("after", "\nRun `nustack` with no command to bootstrap: it checks your sign-in, runs login if needed, then init.");
+program
+    .command("login")
+    .description("Sign in with your browser; this machine's grant is saved to your OS keychain")
+    .option("--no-open", "don't auto-open the browser; just print the sign-in URL")
+    .option("--manual", "sign in anywhere and paste the code here instead of using a browser on this machine")
+    .option("--force", "sign in again even if this machine is already signed in")
+    .action(async (options) => runLogin(program.opts(), options));
+program
+    .command("logout")
+    .description("Sign out: end this machine's grant and clear the shared keychain credential (both CLI and desktop)")
+    .option("--forget-device", "also clear the shared ~/.nustack/device_id machine identity")
+    .action(async (options) => runLogout(program.opts(), { forgetDevice: options.forgetDevice }));
+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("--yes", "pre-confirm the populated-folder onboarding guard")
+    .action(async (options) => runInit({ ...program.opts(), ...options }));
+program
+    .command("add [service]")
+    .description("Record a stack service in this repo: install its package, add the consumes edge")
+    .option("--json", "emit the versioned machine envelope instead of interactive output")
+    .option("--yes", "assume yes for the package-install and manifest-scaffold prompts")
+    .action(async (service, options) => runAdd(service, { ...program.opts(), ...options }));
+program
+    .command("list")
+    .description("List the services in the NuStack catalogue")
+    .option("--json", "emit the versioned machine envelope wrapping the catalogue entries")
+    .action(async (options) => runList(options, program.opts()));
+program
+    .command("sync")
+    .description("Project this Project's Service credentials into the managed .env block (not Documents or Git)")
+    .option("--project <id>", "the Project to act as (defaults to nustack.service.json / NUSTACK_WORKSPACE_ID)")
+    .option("--json", "emit the versioned machine envelope instead of interactive output")
+    .action(async (options) => runSync({ ...program.opts(), ...options }));
+program
+    .command("describe <service>")
+    .description("Show the full catalogue entry for a service")
+    .option("--json", "emit the raw catalogue entry as JSON")
+    .action(async (service, options) => runDescribe(service, options, program.opts()));
+program
+    .command("validate [manifest]")
+    .description("Validate an nustack.service.json (path or URL) against the nustack.dev/v1 schema")
+    .option("--schema <pathOrUrl>", "override the bundled packages/contracts/spec/schema.json")
+    .option("--json", "emit the versioned machine envelope with { target, isValid, errors }")
+    .action(async (manifest, options) => runValidate(manifest, options));
+program
+    .command("graph [fn] [args...]")
+    .description("The code graph: ask a question of this repository's index, or `index` / `status` / `functions`")
+    .option("--repo <pathOrId>", "the repository to ask about (default: the working tree's root)")
+    .option("--no-refresh", "answer from the index as it stands, however old")
+    .option("--budget <n>", "token ceiling for the answer; 0 means unbounded")
+    .option("--commits <n>", "history depth for `graph index` (default 5000)")
+    .option("--json", "emit the versioned machine envelope with the answer as data")
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .action(async (_fn, _args, options) => runGraph(process.argv, options));
+program
+    .command("logscope [fn] [args...]")
+    .description("Log tracking: ask this machine's log corpus a question, or `index` / `corpora` / `allow` / `prune`")
+    .option("--root <dir>", "the project this command is about (default: the working tree's root)")
+    .option("--corpus <ref>", "a corpus id, or a path belonging to one")
+    .option("--budget <n>", "token ceiling for the answer; 0 means unbounded")
+    .option("--limit <n>", "rows requested — beats a default budget, never an explicit one")
+    .option("--retain <days>", "retention for `index`; 0 keeps the corpus until it is forgotten")
+    .option("--examples", "keep up to three exemplar log lines per template (off by default)")
+    .option("--no-redact", "store exemplars unredacted (loud, recorded on the corpus)")
+    .option("--since <ts>", "window start for container sources")
+    .option("--until <ts>", "window end for container sources")
+    .option("--revision <sha>", "the source revision these logs were written by")
+    .option("--note <text>", "a note recorded with an `allow` grant")
+    .option("--dry-run", "for `prune`: report what would be dropped and delete nothing")
+    .option("--json", "emit the versioned machine envelope with the answer as data")
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .action(async (_fn, _args, options) => runLogscope(process.argv, options));
+program
+    .command("doctor")
+    .description("Run the full local diagnostics matrix (identity, repository, manifests, toolkit, telemetry, credentials)")
+    .option("--project <id>", "the Project to diagnose (defaults to the bound repository)")
+    .option("--json", "emit the versioned machine envelope (secrets and absolute paths redacted)")
+    .option("--local-verbose", "include Device-local absolute paths in the output")
+    .action(async (options) => runDoctor({ ...program.opts(), ...options }));
+registerDeployCommands(program, () => program.opts());
+registerLogsCommand(program, () => program.opts());
+registerWhoamiCommand(program, () => program.opts());
+registerApiCommand(program, () => program.opts());
+registerMcpCommands(program, () => program.opts());
+program
+    .command("open <service>")
+    .description("Open the service's dev endpoint (or repository) in the browser")
+    .option("--env <name>", "pick a specific endpoint environment (default: dev)")
+    .option("--json", "print the resolved URL as the machine envelope instead of launching")
+    .action(async (service, options) => runOpen(service, options, program.opts()));
+const token = program.command("token").description("Mint, list and revoke your personal access tokens (the NUSTACK_TOKEN a pipeline or agent uses)");
+token
+    .command("create")
+    .description("Mint a personal access token; the secret is printed once, on stdout alone")
+    .requiredOption("--label <label>", "a name for the token, unique among your live ones")
+    .option("--expires <days>", "days until the token expires (1–365); no expiry when omitted")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runTokenCreate(options, program.opts()));
+token
+    .command("list")
+    .description("List your personal access tokens (never a secret)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runTokenList(options, program.opts()));
+token
+    .command("revoke <token-id>")
+    .description("Revoke a personal access token; it stops working on the next request")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (tokenId, options) => runTokenRevoke(tokenId, options, program.opts()));
+const device = program.command("device").description("Inspect your signed-in devices and end this machine's access");
+device
+    .command("list")
+    .description("List your signed-in devices (never a token)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runDeviceList(options, program.opts()));
+device
+    .command("status")
+    .description("Show this device's local state merged with its server record")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runDeviceStatus(options, program.opts()));
+device
+    .command("revoke [device-id]")
+    .description("End this machine's access (other machines are revoked from Profile › Devices)")
+    .option("--json", "emit the versioned machine envelope")
+    .option("--yes", "skip the confirmation prompt")
+    .action(async (deviceId, options) => runDeviceRevoke(deviceId, options, program.opts()));
+program
+    .command("telemetry [action]")
+    .description("Inspect or control telemetry (status | enable | disable | reinstall | output | reconcile). Inside a bound folder, enable/disable move that folder alone; output points the shipper at your own Elastic, its key read from NUSTACK_ELASTIC_API_KEY; reconcile asks the server for each project's telemetry part")
+    .option("--json", "emit the versioned machine envelope")
+    .option("--device", "move this machine's switch instead of the current folder's")
+    .option("--local-verbose", "include each folder's absolute path (local consumers only — never pipe into a log)")
+    .option("--elastic-url <url>", "output: the Elastic endpoint (default NUSTACK_ELASTIC_URL)")
+    .option("--index <name>", "output: the index events are written to (default claude-sessions)")
+    .option("--quiet", "reconcile: print nothing")
+    .action(async (action, options) => {
+    const allowed = ["status", "enable", "disable", "reinstall", "output", "reconcile"];
+    const chosen = (allowed.includes(action ?? "") ? action : "status");
+    return runTelemetry(chosen, {
+        ...program.opts(),
+        json: options.json,
+        device: options.device,
+        localVerbose: options.localVerbose,
+        elasticUrl: options.elasticUrl,
+        index: options.index,
+        quiet: options.quiet,
+    });
+});
+const toLimit = (value) => Number.parseInt(value, 10);
+const search = program
+    .command("search [keywords...]")
+    .description("Search the NuStack Directory for projects by keyword")
+    .option("--json", "emit the raw results array as JSON")
+    .option("--category <cat>", "filter projects by category")
+    .option("--limit <n>", "max results (default 20)", toLimit)
+    .action(async (keywords, options) => runSearch(keywords, options, program.opts()));
+search
+    .command("services [keywords...]")
+    .description("Search the services registry by keyword (then `nustack add <name>` to integrate)")
+    .option("--json", "emit the raw results array as JSON")
+    .option("--type <type>", "filter services by type")
+    .option("--limit <n>", "max results (default 20)", toLimit)
+    .action(async (keywords, options) => runSearchServices(keywords, { ...search.opts(), ...options }, program.opts()));
+search.addHelpText("after", '\n`services` is a reserved subcommand. To search projects for the literal word "services", use the\n' +
+    "explicit separator: `nustack search -- services` (everything after `--` is an projects query).");
+const organization = program.command("organization").description("Work with your NuStack Organizations");
+organization
+    .command("list")
+    .description("List your Organization memberships (name, slug, role, active marker)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runOrganizationList(options, program.opts()));
+organization
+    .command("create <name>")
+    .description("Create an Organization and print it")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (name, options) => runOrganizationCreate(name, options, program.opts()));
+organization
+    .command("use <id-or-slug>")
+    .description("Set the active Organization context for this device")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (target, options) => runOrganizationUse(target, options, program.opts()));
+const project = program.command("project").description("Work with NuStack Projects");
+registerProjectCommands(project, () => program.opts());
+registerProjectSetCommand(project, () => program.opts());
+registerActivityCommand(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());
+registerRecordAliases(program, () => program.opts());
+const LOCAL_ONLY_COMMANDS = ["census"];
+const UNDRAINED_GROUPS = ["records", "gate", ...RECORD_ALIAS_GROUPS];
+program.hook("preAction", async (_program, action) => {
+    if (program.opts().nonInteractive)
+        process.env[NON_INTERACTIVE_VARIABLE] = "1";
+    if (action.parent === program && LOCAL_ONLY_COMMANDS.includes(action.name()))
+        return;
+    const group = action.parent?.name() ?? "";
+    if (!UNDRAINED_GROUPS.includes(group))
+        await startDrainIfDue(program.opts());
+    if (action.name() !== "telemetry" && isPartCheckStale())
+        startTelemetryReconcile({ nustackUrl: program.opts().nustackUrl });
+});
+const docs = program.command("docs").description("Work with a Project's Documents");
+docs
+    .command("list")
+    .description("List the Project's Documents")
+    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runDocsList(options, program.opts()));
+docs
+    .command("show <slug-or-id>")
+    .description("Show a Document: a bounded inline body or its content URL")
+    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (target, options) => runDocsShow(target, options, program.opts()));
+docs
+    .command("status")
+    .description("Report per-path local/cloud Document convergence for the bound repository")
+    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runDocsStatus(options, program.opts()));
+const handoff = program.command("handoff").description("Work with a Project's Handoffs");
+handoff
+    .command("list")
+    .description("List the Project's Handoffs")
+    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runHandoffList(options, program.opts()));
+handoff
+    .command("show <id>")
+    .description("Show a Handoff (add --targets for the binding-scoped per-target manifest)")
+    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
+    .option("--targets", "list each target's path, operation, and base semantics")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (id, options) => runHandoffShow(id, options, program.opts()));
+const sessions = program
+    .command("sessions")
+    .description("Sessions on this machine — the engine the desktop drives, and the record of what ran");
+sessions
+    .command("serve")
+    .description("Run the long-lived session supervisor: JSONL frames on stdin/stdout (used by the NuStack desktop)")
+    .action(async () => runSessionsServe(version));
+sessions
+    .command("record")
+    .description("Record the sessions one desktop scan found in a bound folder (used by the NuStack desktop)")
+    .option("--scan <json>", "the scan payload as JSON, or @<path> to read it from a file")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runSessionsRecord(options, program.opts()));
+sessions
+    .command("list")
+    .description("List the sessions this machine's engine opened, and what each one's worktree and branch still hold")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runSessionsList(options));
+sessions
+    .command("prune")
+    .description("Reclaim the worktree and branch of a session that has ended (preview unless --yes)")
+    .option("--session <id>", "reclaim one session instead of every reclaimable one")
+    .option("--yes", "apply the preview without prompting")
+    .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")
+    .description("Compare the cloud pin against .nustack/workspace.json and nustack.service.json (F-026)")
+    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runToolkitStatus(options, program.opts()));
+toolkit
+    .command("reconcile")
+    .description("Preview and apply the deterministic toolkit repair (no User content is touched)")
+    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
+    .option("--yes", "apply the deterministic preview without prompting")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runToolkitReconcile(options, program.opts()));
+const agent = program.command("agent").description("The discovery hook an agent uses to find the running NuStack desktop");
+agent
+    .command("context")
+    .description("Print the SessionStart hook payload when the NuStack desktop is reachable (silent otherwise)")
+    .action(async () => runAgentContext());
+const agentHook = agent.command("hook").description("Manage the `nustack agent context` SessionStart hook in ~/.claude/settings.json");
+agentHook
+    .command("install")
+    .description("Register the SessionStart hook (idempotent — a second install is a no-op)")
+    .action(async () => runAgentHookInstall());
+agentHook
+    .command("remove")
+    .description("Remove exactly the managed SessionStart hook entry")
+    .action(async () => runAgentHookRemove());
+program
+    .command("census")
+    .description("Measure where your Claude Code tokens go, from your own transcripts, and recommend the large-read gate's threshold")
+    .option("--root <dir>", "the transcript root (default ~/.claude/projects)")
+    .option("--since <date>", "only sessions changed on or after this date (YYYY-MM-DD)")
+    .option("--max-sessions <n>", "only the most recently changed n sessions")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runCensus(options));
+const gate = program.command("gate").description("The large-read gate: answer a large full read with an outline, once per session");
+for (const subcommand of HOOK_SUBCOMMANDS) {
+    gate.command(subcommand)
+        .description(`Claude Code PreToolUse hook entry point (${subcommand}); reads the hook JSON on stdin`)
+        .action(async () => {
+        const { runGateHook } = await import("./lib/gate/hook.js");
+        await runGateHook(subcommand);
+    });
+}
+gate.command("install")
+    .description("Register the gate's Read and Bash hooks in ~/.claude/settings.json (idempotent)")
+    .action(async () => runGateInstall());
+gate.command("remove")
+    .description("Remove exactly the gate's Read and Bash hook entries")
+    .action(async () => runGateRemove());
+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));
+function describeError(error) {
+    const directCode = error?.code;
+    if (directCode === "PROJECT_CONTEXT_MISSING") {
+        return "no Project in context — run inside a bound repository (`.nustack/workspace.json`) or pass `--project <id>`.";
+    }
+    if (directCode === "ORGANIZATION_CONTEXT_MISSING") {
+        return "no Organization in context — run `nustack organization use <id>` or pass `--organization <id>`.";
+    }
+    if (directCode === "TOOLKIT_INCOMPATIBLE") {
+        return "the installed toolkit is incompatible with the Project's cloud pin — run `nustack toolkit reconcile`.";
+    }
+    const cause = error?.cause;
+    const code = cause?.code;
+    if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+        return "couldn't resolve the NuStack host — check your connection or pass --nustack-url.";
+    }
+    if (code === "ECONNREFUSED") {
+        return "the NuStack host refused the connection — is it up? Override with --nustack-url.";
+    }
+    if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
+        return "the request to NuStack timed out — check your connection or try again.";
+    }
+    if (error instanceof Error && error.message === "fetch failed") {
+        return "couldn't reach NuStack — check your connection or pass --nustack-url.";
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function searchSeparatorInvocation(rawArgv) {
+    const args = rawArgv.slice(2);
+    const searchIdx = args.indexOf("search");
+    if (searchIdx === -1)
+        return null;
+    if (searchIdx > 0 && args[searchIdx - 1] === "--nustack-url")
+        return null;
+    let cut = searchIdx + 1;
+    while (cut < args.length) {
+        const token = args[cut] ?? "";
+        if (token === "--category" || token === "--limit" || token === "--nustack-url") {
+            cut += 2;
+        }
+        else if (token.startsWith("--") && token !== "--") {
+            cut += 1;
+        }
+        else {
+            break;
+        }
+    }
+    if (args[cut] !== "--")
+        return null;
+    const beforeSeparator = args.slice(0, cut);
+    const literalKeywords = args.slice(cut + 1);
+    return {
+        run: async () => {
+            const scoped = new Command();
+            scoped.exitOverride();
+            scoped.name("nustack").option("--nustack-url <url>", "");
+            scoped
+                .command("search [keywords...]")
+                .option("--json", "")
+                .option("--category <cat>", "")
+                .option("--limit <n>", "", toLimit)
+                .action(async (keywords, options) => runSearch(keywords, options, scoped.opts()));
+            await scoped.parseAsync(["node", "nustack", ...beforeSeparator, ...literalKeywords]);
+        },
+    };
+}
+function isJsonInvocation(argv) {
+    return argv.slice(2).includes("--json");
+}
+function commandLabelFromArgv(argv) {
+    const args = argv.slice(2);
+    const parts = [];
+    for (let i = 0; i < args.length; i++) {
+        const token = args[i] ?? "";
+        if (token === "--nustack-url") {
+            i++;
+            continue;
+        }
+        if (token.startsWith("-"))
+            break;
+        parts.push(token);
+    }
+    return parts.length ? parts.join(" ") : "nustack";
+}
+function errorCodeOf(error) {
+    const direct = error?.code ?? error?.cause?.code;
+    return typeof direct === "string" ? direct : "UNEXPECTED";
+}
+try {
+    const separated = searchSeparatorInvocation(process.argv);
+    if (separated)
+        await separated.run();
+    else
+        await program.parseAsync(process.argv);
+}
+catch (error) {
+    if (isJsonInvocation(process.argv)) {
+        printJsonError(commandLabelFromArgv(process.argv), { code: errorCodeOf(error), message: describeError(error) });
+    }
+    else {
+        console.error(`nustack: ${describeError(error)}`);
+        process.exitCode = 1;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/nustack",
-  "version": "0.23.9",
+  "version": "0.23.10",
   "description": "The nustack CLI — bootstrap NuStack services into a repo via the NuStack discovery plane.",
   "type": "module",
   "private": false,
@@ -35,8 +35,8 @@
     "@types/node": "^22.19.20",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@nurix/nustack.studio": "0.0.0",
     "@nurix/contracts": "2.0.1",
+    "@nurix/nustack.studio": "0.0.0",
     "@nurix/nustack.ui": "0.0.0"
   },
   "publishConfig": {