@nurix/nustack 0.23.3 → 0.23.5

package/dist/commands/recordAliases.js

@@ -0,0 +1,183 @@
+import { readFile } from "node:fs/promises";
+import { openLocalStore } from "../lib/local_store/database.js";
+import { idempotencyKeyOf, splitObligationKey } from "../lib/records/naturalKey.js";
+import { findRecordByKey } from "../lib/records/recordsTable.js";
+import { emitRows, refuseEmit, resolveCaller } from "./records.js";
+export const RECORD_ALIAS_GROUPS = ["obligation", "backlog", "changelog", "journal"];
+const VERDICTS_NEEDING_REASON = new Set(["owes_nothing", "blocked", "dismissed"]);
+const PLAN_ANCHOR = /^\d{4}-\d{2}-\d{2}-[a-z0-9][a-z0-9-]*$/;
+function requestOf(command, kind, rows, options) {
+    return {
+        command,
+        target: command,
+        kind,
+        rows,
+        json: options.json === true,
+        ...(options.root !== undefined ? { root: options.root } : {}),
+        ...(options.project !== undefined ? { project: options.project } : {}),
+        ...(options.session !== undefined ? { session: options.session } : {}),
+    };
+}
+function refusal(command, options, message, globals) {
+    return refuseEmit(requestOf(command, "obligation", [], options), "VALIDATION_FAILED", "records-validation", message, globals);
+}
+export async function runObligationAdd(options, globals) {
+    const command = "obligation add";
+    if (!options.plan && !options.origin)
+        return refusal(command, options, "obligation add takes --plan <anchor> or --origin <origin>", globals);
+    const payload = {
+        origin: options.origin ?? `plan:${options.plan}`,
+        type: options.type,
+        subject: options.subject,
+        ...(options.claim !== undefined ? { claim: options.claim } : {}),
+        ...(options.ownerAgent !== undefined ? { ownerAgentDefinitionId: options.ownerAgent } : {}),
+        state: "open",
+    };
+    await emitRows(requestOf(command, "obligation", [{ payload, ...(options.plan ? { planAnchor: options.plan } : {}) }], options), globals);
+}
+const COPIED_FIELDS = ["origin", "type", "subject", "claim", "ownerAgentDefinitionId", "isGateCounted"];
+export async function runObligationDischarge(options, globals) {
+    const command = "obligation discharge";
+    const key = options.key ?? "";
+    if (options.outcome && VERDICTS_NEEDING_REASON.has(options.outcome) && !options.reason) {
+        return refusal(command, options, `--outcome ${options.outcome} needs a --reason`, globals);
+    }
+    const caller = await resolveCaller(options);
+    const store = await openLocalStore();
+    let stored;
+    try {
+        stored = findRecordByKey(store.db, idempotencyKeyOf(caller.projectId ?? caller.root, "obligation", key));
+    }
+    finally {
+        store.close();
+    }
+    let fields;
+    let planAnchor;
+    if (stored && stored.kind === "obligation") {
+        const storedPayload = JSON.parse(stored.payloadJson);
+        fields = {};
+        for (const field of COPIED_FIELDS)
+            if (storedPayload[field] !== undefined)
+                fields[field] = storedPayload[field];
+        planAnchor = stored.planAnchor;
+    }
+    else {
+        const split = splitObligationKey(key);
+        if (!split)
+            return refusal(command, options, "--key must be an obligation's natural key, <origin>#<type>:<subject>", globals);
+        fields = { ...split };
+        const plan = split.origin.startsWith("plan:") ? split.origin.slice("plan:".length) : null;
+        planAnchor = plan !== null && PLAN_ANCHOR.test(plan) ? plan : null;
+    }
+    const payload = {
+        ...fields,
+        state: "discharged",
+        outcome: { verdict: options.outcome, ...(options.reason !== undefined ? { reason: options.reason } : {}) },
+    };
+    await emitRows(requestOf(command, "obligation", [{ payload, ...(planAnchor !== null ? { planAnchor } : {}) }], options), globals);
+}
+export async function runBacklogAdd(options, globals) {
+    const payload = {
+        anchor: options.anchor,
+        priority: options.priority,
+        text: options.text,
+        ...(options.discoveredBy !== undefined ? { discoveredBy: options.discoveredBy } : {}),
+        ...(options.section !== undefined ? { section: options.section } : {}),
+    };
+    await emitRows(requestOf("backlog add", "backlog", [{ payload }], options), globals);
+}
+export async function runChangelogAdd(options, globals) {
+    const command = "changelog add";
+    if (!options.plan && !options.change)
+        return refusal(command, options, "changelog add takes --plan <anchor> or --change <change id>", globals);
+    let body = options.body;
+    if (body === undefined && options.bodyFile !== undefined) {
+        try {
+            body = await readFile(options.bodyFile, "utf8");
+        }
+        catch (error) {
+            return refusal(command, options, `--body-file could not be read: ${error instanceof Error ? error.message : String(error)}`, globals);
+        }
+    }
+    if (body === undefined)
+        return refusal(command, options, "changelog add takes --body <text> or --body-file <path>", globals);
+    const payload = {
+        origin: options.plan ? `plan:${options.plan}` : `change:${options.change}`,
+        title: options.title,
+        body,
+        ...(options.commit && options.commit.length > 0 ? { commits: options.commit } : {}),
+    };
+    await emitRows(requestOf(command, "changelog", [{ payload, ...(options.plan ? { planAnchor: options.plan } : {}) }], options), globals);
+}
+export async function runJournalAdd(options, globals) {
+    const command = "journal add";
+    const caller = await resolveCaller(options);
+    const sessionId = caller.refusalContext.sessionId;
+    if (!options.plan && !sessionId) {
+        return refusal(command, options, "journal add takes --plan <anchor>, or a session (--session or $NUSTACK_SESSION_ID)", globals);
+    }
+    const occurredAt = caller.refusalContext.now.toISOString();
+    const payload = {
+        origin: options.plan ? `plan:${options.plan}` : `session:${sessionId}`,
+        type: "documentation",
+        subject: `journal-${occurredAt}`,
+        claim: options.text,
+        isGateCounted: false,
+        state: "open",
+    };
+    await emitRows(requestOf(command, "obligation", [{ payload, occurredAt, ...(options.plan ? { planAnchor: options.plan } : {}) }], options), globals);
+}
+const collect = (value, previous = []) => [...previous, value];
+function withCommon(command) {
+    return command
+        .option("--root <dir>", "the folder the record is about (default: the current directory)")
+        .option("--project <id>", "the Project, when the folder carries no binding marker")
+        .option("--session <id>", "the session the record belongs to (default: $NUSTACK_SESSION_ID)")
+        .option("--json", "emit the versioned machine envelope");
+}
+export function registerRecordAliases(program, getGlobalOptions) {
+    const obligation = program.command("obligation").description("Open and discharge obligations (harness records)");
+    withCommon(obligation
+        .command("add")
+        .description("Open an obligation under a plan or an origin")
+        .option("--plan <anchor>", "the plan the obligation belongs to (origin plan:<anchor>)")
+        .option("--origin <origin>", "the origin, when it is not a plan: plan:, change:, path:, session: or run:")
+        .requiredOption("--type <type>", "documentation, test, security, or an agent-owned type")
+        .requiredOption("--subject <text>", "what the obligation is about: a doc path, a row number, a finding target")
+        .option("--claim <text>", "what is owed")
+        .option("--owner-agent <slug>", "the agent definition slug that alone discharges it")).action(async (options) => runObligationAdd(options, getGlobalOptions()));
+    withCommon(obligation
+        .command("discharge")
+        .description("Discharge an obligation by its natural key, with a verdict")
+        .requiredOption("--key <naturalKey>", "the obligation's natural key, <origin>#<type>:<subject>")
+        .requiredOption("--outcome <verdict>", "updated, satisfied, fixed, owes_nothing, blocked or dismissed")
+        .option("--reason <text>", "why; required for owes_nothing, blocked and dismissed")).action(async (options) => runObligationDischarge(options, getGlobalOptions()));
+    withCommon(program
+        .command("backlog")
+        .description("Log backlog items (harness records)")
+        .command("add")
+        .description("Log one backlog item")
+        .requiredOption("--anchor <anchor>", "the item's stable id")
+        .requiredOption("--text <text>", "the item")
+        .requiredOption("--priority <priority>", "P0, P1, P2 or P3")
+        .option("--discovered-by <who>", "the plan or agent that found it")
+        .option("--section <name>", "the backlog section")).action(async (options) => runBacklogAdd(options, getGlobalOptions()));
+    withCommon(program
+        .command("changelog")
+        .description("Write changelog entries (harness records)")
+        .command("add")
+        .description("Write a changelog entry for a plan or a change; a later call supersedes it")
+        .option("--plan <anchor>", "the plan the entry describes")
+        .option("--change <id>", "the NuStack Change the entry describes")
+        .requiredOption("--title <line>", "the entry's one-line summary")
+        .option("--body <text>", "the entry's body")
+        .option("--body-file <path>", "read the entry's body from a file")
+        .option("--commit <sha>", "a commit the entry covers (repeatable)", collect)).action(async (options) => runChangelogAdd(options, getGlobalOptions()));
+    withCommon(program
+        .command("journal")
+        .description("Write journal entries (harness records)")
+        .command("add")
+        .description("Write a journal entry: a documentation obligation the gate never counts")
+        .requiredOption("--text <text>", "the entry")
+        .option("--plan <anchor>", "the plan the entry belongs to (else the session)")).action(async (options) => runJournalAdd(options, getGlobalOptions()));
+}

