@nurix/nustack 0.10.0-dev.18 → 0.10.0-dev.20

package/dist/commands/logscope.js

@@ -0,0 +1,55 @@
+import { answerLogscope, listLogscopeFunctions } from "../lib/logs/answer.js";
+import { loadLogscope } from "../lib/logs/library.js";
+import { allowSources, forgetCorpusCommand, indexLogs, listAllowed, listCorpora, pruneCorpora, revokeSources, } from "../lib/logs/lifecycle.js";
+export function logscopeArgv(rawArgv) {
+    const args = rawArgv.slice(2);
+    const at = args.indexOf("logscope");
+    return at === -1 ? [] : args.slice(at + 1);
+}
+const VALUED = ["--root", "--corpus", "--budget", "--retain", "--since", "--until", "--revision", "--note"];
+const BARE = ["--json", "--examples", "--no-redact", "--dry-run"];
+export function functionArgv(argv, fn) {
+    const valued = fn !== undefined && fn.args["limit"] !== undefined ? VALUED : [...VALUED, "--limit"];
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i] ?? "";
+        if (valued.includes(token)) {
+            i++;
+            continue;
+        }
+        if (valued.some((flag) => token.startsWith(`${flag}=`)))
+            continue;
+        if (BARE.includes(token))
+            continue;
+        out.push(token);
+    }
+    return out;
+}
+function positionals(argv) {
+    return functionArgv(argv)
+        .slice(1)
+        .filter((token) => !token.startsWith("--"));
+}
+export async function runLogscope(rawArgv, options, cwd = process.cwd()) {
+    const argv = logscopeArgv(rawArgv);
+    const fn = argv.find((token) => !token.startsWith("--"));
+    if (fn === undefined || fn === "functions")
+        return listLogscopeFunctions(options);
+    if (fn === "index")
+        return indexLogs(positionals(argv), options, cwd);
+    if (fn === "corpora")
+        return listCorpora(options);
+    if (fn === "allow")
+        return allowSources(positionals(argv), options, cwd);
+    if (fn === "allowed")
+        return listAllowed(options, cwd);
+    if (fn === "revoke")
+        return revokeSources(positionals(argv), options, cwd);
+    if (fn === "prune")
+        return pruneCorpora(options, cwd);
+    if (fn === "forget")
+        return forgetCorpusCommand(positionals(argv)[0], options);
+    const library = await loadLogscope();
+    const rest = functionArgv(argv, library.findFn(fn));
+    return answerLogscope(fn, rest.slice(1), options, cwd);
+}

package/dist/commands/review.js

@@ -8,16 +8,30 @@ const EXIT_FOR = {
     none: 1,
     unreachable: 2,
 };
+const latestAnswered = (items) => items.find((item) => item.answer?.verdict === "signed" || item.answer?.verdict === "refused");
 export function decisionStateOf(items) {
-    const latest = items.find((item) => item.answer?.verdict === "signed" || item.answer?.verdict === "refused");
+    const latest = latestAnswered(items);
     if (!latest)
         return "none";
     return latest.answer?.verdict === "signed" ? "signed" : "refused";
 }
