@bli-cockpit/cli 0.2.45 → 0.2.47

package/dist/commands/doctor.js

@@ -1,12 +1,13 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { autostartStatus, installAutostartAgent } from "../autostart.js";
+import { autostartStatus, installAutostartAgent, registeredRuntimePathProblems, } from "../autostart.js";
 import { savedDiscoveryLimitArgs } from "../discovery-limits.js";
 import { describeError, redactedHealthDetail } from "../health-detail.js";
 import { inspectBackfillLock } from "../backfill-lock.js";
 import { backfillCompletionCovers, readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, readLocalCollectorSessionFile, } from "../local-state.js";
 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 { createInteractiveExecRunner } from "../process-runner.js";
@@ -71,6 +72,10 @@ function doctorInvariants() {
             fix: fixRootState,
             requiresInteractiveFix: true,
         },
+        // Deliberately has NO fix: uninstalling software the operator did not ask
+        // to have uninstalled is not a repair (BLI-3218/BLI-3553). Doctor names the
+        // other install and the exact command; the person decides.
+        { id: "single-install", check: (context) => context.deps.checkSingleInstall(context) },
         {
             id: "autostart-alive",
             check: (context) => context.deps.checkAutostart(context),
@@ -103,6 +108,7 @@ function defaultDoctorDeps(hooks) {
         runLogin: (context) => hooks.runLogin(context.command, context.io),
         readRoots: readRootState,
         resolveAndSaveRoots: (context) => hooks.resolveAndSaveRoots(context.command, context.io),
+        checkSingleInstall: checkSingleInstallState,
         checkAutostart: checkAutostartState,
         fixAutostart: fixAutostartState,
         checkBackfill: checkBackfillState,
@@ -221,6 +227,37 @@ async function readRootState(context) {
         "  3) There is no `--repair` flag; the onboard-rerun is the repair path.",
     ].join("\n"));
 }
