@bli-cockpit/cli 0.2.58 → 0.2.60

package/README.md

@@ -65,7 +65,7 @@ normal user, on both macOS and Windows.
 | Command | What it does | Why it exists / why this name |
 |---|---|---|
 | `cockpit onboard` | The named setup subset: signs you in (email code), registers this machine, starts capture, uploads once, completes all-history Codex and Claude backfill for saved approved roots, installs the 15-min background sync, and only then prints proof you're live. | You are boarding the crew. `do-everything` calls this flow when setup is missing; rerunning it directly is safe. Partial or failed backfill blocks readiness with an exact retry reason. |
-| `cockpit do-everything` / `cockpit fix` | Converges a Mac or Windows PC from blank or already-onboarded state: latest CLI, signed-in device token, saved roots, autostart, historical backfill, raw-evidence GC, and fresh sync. Interactive first runs prompt for email OTP and collection roots; headless/`--json` runs explain and exit instead of blocking. `--dry-run` previews without writing. | Edward can post one line and every intern machine should end green. `fix` is the alias people guess. |
+| `cockpit do-everything` / `cockpit fix` / `cockpit doctor` | Converges a Mac or Windows PC from blank or already-onboarded state: latest CLI, signed-in device token, saved roots, autostart, historical backfill, raw-evidence GC, and fresh sync. Interactive first runs prompt for email OTP and collection roots; headless/`--json` runs explain and exit instead of blocking. `--dry-run` previews without writing. | Edward can post one line and every intern machine should end green. `fix` is the alias people guess; `doctor` is the alias the ops board, the setup receipt and the heartbeat all tell you to run, and it is the same command (it checks each row, then fixes it). |
 | `cockpit status` | Prints install / sign-in / capture / upload health in one screen. | The "is it working?" command. Run it whenever you're unsure. |
 | `cockpit backfill --all` | Uploads your HISTORICAL Codex + Claude sessions (from before Cockpit existed on this machine). Discovery defaults to depth 3 and 50 repos; raise `--max-depth` or `--max-repos` when the returned retry command says a cap was reached. | One-time catch-up so your past work counts too. "Backfill" = fill in the back-catalog. |
 | `cockpit sync` | Captures and uploads once, right now. This is what the background agent runs every 15 min — you almost never type it yourself. | Named for what it does: synchronize local session files up to the dashboard. |

package/dist/commands/browser-open.js

