@nurix/nustack 0.23.13 → 0.23.15

package/dist/lib/sessions/brief.js

@@ -0,0 +1,102 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { ensureAccessToken } from "../auth_grant.js";
+import { briefCachePath } from "../local_store/paths.js";
+import { assertCredentialOrigin } from "../nustack_client.js";
+import { resolveDoor } from "../records/door.js";
+export const BRIEF_FETCH_TIMEOUT_MS = 3_000;
+export const BRIEF_CONTEXT_CAP = 4_000;
+export const BRIEF_CONTEXT_OBLIGATIONS = 20;
+export const HANDOVER_LINE = "Before you finish, leave a handover for the next session: `nustack session end --handover -` with the note on stdin.";
+const EMPTY_BRIEF = { previousHandover: null, openObligations: { total: 0, items: [] }, generatedAt: "" };
+export function readCache(file) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return typeof parsed.fetchedAt === "string" && parsed.value !== undefined ? { fetchedAt: parsed.fetchedAt, value: parsed.value } : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCache(file, value) {
+    try {
+        mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        const temporary = `${file}.${process.pid}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify({ fetchedAt: new Date().toISOString(), value })}\n`, { mode: 0o600 });
+        renameSync(temporary, file);
+    }
+    catch {
+    }
+}
+export async function getFromDoor(root, globals, projectId, pathAndQuery, timeoutMs) {
+    try {
+        const door = await resolveDoor(root, globals, projectId);
+        if (door.kind !== "door")
+            return null;
+        await assertCredentialOrigin(door.doorUrl);
+        const auth = await ensureAccessToken();
+        if (!auth)
+            return null;
+        const response = await fetch(`${door.doorUrl}/api/v2/projects/${encodeURIComponent(projectId)}${pathAndQuery}`, {
+            headers: { authorization: `Bearer ${auth.accessToken}` },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        return body.data === undefined ? null : { data: body.data, meta: body.meta ?? null };
+    }
+    catch {
+        return null;
+    }
+}
+export async function readBrief(root, globals, projectId, sessionId, refusalCount) {
+    const query = sessionId ? `?sessionId=${encodeURIComponent(sessionId)}` : "";
+    const answered = await getFromDoor(root, globals, projectId, `/sessions/brief${query}`, BRIEF_FETCH_TIMEOUT_MS);
+    const cacheFile = briefCachePath(projectId);
+    if (answered && answered.data && typeof answered.data === "object") {
+        const brief = answered.data;
+        writeCache(cacheFile, brief);
+        return { ...brief, refusalCount, offline: null, source: "server" };
+    }
+    const cached = readCache(cacheFile);
+    const since = cached?.fetchedAt ?? new Date().toISOString();
+    return {
+        ...(cached?.value ?? EMPTY_BRIEF),
+        refusalCount,
+        offline: { since, durationMs: Math.max(0, Date.now() - Date.parse(since)) },
+        source: "cache",
+    };
+}
+function obligationLine(item) {
+    const claim = typeof item.payload.claim === "string" ? ` — ${item.payload.claim}` : "";
+    return `- ${item.naturalKey}${claim}`;
+}
+export function renderBrief(brief, options = {}) {
+    const lines = ["NuStack session brief"];
+    if (brief.offline)
+        lines.push(`(offline since ${brief.offline.since}; this is the cached brief)`);
+    if (brief.previousHandover) {
+        const runtime = brief.previousHandover.runtime ? ` (${brief.previousHandover.runtime.replace(/_/g, " ")})` : "";
+        lines.push("", `Previous handover${runtime}, ${brief.previousHandover.createdAt}:`, brief.previousHandover.handover);
+    }
+    else {
+        lines.push("", "No previous handover.");
+    }
+    const items = brief.openObligations.items.slice(0, options.obligationLimit ?? brief.openObligations.items.length);
+    lines.push("", `Open obligations: ${brief.openObligations.total}`);
+    for (const item of items)
+        lines.push(obligationLine(item));
+    if (brief.openObligations.total > items.length)
+        lines.push(`… and ${brief.openObligations.total - items.length} more (nustack obligation list --plan <anchor>)`);
+    if (brief.refusalCount > 0)
+        lines.push("", `Refused record writes on this device: ${brief.refusalCount} (nustack records list).`);
+    return lines.join("\n");
+}
+export function renderHookOutput(brief) {
+    const tail = `\n\n${HANDOVER_LINE}`;
+    let body = renderBrief(brief, { obligationLimit: BRIEF_CONTEXT_OBLIGATIONS });
+    if (body.length + tail.length > BRIEF_CONTEXT_CAP)
+        body = `${body.slice(0, BRIEF_CONTEXT_CAP - tail.length - 1)}…`;
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: `${body}${tail}` } });
+}