+/**
+ * BLI-3218/BLI-3553. Two Tower installs on one machine make each one's tick
+ * call the other's registration stale and re-register itself, so the plist
+ * flaps every 15 minutes and the device reports two CLI versions the same
+ * morning. Doctor OFFERS the removal and never performs it: an operator may
+ * have a second prefix on purpose, and `npm uninstall -g` of something nobody
+ * asked to remove is not a repair. The row therefore has no `fix` — it is
+ * information, and doctor still exits 0.
+ */
+async function checkSingleInstallState(context) {
+    const exec = context.io.exec;
+    if (!exec) {
+        return skipped("single-install", "runner_unavailable", "could not look for a second Tower install");
+    }
+    const finding = await detectSecondCockpitInstall({ exec });
+    if (!finding.detected) {
+        return ok("single-install", finding.reason, finding.install_count === 1
+            ? "one Tower install on this machine"
+            : "no second Tower install found");
+    }
+    // The full paths go to the operator's own screen; redactedHealthDetail
+    // masks them again before any of this is uploaded.
+    return needsFix("single-install", "second_install_detected", [
+        `${finding.install_count} Tower installs are on this machine's PATH:`,
+        ...finding.paths.map((entry) => `  - ${entry}`),
+        "Both will fight over the background scheduler, re-registering it against each other.",
+        "Keep one. To remove the other:",
+        `  npm uninstall -g @bli-cockpit/cli   # run it with the node that owns ${finding.other_bin ?? "the other bin"}`,
+        "Nothing was uninstalled — that is your call.",
+    ].join("\n"));
+}
 async function checkAutostartState(context) {
     const exec = context.io.exec;
     if (!exec) {
@@ -234,6 +271,15 @@ async function checkAutostartState(context) {
         exec,
     });
     if (result.status === "loaded") {
+        // BLI-3553: "loaded" only means the scheduler accepted the registration.
+        // It says nothing about whether the binary that registration names still
+        // exists — and `brew upgrade node` deletes exactly that. Ask the
+        // filesystem about the paths the PLATFORM holds, not the ones this process
+        // happens to be running under.
+        const missing = await registeredRuntimePathProblems({ exec });
+        if (missing.length > 0) {
+            return needsFix("autostart-alive", "runtime_path_missing", `background sync is registered but cannot run: ${missing.join("; ")}`);
+        }
         return ok("autostart-alive", "already_installed", "background sync is running");
     }
     if (result.status === "unsupported") {

package/dist/commands/heartbeat.js

@@ -0,0 +1,175 @@
+/**
+ * "I am alive, and these are the folders I may look at." One POST per tick.
+ *
+ * BLI-3551. The dashboard learned a device was alive only when an ambient
+ * envelope arrived, and an envelope only arrives when there was something to
+ * collect. A machine whose operator works entirely outside the approved roots
+ * therefore went silent while working perfectly: 377 ticks in 38 hours without
+ * `last_seen_at` moving once. Dead and quiet looked identical.
+ *
+ * Three deliberate choices:
+ *
+ * - **Not spooled.** The install-events outbox retries for days, which is right
+ *   for a receipt and wrong for a heartbeat: a heartbeat delivered tomorrow is
+ *   a lie about today. A failed send is logged and dropped, and the next tick
+ *   is fifteen minutes away.
+ * - **Never throws, never fails the sync.** Same rule as the self-update tail.
+ * - **Roots travel as labels.** `{ basename, path_sha256 }` — the folder name a
+ *   person recognises plus the stable identity of the normalized absolute path.
+ *   The path itself never leaves the machine, exactly as with `cwd_hash` on the
+ *   session rows.
+ */
+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 { describeError } from "../health-detail.js";
+import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
+const HEARTBEAT_TIMEOUT_MS = 5_000;
+/**
+ * The label form of one approved root.
+ *
+ * `path.resolve` first so `~/BLI`, `~/BLI/` and `~/BLI/.` are one identity, and
+ * on Windows so `c:\users\…` and `C:\Users\…` do not hash apart — the platform
+ * treats them as the same folder, and two machines pointing at it must compare
+ * equal. Case is folded ONLY on Windows, where the filesystem is
+ * case-insensitive; folding on macOS would merge two genuinely distinct roots.
+ */
+export function collectionRootLabel(root, platform = process.platform) {
+    const pathApi = platform === "win32" ? path.win32 : path.posix;
+    const resolved = platform === "win32"
+        ? path.win32.normalize(root).replace(/[\\/]+$/u, "")
+        : path.posix.normalize(root).replace(/\/+$/u, "");
+    const canonical = platform === "win32" ? resolved.toLowerCase() : resolved;
+    const basename = pathApi.basename(resolved) || resolved;
+    return {
+        basename: basename.slice(0, 160),
+        path_sha256: crypto
+            .createHash("sha256")
+            .update(canonical, "utf8")
+            .digest("hex"),
+    };
+}
+/**
+ * The label set for a machine's approved roots, one entry per real folder.
+ *
+ * The collector deliberately keeps CONSENT ALIASES — on macOS an approved
+ * `/var/folders/…` root is held alongside its `/private/var/folders/…`
+ * realpath, so attribution matches either spelling. Both are true, and both
+ * name one folder; a heartbeat that shipped both would make every Mac look like
+ * it had twice the roots it has. Symlinks are resolved before hashing so the
+ * aliases collapse into the one folder they describe, and a path that cannot be
+ * resolved (deleted, or a Windows spelling on a POSIX host) keeps its own
+ * spelling rather than being dropped.
+ */
+export function collectionRootLabels(roots, platform = process.platform, realpath = defaultRealpath) {
+    const byHash = new Map();
+    for (const root of roots) {
+        if (!root.trim())
+            continue;
+        let resolved = root;
+        try {
+            resolved = realpath(root);
+        }
+        catch {
+            // Keep the spelling we were given: a root that is not on disk right now
+            // is still a root this machine is allowed to look at.
+        }
+        const label = collectionRootLabel(resolved, platform);
+        if (!byHash.has(label.path_sha256))
+            byHash.set(label.path_sha256, label);
+    }
+    return [...byHash.values()];
+}
+function defaultRealpath(input) {
+    return fs.realpathSync.native(input);
+}
+export function buildCollectorHeartbeat(options) {
+    const platform = options.platform ?? os.platform();
+    return {
+        schema_version: COLLECTOR_HEARTBEAT_SCHEMA_VERSION,
+        generated_at: (options.now ?? new Date()).toISOString(),
+        collector_version: options.collectorVersion ?? LOCAL_COLLECTOR_VERSION,
+        os_platform: platform,
+        roots: collectionRootLabels(options.roots, platform),
+        last_sync_status: options.facts.status,
+        ...(options.facts.reason ? { last_sync_reason: options.facts.reason } : {}),
+        ...(typeof options.facts.sessionsObserved === "number"
+            ? { sessions_observed: options.facts.sessionsObserved }
+            : {}),
+        ...(typeof options.facts.sessionsOutsideRoot === "number"
+            ? { sessions_outside_root: options.facts.sessionsOutsideRoot }
+            : {}),
+    };
+}
+/**
+ * Sends the heartbeat. Returns whether it landed; never throws.
+ *
+ * Every branch says something (BLI-3551 / the logging contract): a missing
+ * device session, a refusal, a transport failure and the success all get one
+ * line, because "did this machine check in today?" must be answerable from
+ * `sync.err.log` alone when the dashboard says a device is quiet.
+ */
+export async function sendCollectorHeartbeatBestEffort(options) {
+    const paths = getCollectorRuntimePaths(options.homeDir);
+    const session = await readLocalCollectorSessionFile(paths).catch(() => null);
+    if (!session ||
+        session.session_state !== "valid" ||
+        typeof session.device_token !== "string" ||
+        !session.device_token) {
+        console.error("[heartbeat] no valid device session on this machine; the dashboard will show it as quiet", JSON.stringify({
+            reason: "no_device_session",
+            next_action: "run `cockpit do-everything` to pair this machine again",
+        }));
+        return false;
+    }
+    const heartbeat = buildCollectorHeartbeat({
+        roots: options.roots,
+        facts: options.facts,
+        ...(options.now ? { now: options.now } : {}),
+    });
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), HEARTBEAT_TIMEOUT_MS);
+    try {
+        const response = await options.io.fetch(`${options.dashboardUrl}/api/ambient/heartbeat`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${session.device_token}`,
+            },
+            body: JSON.stringify(heartbeat),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            // A heartbeat is not retried, so the reason has to be said once, here.
+            console.error("[heartbeat] the dashboard refused this tick's heartbeat", JSON.stringify({
+                reason: "heartbeat_rejected",
+                http_status: response.status,
+                root_count: heartbeat.roots.length,
+            }));
+            return false;
+        }
+        console.error("[heartbeat] checked in", JSON.stringify({
+            reason: "heartbeat_recorded",
+            http_status: response.status,
+            root_count: heartbeat.roots.length,
+            sync_status: heartbeat.last_sync_status,
+            sync_reason: heartbeat.last_sync_reason ?? null,
+            sessions_observed: heartbeat.sessions_observed ?? null,
+            sessions_outside_root: heartbeat.sessions_outside_root ?? null,
+        }));
+        return true;
+    }
+    catch (error) {
+        console.error("[heartbeat] could not reach the dashboard this tick", JSON.stringify({
+            reason: "heartbeat_transport_failed",
+            root_count: heartbeat.roots.length,
+            ...describeError(error),
+        }));
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/commands/install-receipts.js

@@ -14,7 +14,6 @@ import { errorMessage, writeLine } from "./cli-io.js";
 import { describeError, maskLocalIdentifiers, redactedHealthDetail, } from "../health-detail.js";
 import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
 import { redactSecretLikeContent } from "@bli-cockpit/telemetry-core";
-import { COLLECTION_ROOT_REQUIRED } from "../onboarding-roots.js";
 import { enqueueInstallEventEntry, readPendingInstallEventEntries, recordInstallEventAttemptFailure, removeInstallEventEntry, } from "../spool/install-event-outbox.js";
 export function addInstallEvent(events, step, status, errorCode, 
 // BLI-2542: the bucket alone cannot be acted on. Callers that hold the reason
@@ -188,24 +187,17 @@ function classifyInstallTelemetryError(error) {
         return "network";
     return "failed";
 }
-export function classifySyncHealthError(error) {
-    const message = errorMessage(error);
-    if (/auth|token|session|unauthorized|forbidden|401|403/iu.test(message)) {
-        return "auth_failed";
-    }
-    if (/fetch|network|enotfound|econnrefused|timeout/iu.test(message)) {
-        return "network_failed";
-    }
-    // Anchored on the code the collector actually throws rather than on loose
-    // vocabulary. The old test matched /collection.root|workspace|repo|worktree/
-    // against the message, so any failure that merely mentioned a repo was filed
-    // as a collection-root failure and the real reason was lost (BLI-2492).
-    if (message.includes(COLLECTION_ROOT_REQUIRED) ||
-        /collection root/iu.test(message)) {
-        return "collection_root_failed";
-    }
-    return "sync_failed";
-}
+/**
+ * The bucket a `sync_complete` receipt carries.
+ *
+ * The implementation moved to `../sync-health-class.js` in BLI-3551 and is
+ * re-exported here because this module's export surface is what `local.ts` and
+ * the tests import. It no longer reads the error's message: matching
+ * `/auth|token|session|…/` against the text filed the sync's own
+ * `session_report_unposted:no_successful_sync` label as `auth_failed` on every
+ * tick of a machine whose credentials were fine.
+ */
+export { classifySyncHealthError, classifySyncFailureRecords, } from "../sync-health-class.js";
 // The bucket above is for aggregation. This is the reason — the actual message,
 // redacted on the machine that produced it, before it ever leaves.
 //

package/dist/commands/install-update.js

@@ -14,7 +14,7 @@ import { defaultExec, defaultInteractiveExec, writeExecOutput, writeLine } from
 import { assertCollectionRootPersisted } from "./collection-roots.js";
 import { addInstallEvent, reportInstallEventsBestEffort } from "./install-receipts.js";
 import { installLocalCollector, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
-import { COLLECTION_ROOT_REQUIRED, missingCollectionRootMessage, normalizeRootsDetailed, rootRejectionExplanation, } from "../onboarding-roots.js";
+import { COLLECTION_ROOT_REQUIRED, CollectionRootRequiredError, missingCollectionRootMessage, normalizeRootsDetailed, rootRejectionExplanation, } from "../onboarding-roots.js";
 export class SelfUpdateError extends Error {
     result;
     eacces;
@@ -75,9 +75,9 @@ function resolveInstallCommandRoots(command) {
         };
     }
     if (detailed.rejected.length > 0) {
-        throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${rootRejectionExplanation(detailed.rejected[0], command)}`);
+        throw new CollectionRootRequiredError(rootRejectionExplanation(detailed.rejected[0], command));
     }
-    throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${missingCollectionRootMessage(command)}`);
+    throw new CollectionRootRequiredError(missingCollectionRootMessage(command));
 }
 export async function runUpdate(command, io) {
     const installEvents = [];

package/dist/commands/jarvis.js

@@ -174,6 +174,9 @@ async function sendOneTurn(context, prompt, io) {
                 thread: context.command.thread,
                 subject: context.command.subject,
                 model: context.command.model,
+                // BLI-3484: which day's page this turn is about. Sent verbatim — the
+                // dashboard decides what counts as a date and whose day it is.
+                date: context.command.date,
             },
         log,
     });
@@ -263,6 +266,8 @@ function buildAttachmentForm(command, prompt, attachment) {
         form.set("subject", command.subject);
     if (command.model)
         form.set("model", command.model);
+    if (command.date)
+        form.set("date", command.date);
     form.set("image", new File([attachment.bytes], attachment.fileName, { type: attachment.mimeType }));
     return form;
 }

package/dist/commands/local-args.js

@@ -776,6 +776,7 @@ function parseAutostartArgs(args) {
             "--workspace",
             "--dashboard-url",
             "--interval-seconds",
+            "--parent-pid",
             "--json",
         ],
         valueFlags: [
@@ -784,13 +785,17 @@ function parseAutostartArgs(args) {
             "--workspace",
             "--dashboard-url",
             "--interval-seconds",
+            "--parent-pid",
         ],
     });
     if (values.positionals.length > 1) {
         throw new Error("autostart accepts at most one action (install|uninstall|status).");
     }
     const action = values.positionals[0] ?? "install";
-    if (action !== "install" && action !== "uninstall" && action !== "status") {
+    if (action !== "install" &&
+        action !== "uninstall" &&
+        action !== "status" &&
+        action !== "heal-detached") {
         throw new Error("autostart action must be install, uninstall, or status.");
     }
     return {
@@ -800,6 +805,7 @@ function parseAutostartArgs(args) {
         repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         dashboardUrl: normalizeUrl(values.flags.get("--dashboard-url") ?? DEFAULT_DASHBOARD_URL),
         intervalSeconds: optionalPositiveInteger(values.flags.get("--interval-seconds"), "--interval-seconds") ?? DEFAULT_AUTOSTART_INTERVAL_SECONDS,
+        parentPid: optionalPositiveInteger(values.flags.get("--parent-pid"), "--parent-pid"),
         json: values.booleans.has("--json"),
     };
 }
@@ -842,6 +848,8 @@ function parseJarvisArgs(args) {
             "--image",
             "--file",
             "--no-stream",
+            // BLI-3484: which day's page this turn is about.
+            "--date",
             // BLI-3458: reading back what was already said, rather than saying
             // something new. Neither takes a turn or reaches the model.
             "--threads",
@@ -858,6 +866,7 @@ function parseJarvisArgs(args) {
             "--model",
             "--image",
             "--file",
+            "--date",
             "--limit",
         ],
     });
@@ -892,6 +901,14 @@ function parseJarvisArgs(args) {
     if ((threads || history) && image) {
         throw new Error("jarvis --threads and --history do not take an attachment.");
     }
+    // BLI-3484. `--date` binds the page that was live on one of the subject's
+    // days, so a turn can be about Sunday's page. Refused on the two reading
+    // commands for the same reason an attachment is: they replay what was said
+    // and bind no page at all.
+    const date = optionalNonEmpty(values.flags.get("--date"));
+    if ((threads || history) && date) {
+        throw new Error("jarvis --threads and --history replay what was said; they bind no page.");
+    }
     return {
         kind: "jarvis",
         homeDir: optionalNonEmpty(values.flags.get("--home")),
@@ -905,6 +922,7 @@ function parseJarvisArgs(args) {
         // BLI-3381: no client-side allowlist — the dashboard forwards this key
         // to the inference server's own allowlist and relays its refusal.
         model: optionalNonEmpty(values.flags.get("--model")),
+        ...(date ? { date } : {}),
         imagePath: image ?? file,
         // BLI-3457: streaming is on unless a caller opts out. A dashboard that
         // does not stream yet still answers plain JSON, so this flag is for
@@ -1137,6 +1155,12 @@ function parseWorkbookArgs(args) {
  * does: the dashboard resolves it against the roster and the database (or the
  * route's own mirror of the database's rule) decides whether the page opens.
  * Nothing is decided here.
+ *
+ * `--date` (BLI-3484) is the terminal's `?d=`, and the same sentence applies to
+ * it twice over: what counts as a date, where that person's day starts, and
+ * whether anything was compiled for it are all the dashboard's answer. A local
+ * copy of "when does Tuesday begin" would be a second answer to a question this
+ * product already answers per person, per zone.
  */
 function parseBriefArgs(args) {
     const values = parseNamedArgs(args, {
@@ -1147,6 +1171,10 @@ function parseBriefArgs(args) {
             "--as",
             "--who",
             "--version",
+            "--date",
+            "--delta",
+            "--against",
+            "--days",
             "--tldr",
             "--full",
             "--versions",
@@ -1157,15 +1185,26 @@ function parseBriefArgs(args) {
             "--no-wait",
             "--json",
         ],
-        valueFlags: ["--home", "--dashboard-url", "--for", "--as", "--who", "--version", "--reason"],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--for",
+            "--as",
+            "--who",
+            "--version",
+            "--date",
+            "--against",
+            "--days",
+            "--reason",
+        ],
     });
     // Bare `cockpit brief` reads the page, which is what somebody typing it almost
     // always wants — the same shape `cockpit notes` and `cockpit scout` have.
     // `status` (BLI-3462) answers why a brief was or was not delivered.
     const first = values.positionals[0];
     const action = (first === undefined ? "read" : first);
-    if (!["read", "edit", "rewrite", "status"].includes(action)) {
-        throw new Error(`Unknown brief command: ${first}. Try edit, rewrite or status, or nothing to read it.`);
+    if (!["read", "edit", "rewrite", "history", "status"].includes(action)) {
+        throw new Error(`Unknown brief command: ${first}. Try edit, rewrite, history or status, or nothing to read it.`);
     }
     if (values.positionals.length > (first === undefined ? 0 : 1)) {
         throw new Error(`brief ${action} does not take "${values.positionals[1]}".`);
@@ -1192,6 +1231,29 @@ function parseBriefArgs(args) {
     if (action !== "rewrite" && (wait || noWait)) {
         throw new Error("--wait and --no-wait belong to `cockpit brief rewrite`.");
     }
+    // ── Reading a past day (BLI-3484) ────────────────────────────────────────
+    const date = optionalNonEmpty(values.flags.get("--date"));
+    const against = optionalNonEmpty(values.flags.get("--against"));
+    const delta = values.booleans.has("--delta");
+    const days = optionalPositiveInteger(values.flags.get("--days"), "--days");
+    if (date && action !== "read") {
+        throw new Error("--date belongs to `cockpit brief` on its own — it reads one day's page.");
+    }
+    if (delta && action !== "read") {
+        throw new Error("--delta belongs to `cockpit brief` on its own.");
+    }
+    if (against && !delta) {
+        // Said rather than silently ignored: somebody who typed `--against` asked
+        // for a comparison, and running the plain read would answer a different
+        // question without saying so.
+        throw new Error("--against needs --delta: it names the day to compare against.");
+    }
+    if (days !== undefined && action !== "history") {
+        throw new Error("--days belongs to `cockpit brief history`.");
+    }
+    if (action === "history" && (values.booleans.has("--tldr") || values.booleans.has("--claims"))) {
+        throw new Error("brief history lists days; --tldr and --claims belong to reading a page.");
+    }
     // `--as` is accepted as an alias so the two conversational commands read the
     // same way; `cockpit jarvis --as <person>` has meant this since BLI-3380.
     // `--who` is the third spelling, and it exists because `cockpit brief status
@@ -1215,6 +1277,10 @@ function parseBriefArgs(args) {
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
         subject: forPerson ?? asPerson ?? whoPerson,
         version: optionalNonEmpty(values.flags.get("--version")),
+        ...(date ? { date } : {}),
+        ...(delta ? { delta: true } : {}),
+        ...(against ? { against } : {}),
+        ...(days !== undefined ? { days } : {}),
         tldr,
         versions: values.booleans.has("--versions"),
         claims: values.booleans.has("--claims"),

package/dist/commands/local-help.js

@@ -56,7 +56,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>] [--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>]] [--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]",
@@ -64,7 +64,7 @@ export function localCommandHelp(command) {
         "  cockpit settings [personal [--chat-model <key>] [--brief-model <key>] | switches [set <key> <value>] | models [set --chat <key>] [--memory <id>] | env list|set --project <p> --file <f> --content-stdin|delete --id <uuid> [--yes]] [--json]",
         "  cockpit team [members | invite <email> --role <role> [--team-id <uuid>] | role <userId> --role <role> [--yes]] [--json]",
         "  cockpit workbook [<project> [<doc>]] [--section <id>] [--markdown] [--width <n>] [--dashboard-url <url>] [--json]",
-        "  cockpit brief [edit|rewrite] [--for <person>] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--reason \"<why>\"] [--wait|--no-wait] [--dashboard-url <url>] [--json]",
+        "  cockpit brief [edit|rewrite|history] [--for <person>] [--date <YYYY-MM-DD>] [--delta [--against <YYYY-MM-DD>]] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--days <n>] [--reason \"<why>\"] [--wait|--no-wait] [--dashboard-url <url>] [--json]",
         "  cockpit brief status [--who <person>] [--render] [--dashboard-url <url>] [--json]",
         "  cockpit correct --claim <claimId> --text \"<what is wrong>\" [--for <person>] [--version <pageId>] [--supersedes <id>] [--dashboard-url <url>] [--json]",
         "  cockpit notes [list|show <id>|shelf|shelves|upload <paths...>|paste|share <id>|unshare <id>|move <id>] [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--file <path>] [--name <n>] [--exclude \"<sentence>\"] [--to \"<shelf>\"|--clear-shelf] [--yes] [--dashboard-url <url>] [--json]",
@@ -274,10 +274,11 @@ function localSubcommandHelp(command) {
         [
             "jarvis",
             [
-                "Usage: cockpit jarvis [question] [--prompt <question>] [--as <person>] [--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>]] [--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.",
+                "--date <YYYY-MM-DD> binds the page that was live on one of that person's days (`today` and `yesterday` work too), so the turn is about that day's page instead of the newest one. A day with nothing compiled binds no page and JARVIS says so rather than answering from a different day.",
                 "--model <key> requests one provider:model pair (e.g. openai:gpt-5.6-terra); an unrecognised key is refused by the dashboard, not this command.",
                 "--image <path> (alias --file) attaches one local PNG, JPEG, or WEBP under 10 MB with the question, the same one-image gate the JARVIS panel uses. A bad path, an unsupported type, or an oversized file is refused with its own plain sentence — never a stack trace.",
                 "Run with no question for an interactive terminal conversation.",
@@ -377,7 +378,7 @@ function localSubcommandHelp(command) {
         [
             "brief",
             [
-                "Usage: cockpit brief [edit|rewrite] [--for <person>] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--reason \"<why>\"] [--wait|--no-wait] [--dashboard-url <url>] [--json]",
+                "Usage: cockpit brief [edit|rewrite|history] [--for <person>] [--date <YYYY-MM-DD>] [--delta [--against <YYYY-MM-DD>]] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--days <n>] [--reason \"<why>\"] [--wait|--no-wait] [--dashboard-url <url>] [--json]",
                 "",
                 "Prints the TODAY page — the same page the Tower website shows, rendered for a terminal.",
                 "--for opens somebody else's page; the website's own rule decides whether you may, and it refuses in plain words when you may not.",
@@ -386,6 +387,14 @@ function localSubcommandHelp(command) {
                 "--claims prints the [claimId] beside every line, which is what `cockpit correct --claim` takes.",
                 "Reading it here counts as opening it, exactly as opening it in a browser does.",
                 "",
+                "--date <YYYY-MM-DD> reads the page that was live on one day — `today` and `yesterday` work too. Days are that person's own days, in their own timezone, so a page always sits on the date its own masthead says.",
+                "  A day with nothing compiled says so by name, and says which day is nearest. It never quietly hands you a different day's page.",
+                "--delta says what changed between that day and the day before it, in the same words the website's version history uses. --against <day> compares against a day you name instead.",
+                "  Comparisons that skip versions are worked out fresh each time and say `(not kept)` — a day with several compiles is one of those.",
+                "",
+                "history — the days there are, newest first, each with its masthead line and how many times it compiled that day. --days <n> asks for more than the last 14.",
+                "  Pass any date it prints back to `--date`.",
+                "",
                 "  cockpit brief status [--who <person>] [--render]",
                 "      Why your brief did or did not arrive this morning — one reason, from the same",
                 "      chain the Slack DM cron itself follows: not_due, not_monday, not_the_1st,",