@@ -0,0 +1,88 @@
+/**
+ * Opening a URL in the person's own browser (BLI-3731).
+ *
+ * One sign-in means the terminal hands the browser a link. That is the whole
+ * job here, and it follows the same discipline `commands/editor.ts` wrote down
+ * for spawning a program on somebody's behalf:
+ *
+ * 1. **`spawnSync` with an ARRAY of arguments and `shell: false`.** Nothing is
+ *    interpolated into a command line, ever.
+ * 2. **Windows does NOT go through `cmd /c start`.** `start` is a cmd builtin,
+ *    so reaching it means handing cmd.exe a string it re-parses — and `&` in a
+ *    query string is a command separator there. `rundll32 url.dll,
+ *    FileProtocolHandler <url>` takes the URL as one argv and never sees a
+ *    shell. (Our own URL has no `&` today; the point is that it cannot ever
+ *    matter.)
+ * 3. **The URL is validated before it is spawned.** Only `https:` and a
+ *    loopback `http:` are opened, so a bad dashboard URL cannot turn into a
+ *    `file:` or a custom protocol handler.
+ *
+ * Opening is BEST EFFORT and never fatal: the caller has already printed the
+ * link, so a machine with no browser — an SSH session, a locked-down Windows
+ * host — loses nothing but a convenience. Every branch returns a reason label,
+ * success included, and the caller logs it.
+ */
+import { spawnSync } from "node:child_process";
+/** `https:` anywhere, `http:` only on loopback — a dev dashboard is the reason. */
+export function isOpenableUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol === "https:")
+        return true;
+    return (parsed.protocol === "http:" &&
+        (parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1"));
+}
+export function openInBrowser(url, options = {}) {
+    if (!isOpenableUrl(url)) {
+        return {
+            ok: false,
+            reason: "url_not_openable",
+            detail: "Only https:// (or http:// on localhost) links are opened.",
+        };
+    }
+    const platform = options.platform ?? process.platform;
+    const spawnImpl = options.spawn ?? spawnSync;
+    const opener = openerFor(platform, url);
+    if (!opener) {
+        return {
+            ok: false,
+            reason: "no_opener_for_platform",
+            detail: `No known browser opener for ${platform}; open the link by hand.`,
+        };
+    }
+    const result = spawnImpl(opener.program, opener.args, {
+        stdio: "ignore",
+        shell: false,
+    });
+    if (result.error) {
+        return {
+            ok: false,
+            reason: "opener_not_started",
+            detail: `${opener.program} could not be started; open the link by hand.`,
+        };
+    }
+    if (typeof result.status === "number" && result.status !== 0) {
+        return {
+            ok: false,
+            reason: "opener_exited_nonzero",
+            detail: `${opener.program} exited ${result.status}; open the link by hand.`,
+        };
+    }
+    return { ok: true, reason: "launched", program: opener.program };
+}
+function openerFor(platform, url) {
+    if (platform === "darwin")
+        return { program: "open", args: [url] };
+    if (platform === "win32") {
+        // See rule 2 in the header: never `cmd /c start`.
+        return { program: "rundll32.exe", args: ["url.dll,FileProtocolHandler", url] };
+    }
+    if (platform === "linux")
+        return { program: "xdg-open", args: [url] };
+    return null;
+}

package/dist/commands/docs.js

@@ -14,6 +14,14 @@
  * /api/docs/documents` already returns — the same read `docs list` prints,
  * never a second query the server does not already answer.
  *
+ * THE LIST IS METADATA (BLI-3737). It carries id, slug, title, visibility,
+ * parent, author, updated_at and `body_chars` — never a body. On 2026-09-05
+ * `cockpit docs list --json` answered 603,779 bytes for 155 documents,
+ * because the door's select still carried `body_markdown`; an agent had to
+ * spend the whole library to learn 155 titles. `--parent`, `--query` and
+ * `--limit` ride to the door as query parameters, so the narrowing happens in
+ * the database rather than here.
+ *
  * A refusal keeps the door's own `reason` label verbatim (`agent-door.ts`):
  * `needs_rls_client`, `document_not_found_or_unreadable`,
  * `document_not_writable`, `title_too_long`, `content_too_long`,
@@ -30,7 +38,7 @@ export async function runDocs(command, io) {
     const door = await openAgentDoor("docs", command, io);
     switch (command.action) {
         case "list":
-            return listDocs(door);
+            return listDocs(command, door);
         case "tree":
             return treeDocs(door);
         case "read":
@@ -41,9 +49,21 @@ export async function runDocs(command, io) {
             return updateDoc(command, door);
     }
 }
-async function listDocs(door) {
+/** `--parent`, `--query`, `--limit` as the door's own query parameters (BLI-3737). */
+export function docsListPath(command) {
+    const params = new URLSearchParams();
+    if (command.parentId)
+        params.set("parent_id", command.parentId);
+    if (command.query)
+        params.set("query", command.query);
+    if (command.limit !== undefined)
+        params.set("limit", String(command.limit));
+    const search = params.toString();
+    return search.length > 0 ? `/api/docs/documents?${search}` : "/api/docs/documents";
+}
+async function listDocs(command, door) {
     const answer = await askAgentDoor(door, {
-        path: "/api/docs/documents",
+        path: docsListPath(command),
         method: "GET",
         label: "docs list",
         timeoutMs: READ_DEADLINE_MS,
@@ -54,14 +74,15 @@ async function listDocs(door) {
     if (door.json)
         return emitAgentDoor(door, { ok: true, documents });
     if (documents.length === 0) {
-        writeLine(door.io.stdout, "No documents.");
+        writeLine(door.io.stdout, command.query ? `No document matches "${command.query}".` : "No documents.");
         return 0;
     }
     for (const doc of documents) {
-        writeLine(door.io.stdout, `${doc.id}  ${doc.visibility.padEnd(7)}  ${doc.slug ?? "(no slug)"}  ${doc.title}`);
+        const size = typeof doc.body_chars === "number" ? `${doc.body_chars}c`.padStart(8) : "       ?";
+        writeLine(door.io.stdout, `${doc.id}  ${doc.visibility.padEnd(7)}  ${size}  ${doc.slug ?? "(no slug)"}  ${doc.title}`);
     }
     writeLine(door.io.stdout, "");
-    writeLine(door.io.stdout, `${documents.length} document(s).`);
+    writeLine(door.io.stdout, `${documents.length} document(s). Bodies come from \`cockpit docs read <id|slug>\`.`);
     return 0;
 }
 function renderTree(nodes, io, depth) {
@@ -214,6 +235,11 @@ async function updateDoc(command, door) {
             ...(bodyMarkdown !== undefined ? { body_markdown: bodyMarkdown } : {}),
             ...(command.visibility !== undefined ? { visibility: command.visibility } : {}),
             ...(command.clearParent ? { parent_id: null } : command.parentId ? { parent_id: command.parentId } : {}),
+            // BLI-3759: only ever sent when the operator asked for it. Without the
+            // key, a body that would empty a document holding text comes back as the
+            // door's own `refused_empty_body` (409), which `failAgentDoor` prints
+            // verbatim — the CLI never rephrases it and never retries with the flag.
+            ...(command.allowEmpty ? { allow_empty: true } : {}),
         },
     });
     if (!answer.ok)