package/dist/lib/sessions/client.js

@@ -1,6 +1,28 @@
 import { assertSafeOpaqueId } from "../guards.js";
 import { apiError } from "../nustack_client.js";
 const REQUEST_TIMEOUT_MS = 10_000;
+export async function postSessionEvents(baseUrl, accessToken, projectId, request) {
+    let response;
+    try {
+        const safeId = assertSafeOpaqueId("The Project id", projectId);
+        response = await globalThis.fetch(`${baseUrl}/api/v2/projects/${encodeURIComponent(safeId)}/records/session-events`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+            body: JSON.stringify(request),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        return { ok: false, status: 0, code: null, message: `the door did not answer: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const body = (await response.json().catch(() => null));
+    if (!response.ok) {
+        const code = typeof body?.error?.code === "string" ? body.error.code : null;
+        const detail = typeof body?.error?.message === "string" ? body.error.message : `HTTP ${response.status}`;
+        return { ok: false, status: response.status, code, message: `${code ?? `HTTP ${response.status}`}: ${detail}` };
+    }
+    return { ok: true, landed: body?.data?.landed ?? 0, skipped: body?.data?.skipped ?? 0 };
+}
 export function makeSessionsClient(baseUrl, accessToken) {
     const headers = {
         Authorization: `Bearer ${accessToken}`,
@@ -34,6 +56,9 @@ export function makeSessionsClient(baseUrl, accessToken) {
         async setVendorSessionId(projectId, sessionId, vendorSessionId) {
             return this.transitionSession(projectId, sessionId, "running", { vendorSessionId });
         },
+        postSessionEvents(projectId, request) {
+            return postSessionEvents(baseUrl, accessToken, projectId, request);
+        },
     };
 }
 export function sessionsClientFromEnv(env = process.env) {

package/dist/lib/sessions/hookInput.js

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const text = (value) => (typeof value === "string" && value.trim() ? value.trim() : null);
+export function parseHookInput(raw) {
+    let parsed = null;
+    try {
+        parsed = raw.trim() ? JSON.parse(raw) : null;
+    }
+    catch {
+        parsed = null;
+    }
+    const body = (parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {});
+    const model = text(body.model) ?? (body.model && typeof body.model === "object" ? text(body.model.id) : null);
+    return { sessionId: text(body.session_id), cwd: text(body.cwd), hookEventName: text(body.hook_event_name), model };
+}
+export function resolveModel(input, env = process.env, home = os.homedir()) {
+    if (input.model)
+        return input.model;
+    const fromEnv = text(env.ANTHROPIC_MODEL);
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const settings = JSON.parse(readFileSync(path.join(home, ".claude", "settings.json"), "utf8"));
+        return text(settings.model);
+    }
+    catch {
+        return null;
+    }
+}
+export async function readAllStdin() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}

package/dist/lib/sessions/memoryShip.js

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { memoryManifestPath } from "../local_store/paths.js";
+import { claudeProjectDir } from "../telemetry/provider_paths.js";
+function walk(root, relative = "") {
+    const files = [];
+    let names;
+    try {
+        names = readdirSync(path.join(root, relative));
+    }
+    catch {
+        return files;
+    }
+    for (const name of names.sort()) {
+        if (name.startsWith("."))
+            continue;
+        const next = relative ? `${relative}/${name}` : name;
+        const stat = lstatSync(path.join(root, next));
+        if (stat.isSymbolicLink())
+            continue;
+        if (stat.isDirectory())
+            files.push(...walk(root, next));
+        else if (stat.isFile())
+            files.push(next);
+    }
+    return files;
+}
+function readManifest(file) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeManifest(file, manifest) {
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, file);
+}
+export function memoryRootOf(repositoryRoot) {
+    return path.join(claudeProjectDir(repositoryRoot), "memory");
+}
+export async function shipChangedMemory(input, globals, write) {
+    const result = { written: 0, refused: 0, unchanged: 0 };
+    try {
+        const memoryRoot = memoryRootOf(input.repositoryRoot);
+        const manifestFile = memoryManifestPath(input.projectId);
+        const manifest = readManifest(manifestFile);
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        for (const relative of walk(memoryRoot)) {
+            const bytes = readFileSync(path.join(memoryRoot, relative));
+            const sha256 = createHash("sha256").update(bytes).digest("hex");
+            if (manifest[relative] === sha256) {
+                result.unchanged += 1;
+                continue;
+            }
+            let body;
+            try {
+                body = decoder.decode(bytes);
+            }
+            catch {
+                continue;
+            }
+            const outcome = await write({
+                command: "session end",
+                target: "session end --hook (memory)",
+                kind: "memory",
+                rows: [{ payload: { path: relative, body } }],
+                root: input.repositoryRoot,
+                project: input.projectId,
+                session: input.sessionId,
+                json: true,
+            }, globals);
+            if (outcome.ok)
+                result.written += outcome.data.written;
+            else
+                result.refused += 1;
+            manifest[relative] = sha256;
+            writeManifest(manifestFile, manifest);
+        }
+    }
+    catch {
+    }
+    return result;
+}

package/dist/lib/sessions/mountFacts.js

@@ -0,0 +1,42 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { loadHarness } from "../harness/vendor.js";
+const MOUNT_RUNTIME = {
+    claude_code: "claude-code",
+    codex: "codex",
+    opencode: "opencode",
+    copilot_cli: "copilot-cli",
+    nustack: null,
+};
+const NONE = { harnessSemver: null, harnessDigest: null, configDigest: null };
+const SHA256 = /^[0-9a-f]{64}$/;
+export async function mountFacts(root, runtime) {
+    const key = MOUNT_RUNTIME[runtime];
+    if (!key)
+        return NONE;
+    try {
+        const { readMountRecord } = await loadHarness("mount");
+        const { contentDigest } = await loadHarness("digest");
+        const record = readMountRecord(root);
+        const entry = record?.runtimes?.[key];
+        if (!record || !entry)
+            return NONE;
+        const harnessDigest = typeof record.digest === "string" && SHA256.test(record.digest) ? record.digest : SHA256.test(entry.digest) ? entry.digest : null;
+        const harnessSemver = typeof record.version === "string" ? record.version : entry.semver || null;
+        if (!harnessDigest)
+            return NONE;
+        const onDisk = [];
+        for (const file of entry.files ?? []) {
+            try {
+                onDisk.push({ path: file.path, content: readFileSync(path.join(root, file.path)) });
+            }
+            catch {
+            }
+        }
+        const recomputed = contentDigest(onDisk);
+        return { harnessSemver, harnessDigest, configDigest: recomputed === entry.treeDigest ? harnessDigest : recomputed };
+    }
+    catch {
+        return NONE;
+    }
+}

package/dist/lib/sessions/outsideSessions.js

@@ -33,6 +33,7 @@ export async function recordOutsideSessions(client, input) {
                 nustack: isEngineSession ? 1 : 0,
                 vendor: kinds.vendor,
                 renderer: kinds.renderer,
+                runtime: transcript.provider,
                 status: stale ? "done" : "running",
                 ...(vendorSessionId ? { vendorSessionId } : {}),
             });

package/dist/lib/sessions/sessionEvents.js

@@ -0,0 +1,203 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { ensureAccessToken } from "../auth_grant.js";
+import { sessionEventsDir } from "../local_store/paths.js";
+import { labelRowWire, listPendingLabelRows, markLabelRowsRefused, markLabelRowsSynced } from "../local_store/routing.js";
+import { RECORDS_BATCH_CAP, resolveDoor } from "../records/door.js";
+import { makeSessionsClient, postSessionEvents } from "./client.js";
+export const SESSION_SPOOL_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const SESSION_DRAIN_PASSES = 3;
+const spoolPath = (rowId) => path.join(sessionEventsDir(), `${rowId}.json`);
+export function readSpool(rowId) {
+    try {
+        const parsed = JSON.parse(readFileSync(spoolPath(rowId), "utf8"));
+        return parsed && typeof parsed.rowId === "string" && Array.isArray(parsed.pending) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSpool(spool) {
+    mkdirSync(sessionEventsDir(), { recursive: true, mode: 0o700 });
+    const target = spoolPath(spool.rowId);
+    const temporary = `${target}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(spool, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, target);
+}
+export function listSpools() {
+    if (!existsSync(sessionEventsDir()))
+        return [];
+    const spools = [];
+    for (const name of readdirSync(sessionEventsDir())) {
+        if (!name.endsWith(".json"))
+            continue;
+        const spool = readSpool(name.slice(0, -".json".length));
+        if (spool)
+            spools.push(spool);
+    }
+    return spools;
+}
+export function spoolEvent(identity, event, options = {}) {
+    const held = readSpool(identity.rowId);
+    const spool = {
+        ...identity,
+        runtimeSessionId: identity.runtimeSessionId ?? held?.runtimeSessionId ?? null,
+        pending: [...(held?.pending ?? []), ...(event ? [event] : [])],
+        isClosePending: (held?.isClosePending ?? false) || options.isClosePending === true,
+        lastSyncedAt: held?.lastSyncedAt ?? null,
+        lastEventAt: new Date().toISOString(),
+    };
+    writeSpool(spool);
+    return spool;
+}
+async function doorFor(root, globals, bearers) {
+    const door = await resolveDoor(root, globals).catch(() => null);
+    if (!door || door.kind !== "door")
+        return null;
+    if (!bearers.has(door.doorUrl)) {
+        bearers.set(door.doorUrl, await ensureAccessToken().then((auth) => auth?.accessToken ?? null, () => null));
+    }
+    const bearer = bearers.get(door.doorUrl) ?? null;
+    return bearer ? { doorUrl: door.doorUrl, bearer } : null;
+}
+const isRefusal = (outcome) => !outcome.ok && outcome.status === 400;
+export async function drainSessionEvents(globals, result, bearers = new Map()) {
+    for (const spool of listSpools()) {
+        if (spool.pending.length === 0 && !spool.isClosePending)
+            continue;
+        const door = await doorFor(spool.root, globals, bearers);
+        if (!door)
+            continue;
+        let pending = spool.pending;
+        if (pending.length > 0) {
+            const kept = [];
+            for (let start = 0; start < pending.length; start += RECORDS_BATCH_CAP) {
+                const batch = pending.slice(start, start + RECORDS_BATCH_CAP);
+                const outcome = await postSessionEvents(door.doorUrl, door.bearer, spool.projectId, { events: batch, labelRows: [] });
+                if (outcome.ok) {
+                    result.eventsSent += batch.length;
+                    continue;
+                }
+                result.lastError = outcome.message;
+                if (!isRefusal(outcome)) {
+                    kept.push(...batch);
+                    continue;
+                }
+                for (const event of batch) {
+                    const alone = await postSessionEvents(door.doorUrl, door.bearer, spool.projectId, { events: [event], labelRows: [] });
+                    if (alone.ok)
+                        result.eventsSent += 1;
+                    else if (isRefusal(alone))
+                        result.eventsDropped += 1;
+                    else
+                        kept.push(event);
+                }
+            }
+            const fresh = readSpool(spool.rowId) ?? spool;
+            pending = [...kept, ...fresh.pending.slice(spool.pending.length)];
+            writeSpool({ ...fresh, pending, lastSyncedAt: kept.length === 0 ? new Date().toISOString() : fresh.lastSyncedAt });
+        }
+        const current = readSpool(spool.rowId) ?? spool;
+        if (pending.length > 0 || current.pending.length > 0 || !current.isClosePending)
+            continue;
+        if (spool.isEngineSession) {
+            writeSpool({ ...(readSpool(spool.rowId) ?? spool), isClosePending: false });
+            continue;
+        }
+        try {
+            await makeSessionsClient(door.doorUrl, door.bearer).transitionSession(spool.projectId, spool.rowId, "done");
+            result.closed += 1;
+            writeSpool({ ...(readSpool(spool.rowId) ?? spool), isClosePending: false });
+        }
+        catch (error) {
+            const code = error.code;
+            if (typeof code === "string" && !["UNEXPECTED", "SIGNED_OUT", "RATE_LIMITED", "INTERNAL_ERROR"].includes(code)) {
+                writeSpool({ ...(readSpool(spool.rowId) ?? spool), isClosePending: false });
+            }
+            else {
+                result.lastError = error instanceof Error ? error.message : String(error);
+            }
+        }
+    }
+}
+function spoolOf(sessionId, spools) {
+    return spools.find((spool) => spool.rowId === sessionId) ?? spools.find((spool) => spool.runtimeSessionId === sessionId) ?? null;
+}
+export async function drainLabelRows(store, globals, result, bearers = new Map(), now = Date.now()) {
+    const rows = listPendingLabelRows(store, RECORDS_BATCH_CAP);
+    if (rows.length === 0)
+        return;
+    const spools = listSpools();
+    const groups = new Map();
+    const stale = [];
+    for (const record of rows) {
+        const spool = spoolOf(record.session_id, spools);
+        if (!spool) {
+            if (now - record.created_at > SESSION_SPOOL_RETENTION_MS)
+                stale.push(record.id);
+            continue;
+        }
+        const key = `${spool.root}\u0000${spool.projectId}`;
+        const group = groups.get(key) ?? { spool, rows: [] };
+        group.rows.push({ record, wire: { ...labelRowWire(record), sessionId: spool.rowId } });
+        groups.set(key, group);
+    }
+    if (stale.length > 0)
+        result.labelRowsRefused += markLabelRowsRefused(store, stale);
+    for (const { spool, rows: batch } of groups.values()) {
+        const door = await doorFor(spool.root, globals, bearers);
+        if (!door)
+            continue;
+        const request = { events: [], labelRows: batch.map((row) => row.wire) };
+        const outcome = await postSessionEvents(door.doorUrl, door.bearer, spool.projectId, request);
+        if (outcome.ok) {
+            result.labelRowsSynced += markLabelRowsSynced(store, batch.map((row) => row.record.id));
+            continue;
+        }
+        result.lastError = outcome.message;
+        if (!isRefusal(outcome))
+            continue;
+        for (const row of batch) {
+            const alone = await postSessionEvents(door.doorUrl, door.bearer, spool.projectId, { events: [], labelRows: [row.wire] });
+            if (alone.ok)
+                result.labelRowsSynced += markLabelRowsSynced(store, [row.record.id]);
+            else if (isRefusal(alone))
+                result.labelRowsRefused += markLabelRowsRefused(store, [row.record.id]);
+        }
+    }
+}
+export function pruneSpools(now = Date.now()) {
+    let pruned = 0;
+    for (const spool of listSpools()) {
+        if (spool.pending.length > 0 || spool.isClosePending)
+            continue;
+        if (now - Date.parse(spool.lastEventAt) <= SESSION_SPOOL_RETENTION_MS)
+            continue;
+        try {
+            unlinkSync(spoolPath(spool.rowId));
+            pruned += 1;
+        }
+        catch {
+        }
+    }
+    return pruned;
+}
+export async function drainSessionLegs(store, globals) {
+    const result = { eventsSent: 0, eventsDropped: 0, closed: 0, labelRowsSynced: 0, labelRowsRefused: 0, lastError: null };
+    const bearers = new Map();
+    try {
+        for (let pass = 0; pass < SESSION_DRAIN_PASSES; pass += 1) {
+            const before = result.eventsSent + result.eventsDropped + result.closed;
+            await drainSessionEvents(globals, result, bearers);
+            const isIdle = listSpools().every((spool) => spool.pending.length === 0 && !spool.isClosePending);
+            if (isIdle || result.eventsSent + result.eventsDropped + result.closed === before)
+                break;
+        }
+        await drainLabelRows(store, globals, result, bearers);
+        pruneSpools();
+    }
+    catch (error) {
+        result.lastError = error instanceof Error ? error.message : String(error);
+    }
+    return result;
+}

package/dist/lib/sessions/sessionKey.js

@@ -0,0 +1,16 @@
+import { createHash } from "node:crypto";
+const SESSION_KEY_LENGTH = 32;
+export function sessionRowIdOf(runtime, runtimeSessionId) {
+    return createHash("sha256").update(`${runtime}:${runtimeSessionId}`).digest("hex").slice(0, SESSION_KEY_LENGTH);
+}
+export const RUNTIME_VENDOR = {
+    claude_code: { vendor: "claude_code", renderer: "claude_transcript" },
+    codex: { vendor: "codex", renderer: "codex_transcript" },
+    opencode: { vendor: "opencode", renderer: "opencode_log" },
+    copilot_cli: { vendor: "nustack", renderer: "chat" },
+    nustack: { vendor: "nustack", renderer: "chat" },
+};
+export const HOOK_RUNTIMES = ["claude_code", "codex", "opencode", "copilot_cli", "nustack"];
+export function isSessionRuntime(value) {
+    return typeof value === "string" && HOOK_RUNTIMES.includes(value);
+}

package/dist/program.js

@@ -34,11 +34,13 @@ 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";
+import { registerSessionCommands } from "./commands/session.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 { 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";
@@ -248,7 +250,7 @@ registerReviewCommands(program.command("review").description("Read and mirror Nu
 registerRecordsCommands(program.command("records").description("Emit, send and list harness records"), () => program.opts());
 registerRecordAliases(program, () => program.opts());
 const LOCAL_ONLY_COMMANDS = ["census", "check"];
-const UNDRAINED_GROUPS = ["records", "gate", ...RECORD_ALIAS_GROUPS];
+const UNDRAINED_GROUPS = ["records", "gate", "session", "read", ...RECORD_ALIAS_GROUPS];
 program.hook("preAction", async (_program, action) => {
     if (program.opts().nonInteractive)
         process.env[NON_INTERACTIVE_VARIABLE] = "1";
@@ -326,6 +328,7 @@ 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));
+registerSessionCommands(program, () => program.opts());
 const harness = program.command("harness").description("Mount the Project's harness and compare it with the cloud pin");
 harness
     .command("mount [path]")
@@ -396,6 +399,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") {