@bli-cockpit/cli 0.2.49 → 0.2.51

package/dist/commands/doctor.js

@@ -10,6 +10,7 @@ import { normalizeCollectionRoots } from "../root-normalization.js";
 import { detectSecondCockpitInstall } from "../second-install.js";
 import { runRawEvidenceLocalGc, rawEvidenceGcSummary } from "../raw-evidence-gc.js";
 import { runBackfillCommand } from "./backfill.js";
+import { installMemoryIntegration, inspectMemoryIntegration, } from "./memory-install.js";
 import { createInteractiveExecRunner } from "../process-runner.js";
 const GC_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export async function runDoctor(command, io, hooks, overrides = {}) {
@@ -81,6 +82,14 @@ function doctorInvariants() {
             check: (context) => context.deps.checkAutostart(context),
             fix: (context, _state) => context.deps.fixAutostart(context),
         },
+        // BLI-3580. Runs right after autostart because it is the same kind of
+        // thing: a registration on this machine that nobody should have to be
+        // asked about. Its fix writes host configs, never installs software.
+        {
+            id: "memory-registered",
+            check: (context) => context.deps.checkMemory(context),
+            fix: (context, _state) => context.deps.fixMemory(context),
+        },
         {
             id: "backfill-complete",
             check: (context) => context.deps.checkBackfill(context),
@@ -111,6 +120,8 @@ function defaultDoctorDeps(hooks) {
         checkSingleInstall: checkSingleInstallState,
         checkAutostart: checkAutostartState,
         fixAutostart: fixAutostartState,
+        checkMemory: checkMemoryState,
+        fixMemory: fixMemoryState,
         checkBackfill: checkBackfillState,
         fixBackfill: fixBackfillState,
         checkGc: checkGcState,
@@ -307,6 +318,52 @@ async function fixAutostartState(context) {
     }
     return ok("autostart-alive", "installed", "background sync installed and running");
 }
+/**
+ * BLI Memory's registration on this machine (BLI-3580).
+ *
+ * The step owns the CONFIG, never the software: it writes the MCP entry, the
+ * hooks and the Codex table only when `bli-memory-mcp` actually resolves. With
+ * no server it writes NOTHING and reads `skipped bin_missing` — registering
+ * hooks that point at an absent binary would make every Claude Code turn print
+ * a hook failure, which is worse than waiting a day.
+ */
+async function checkMemoryState(context) {
+    const outcome = await inspectMemoryIntegration(memoryCommandFor(context), context.io);
+    return memoryStepState(outcome, "check");
+}
+async function fixMemoryState(context) {
+    const outcome = await installMemoryIntegration(memoryCommandFor(context), context.io);
+    return memoryStepState(outcome, "fix");
+}
+function memoryCommandFor(context) {
+    return {
+        kind: "memory",
+        action: "install",
+        homeDir: context.command.homeDir,
+        dashboardUrl: context.command.dashboardUrl,
+        dryRun: false,
+        json: context.command.json,
+    };
+}
+function memoryStepState(outcome, phase) {
+    const broken = outcome.targets.filter((target) => target.target !== "bin" && target.status === "failed");
+    if (broken.length > 0) {
+        const first = broken[0];
+        const message = `${first?.target ?? "memory"}: ${first?.reason ?? "failed"}`;
+        return phase === "fix"
+            ? fail("memory-registered", first?.reason ?? "memory_install_failed", message)
+            : needsFix("memory-registered", first?.reason ?? "memory_install_failed", message);
+    }
+    const pending = outcome.targets.filter((target) => target.target !== "bin" &&
+        (target.status === "missing" || target.status === "mismatch"));
+    if (pending.length > 0) {
+        return needsFix("memory-registered", "registration_incomplete", `BLI Memory is not registered with ${pending.map((target) => target.target).join(", ")}`);
+    }
+    if (!outcome.bin_found) {
+        return skipped("memory-registered", "bin_missing", "bli-memory-mcp is not on this machine yet; nothing was written and the next run will try again");
+    }
+    return ok("memory-registered", phase === "fix" ? "installed" : "already_installed", "BLI Memory is registered with both agent hosts");
+}
 /**
  * Pure so it can be unit-tested without touching the real machine's home
  * directory (`getCollectorRuntimePaths()` defaults to `os.homedir()` and

package/dist/commands/jarvis-trace.js

@@ -0,0 +1,184 @@
+/**
+ * `cockpit jarvis --trace <id|last>` — the step tree of one turn (BLI-3560).
+ *
+ * The one thing anybody here ever opened Langfuse for, in the terminal where
+ * the turn was asked. Every model step, every tool call, every server-side
+ * memory step (BLI-3416's doubled answer was one of those and no other surface
+ * showed it), with how long each took, which model ran it, what it spent and
+ * whether it failed.
+ *
+ * ## `last` and the remembered receipt
+ *
+ * A turn now hands back its own trace id, and this module writes that id — with
+ * the conversation it belonged to — to one small file beside the collector's
+ * other state. `--trace last` reads it, so the loop is: ask a question, watch
+ * it come back slow, type `cockpit jarvis --trace last`. If the file is not
+ * there (a fresh shell, a machine that has not asked anything since the
+ * release), the file's remembered THREAD is used to ask the server for that
+ * conversation's newest turn instead — and when there is neither, the refusal
+ * says so in words rather than printing nothing.
+ *
+ * The file holds two opaque ids and a timestamp. No question, no answer, no
+ * name; it is a bookmark, not a transcript.
+ *
+ * ## The lines
+ *
+ * Rendered SERVER-SIDE and printed verbatim. That is deliberate: the ops door,
+ * this terminal and JARVIS's own `readTurnTrace` tool all read the same
+ * sentences from `lib/ops/turn-trace-lines.ts`, so an older CLI against a newer
+ * dashboard still prints the current tree rather than its own stale idea of one.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { colorEnabled, dim, writeLine } from "./cli-io.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+import { towerFailureDetail, towerJsonRequest } from "../tower-client.js";
+/** The bookmark file's name, inside the collector's own state directory. */
+const LAST_TURN_FILE = "last-turn-trace.json";
+function bookmarkPath(homeDir) {
+    const paths = getCollectorRuntimePaths(homeDir ?? os.homedir());
+    return path.join(paths.state_dir, LAST_TURN_FILE);
+}
+/**
+ * Remember the turn that just happened. Never throws: a bookmark that could not
+ * be written must not fail the answer a person already received, so the failure
+ * is named on stderr and the turn stands.
+ */
+export async function rememberTurnTrace(turn, io, homeDir) {
+    if (!turn.traceId && !turn.threadId)
+        return;
+    const file = bookmarkPath(homeDir);
+    const payload = {
+        traceId: turn.traceId ?? null,
+        threadId: turn.threadId ?? null,
+        at: new Date().toISOString(),
+    };
+    try {
+        await mkdir(path.dirname(file), { recursive: true });
+        await writeFile(file, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    }
+    catch (error) {
+        writeLine(io.stderr, `[jarvis cli] could not remember this turn's trace ${JSON.stringify({
+            reason: "bookmark_write_failed",
+            error: error instanceof Error ? error.name : "unknown",
+        })}`);
+    }
+}
+/** The remembered turn, or null when there is not one. Never throws. */
+export async function readRememberedTurn(homeDir) {
+    try {
+        const raw = await readFile(bookmarkPath(homeDir), "utf8");
+        const parsed = JSON.parse(raw);
+        const traceId = typeof parsed.traceId === "string" ? parsed.traceId : null;
+        const threadId = typeof parsed.threadId === "string" ? parsed.threadId : null;
+        if (!traceId && !threadId)
+            return null;
+        return { traceId, threadId, at: typeof parsed.at === "string" ? parsed.at : "" };
+    }
+    catch {
+        // A missing or unreadable bookmark is "nothing is remembered", which is the
+        // exact answer asked for. The caller says so out loud in a sentence.
+        return null;
+    }
+}
+export async function runJarvisTrace(context, io) {
+    const log = (line) => writeLine(io.stderr, line);
+    let traceId = context.requested;
+    let resolvedFrom = "argument";
+    if (context.requested === "last") {
+        const remembered = await readRememberedTurn(context.homeDir);
+        if (!remembered) {
+            return refuse(context, io, "no_remembered_turn", "This machine has not asked JARVIS anything since traces were turned on, so there is no last turn to open. Ask something, then run this again — or pass the trace id from the turn's receipt.");
+        }
+        if (remembered.traceId) {
+            traceId = remembered.traceId;
+            resolvedFrom = "bookmark";
+        }
+        else if (remembered.threadId) {
+            // The bookmark knew the conversation but not the turn (an older receipt).
+            // Ask the server for that conversation's newest turn rather than nothing.
+            const newest = await newestTraceForThread(context, remembered.threadId, io);
+            if (!newest) {
+                return refuse(context, io, "no_traces_in_thread", "That conversation has no recorded turns inside the 30-day retention. Pass a trace id, or ask something new.");
+            }
+            traceId = newest;
+            resolvedFrom = "thread";
+        }
+    }
+    const result = await towerJsonRequest({
+        dashboardUrl: context.dashboardUrl,
+        path: `/api/ops/trace/${encodeURIComponent(traceId)}`,
+        deviceToken: context.deviceToken,
+        fetch: io.fetch,
+        method: "GET",
+        label: "jarvis:trace",
+        timeoutMs: 30_000,
+        log,
+    });
+    if (!result.ok) {
+        return refuse(context, io, result.reason, towerFailureDetail(result.reason, result.detail));
+    }
+    const body = result.body;
+    if (body.ok === false) {
+        return refuse(context, io, body.error ?? "trace_unavailable", body.message ?? "Tower had nothing to show for that turn.");
+    }
+    if (context.json) {
+        writeLine(io.stdout, JSON.stringify(body));
+    }
+    else {
+        writeTraceTree(io, traceId, body);
+    }
+    writeLine(io.stderr, `[jarvis cli] trace read ${JSON.stringify({
+        resolved_from: resolvedFrom,
+        spans: body.trace?.spanCount ?? null,
+        errors: body.trace?.errorCount ?? null,
+        running: body.trace?.runningCount ?? null,
+        duration_ms: body.trace?.durationMs ?? null,
+        truncated: body.truncated ?? null,
+    })}`);
+    return 0;
+}
+async function newestTraceForThread(context, threadId, io) {
+    const result = await towerJsonRequest({
+        dashboardUrl: context.dashboardUrl,
+        path: `/api/ops/trace?thread=${encodeURIComponent(threadId)}&limit=1`,
+        deviceToken: context.deviceToken,
+        fetch: io.fetch,
+        method: "GET",
+        label: "jarvis:trace-thread",
+        timeoutMs: 30_000,
+        log: (line) => writeLine(io.stderr, line),
+    });
+    if (!result.ok)
+        return null;
+    const body = result.body;
+    return body.traces?.[0]?.traceId ?? null;
+}
+function writeTraceTree(io, traceId, body) {
+    const styled = colorEnabled(io);
+    writeLine(io.stdout, `Turn ${traceId}`);
+    if (body.headline)
+        writeLine(io.stdout, dim(body.headline, styled));
+    writeLine(io.stdout, "");
+    for (const line of body.lines ?? [])
+        writeLine(io.stdout, line);
+    if ((body.lines ?? []).length === 0) {
+        // Never a blank screen: an empty tree is a fact and it gets a sentence.
+        writeLine(io.stdout, "That turn recorded no steps.");
+    }
+    if (body.truncated) {
+        writeLine(io.stdout, "");
+        writeLine(io.stdout, dim("Only the first 1000 spans of this turn are shown.", styled));
+    }
+}
+function refuse(context, io, reason, detail) {
+    if (context.json) {
+        writeLine(io.stdout, JSON.stringify({ ok: false, error: reason, detail }));
+    }
+    else {
+        writeLine(io.stderr, detail);
+    }
+    writeLine(io.stderr, `[jarvis cli] trace unavailable ${JSON.stringify({ reason })}`);
+    return 1;
+}

package/dist/commands/jarvis.js

@@ -7,8 +7,9 @@
  */
 import { colorEnabled, dim, isInteractiveStdin, readLine, readPipedText, writeFragment, writeLine, } from "./cli-io.js";
 import { attachedFileRefusalSentence, readAttachedImage, } from "./jarvis-attachment.js";
+import { rememberTurnTrace, runJarvisTrace } from "./jarvis-trace.js";
 import { loadPairedSession, towerFailureDetail, towerJsonRequest, towerRequest, } from "../tower-client.js";
-import { readTowerTurn, streamFailureDetail, } from "../tower-stream.js";
+import { readTowerTurn, streamFailureDetail, turnTimingFields, } from "../tower-stream.js";
 /**
  * A citation line's link, as the dashboard mints it (BLI-3570):
  * `Source: BLI-1234 — Judge outage <https://linear.app/…>`. The words are the
@@ -74,7 +75,12 @@ function writeReplyContinuation(io, tail) {
  */
 const TURN_DEADLINE_MS = 125_000;
 export async function runJarvis(command, io) {
+    // Milliseconds since this process started (`performance.now()` counts from
+    // `timeOrigin`), captured before this command does anything of its own.
+    const bootMs = Math.round(performance.now());
+    const sessionStartedAt = Date.now();
     const session = await loadPairedSession("jarvis", command.homeDir);
+    const sessionMs = Date.now() - sessionStartedAt;
     const dashboardUrl = command.dashboardUrl ?? session.dashboard_url;
     // BLI-3458: reading back what was already said. No turn, no model, no
     // conversation-ledger write — and, on the server, only ever THIS device
@@ -82,9 +88,32 @@ export async function runJarvis(command, io) {
     if (command.threads || command.history) {
         return readHistory({ command, dashboardUrl, deviceToken: session.device_token }, io);
     }
+    // BLI-3560: reading back what a turn DID. Same class of act, same absence of
+    // a model call — this one asks the ops trace door rather than the ledger.
+    if (command.trace) {
+        return runJarvisTrace({
+            dashboardUrl,
+            deviceToken: session.device_token,
+            requested: command.trace,
+            json: command.json,
+            homeDir: command.homeDir,
+        }, io);
+    }
+    const promptStartedAt = Date.now();
     const oneShotPrompt = await resolveOneShotPrompt(command, io);
     if (oneShotPrompt !== null) {
-        return sendOneTurn({ command, dashboardUrl, deviceToken: session.device_token }, oneShotPrompt, io);
+        return sendOneTurn({
+            command,
+            dashboardUrl,
+            deviceToken: session.device_token,
+            boot: {
+                bootMs,
+                sessionMs,
+                // Only meaningful when the question was piped; an argument costs
+                // nothing to read and reporting a stdin wait for it would be a lie.
+                promptMs: command.prompt ? null : Date.now() - promptStartedAt,
+            },
+        }, oneShotPrompt, io);
     }
     if (command.json) {
         throw new Error("cockpit jarvis --json needs --prompt, positional text, or piped stdin.");
@@ -96,7 +125,14 @@ export async function runJarvis(command, io) {
             continue;
         if (prompt === "/exit" || prompt === "/quit")
             return 0;
-        const exitCode = await sendOneTurn({ command, dashboardUrl, deviceToken: session.device_token }, prompt, io);
+        const exitCode = await sendOneTurn({
+            command,
+            dashboardUrl,
+            deviceToken: session.device_token,
+            // The typing wait belongs to the person, not to the turn, so no prompt
+            // span is reported for an interactive turn.
+            boot: { bootMs, sessionMs, promptMs: null },
+        }, prompt, io);
         if (exitCode !== 0)
             return exitCode;
     }
@@ -216,6 +252,13 @@ async function sendOneTurn(context, prompt, io) {
     // works against both server versions with no flag.
     const wantsStream = context.command.stream !== false;
     const log = (line) => writeLine(io.stderr, line);
+    // BLI-3591: everything this turn did before the question left the machine.
+    // There is no self-update probe, no floor check and no settings fetch on
+    // this path — the ONLY awaits between the command starting and the POST are
+    // the paired-session read, the piped-prompt read and an attached image, and
+    // 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;
     const requested = await towerRequest({
         dashboardUrl: context.dashboardUrl,
         path: "/api/jarvis/cli",
@@ -283,6 +326,11 @@ async function sendOneTurn(context, prompt, io) {
     // because it already sent every step live; the activity we collected is that
     // same trace, so `--json` still gets one.
     const trace = body.trace ?? activityToTrace(turn.activity);
+    // BLI-3560: bookmark this turn so `cockpit jarvis --trace last` can open its
+    // step tree. Written before the reply is printed for no reason other than
+    // keeping the failure — which is only ever a stderr line — above the answer
+    // rather than after it.
+    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,
@@ -291,6 +339,23 @@ async function sendOneTurn(context, prompt, io) {
             model: body.model ?? null,
             trace,
             subject: body.subject ?? null,
+            // BLI-3582: the server's own split of the wait. `null` from a
+            // dashboard that does not measure it yet.
+            latency: latencyFields(body.latency),
+            // BLI-3591: this side's own half of the same wait, so a consumer can
+            // put the whole journey together without a stopwatch of its own.
+            clientLatency: {
+                bootMs: context.boot.bootMs,
+                sessionMs: context.boot.sessionMs,
+                promptMs: context.boot.promptMs,
+                preRequestMs,
+                respondedMs: requested.respondedMs,
+                firstByteMs: turn.timing.firstByteMs,
+                firstFrameMs: turn.timing.firstFrameMs,
+                firstTokenMs: turn.timing.firstTokenMs,
+                elapsedMs: Date.now() - startedAt,
+            },
+            ...(body.traceId ? { traceId: body.traceId } : {}),
         }));
     }
     else {
@@ -324,9 +389,43 @@ async function sendOneTurn(context, prompt, io) {
         // dashboard means the answer landed all at once.
         streamed_chars: turn.draft.length,
         revised: body.revised === true,
+        // BLI-3582: `elapsed_ms` above is the whole wait as this side felt it;
+        // these three say which part of it was the dashboard's prep, which was
+        // the model's first token, and how long the socket stayed silent before
+        // the first byte. All null against a dashboard that does not send them.
+        ...latencyLogFields(body.latency),
+        // BLI-3591: the terminal's own half, on the same line, so the gap
+        // between the dashboard's first token and the first character a person
+        // sees stops being a mystery with nobody's name on it. `boot_ms` and
+        // `session_ms` are process facts (identical on every turn of an
+        // interactive session); the rest are this turn's, measured from the
+        // moment the turn started.
+        ...clientTimingFields(context.boot, {
+            preRequestMs,
+            respondedMs: requested.respondedMs,
+            timing: turn.timing,
+        }),
     })}`);
     return 0;
 }
+/**
+ * The terminal's own spans as log fields (BLI-3591).
+ *
+ * Deliberately snake_case beside the dashboard's three, and deliberately
+ * distinct names: `model_ttft_ms` is the dashboard's clock, `first_token_ms`
+ * is this one, and confusing them is how a latency line stops being
+ * answerable.
+ */
+function clientTimingFields(boot, turn) {
+    return {
+        boot_ms: boot.bootMs,
+        session_ms: boot.sessionMs,
+        prompt_ms: boot.promptMs,
+        pre_request_ms: turn.preRequestMs,
+        responded_ms: turn.respondedMs,
+        ...turnTimingFields(turn.timing),
+    };
+}
 /**
  * The answer as it is written, in a terminal (BLI-3517).
  *
@@ -524,7 +623,7 @@ function writeModelReceipt(io, model) {
     if (!model)
         return;
     const requested = typeof model.requestedModel === "string" ? model.requestedModel : null;
-    const answered = typeof model.model === "string" ? model.model : null;
+    const answered = namedModel(model.model);
     const mismatched = requested !== null && answered !== null && requested !== answered;
     if (!model.fallback && !mismatched)
         return;
@@ -533,6 +632,47 @@ function writeModelReceipt(io, model) {
     // schema. Say what the receipt actually reports.
     writeLine(io.stdout, `Model: ${answered ?? "an unknown model"} answered instead of ${requested ?? "the requested model"}`);
 }
+/** One millisecond span off the wire, or null for anything that is not a number. */
+function latencyMs(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/** The latency split for `--json`, always the same three keys so a consumer can rely on them. */
+function latencyFields(latency) {
+    return {
+        wireMs: latencyMs(latency?.wireMs),
+        prepMs: latencyMs(latency?.prepMs),
+        modelTtftMs: latencyMs(latency?.modelTtftMs),
+    };
+}
+/** The same three spans as log fields, snake_case like everything else on that line. */
+function latencyLogFields(latency) {
+    const split = latencyFields(latency);
+    return {
+        wire_ms: split.wireMs,
+        prep_ms: split.prepMs,
+        model_ttft_ms: split.modelTtftMs,
+    };
+}
+/**
+ * The receipt's `model` field, unless it is the server's own "I could not tell"
+ * sentinel (BLI-3582).
+ *
+ * `modelReceipt` on the dashboard writes the literal string `"unknown"` when
+ * the run reported no model, and this side used to read that as a model NAME —
+ * so a turn whose model was simply unnamed printed
+ * `Model: unknown answered instead of gpt-5.6-terra`, a fallback notice for a
+ * fallback that never happened. Every streamed turn hit it. The dashboard fix
+ * makes the streamed path name the model again; this one makes the sentinel
+ * unable to invent a fallback on any dashboard version, old or new.
+ */
+function namedModel(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.toLowerCase() === "unknown")
+        return null;
+    return trimmed;
+}
 function writeFailure(command, io, reason, detail) {
     if (command.json) {
         writeLine(io.stdout, JSON.stringify({ ok: false, error: reason, detail }));

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

@@ -570,6 +570,32 @@ export function parseAgentRulesArgs(args) {
         json: values.booleans.has("--json"),
     };
 }
+/**
+ * BLI-3580. `install` is the default action on purpose: this command exists to
+ * be run unasked (by `do-everything` and by the sync tick), and a bare
+ * `cockpit memory` should do the thing rather than print usage.
+ */
+export function parseMemoryArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--dashboard-url", "--dry-run", "--json"],
+        valueFlags: ["--home", "--dashboard-url"],
+    });
+    if (values.positionals.length > 1) {
+        throw new Error("memory accepts at most one action (install|status).");
+    }
+    const action = values.positionals[0] ?? "install";
+    if (action !== "install" && action !== "status") {
+        throw new Error("memory action must be install or status.");
+    }
+    return {
+        kind: "memory",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        dryRun: values.booleans.has("--dry-run"),
+        json: values.booleans.has("--json"),
+    };
+}
 function parseAgentRulesHost(value) {
     const host = value?.trim().toLowerCase() || "all";
     if (host === "codex" || host === "claude" || host === "all")

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

@@ -32,6 +32,8 @@ export function parseJarvisArgs(args) {
             // something new. Neither takes a turn or reaches the model.
             "--threads",
             "--history",
+            // BLI-3560: reading back what a turn DID — the step tree of one turn.
+            "--trace",
             "--limit",
             "--json",
         ],
@@ -42,6 +44,7 @@ export function parseJarvisArgs(args) {
             "--as",
             "--thread",
             "--model",
+            "--trace",
             "--image",
             "--file",
             "--date",
@@ -87,6 +90,23 @@ export function parseJarvisArgs(args) {
     if ((threads || history) && date) {
         throw new Error("jarvis --threads and --history replay what was said; they bind no page.");
     }
+    // BLI-3560. `--trace` reads back what a turn DID, the same class of act as
+    // `--threads` and `--history`, and refused alongside them for the same
+    // reason: a command that quietly asked a question while you asked to see one
+    // is worse than a refusal.
+    const trace = optionalNonEmpty(values.flags.get("--trace"));
+    if (trace && (threads || history)) {
+        throw new Error("jarvis --trace shows one turn's steps; --threads and --history replay what was said. Pass one.");
+    }
+    if (trace && (flaggedPrompt || positionalPrompt)) {
+        throw new Error("jarvis --trace shows a turn that already ran; it does not take a question.");
+    }
+    if (trace && image) {
+        throw new Error("jarvis --trace does not take an attachment.");
+    }
+    if (trace !== undefined && !/^(last|[A-Za-z0-9_-]{1,64})$/.test(trace)) {
+        throw new Error("jarvis --trace takes `last` or a trace id (up to 64 letters, numbers, underscores or hyphens).");
+    }
     return {
         kind: "jarvis",
         homeDir: optionalNonEmpty(values.flags.get("--home")),
@@ -96,6 +116,7 @@ export function parseJarvisArgs(args) {
         thread,
         threads,
         history,
+        ...(trace ? { trace } : {}),
         limit: optionalPositiveInteger(values.flags.get("--limit"), "--limit"),
         // BLI-3381: no client-side allowlist — the dashboard forwards this key
         // to the inference server's own allowlist and relays its refusal.

package/dist/commands/local-args.js

@@ -1,4 +1,4 @@
-import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
+import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
 import { parseBriefArgs, parseCorrectArgs, parseJarvisArgs, parseModelArgs, parseNotesArgs, parseOpsArgs, parseScoutArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
@@ -80,6 +80,8 @@ export function parseLocalArgs(argv) {
             return parseAutostartArgs(argv.slice(1));
         case "agent-rules":
             return parseAgentRulesArgs(argv.slice(1));
+        case "memory":
+            return parseMemoryArgs(argv.slice(1));
         case "release":
             return parseReleaseArgs(argv.slice(1));
         default:

package/dist/commands/local-help.js

@@ -38,6 +38,7 @@ export const rootCommandNames = new Set([
     "serve",
     "autostart",
     "agent-rules",
+    "memory",
     "release",
 ]);
 export function localCommandHelp(command) {
@@ -56,7 +57,7 @@ export function localCommandHelp(command) {
         "  cockpit start [--ticket <id>|--clear-ticket] [--topic <label>] [--intent <intent>] [--phase <phase>] [--workspace <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sync [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit analyze [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit jarvis [question] [--prompt <question>] [--as <person>] [--date <YYYY-MM-DD>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--dashboard-url <url>] [--json]",
+        "  cockpit jarvis [question] [--prompt <question>] [--as <person>] [--date <YYYY-MM-DD>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--trace <id|last>] [--dashboard-url <url>] [--json]",
         "  cockpit model [show|set <provider:model>] [--json]",
         "  cockpit scout [start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
         "  cockpit ops [status [--job <id>] [--skips] | recompile --person <email|name|id> [--dry-run]] [--dashboard-url <url>] [--json]",
@@ -74,6 +75,7 @@ export function localCommandHelp(command) {
         "  cockpit serve [--port <port>] [--workspace <path>]",
         "  cockpit autostart [install|uninstall|status] [--workspace <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
         "  cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
+        "  cockpit memory [install|status] [--dashboard-url <url>] [--dry-run] [--json]",
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
         "",
         `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,
@@ -279,7 +281,7 @@ function localSubcommandHelp(command) {
         [
             "jarvis",
             [
-                "Usage: cockpit jarvis [question] [--prompt <question>] [--as <person>] [--date <YYYY-MM-DD>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--dashboard-url <url>] [--json]",
+                "Usage: cockpit jarvis [question] [--prompt <question>] [--as <person>] [--date <YYYY-MM-DD>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--trace <id|last>] [--dashboard-url <url>] [--json]",
                 "",
                 "Chats with the same JARVIS used by Tower web chat and the BLI Slack DM.",
                 "--as selects the existing website person space; it changes who the chat is about, never who is authenticated.",
@@ -294,6 +296,7 @@ function localSubcommandHelp(command) {
                 "A turn that outlives the dashboard's own ceiling is reported as turn_timed_out — an incomplete answer is never printed as a finished one.",
                 "The command uses the existing paired device identity. It cannot override the caller, team, role, or person scope.",
                 "--threads lists the terminal conversations on this account; --thread <name> --history replays one (the newest --limit <n> messages). Neither takes a question, and neither can reach anybody else's conversations.",
+                "--trace <id|last> prints the step tree of one turn — every model step, tool call and server-side memory step, with how long each took, which model ran it, the tokens it spent and what failed. `last` opens the turn this machine asked most recently. Like --threads it takes no question and reaches no model.",
                 "Run `cockpit login` first if this machine is not paired.",
             ],
         ],
@@ -529,6 +532,20 @@ function localSubcommandHelp(command) {
                 "Action defaults to `install`.",
             ],
         ],
+        [
+            "memory",
+            [
+                "Usage: cockpit memory [install|status] [--dashboard-url <url>] [--dry-run] [--json]",
+                "",
+                "Registers BLI Memory on this machine: the `bli-memory` MCP server plus the",
+                "recall/save hooks, for Claude Code (~/.claude.json, ~/.claude/settings.json)",
+                "and for Codex (~/.codex/config.toml, ~/.codex/skills/bli-memory/).",
+                "Idempotent: it merges with what is already there, never duplicates its own",
+                "entries, and reads the stored config back before reporting success.",
+                "`do-everything` runs it, and the sync tick re-runs it at most once a day.",
+                "Action defaults to `install`. See docs/runbooks/bli-memory-install.md.",
+            ],
+        ],
         [
             "release",
             [

package/dist/commands/local.js

@@ -30,6 +30,7 @@ import { runNotes } from "./notes.js";
 import { runServe } from "./serve.js";
 import { runAutostart } from "./autostart-command.js";
 import { runAgentRules } from "./agent-rules-command.js";
+import { runMemoryInstall } from "./memory-install.js";
 import { parseLocalArgs } from "./local-args.js";
 // `./local.js` is the published entry point for this command surface: the
 // public CLI's generated root, commands/root.ts, doctor.ts and the test suite
@@ -125,6 +126,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runAutostart(command, io);
             case "agent-rules":
                 return await runAgentRules(command, io);
+            case "memory":
+                return await runMemoryInstall(command, io);
             case "release":
                 return await runRelease(command, io);
         }