package/dist/commands/doctor-report.js

@@ -1,4 +1,5 @@
 import { redactedHealthDetail } from "../health-detail.js";
+import { setupReceiptBlock } from "./setup-receipt-lines.js";
 export function ok(id, code, message) {
     return { id, status: "ok", code, message };
 }
@@ -37,7 +38,9 @@ export async function maybeReportDoctorEvents(context, rows) {
         io: context.io,
     });
 }
-export function writeDoctorOutput(command, io, rows) {
+export function writeDoctorOutput(command, io, rows, 
+/** BLI-3731. Absent means it could not be read; doctor says so rather than nothing. */
+setupReceipt) {
     if (command.json) {
         writeLine(io.stdout, JSON.stringify({
             status: rows.some((row) => row.status === "fail" || row.hardStop)
@@ -45,6 +48,8 @@ export function writeDoctorOutput(command, io, rows) {
                 : "pass",
             dry_run: command.dryRun,
             steps: rows,
+            setup_receipt: setupReceipt?.receipt ?? null,
+            memory_install: setupReceipt?.memory ?? null,
         }, null, 2));
         return;
     }
@@ -61,6 +66,17 @@ export function writeDoctorOutput(command, io, rows) {
         writeLine(io.stderr, `${row.id}:`);
         writeLine(io.stderr, row.message);
     }
+    // BLI-3731. The invariant table says whether collection is healthy; this
+    // says whether the machine is CONNECTED — the browser sign-in, the device
+    // session, both agent hosts and the scheduler, every word read back off this
+    // host. Printed last because it is what a person came to check on day one.
+    writeLine(io.stdout, "");
+    writeLine(io.stdout, "Connected:");
+    for (const line of setupReceipt
+        ? setupReceiptBlock(setupReceipt, { indent: "  " })
+        : ["  unknown — this machine could not be read this run."]) {
+        writeLine(io.stdout, line);
+    }
 }
 function doctorEvent(row) {
     const status = row.status === "fail" || row.hardStop

package/dist/commands/doctor.js

@@ -2,6 +2,7 @@ import { checkSingleInstallState, fixAuthState, fixRootState, readAuthState, rea
 import { backfillCompletionStepState, checkBackfillState, checkDiskState, checkGcState, checkSyncState, fixBackfillState, fixDiskState, fixGcState, fixSyncState, syncBacklogDrainingVerdict, } from "./doctor-pipeline.js";
 import { checkAutostartState, checkMemoryState, fixAutostartState, fixMemoryState, } from "./doctor-registration.js";
 import { dryRunPreview, isInteractiveDoctorFix, maybeReportDoctorEvents, writeDoctorOutput, } from "./doctor-report.js";
+import { refreshSetupReceipt } from "./setup-receipt.js";
 import { checkCliLatest, fixCliLatest, latestCliVersionFromNpm, reexecDoctor, } from "./doctor-update.js";
 export async function runDoctor(command, io, hooks, overrides = {}) {
     const deps = { ...defaultDoctorDeps(hooks), ...overrides };
@@ -40,12 +41,15 @@ export async function runDoctorWithDeps(command, io, deps) {
             break;
         if (fixed.reexecExitCode !== undefined) {
             await maybeReportDoctorEvents(context, rows);
-            writeDoctorOutput(command, io, rows);
+            writeDoctorOutput(command, io, rows, await deps.readSetupReceipt(context));
             return fixed.reexecExitCode;
         }
     }
     await maybeReportDoctorEvents(context, rows);
-    writeDoctorOutput(command, io, rows);
+    // Doctor is the surface a person opens when something is wrong, so it
+    // re-READS the machine rather than quoting a cache — and caching what it
+    // read is what keeps the 15-minute heartbeat from paying for the probe.
+    writeDoctorOutput(command, io, rows, await deps.readSetupReceipt(context));
     return rows.some((row) => row.status === "fail" || row.hardStop) ? 1 : 0;
 }
 function doctorInvariants() {
@@ -129,6 +133,12 @@ function defaultDoctorDeps(hooks) {
         fixDisk: fixDiskState,
         checkSync: checkSyncState,
         fixSync: fixSyncState,
+        readSetupReceipt: (context) => refreshSetupReceipt(context.io, {
+            ...(context.command.homeDir ? { homeDir: context.command.homeDir } : {}),
+            ...(context.command.dashboardUrl
+                ? { dashboardUrl: context.command.dashboardUrl }
+                : {}),
+        }),
     };
 }
 // Re-exported so every consumer keeps importing from `./doctor.js` regardless

package/dist/commands/heartbeat.js

@@ -23,10 +23,12 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { COLLECTOR_HEARTBEAT_SCHEMA_VERSION, } from "@bli-cockpit/telemetry-core";
+import { COLLECTOR_HEARTBEAT_SCHEMA_VERSION, MemoryInstallReceiptSchema, memoryInstallGaps, setupReceiptGaps, } from "@bli-cockpit/telemetry-core";
+import { readCachedSetupReceipt } from "./setup-receipt.js";
 import { describeError } from "../health-detail.js";
 import { shouldSuppressFleetReceipts, } from "../dev-build.js";
 import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
+import { readMemoryReceiptFile } from "./memory-install-receipt.js";
 const HEARTBEAT_TIMEOUT_MS = 5_000;
 /**
  * The label form of one approved root.
@@ -108,8 +110,40 @@ export function buildCollectorHeartbeat(options) {
         ...(typeof options.facts.sessionsPendingUpload === "number"
             ? { sessions_pending_upload: options.facts.sessionsPendingUpload }
             : {}),
+        ...(options.memoryInstall ? { memory_install: options.memoryInstall } : {}),
+        ...(options.setupReceipt ? { setup_receipt: options.setupReceipt } : {}),
     };
 }
+/**
+ * The cached memory receipt for this tick, or null with a named reason
+ * (BLI-3729).
+ *
+ * Reads the file `cockpit memory install` / `cockpit memory status` left
+ * behind; it does NOT re-inspect the host configs, which would cost five file
+ * reads and a `--print-config` spawn every fifteen minutes to re-prove a state
+ * that changes about once a month. The reason is returned rather than logged
+ * here so the ONE heartbeat log line carries it.
+ */
+export async function readHeartbeatMemoryReceipt(options) {
+    const paths = getCollectorRuntimePaths(options.homeDir);
+    const result = await readMemoryReceiptFile({
+        stateDir: paths.state_dir,
+        readText: async (file) => {
+            try {
+                return await fs.promises.readFile(file, "utf8");
+            }
+            catch {
+                return null;
+            }
+        },
+        ...(options.now ? { now: options.now } : {}),
+        parse: (value) => {
+            const parsed = MemoryInstallReceiptSchema.safeParse(value);
+            return parsed.success ? parsed.data : null;
+        },
+    });
+    return { receipt: result.receipt, reason: result.reason };
+}
 /**
  * Sends the heartbeat. Returns whether it landed; never throws.
  *
@@ -148,10 +182,34 @@ export async function sendCollectorHeartbeatBestEffort(options) {
         }));
         return false;
     }
+    const memory = await readHeartbeatMemoryReceipt({
+        ...(options.homeDir ? { homeDir: options.homeDir } : {}),
+        ...(options.now ? { now: options.now } : {}),
+    }).catch(() => ({ receipt: null, reason: "receipt_read_threw" }));
+    // BLI-3731. Read the CACHE, never re-probe: computing the receipt costs five
+    // file reads and a `--print-config` spawn, and these facts change about
+    // monthly. `cockpit memory install`, `onboard` and `doctor` refresh it; a
+    // tick only carries it. Both branches say something, because "the ops board
+    // shows no receipt for this machine" has two very different causes.
+    const setupReceipt = await readCachedSetupReceipt(options.homeDir, options.now ?? new Date());
+    console.error(setupReceipt
+        ? "[heartbeat] carrying this machine's setup receipt"
+        : "[heartbeat] no usable setup receipt to carry; the ops board keeps the last one it has", JSON.stringify(setupReceipt
+        ? {
+            reason: "setup_receipt_cached",
+            gap_count: setupReceiptGaps(setupReceipt).length,
+            gaps: setupReceiptGaps(setupReceipt),
+        }
+        : {
+            reason: "setup_receipt_absent_or_stale",
+            next_action: "run `cockpit doctor` to refresh it",
+        }));
     const heartbeat = buildCollectorHeartbeat({
         roots: options.roots,
         facts: options.facts,
+        setupReceipt,
         ...(options.now ? { now: options.now } : {}),
+        memoryInstall: memory.receipt,
     });
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), HEARTBEAT_TIMEOUT_MS);
@@ -184,6 +242,12 @@ export async function sendCollectorHeartbeatBestEffort(options) {
             sessions_outside_root: heartbeat.sessions_outside_root ?? null,
             sessions_new_this_tick: heartbeat.sessions_new_this_tick ?? null,
             sessions_pending_upload: heartbeat.sessions_pending_upload ?? null,
+            // BLI-3729. Both branches: a tick that reports no receipt says WHY,
+            // and a tick that reports one says whether memory is fully on. "Is BLI
+            // Memory switched on for this machine?" is now answerable from
+            // sync.err.log alone.
+            memory_receipt: memory.reason,
+            memory_gaps: memory.receipt ? memoryInstallGaps(memory.receipt) : null,
         }));
         return true;
     }

package/dist/commands/jarvis-answer-envelope.js

@@ -0,0 +1,82 @@
+/**
+ * The ONE shape a JARVIS answer wears when nobody is reading it with their
+ * eyes (BLI-3732).
+ *
+ * `cockpit jarvis --json` and the `bli-tower` MCP server's `jarvis_ask` reach
+ * the same door (`POST /api/jarvis/cli`) with the same device token and get
+ * the same reply body back. Before this file they described that body two
+ * different ways, so a script and an agent read two contracts for one turn.
+ * Now both build this envelope, and the five fields a consumer actually asks
+ * for — the answer, where it came from, which turn it was, which conversation
+ * it belongs to, and whether anything about it was second-rate — have one
+ * spelling each.
+ *
+ * ## Where the second copy is, and why
+ *
+ * `packages/bli-cockpit-mcp/src/jarvis-answer-envelope.ts` is a deliberate
+ * copy of this file. That package declares no dependency on this one — see
+ * `packages/bli-cockpit-mcp/src/agent-door-session.ts`, whose own header makes
+ * the same call for the same reason — so the shape is duplicated rather than
+ * imported. Both copies are pinned by a test on the same literal key list
+ * (`JARVIS_ANSWER_ENVELOPE_KEYS` below), so a field added on one side and not
+ * the other fails a suite instead of drifting quietly.
+ *
+ * ## What `--json` still prints
+ *
+ * These keys are ADDED to what `cockpit jarvis --json` already printed; the
+ * older `reply` / `thread` / `traceId` / `model` / `trace` / `latency` /
+ * `clientLatency` keys are untouched, because scripts already read them and a
+ * one-contract ticket that broke the contract would be a joke.
+ */
+/**
+ * Every key of the envelope, in the order it is written. The literal list IS
+ * the contract: both copies assert against it, so a drift is a red suite.
+ */
+export const JARVIS_ANSWER_ENVELOPE_KEYS = [
+    "ok",
+    "answer",
+    "sources",
+    "turn_id",
+    "thread_id",
+    "trace_thread_id",
+    "proposal_id",
+    "degraded",
+    "degraded_reasons",
+];
+/** A `Source:` line, as the grounding gate renders it into the answer. */
+const SOURCE_LINE = /^\s*Source:\s*\S/;
+/**
+ * The `Source:` lines inside an answer. Pure string work on what the server
+ * already sent — this side never decides what a source IS, it only finds the
+ * lines the server wrote, so a new citation kind needs no change here.
+ */
+export function extractSourceLines(answer) {
+    return answer
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => SOURCE_LINE.test(line));
+}
+export function buildJarvisAnswerEnvelope(input) {
+    const reasons = [];
+    if (input.modelFallback === true)
+        reasons.push("model_fallback");
+    if (input.revised === true)
+        reasons.push("answer_revised");
+    if ((input.trace ?? []).some((step) => step?.status === "failed")) {
+        reasons.push("tool_step_failed");
+    }
+    const turnId = input.traceId ?? null;
+    if (!turnId)
+        reasons.push("no_turn_id");
+    return {
+        ok: true,
+        answer: input.reply,
+        sources: extractSourceLines(input.reply),
+        turn_id: turnId,
+        thread_id: input.thread ?? null,
+        trace_thread_id: input.traceThread ?? null,
+        proposal_id: input.proposalId ?? null,
+        degraded: reasons.length > 0,
+        degraded_reasons: reasons,
+    };
+}

package/dist/commands/jarvis-render.js

@@ -37,6 +37,19 @@ export function validatePrompt(raw) {
  * (BLI-3414) — same field names the request handler parses, mirroring the
  * JSON body's fields plus one `image` file field.
  */
+/**
+ * Whether a PROGRAM is reading this turn's answer (BLI-3755).
+ *
+ * `--json` is a script's contract, and the coding arm's approval gate assumes
+ * the code it hands back reaches a person. So a `--json` turn declares itself
+ * an agent surface and JARVIS answers with a proposal id in place of the code;
+ * `--show-approval-code` opts a script that really is driving a dispatch for a
+ * human back in, and the terminal logs that it did. An interactive turn is
+ * always a person's and never sends this.
+ */
+export function agentSurface(command) {
+    return command.json === true && command.showApprovalCode !== true;
+}
 export function buildAttachmentForm(command, prompt, attachment) {
     const form = new FormData();
     form.set("question", prompt);
@@ -47,6 +60,11 @@ export function buildAttachmentForm(command, prompt, attachment) {
         form.set("model", command.model);
     if (command.date)
         form.set("date", command.date);
+    // BLI-3755: an attached-image turn is still a turn on some surface, and the
+    // coding arm rides the same belt — dropping this here would hand a code to a
+    // program that sent a screenshot.
+    if (agentSurface(command))
+        form.set("surface", "agent");
     form.set("image", new File([attachment.bytes], attachment.fileName, { type: attachment.mimeType }));
     return form;
 }

package/dist/commands/jarvis-turn.js

@@ -7,11 +7,12 @@
  * `jarvis-render.ts` — imported one direction only.
  */
 import { colorEnabled, dim, writeLine } from "./cli-io.js";
+import { buildJarvisAnswerEnvelope } from "./jarvis-answer-envelope.js";
 import { readAttachedImage } from "./jarvis-attachment.js";
 import { rememberTurnTrace } from "./jarvis-trace.js";
 import { towerFailureDetail, towerJsonRequest, towerRequest } from "../tower-client.js";
 import { readTowerTurn, streamFailureDetail } from "../tower-stream.js";
-import { activityToTrace, ANSWER_UPDATING_LINE, buildAttachmentForm, clientTimingFields, createLiveAnswer, latencyFields, latencyLogFields, TURN_DEADLINE_MS, writeActivityLine, writeAttachmentRefusal, writeFailure, writeModelReceipt, writeRevision, writeTraceBlock, } from "./jarvis-render.js";
+import { activityToTrace, agentSurface, ANSWER_UPDATING_LINE, buildAttachmentForm, clientTimingFields, createLiveAnswer, latencyFields, latencyLogFields, TURN_DEADLINE_MS, writeActivityLine, writeAttachmentRefusal, writeFailure, writeModelReceipt, writeRevision, writeTraceBlock, } from "./jarvis-render.js";
 export async function sendOneTurn(context, prompt, io) {
     const startedAt = Date.now();
     // BLI-3414: an attached file is read and locally screened (exists,
@@ -40,6 +41,11 @@ export async function sendOneTurn(context, prompt, io) {
     // all three are named. If this number is ever large, the step that made it
     // large is on the same line.
     const preRequestMs = Date.now() - startedAt;
+    // BLI-3755: never silently. A script that asked for the code is a script
+    // that can spend a human's approval, and the one line saying so is here.
+    if (context.command.json && context.command.showApprovalCode) {
+        log("[jarvis] approval code requested by a --json caller (--show-approval-code)");
+    }
     const requested = await towerRequest({
         dashboardUrl: context.dashboardUrl,
         path: "/api/jarvis/cli",
@@ -64,6 +70,12 @@ export async function sendOneTurn(context, prompt, io) {
                 // there is nothing above to revise.
                 previousAnswer: context.previous?.answer,
                 previousQuestion: context.previous?.question,
+                // BLI-3755: who is reading this answer. A `--json` turn is a
+                // PROGRAM's, so the coding arm withholds its approval code and
+                // answers with a proposal id instead; an interactive turn is a
+                // person's and is unchanged. `--show-approval-code` opts a script
+                // back in, and says so on stderr below.
+                surface: agentSurface(context.command) ? "agent" : undefined,
             },
         log,
     });
@@ -131,7 +143,22 @@ export async function sendOneTurn(context, prompt, io) {
     await rememberTurnTrace({ traceId: body.traceId ?? null, threadId: body.traceThread ?? null }, io, context.command.homeDir);
     if (context.command.json) {
         writeLine(io.stdout, JSON.stringify({
-            ok: true,
+            // BLI-3732: the shared envelope FIRST — `answer`, `sources`,
+            // `turn_id`, `thread_id`, `trace_thread_id`, `degraded`,
+            // `degraded_reasons` — so a script here and an agent on the
+            // `jarvis_ask` MCP tool read one contract for one turn. The keys
+            // below it are the ones this command has always printed and are
+            // untouched; `reply` and `answer` are the same string.
+            ...buildJarvisAnswerEnvelope({
+                reply: body.reply,
+                thread: body.thread ?? context.command.thread,
+                traceId: body.traceId,
+                traceThread: body.traceThread,
+                modelFallback: body.model?.fallback,
+                revised: body.revised,
+                trace,
+                proposalId: body.proposalId,
+            }),
             reply: body.reply,
             thread: body.thread ?? context.command.thread,
             model: body.model ?? null,

package/dist/commands/jarvis.js

@@ -12,6 +12,9 @@
  * - `jarvis-contracts.ts` — the parsed `cockpit jarvis` command type, and the
  *   loose reply shapes read off `/api/jarvis/cli`, `--threads` and
  *   `--history`.
+ * - `jarvis-answer-envelope.ts` — the shape `--json` prints (BLI-3732), which
+ *   is the same shape the `bli-tower` MCP server's `jarvis_ask` returns, so a
+ *   script and an agent read one contract for one turn.
  * - `jarvis-turn.ts` — the turn engine: `sendOneTurn` (attach, request,
  *   stream, settle, print, log — the one send for both a one-shot invocation
  *   and the interactive loop below) and `readHistory` (`--threads` /

package/dist/commands/local-args-collector-setup.js

@@ -31,6 +31,11 @@ function parseOnboardLikeArgs(args, command) {
             "--max-depth",
             "--max-repos",
             "--allow-home-root",
+            // BLI-3731, the one-sign-in ceremony. Same three flags as `login`, so a
+            // person who learned them on one door does not relearn them on another.
+            "--pair",
+            "--no-browser",
+            "--legacy-pair",
         ],
         valueFlags: [
             "--home",
@@ -45,6 +50,7 @@ function parseOnboardLikeArgs(args, command) {
             "--timeout-ms",
             "--max-depth",
             "--max-repos",
+            "--pair",
         ],
     });
     assertNoPositionals(values.positionals, command);
@@ -65,6 +71,9 @@ function parseOnboardLikeArgs(args, command) {
         maxDepth: optionalPositiveInteger(values.flags.get("--max-depth"), "--max-depth"),
         maxRepos: optionalPositiveInteger(values.flags.get("--max-repos"), "--max-repos"),
         allowHomeRoot: values.booleans.has("--allow-home-root"),
+        noBrowser: values.booleans.has("--no-browser"),
+        legacyPair: values.booleans.has("--legacy-pair"),
+        pairCode: optionalNonEmpty(values.flags.get("--pair")),
     };
 }
 export function parseOnboardArgs(args) {
@@ -210,6 +219,10 @@ export function parseLoginArgs(args) {
             "--no-auth",
             "--poll-interval-ms",
             "--timeout-ms",
+            // BLI-3731, the one-sign-in ceremony.
+            "--pair",
+            "--no-browser",
+            "--legacy-pair",
         ],
         valueFlags: [
             "--home",
@@ -218,6 +231,7 @@ export function parseLoginArgs(args) {
             "--device-name",
             "--poll-interval-ms",
             "--timeout-ms",
+            "--pair",
         ],
     });
     assertNoPositionals(values.positionals, "login");
@@ -231,6 +245,9 @@ export function parseLoginArgs(args) {
         noAuth: values.booleans.has("--no-auth"),
         pollIntervalMs: optionalPositiveInteger(values.flags.get("--poll-interval-ms"), "--poll-interval-ms"),
         timeoutMs: optionalPositiveInteger(values.flags.get("--timeout-ms"), "--timeout-ms"),
+        pairCode: optionalNonEmpty(values.flags.get("--pair")),
+        noBrowser: values.booleans.has("--no-browser"),
+        legacyPair: values.booleans.has("--legacy-pair"),
     };
 }
 export function parseLogoutArgs(args) {

package/dist/commands/local-args-tower-admin.js

@@ -48,7 +48,7 @@ export function parseScoutArgs(args) {
     return { kind: "scout", action: rawAction, experimentRef, ...base };
 }
 /**
- * `cockpit ops status [--job <id>] [--skips]` and
+ * `cockpit ops status [--job <id>] [--skips] [--memory [--memory-days N]]` and
  * `cockpit ops recompile --person <p> [--dry-run]` (BLI-3462).
  *
  * There is deliberately **no `--cadence`** on `recompile`. The compile path
@@ -64,11 +64,13 @@ export function parseOpsArgs(args) {
             "--dashboard-url",
             "--job",
             "--skips",
+            "--memory",
+            "--memory-days",
             "--person",
             "--dry-run",
             "--json",
         ],
-        valueFlags: ["--home", "--dashboard-url", "--job", "--person"],
+        valueFlags: ["--home", "--dashboard-url", "--job", "--person", "--memory-days"],
     });
     if (values.positionals.length > 1) {
         throw new Error("ops accepts one action: status or recompile.");
@@ -83,11 +85,19 @@ export function parseOpsArgs(args) {
         json: values.booleans.has("--json"),
     };
     if (rawAction === "status") {
+        // BLI-3729: `--memory-days N` implies `--memory`, because asking for a
+        // window and getting nothing back is the silent breakage BLI-2490 forbids.
+        const memoryDays = optionalNonEmpty(values.flags.get("--memory-days"));
+        if (memoryDays !== undefined && !/^[0-9]{1,2}$/u.test(memoryDays)) {
+            throw new Error("ops --memory-days takes a whole number of days, 1 to 30.");
+        }
         return {
             kind: "ops",
             action: "status",
             job: optionalNonEmpty(values.flags.get("--job")),
             skips: values.booleans.has("--skips"),
+            memory: values.booleans.has("--memory") || memoryDays !== undefined,
+            ...(memoryDays === undefined ? {} : { memoryDays: Number(memoryDays) }),
             ...base,
         };
     }