-function checkLine(state, commit) {
+export function waivedKeysOf(items) {
+    const latest = latestAnswered(items);
+    if (latest?.answer?.verdict !== "signed")
+        return [];
+    const waivers = latest.answer.waivers;
+    if (!Array.isArray(waivers))
+        return [];
+    return waivers
+        .map((waiver) => waiver?.criterionKey)
+        .filter((key) => typeof key === "string" && key.length > 0);
+}
+function checkLine(state, commit, waived) {
     switch (state) {
         case "signed":
-            return `review check: ${commit} is signed off\n`;
+            return waived.length
+                ? `review check: ${commit} is signed off — ${waived.length} ${waived.length === 1 ? "criterion" : "criteria"} waived: ${waived.join(", ")}\n`
+                : `review check: ${commit} is signed off\n`;
         case "refused":
             return `review check: ${commit} was refused\n`;
         case "none":
@@ -34,11 +48,11 @@ export async function runReviewCheck(options, globals) {
         process.exitCode = 2;
         return;
     }
-    const report = (state) => {
+    const report = (state, waived = []) => {
         if (json)
-            printJsonSuccess("review check", { commit, state, exitCode: EXIT_FOR[state] });
+            printJsonSuccess("review check", { commit, state, exitCode: EXIT_FOR[state], waived });
         else
-            process.stdout.write(checkLine(state, commit));
+            process.stdout.write(checkLine(state, commit, waived));
         process.exitCode = EXIT_FOR[state];
     };
     const baseUrl = resolveNuStackUrl(globals);
@@ -47,7 +61,7 @@ export async function runReviewCheck(options, globals) {
         return report("unreachable");
     try {
         const items = await makeReviewClient(baseUrl, deviceAuth.accessToken).readDecisions(commit, options.repository?.trim() || null);
-        report(decisionStateOf(items));
+        report(decisionStateOf(items), waivedKeysOf(items));
     }
     catch (error) {
         if (error instanceof ReviewUnreachableError)
@@ -77,7 +91,16 @@ function readSubject(raw) {
         type: "tool_permission",
         toolName,
         displayName,
-        toolInput: row.toolInput ?? null,
+        ...(typeof row.target === "string" || row.target === null ? { target: row.target } : {}),
+        ...(typeof row.inputBytes === "number" && Number.isFinite(row.inputBytes)
+            ? { inputBytes: row.inputBytes }
+            : {}),
+        ...(Array.isArray(row.inputFields) && row.inputFields.every((field) => typeof field === "string")
+            ? { inputFields: row.inputFields }
+            : {}),
+        ...(typeof row.redactionVersion === "number" && Number.isFinite(row.redactionVersion)
+            ? { redactionVersion: row.redactionVersion }
+            : {}),
         ...(typeof row.description === "string" ? { description: row.description } : {}),
     };
 }
@@ -140,9 +163,9 @@ export function registerReviewCommands(reviewCommand, getGlobalOptions) {
         .action(async (options) => runReviewCheck(options, getGlobalOptions()));
     reviewCommand
         .command("mirror")
-        .description("Reflect a lane's permission prompt, or its answer, into the Review pane")
-        .option("--session <laneId>", "the lane's session id")
-        .option("--project <id>", "the Project the lane's folder is bound to (required with --state open)")
+        .description("Reflect a session's permission prompt, or its answer, into the Review pane")
+        .option("--session <sessionId>", "the session's id")
+        .option("--project <id>", "the Project the session's folder is bound to (required with --state open)")
         .option("--state <state>", "open or answered")
         .option("--subject <json>", "the tool-permission subject, as JSON (required with --state open)")
         .option("--verdict <verdict>", "allow or deny (required with --state answered)")

package/dist/commands/sessions.js

@@ -1,9 +1,25 @@
 import { readFile } from "node:fs/promises";
+import path from "node:path";
+import * as p from "@clack/prompts";
 import { ensureAccessToken } from "../lib/auth_grant.js";
+import { isInteractive } from "../lib/interactive.js";
 import { resolveNuStackUrl } from "../lib/nustack_client.js";
-import { makeSessionsClient } from "../lib/sessions/client.js";
+import { makeSessionsClient, sessionsClientFromEnv } from "../lib/sessions/client.js";
 import { recordOutsideSessions, } from "../lib/sessions/outsideSessions.js";
-import { printJsonSuccess } from "../lib/json_output.js";
+import { inspectSession, readOrphanedWorktrees, reclaimSession, } from "../lib/session-engine/prune.js";
+import { readSessionRegistry, sessionRegistryPath } from "../lib/session-engine/registry.js";
+import { SessionSupervisor } from "../lib/session-engine/supervisor.js";
+import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
+export async function runSessionsServe(engineVersion) {
+    const supervisor = new SessionSupervisor({
+        input: process.stdin,
+        output: process.stdout,
+        engineVersion,
+        sessions: sessionsClientFromEnv(process.env),
+    });
+    await supervisor.run();
+    process.exit(0);
+}
 async function readScanArgument(raw) {
     const body = raw.startsWith("@") ? await readFile(raw.slice(1), "utf8") : raw;
     return JSON.parse(body);
@@ -46,6 +62,10 @@ export async function runSessionsRecord(options, globals) {
     if (!options.scan)
         return report("sessions record", EMPTY, json, "no scan payload");
     const payload = (await readScanArgument(options.scan).catch(() => null));
+    if (payload && "laneSessionIds" in payload) {
+        process.stderr.write("sessions record: this NuStack desktop is older than this CLI: it sent laneSessionIds, which is now engineSessionIds. Update both.\n");
+        process.exit(1);
+    }
     const transcripts = readTranscripts(payload?.sessions);
     if (transcripts.length === 0)
         return report("sessions record", EMPTY, json, "nothing to record");
@@ -54,9 +74,140 @@ export async function runSessionsRecord(options, globals) {
         return report("sessions record", EMPTY, json, "signed out");
     const summary = await recordOutsideSessions(makeSessionsClient(baseUrl, deviceAuth.accessToken), {
         transcripts,
-        laneSessionIds: Array.isArray(payload?.laneSessionIds)
-            ? payload.laneSessionIds.filter((id) => typeof id === "string")
+        engineSessionIds: Array.isArray(payload?.engineSessionIds)
+            ? payload.engineSessionIds.filter((id) => typeof id === "string")
             : [],
     });
     report("sessions record", summary, json);
 }
+async function readSessions() {
+    const { records, dropped } = await readSessionRegistry();
+    const orphans = await readOrphanedWorktrees();
+    const sessions = [];
+    for (const record of [...records, ...orphans.records]) {
+        sessions.push({ record, facts: await inspectSession(record) });
+    }
+    return { sessions, unreadable: dropped, undecipherableOrphans: orphans.undecipherable };
+}
+function statusWord(entry) {
+    if (entry.facts.orphaned)
+        return "orphaned";
+    if (entry.facts.stale)
+        return "stale";
+    return entry.record.status;
+}
+function formatSessionRow(entry) {
+    const checkout = path.basename(entry.record.projectPath);
+    return (`${entry.record.sessionId.padEnd(38)} ${checkout.padEnd(22)} ${(entry.record.branch ?? "—").padEnd(31)} ` +
+        `${statusWord(entry).padEnd(10)} ${entry.facts.reason}`);
+}
+function toJsonView(entry) {
+    const { record, facts } = entry;
+    return {
+        sessionId: record.sessionId,
+        projectPath: record.projectPath,
+        worktreePath: record.worktreePath,
+        branch: record.branch,
+        status: record.status,
+        nustack: record.nustack,
+        createdAt: record.createdAt,
+        closedAt: record.closedAt ?? null,
+        permissionMode: record.permissionMode ?? null,
+        baseBranch: record.baseBranch ?? null,
+        isolated: facts.isolated,
+        checkoutPresent: facts.checkoutPresent,
+        worktreePresent: facts.worktreePresent,
+        branchExists: facts.branchExists,
+        reading: facts.reading,
+        dirty: facts.dirty,
+        stale: facts.stale,
+        orphaned: facts.orphaned,
+        reclaimable: facts.reclaimable,
+        reason: facts.reason,
+    };
+}
+export async function runSessionsList(options) {
+    const json = options.json === true;
+    const { sessions, unreadable, undecipherableOrphans } = await readSessions();
+    if (json) {
+        printJsonSuccess("sessions list", {
+            registryPath: sessionRegistryPath(),
+            unreadable,
+            undecipherableOrphans,
+            sessions: sessions.map(toJsonView),
+        });
+        return;
+    }
+    if (sessions.length === 0 && unreadable === 0 && undecipherableOrphans.length === 0) {
+        console.log("No engine-opened sessions on this machine.");
+        return;
+    }
+    if (sessions.length > 0) {
+        console.log(`${"SESSION".padEnd(38)} ${"CHECKOUT".padEnd(22)} ${"BRANCH".padEnd(31)} ${"STATUS".padEnd(10)} HOLDS`);
+        for (const entry of sessions)
+            console.log(formatSessionRow(entry));
+    }
+    if (unreadable > 0)
+        console.log(`${unreadable} row(s) in the registry could not be read and were skipped.`);
+    for (const orphan of undecipherableOrphans) {
+        console.log(`1 worktree under the pre-rename engine home names no checkout and must be removed by hand: ${orphan}.`);
+    }
+}
+function previewLine(entry) {
+    const verb = entry.facts.reclaimable ? "reclaim" : "refuse";
+    return `  ${verb}  ${entry.record.sessionId}  ${entry.record.branch ?? "—"}  — ${entry.facts.reason}`;
+}
+export async function runSessionsPrune(options) {
+    const json = options.json === true;
+    const force = options.force === true;
+    const { sessions } = await readSessions();
+    const scoped = options.session ? sessions.filter((entry) => entry.record.sessionId === options.session) : sessions;
+    if (options.session && scoped.length === 0) {
+        const message = `No session ${options.session} in this machine's registry — pass one from \`nustack sessions list\`.`;
+        if (json)
+            return printJsonError("sessions prune", { code: "SESSION_NOT_FOUND", message });
+        p.log.error(message);
+        process.exitCode = 1;
+        return;
+    }
+    const candidates = scoped.filter((entry) => force || entry.facts.reclaimable);
+    if (options.yes !== true) {
+        const plan = candidates.map((entry) => ({
+            sessionId: entry.record.sessionId,
+            branch: entry.record.branch,
+            worktreePath: entry.record.worktreePath,
+            orphaned: entry.facts.orphaned,
+            reclaimable: entry.facts.reclaimable,
+            reason: entry.facts.reason,
+        }));
+        if (json)
+            return printJsonSuccess("sessions prune", { applied: false, plan, note: "preview only — pass --yes to apply" });
+        if (plan.length === 0) {
+            console.log("Nothing to reclaim.");
+            return;
+        }
+        console.log(`Would reclaim ${plan.length} session(s):`);
+        for (const entry of candidates)
+            console.log(previewLine(entry));
+        if (!isInteractive()) {
+            console.log("Preview only — re-run with --yes to apply.");
+            return;
+        }
+        const answer = await p.confirm({ message: "Remove these worktrees and delete their branches?" });
+        if (p.isCancel(answer) || !answer) {
+            p.outro("Cancelled — nothing reclaimed.");
+            return;
+        }
+    }
+    const reclaimed = [];
+    const refused = [];
+    for (const entry of candidates) {
+        const outcome = await reclaimSession(entry.record, { force });
+        (outcome.reason === null ? reclaimed : refused).push(outcome);
+    }
+    if (json)
+        return printJsonSuccess("sessions prune", { applied: true, reclaimed, refused });
+    console.log(`Reclaimed ${reclaimed.length} session(s); refused ${refused.length}.`);
+    for (const outcome of refused)
+        console.log(`  refused  ${outcome.sessionId} — ${outcome.reason ?? "unknown"}`);
+}

package/dist/index.js

@@ -9,6 +9,7 @@ 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";
@@ -23,8 +24,7 @@ import { runOrganizationList, runOrganizationCreate, runOrganizationUse } from "
 import { runDocsList, runDocsShow, runDocsStatus } from "./commands/docs.js";
 import { runHandoffList, runHandoffShow } from "./commands/handoff.js";
 import { runToolkitStatus, runToolkitReconcile } from "./commands/toolkit.js";
-import { runLaneServe } from "./commands/lane.js";
-import { runSessionsRecord } from "./commands/sessions.js";
+import { runSessionsList, runSessionsPrune, runSessionsRecord, runSessionsServe, } from "./commands/sessions.js";
 import { registerReviewCommands } from "./commands/review.js";
 import { runAgentContext, runAgentHookInstall, runAgentHookRemove } from "./commands/agent.js";
 import { printJsonError } from "./lib/json_output.js";
@@ -96,6 +96,25 @@ program
     .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)")
@@ -230,18 +249,32 @@ handoff
     .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 lane = program.command("lane").description("The desktop build room's lane engine");
-lane
+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 lane supervisor: JSONL frames on stdin/stdout (used by the NuStack desktop)")
-    .action(async () => runLaneServe(version));
-const sessions = program.command("sessions").description("The session record over this machine's agent work");
+    .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 toolkit = program.command("toolkit").description("Inspect and reconcile the Project's toolkit pin");
 toolkit
     .command("status")

package/dist/lib/logs/answer.js

@@ -0,0 +1,99 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { printJsonSuccess } from "../json_output.js";
+import { loadLogscope } from "./library.js";
+export class LogsNoRepository extends Error {
+    code = "LOGS_NO_REPOSITORY";
+    constructor(where) {
+        super(`not a git repository: ${where} — pass --root <path> or run inside a checkout`);
+        this.name = "LogsNoRepository";
+    }
+}
+export class LogsUnavailable extends Error {
+    code = "LOGS_UNAVAILABLE";
+    constructor(reason) {
+        super(reason);
+        this.name = "LogsUnavailable";
+    }
+}
+export class LogsRefused extends Error {
+    code = "LOGS_REFUSED";
+    constructor(reason) {
+        super(reason);
+        this.name = "LogsRefused";
+    }
+}
+export class LogsNotFound extends Error {
+    code = "LOGS_NOT_FOUND";
+    constructor(reason) {
+        super(reason);
+        this.name = "LogsNotFound";
+    }
+}
+export function resolveRoot(root, cwd) {
+    if (root !== undefined) {
+        const path = resolve(cwd, root);
+        if (!existsSync(path))
+            throw new LogsNoRepository(root);
+        return path;
+    }
+    return gitRoot(cwd);
+}
+function gitRoot(from) {
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: from, stdio: ["ignore", "pipe", "ignore"] })
+            .toString("utf8")
+            .trim();
+    }
+    catch {
+        throw new LogsNoRepository(from);
+    }
+}
+export const progress = (line) => {
+    process.stderr.write(`${line}\n`);
+};
+export async function answerLogscope(fn, argv, options, cwd) {
+    const library = await loadLogscope();
+    const known = library.findFn(fn);
+    if (known === undefined) {
+        throw new LogsUnavailable(`unknown logscope function '${fn}' — run \`nustack logscope functions\` for the list`);
+    }
+    const args = library.parseArgs(known, argv);
+    if (known.args["root"] !== undefined && args["root"] === undefined) {
+        args["root"] = resolveRoot(options.root, cwd);
+    }
+    if (args["limit"] === undefined && options.limit !== undefined)
+        args["limit"] = Number(options.limit);
+    const limit = args["limit"];
+    const budget = options.budget !== undefined ? Number(options.budget) : limit !== undefined ? 0 : library.DEFAULT_BUDGET;
+    const result = library.dispatch({ fn: known.name, args, corpus: options.corpus, budget });
+    if (result.answer.unavailable !== undefined)
+        throw new LogsUnavailable(result.answer.unavailable);
+    if (options.json === true) {
+        printJsonSuccess(`logscope ${known.name}`, result.answer);
+        return;
+    }
+    console.log(result.rendered);
+}
+export async function listLogscopeFunctions(options) {
+    const library = await loadLogscope();
+    const budget = options.budget !== undefined ? Number(options.budget) : 0;
+    const result = library.dispatch({ fn: "functions", args: {}, budget });
+    if (options.json === true) {
+        printJsonSuccess("logscope functions", result.answer);
+        return;
+    }
+    console.log(result.rendered);
+    console.log([
+        "",
+        "lifecycle — `nustack logscope <verb>`",
+        "  allow <targets...>   grant a log source; nothing is read before this",
+        "  allowed              the grants covering this project",
+        "  revoke <targets...>  withdraw grants",
+        "  index <sources...>   ingest or refresh a corpus from granted sources",
+        "  corpora              every corpus indexed on this machine",
+        "  prune [--dry-run]    drop every corpus past its retention",
+        "  forget <id>          drop one corpus and its store",
+    ].join("\n"));
+}

package/dist/lib/logs/library.js

@@ -0,0 +1,19 @@
+export class LogsLibraryMissing extends Error {
+    code = "LOGS_LIBRARY_MISSING";
+    constructor() {
+        super("the log-tracking library is not installed with this nustack — install it beside the CLI (`npm i -g @nurix/logscope`) or run nustack from a checkout of the monorepo.");
+        this.name = "LogsLibraryMissing";
+    }
+}
+let cached = null;
+export async function loadLogscope() {
+    if (cached !== null)
+        return cached;
+    try {
+        cached = (await import("@nurix/logscope"));
+        return cached;
+    }
+    catch {
+        throw new LogsLibraryMissing();
+    }
+}