package/dist/commands/records.js

@@ -1,8 +1,15 @@
 import { existsSync } from "node:fs";
+import { readDesktopSettings } from "../lib/desktop_settings.js";
 import { openLocalStore } from "../lib/local_store/database.js";
 import { stateDbPath } from "../lib/local_store/paths.js";
 import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
-import { RECORDS_BATCH_CAP, drainOutbox, drainStore, emitRecords, isRecordKind, listOutbox, listStored, resolveDoor, } from "../lib/records/door.js";
+import { resolveProjectId } from "../lib/project_context.js";
+import { isEmitKind } from "../lib/records/door.js";
+import { acquireDrainLock, drainRecords, refreshDrainLock, releaseDrainLock, startDetachedDrain } from "../lib/records/drain.js";
+import { DEVICE_TOKEN_VARIABLE, DRAIN_CHILD_VARIABLE, SESSION_ID_VARIABLE, isFlagSet, readVariable, recordCredentialOf, } from "../lib/records/environment.js";
+import { UNKNOWN_KIND_MESSAGE, assembleRecord, parseRowsText, translateRow, } from "../lib/records/recordInput.js";
+import { AgentOwnedError, OBLIGATION_AGENT_OWNED, countRecords, hasDueRecord, listRecords, releaseUnboundRows, writeRecords, } from "../lib/records/recordsTable.js";
+import { logRefusals } from "../lib/records/refusalLog.js";
 async function readStdin() {
     if (process.stdin.isTTY)
         return "";
@@ -11,101 +18,180 @@ async function readStdin() {
         chunks.push(chunk);
     return Buffer.concat(chunks).toString("utf8");
 }
-function parseRows(raw) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return null;
+export async function resolveCaller(request) {
+    const root = request.root ?? process.cwd();
+    const project = await resolveProjectId(root, request.project ? { project: request.project } : {});
+    const projectId = project.ok ? project.projectId : null;
+    return {
+        root,
+        projectId,
+        refusalContext: {
+            projectId,
+            root,
+            sessionId: request.session ?? readVariable(SESSION_ID_VARIABLE),
+            credential: recordCredentialOf(),
+            now: new Date(),
+        },
+    };
+}
+export async function refuseEmit(request, code, gate, message, globals, caller) {
+    const who = caller ?? (await resolveCaller(request).catch(() => null));
+    if (who) {
+        try {
+            const store = await openLocalStore();
+            try {
+                if (logRefusals(store, [{ gate, verdict: "block", target: request.target, reason: message }], who.refusalContext) > 0) {
+                    startDetachedDrain({ nustackUrl: globals.nustackUrl });
+                }
+            }
+            finally {
+                store.close();
+            }
+        }
+        catch {
+        }
     }
-    let list;
-    let kind;
-    if (Array.isArray(parsed))
-        list = parsed;
-    else if (isEnvelope(parsed)) {
-        list = parsed.rows;
-        kind = parsed.kind;
+    if (request.json)
+        printJsonError(request.command, { code, message });
+    else {
+        process.stderr.write(`${request.command}: ${message}\n`);
+        process.exitCode = 1;
     }
-    else
-        list = [parsed];
-    const rows = list.filter((row) => !!row &&
-        typeof row === "object" &&
-        !Array.isArray(row) &&
-        typeof row.anchor === "string" &&
-        row.anchor.trim() !== "");
-    return rows.length === list.length ? { rows, kind } : null;
-}
-function isEnvelope(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const candidate = value;
-    const hasPayload = !!candidate.payload && typeof candidate.payload === "object" && !Array.isArray(candidate.payload);
-    return Array.isArray(candidate.rows) && typeof candidate.anchor !== "string" && !hasPayload;
 }
-function emitLine(outcome) {
-    if (outcome.rung === 1)
-        return `records emit: landed ${outcome.landed} on NuStack (${outcome.projectId})\n`;
-    if (outcome.rung === 2)
-        return `records emit: the door refused (${outcome.error}); ${outcome.keys.length} row(s) wait in the outbox\n`;
-    return `records emit: ${outcome.reason}; ${outcome.keys.length} row(s) kept in the local store\n`;
-}
-export async function runRecordsEmit(options, globals) {
-    const json = options.json === true;
-    const refuse = (message) => {
-        if (json)
-            printJsonError("records emit", { code: "VALIDATION_FAILED", message });
-        else {
-            process.stderr.write(`records emit: ${message}\n`);
-            process.exitCode = 1;
+export async function emitRows(request, globals) {
+    const caller = await resolveCaller(request);
+    const refuse = (code, gate, message) => refuseEmit(request, code, gate, message, globals, caller);
+    if (!isEmitKind(request.kind))
+        return refuse("VALIDATION_FAILED", "records-unknown-kind", UNKNOWN_KIND_MESSAGE);
+    const kind = request.kind;
+    let rows = request.rows;
+    if (!rows) {
+        const parsed = parseRowsText(request.rowText ?? (await readStdin()));
+        if (!parsed || parsed.rows.length === 0) {
+            return refuse("VALIDATION_FAILED", "records-validation", "the rows must be JSON — one row, an array of rows, or {kind, rows}");
         }
-    };
-    if (!isRecordKind(options.kind))
-        return refuse("--kind must be backlog, backlog.remove, bookkeeping or gate_event");
-    const parsed = parseRows(options.row ?? (await readStdin()));
-    if (!parsed || parsed.rows.length === 0) {
-        return refuse("the rows must be JSON — one row, an array of rows, or {kind, rows} — each an object with an anchor");
+        if (parsed.kind !== undefined && parsed.kind !== kind) {
+            return refuse("VALIDATION_FAILED", "records-validation", `the envelope's kind ${JSON.stringify(parsed.kind)} differs from --kind ${kind}`);
+        }
+        rows = parsed.rows;
     }
-    if (parsed.kind !== undefined && parsed.kind !== options.kind) {
-        return refuse(`the envelope's kind ${JSON.stringify(parsed.kind)} differs from --kind ${options.kind}`);
+    const context = {
+        projectId: caller.projectId,
+        root: caller.root,
+        sessionId: caller.refusalContext.sessionId,
+        planAnchor: request.plan ?? null,
+        settings: readDesktopSettings(),
+        credential: caller.refusalContext.credential,
+        now: caller.refusalContext.now,
+    };
+    const writes = [];
+    const flags = [];
+    for (const [index, row] of rows.entries()) {
+        const translated = translateRow(kind, row, index);
+        if (!translated.ok)
+            return refuse("VALIDATION_FAILED", "records-validation", translated.message);
+        const assembled = assembleRecord(translated.kind, translated.input, context, index);
+        if (!assembled.ok)
+            return refuse("VALIDATION_FAILED", "records-validation", assembled.message);
+        writes.push(assembled.write);
+        flags.push(...assembled.flags);
     }
-    const rows = parsed.rows;
-    const root = options.root ?? process.cwd();
-    const resolution = await resolveDoor(root, globals, options.project);
     const store = await openLocalStore();
+    let written;
+    let owned = null;
     try {
-        const outcomes = [];
-        for (let start = 0; start < rows.length; start += RECORDS_BATCH_CAP) {
-            outcomes.push(await emitRecords(store, resolution, options.kind, rows.slice(start, start + RECORDS_BATCH_CAP)));
+        try {
+            written = writeRecords(store, writes);
+        }
+        catch (error) {
+            if (!(error instanceof AgentOwnedError))
+                throw error;
+            owned = error;
+            written = [];
         }
-        if (outcomes.every((outcome) => outcome.rung === 1))
-            await drainOutbox(store, globals, { dueOnly: true });
-        const last = outcomes[outcomes.length - 1];
-        const keys = outcomes.flatMap((outcome) => outcome.keys);
-        if (json)
-            printJsonSuccess("records emit", { ...last, keys });
-        else
-            process.stdout.write(emitLine({ ...last, keys }));
+        if (owned)
+            return;
+        if (caller.projectId !== null)
+            releaseUnboundRows(store, caller.root);
+        logRefusals(store, flags.map((flag) => ({
+            gate: "secret-scan",
+            verdict: "flag",
+            target: request.target,
+            reason: `redacted a ${flag.patternId} match at ${flag.path}`,
+        })), caller.refusalContext);
     }
     finally {
         store.close();
+        if (owned)
+            await refuse(OBLIGATION_AGENT_OWNED, "agent-owned-obligation", owned.message);
+    }
+    if (owned)
+        return;
+    if (flags.length > 0 || written.some((row) => row.syncState === "pending"))
+        startDetachedDrain({ nustackUrl: globals.nustackUrl });
+    const data = {
+        written: written.length,
+        keys: written.map((row) => row.idempotencyKey),
+        local: written.filter((row) => row.syncState === "local").length,
+        flags,
+        projectId: caller.projectId,
+    };
+    if (request.json)
+        printJsonSuccess(request.command, data);
+    else {
+        for (const flag of flags)
+            process.stderr.write(`${request.command}: redacted a ${flag.patternId} match at ${flag.path}\n`);
+        process.stdout.write(`${request.command}: wrote ${data.written} record(s) locally; sending in the background\n`);
+    }
+}
+export async function runRecordsEmit(options, globals) {
+    await emitRows({
+        command: "records emit",
+        target: `records emit --kind ${options.kind ?? ""}`.trim(),
+        kind: options.kind,
+        ...(options.row !== undefined ? { rowText: options.row } : {}),
+        ...(options.root !== undefined ? { root: options.root } : {}),
+        ...(options.project !== undefined ? { project: options.project } : {}),
+        ...(options.session !== undefined ? { session: options.session } : {}),
+        ...(options.plan !== undefined ? { plan: options.plan } : {}),
+        json: options.json === true,
+    }, globals);
+}
+async function drainAs(store, globals, isChild) {
+    if (!isChild)
+        return drainRecords(store, globals, { isForeground: true });
+    if (!acquireDrainLock())
+        return null;
+    try {
+        return await drainRecords(store, globals, { onPass: () => refreshDrainLock() });
+    }
+    finally {
+        releaseDrainLock();
     }
 }
 export async function runRecordsSync(options, globals) {
     const store = await openLocalStore();
     try {
-        const outbox = await drainOutbox(store, globals);
-        const stored = await drainStore(store, globals);
+        const root = process.cwd();
+        const project = await resolveProjectId(root, {});
+        if (project.ok)
+            releaseUnboundRows(store, root);
+        const drained = await drainAs(store, globals, isFlagSet(DRAIN_CHILD_VARIABLE));
+        if (options.quiet)
+            return;
+        const counts = await countRecords(store);
         const result = {
-            sent: outbox.sent + stored.sent,
-            waiting: listOutbox(store).length,
-            stored: listStored(store).length,
-            lastError: outbox.lastError ?? stored.lastError,
+            sent: drained?.sent ?? 0,
+            waiting: counts.waitingCount,
+            stored: counts.storeCount,
+            refused: counts.refusedCount,
+            lastError: drained?.lastError ?? counts.lastError,
         };
         if (options.json)
             printJsonSuccess("records sync", result);
-        else
-            process.stdout.write(`records sync: sent ${result.sent}; ${result.waiting} wait in the outbox, ${result.stored} kept locally\n`);
+        else {
+            process.stdout.write(`records sync: sent ${result.sent}; ${result.waiting} waiting, ${result.stored} kept locally, ${result.refused} refused\n`);
+        }
     }
     finally {
         store.close();
@@ -114,35 +200,42 @@ export async function runRecordsSync(options, globals) {
 export async function runRecordsList(options) {
     const store = await openLocalStore();
     try {
-        const outbox = listOutbox(store, options.project);
-        const stored = listStored(store, options.project ? { projectId: options.project } : {});
-        const newest = [...outbox].sort((a, b) => b.createdAtMs - a.createdAtMs).find((row) => row.lastError !== null);
+        const counts = await countRecords(store, options.project);
+        const records = listRecords(store, {
+            ...(options.project ? { projectId: options.project } : {}),
+            ...(options.kind ? { kind: options.kind } : {}),
+            ...(options.plan ? { planAnchor: options.plan } : {}),
+        });
         const data = {
-            outboxCount: outbox.length,
-            storeCount: stored.length,
-            lastError: newest?.lastError ?? null,
-            outbox,
-            store: stored,
+            outboxCount: counts.outboxCount,
+            storeCount: counts.storeCount,
+            lastError: counts.lastError,
+            pendingCount: counts.pendingCount,
+            refusedCount: counts.refusedCount,
+            localCount: counts.localCount,
+            records,
         };
         if (options.json)
             printJsonSuccess("records list", data);
         else {
-            process.stdout.write(`records list: ${data.outboxCount} in the outbox, ${data.storeCount} kept locally\n`);
-            if (data.lastError)
-                process.stdout.write(`  last error: ${data.lastError}\n`);
+            process.stdout.write(`records list: ${counts.pendingCount} pending, ${counts.refusedCount} refused, ${counts.localCount} kept on this device\n`);
+            if (counts.lastError)
+                process.stdout.write(`  last error: ${counts.lastError}\n`);
         }
     }
     finally {
         store.close();
     }
 }
-export async function drainBeforeCommand(globals) {
-    if (!existsSync(stateDbPath()))
-        return;
+export async function startDrainIfDue(globals) {
     try {
+        if (isFlagSet(DRAIN_CHILD_VARIABLE) || !existsSync(stateDbPath()))
+            return;
         const store = await openLocalStore();
         try {
-            await drainOutbox(store, globals, { dueOnly: true, limit: 20 });
+            if (hasDueRecord(store.db, Date.now(), readVariable(DEVICE_TOKEN_VARIABLE) !== null)) {
+                startDetachedDrain({ nustackUrl: globals.nustackUrl });
+            }
         }
         finally {
             store.close();
@@ -154,22 +247,27 @@ export async function drainBeforeCommand(globals) {
 export function registerRecordsCommands(recordsCommand, getGlobalOptions) {
     recordsCommand
         .command("emit")
-        .description("Land records on NuStack, else park them in the outbox, else keep them locally")
-        .option("--kind <kind>", "backlog, backlog.remove, bookkeeping or gate_event")
+        .description("Write records locally and return; a background drain sends them to NuStack")
+        .option("--kind <kind>", "obligation, gate_event, changelog, memory, backlog, proposal or triage")
         .option("--row <json>", "one row, an array of rows, or {kind, rows}, as JSON (default: read from stdin)")
         .option("--root <dir>", "the folder the records are about (default: the current directory)")
         .option("--project <id>", "the Project, when the folder carries no binding marker")
+        .option("--session <id>", `the session the records belong to (default: $${SESSION_ID_VARIABLE})`)
+        .option("--plan <anchor>", "the plan anchor, when a row names none")
         .option("--json", "emit the versioned machine envelope")
         .action(async (options) => runRecordsEmit(options, getGlobalOptions()));
     recordsCommand
         .command("sync")
-        .description("Send every outbox row, and stored rows whose folder now has a door")
+        .description("Send every due record this device holds to NuStack")
+        .option("--quiet", "print nothing")
         .option("--json", "emit the versioned machine envelope")
         .action(async (options) => runRecordsSync(options, getGlobalOptions()));
     recordsCommand
         .command("list")
-        .description("Show the rows that have not reached NuStack: the outbox and the local store")
+        .description("Show this device's records: what waits, what was refused, what stays local")
         .option("--project <id>", "only this Project's rows")
+        .option("--kind <kind>", "only rows of this kind")
+        .option("--plan <anchor>", "only rows of this plan")
         .option("--json", "emit the versioned machine envelope")
         .action(async (options) => runRecordsList(options));
 }

package/dist/index.js

@@ -33,7 +33,8 @@ import { runToolkitStatus, runToolkitReconcile } from "./commands/toolkit.js";
 import { runHarnessMount, runHarnessStatus } from "./commands/harness.js";
 import { runSessionsList, runSessionsPrune, runSessionsRecord, runSessionsServe, } from "./commands/sessions.js";
 import { registerReviewCommands } from "./commands/review.js";
-import { drainBeforeCommand, registerRecordsCommands } from "./commands/records.js";
+import { registerRecordsCommands, startDrainIfDue } from "./commands/records.js";
+import { RECORD_ALIAS_GROUPS, registerRecordAliases } from "./commands/recordAliases.js";
 import { runAgentContext, runAgentHookInstall, runAgentHookRemove } from "./commands/agent.js";
 import { printJsonError } from "./lib/json_output.js";
 import { setCliVersion } from "./lib/auth_grant.js";
@@ -237,11 +238,13 @@ 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());
 program.hook("preAction", async (_program, action) => {
     if (program.opts().nonInteractive)
         process.env[NON_INTERACTIVE_VARIABLE] = "1";
-    if (action.parent?.name() !== "records")
-        await drainBeforeCommand(program.opts());
+    const group = action.parent?.name() ?? "";
+    if (group !== "records" && !RECORD_ALIAS_GROUPS.includes(group))
+        await startDrainIfDue(program.opts());
 });
 const docs = program.command("docs").description("Work with a Project's Documents");
 docs

package/dist/lib/desktop_settings.js

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { desktopSettingsPath } from "./local_store/paths.js";
+const DEFAULT_PLACEMENT = "server";
+function placementOf(value) {
+    return value === "device" || value === "server" ? value : DEFAULT_PLACEMENT;
+}
+export function readDesktopSettings() {
+    const defaults = { placement: { memory: DEFAULT_PLACEMENT, securityFindings: DEFAULT_PLACEMENT } };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(desktopSettingsPath(), "utf8"));
+    }
+    catch {
+        return defaults;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return defaults;
+    const file = parsed;
+    if (file.schemaVersion !== 1)
+        return defaults;
+    const placement = file.placement && typeof file.placement === "object" ? file.placement : {};
+    return { placement: { memory: placementOf(placement.memory), securityFindings: placementOf(placement.securityFindings) } };
+}

package/dist/lib/local_store/database.js

@@ -41,8 +41,8 @@ export async function openLocalStore(options = {}) {
         const { DatabaseSync } = await loadSqlite();
         return new DatabaseSync(dbFile);
     });
-    db.exec("PRAGMA journal_mode = WAL");
     db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("PRAGMA journal_mode = WAL");
     db.exec("PRAGMA foreign_keys = ON");
     migrateToLatest(db);
     await chmod(dbFile, 0o600).catch(() => { });