@bli-cockpit/cli 0.2.45 → 0.2.47

package/dist/autostart.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths } from "./local-state.js";
 import { savedDiscoveryLimitArgs } from "./discovery-limits.js";
 import { redactedHealthDetail } from "./health-detail.js";
+import { DARWIN_LOGIN_SHELL, resolveStableNodeExecutable, } from "./autostart-node-path.js";
 /** launchd LaunchAgent label; matches docs/runbooks/cockpit-launchd-sync.md. */
 export const AUTOSTART_LABEL = "com.bli.cockpit.sync";
 export const WINDOWS_AUTOSTART_TASK_NAME = "BLI Cockpit Sync";
@@ -37,6 +38,11 @@ export const DEFAULT_AUTOSTART_INTERVAL_SECONDS = 15 * 60;
  */
 export const DARWIN_NETWORK_CHANGE_SIGNAL = "/private/var/run/resolv.conf";
 const UNSUPPORTED_MESSAGE = "autostart is supported on macOS and Windows only";
+/**
+ * What the tick says to sync.err.log when neither the registered node binary
+ * nor a login-shell node exists. Named, actionable, path-free (BLI-3553).
+ */
+export const DARWIN_NODE_MISSING_MESSAGE = "[autostart] tick skipped: reason=node_binary_missing - the registered node binary is gone and no node is on the login PATH; run cockpit doctor to re-register";
 function plistPathFor(homeDir) {
     return path.join(homeDir, "Library", "LaunchAgents", `${AUTOSTART_LABEL}.plist`);
 }
@@ -61,41 +67,8 @@ export async function installAutostartAgent(options) {
         return installWindowsTask(options);
     if (platform !== "darwin")
         return unsupportedResult(options.homeDir);
-    const homeDir = options.homeDir ?? os.homedir();
-    const workDirs = normalizeWorkDirs(options.repoRoots);
-    const workDir = path.resolve(options.repoRoot ?? workDirs[0] ?? process.cwd());
-    const resolvedWorkDirs = workDirs.length > 0 ? workDirs : [workDir];
-    const dashboardUrl = options.dashboardUrl ?? DEFAULT_DASHBOARD_URL;
-    const intervalSeconds = options.intervalSeconds ?? DEFAULT_AUTOSTART_INTERVAL_SECONDS;
-    const nodeExecutable = path.resolve(options.nodeExecutable ?? process.execPath);
-    const cliEntryPoint = path.resolve(options.cliEntryPoint ?? process.argv[1] ?? "");
-    const paths = getCollectorRuntimePaths(homeDir);
-    const plistPath = plistPathFor(homeDir);
-    const stdoutPath = path.join(paths.state_dir, "sync.log");
-    const stderrPath = path.join(paths.state_dir, "sync.err.log");
-    // launchd will not reliably watch a path that does not exist at load time, so
-    // only feed it the transcript dirs that are present right now. A missing dir
-    // is fine — the StartInterval floor still covers it. The network signal is
-    // appended unconditionally: it always exists on the Macs this plist targets,
-    // and an existence filter would drop it when rendering on another host.
-    const watchPaths = [
-        ...(await existingWatchPaths(homeDir)),
-        DARWIN_NETWORK_CHANGE_SIGNAL,
-    ];
-    await mkdir(path.dirname(plistPath), { recursive: true });
-    await mkdir(paths.state_dir, { recursive: true });
-    await writeFile(plistPath, renderPlist({
-        discoveryArgs: await savedDiscoveryLimitArgs(homeDir),
-        workDir,
-        workDirs: resolvedWorkDirs,
-        dashboardUrl,
-        intervalSeconds,
-        nodeExecutable,
-        cliEntryPoint,
-        stdoutPath,
-        stderrPath,
-        watchPaths,
-    }), "utf8");
+    const written = await writeDarwinAutostartPlist(options);
+    const { plist_path: plistPath, work_dir: workDir, work_dirs: resolvedWorkDirs, dashboard_url: dashboardUrl, interval_seconds: intervalSeconds, watch_path_count: watchPathCount, } = written;
     // Unload first so a changed plist is actually picked up; a not-yet-loaded
     // agent makes unload fail harmlessly, so the error is ignored.
     await options.exec("launchctl", ["unload", plistPath]).catch(() => undefined);
@@ -112,7 +85,8 @@ export async function installAutostartAgent(options) {
         console.error("[autostart] launchd agent loaded", JSON.stringify({
             label: AUTOSTART_LABEL,
             interval_seconds: intervalSeconds,
-            watch_path_count: watchPaths.length,
+            watch_path_count: watchPathCount,
+            node_path_reason: written.node_path_reason,
         }));
     }
     else {
@@ -139,6 +113,74 @@ export async function installAutostartAgent(options) {
             }),
     };
 }
+/**
+ * Renders and writes the LaunchAgent plist without touching launchd.
+ *
+ * Split out of `installAutostartAgent` for BLI-3553: the detached macOS healer
+ * (autostart-self-heal.ts) has to write the SAME plist this file writes and
+ * then re-register it with `bootout`/`bootstrap` rather than `unload`/`load`,
+ * and two renderers would be two chances to disagree. One writer, two
+ * registration verbs.
+ */
+export async function writeDarwinAutostartPlist(options) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const workDirs = normalizeWorkDirs(options.repoRoots);
+    const workDir = path.resolve(options.repoRoot ?? workDirs[0] ?? process.cwd());
+    const resolvedWorkDirs = workDirs.length > 0 ? workDirs : [workDir];
+    const dashboardUrl = options.dashboardUrl ?? DEFAULT_DASHBOARD_URL;
+    const intervalSeconds = options.intervalSeconds ?? DEFAULT_AUTOSTART_INTERVAL_SECONDS;
+    const node = await schedulerNodeExecutable(options, "darwin");
+    const cliEntryPoint = path.resolve(options.cliEntryPoint ?? process.argv[1] ?? "");
+    const paths = getCollectorRuntimePaths(homeDir);
+    const plistPath = plistPathFor(homeDir);
+    const stdoutPath = path.join(paths.state_dir, "sync.log");
+    const stderrPath = path.join(paths.state_dir, "sync.err.log");
+    // launchd will not reliably watch a path that does not exist at load time, so
+    // only feed it the transcript dirs that are present right now. A missing dir
+    // is fine — the StartInterval floor still covers it. The network signal is
+    // appended unconditionally: it always exists on the Macs this plist targets,
+    // and an existence filter would drop it when rendering on another host.
+    const watchPaths = [
+        ...(await existingWatchPaths(homeDir)),
+        DARWIN_NETWORK_CHANGE_SIGNAL,
+    ];
+    await mkdir(path.dirname(plistPath), { recursive: true });
+    await mkdir(paths.state_dir, { recursive: true });
+    await writeFile(plistPath, renderPlist({
+        discoveryArgs: await savedDiscoveryLimitArgs(homeDir),
+        workDir,
+        workDirs: resolvedWorkDirs,
+        dashboardUrl,
+        intervalSeconds,
+        nodeExecutable: node.path,
+        cliEntryPoint,
+        stdoutPath,
+        stderrPath,
+        watchPaths,
+    }), "utf8");
+    return {
+        plist_path: plistPath,
+        work_dir: workDir,
+        work_dirs: resolvedWorkDirs,
+        dashboard_url: dashboardUrl,
+        interval_seconds: intervalSeconds,
+        node_executable: node.path,
+        node_path_reason: node.reason,
+        cli_entry_point: cliEntryPoint,
+        watch_path_count: watchPaths.length,
+    };
+}
+/**
+ * The node binary the scheduler should name. BOTH the writer and the read-back
+ * validator go through here — if only the writer pinned the stable alias, every
+ * machine would read "does not match the current Tower runtime" forever, which
+ * is BLI-2541 with a new coat of paint.
+ */
+async function schedulerNodeExecutable(options, platform) {
+    const resolver = platform === "win32" ? path.win32.resolve : path.resolve;
+    const given = resolver(options.nodeExecutable ?? process.execPath);
+    return resolveStableNodeExecutable(given, { platform });
+}
 /**
  * What `launchctl` actually said, or an honest account of it saying nothing.
  *
@@ -198,7 +240,7 @@ export async function autostartStatus(options) {
     const resolvedWorkDirs = workDirs.length > 0 ? workDirs : [workDir];
     const dashboardUrl = options.dashboardUrl ?? DEFAULT_DASHBOARD_URL;
     const intervalSeconds = options.intervalSeconds ?? DEFAULT_AUTOSTART_INTERVAL_SECONDS;
-    const nodeExecutable = path.resolve(options.nodeExecutable ?? process.execPath);
+    const nodeExecutable = (await schedulerNodeExecutable(options, "darwin")).path;
     const cliEntryPoint = path.resolve(options.cliEntryPoint ?? process.argv[1] ?? "");
     const plist = await readFile(plistPath, "utf8").catch(() => "");
     const registrationProblems = darwinAgentRegistrationProblems(plist, {
@@ -238,7 +280,8 @@ async function installWindowsTask(options) {
     const scriptPath = path.join(getCollectorRuntimePaths(homeDir).state_dir, WINDOWS_AUTOSTART_SCRIPT_NAME);
     const registrationPath = path.join(getCollectorRuntimePaths(homeDir).state_dir, WINDOWS_AUTOSTART_REGISTRATION_SCRIPT_NAME);
     const launcherPath = windowsAutostartLauncherPath(homeDir);
-    const nodeExecutable = path.win32.resolve(options.nodeExecutable ?? process.execPath);
+    const node = await schedulerNodeExecutable(options, "win32");
+    const nodeExecutable = node.path;
     const cliEntryPoint = path.win32.resolve(options.cliEntryPoint ?? process.argv[1] ?? "");
     await mkdir(path.dirname(scriptPath), { recursive: true });
     await writeFile(scriptPath, `${UTF8_BOM}${renderWindowsSyncScript({
@@ -414,7 +457,7 @@ async function windowsTaskStatus(options) {
             discoveryArgs: await savedDiscoveryLimitArgs(options.homeDir),
             workDirs: normalizeWindowsWorkDirs(options.repoRoots),
             dashboardUrl: options.dashboardUrl ?? DEFAULT_DASHBOARD_URL,
-            nodeExecutable: path.win32.resolve(options.nodeExecutable ?? process.execPath),
+            nodeExecutable: (await schedulerNodeExecutable(options, "win32")).path,
             cliEntryPoint: path.win32.resolve(options.cliEntryPoint ?? process.argv[1] ?? ""),
             syncLogPath: windowsSyncLogPath(options.homeDir),
         })}`;
@@ -954,8 +997,42 @@ function renderDarwinSyncCommand(options) {
         ? ""
         : ` --dashboard-url ${shellQuote(options.dashboardUrl)}`;
     const discoveryArg = options.discoveryArgs.length > 0 ? ` ${options.discoveryArgs.join(" ")}` : "";
-    const commands = options.workDirs.map((root) => `${shellQuote(options.nodeExecutable)} ${shellQuote(options.cliEntryPoint)} sync --workspace ${shellQuote(root)}${dashboardArg}${discoveryArg} --json || exit_code=1`);
-    return ["exit_code=0", ...commands, 'exit "$exit_code"'].join("; ");
+    const commands = options.workDirs.map((root) => `"$node_bin" ${shellQuote(options.cliEntryPoint)} sync --workspace ${shellQuote(root)}${dashboardArg}${discoveryArg} --json || exit_code=1`);
+    return [
+        "exit_code=0",
+        ...darwinNodeResolutionPreamble(options.nodeExecutable),
+        ...commands,
+        'exit "$exit_code"',
+    ].join("; ");
+}
+/**
+ * The registered node path first, a login-shell PATH lookup second, a named
+ * failure third (BLI-3553).
+ *
+ * The hardcoded absolute path stays FIRST and stays the normal case — launchd
+ * hands the tick `PATH=/usr/bin:/bin:/usr/sbin:/sbin` and nothing this fleet
+ * runs lives there, which is the whole reason the plist names absolutes
+ * (scheduled-self-update.ts:55-62). The fallback only fires when that path is
+ * gone: `brew upgrade node` deleted the Cellar directory, `nvm uninstall`
+ * removed a version, someone moved a prefix. Before this, that state was a
+ * silent `exit 127` every 15 minutes forever, on every tick, with nothing in
+ * sync.err.log naming it.
+ *
+ * `/bin/zsh -lc` because a login shell is where Homebrew's `brew shellenv` and
+ * a machine's own PATH edits live; `command -v` because it is a builtin and
+ * cannot itself be missing. Recovering here is deliberately temporary: running
+ * under a node the plist does not name makes the next status read disagree,
+ * which is exactly what wakes the self-heal up to re-register the new path.
+ * A machine whose node is only on an INTERACTIVE shell's PATH (nvm sourced from
+ * .zshrc) still fails — but now it fails with a reason in the log instead of a
+ * bare 127.
+ */
+function darwinNodeResolutionPreamble(nodeExecutable) {
+    return [
+        `node_bin=${shellQuote(nodeExecutable)}`,
+        `[ -x "$node_bin" ] || node_bin="$(${DARWIN_LOGIN_SHELL} -lc 'command -v node' 2>/dev/null)"`,
+        `[ -x "$node_bin" ] || { echo ${shellQuote(DARWIN_NODE_MISSING_MESSAGE)} >&2; exit 127; }`,
+    ];
 }
 function darwinAgentRegistrationProblems(plist, expected) {
     if (!plist)
@@ -1031,6 +1108,101 @@ function watchPathsBlock(watchPaths) {
         "  </array>",
     ];
 }
+/**
+ * What the platform says it will run, parsed out of the registration itself
+ * (BLI-3553). Deliberately NOT rebuilt from `process.execPath` — the whole
+ * failure this ticket exists for is the registered path outliving the binary,
+ * and a check built from our own current values cannot see that.
+ */
+export async function readRegisteredRuntimePaths(options) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "darwin") {
+        const plist = await readFile(plistPathFor(options.homeDir ?? os.homedir()), "utf8").catch(() => "");
+        const command = decodeXmlEntities(plist);
+        return {
+            node_executable: /node_bin='([^']*)'/u.exec(command)?.[1] ?? null,
+            cli_entry_point: /"\$node_bin" '([^']*)' sync /u.exec(command)?.[1] ?? null,
+        };
+    }
+    if (platform === "win32") {
+        const script = await readFile(windowsAutostartScriptPath(options.homeDir), "utf8").catch(() => "");
+        return {
+            node_executable: /\$nodeExecutable = '([^']*)'/u.exec(script)?.[1] ?? null,
+            cli_entry_point: /\$cliEntryPoint = '([^']*)'/u.exec(script)?.[1] ?? null,
+        };
+    }
+    return { node_executable: null, cli_entry_point: null };
+}
+/**
+ * Named problems with the registered runtime, or an empty list. Path-free
+ * strings: safe to log, safe to upload as an install-event detail.
+ */
+export async function registeredRuntimePathProblems(options) {
+    // A real-host check by nature: this stats paths. A suite simulating win32 on
+    // a Mac (which every Windows test here does) would be asking the wrong
+    // filesystem about `C:\...`, and "missing" would mean nothing. Say nothing
+    // rather than something false.
+    const platform = options.platform ?? process.platform;
+    if (platform !== (options.hostPlatform ?? process.platform))
+        return [];
+    const registered = await readRegisteredRuntimePaths(options);
+    const problems = [];
+    if (registered.node_executable === null) {
+        problems.push("registration names no node binary");
+    }
+    else if (!(await fileExists(registered.node_executable))) {
+        problems.push("registered node binary is missing");
+    }
+    if (registered.cli_entry_point === null) {
+        problems.push("registration names no Tower CLI entry point");
+    }
+    else if (!(await fileExists(registered.cli_entry_point))) {
+        problems.push("registered Tower CLI entry point is missing");
+    }
+    return problems;
+}
+/** `gui/<uid>` — the per-user launchd domain the LaunchAgent lives in. */
+export function launchdUserDomain(uid = process.getuid?.() ?? 0) {
+    return `gui/${uid}`;
+}
+/**
+ * Re-registers the LaunchAgent with the modern verbs (BLI-3553).
+ *
+ * `unload`/`load` is what the interactive install path uses and it stays there;
+ * this exists for the DETACHED healer, where the difference matters:
+ * `bootstrap` reports a rejected plist with a real error, whereas `load` is
+ * documented-deprecated and exits nonzero with empty output for several
+ * unrelated states (see launchctlDetail). The healer gets one shot and has no
+ * human watching, so it uses the verb that says what went wrong.
+ *
+ * `bootout` on a service that is not loaded exits nonzero (`3: No such
+ * process`); that is the expected steady state after the job that spawned us
+ * exited, so it is not treated as a failure. Only `bootstrap` decides the
+ * outcome. If it fails, the agent is left unloaded — recoverable, because
+ * launchd bootstraps everything in ~/Library/LaunchAgents at the next login,
+ * and the plist file itself was already rewritten before this call.
+ */
+export async function reregisterDarwinAgent(options) {
+    const domain = launchdUserDomain(options.uid);
+    const bootout = await options
+        .exec("launchctl", ["bootout", `${domain}/${AUTOSTART_LABEL}`])
+        .catch(() => ({ code: 1, stdout: "", stderr: "" }));
+    const bootstrap = await options
+        .exec("launchctl", ["bootstrap", domain, options.plistPath])
+        .catch(() => ({ code: 1, stdout: "", stderr: "" }));
+    if (bootstrap.code === 0) {
+        return {
+            ok: true,
+            reason: "agent_rebootstrapped",
+            detail: `bootout exit ${bootout.code}`,
+        };
+    }
+    return {
+        ok: false,
+        reason: "bootstrap_failed",
+        detail: `launchctl bootstrap exited ${bootstrap.code}: ${launchctlDetail(bootstrap)}`,
+    };
+}
 function shellQuote(value) {
     return `'${value.replace(/'/g, "'\\''")}'`;
 }

package/dist/commands/autostart-heal.js

@@ -0,0 +1,162 @@
+import path from "node:path";
+import { appendFile } from "node:fs/promises";
+import { AUTOSTART_LABEL, autostartStatus, reregisterDarwinAgent, writeDarwinAutostartPlist, } from "../autostart.js";
+import { redactedHealthDetail } from "../health-detail.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
+import { normalizeCollectionRoots } from "../root-normalization.js";
+import { createCapturedExecRunner } from "../process-runner.js";
+import { reportInstallEventsBestEffort } from "./install-receipts.js";
+/** How long to wait for the launchd job that spawned us to exit. */
+export const HEAL_PARENT_EXIT_TIMEOUT_MS = 120_000;
+const HEAL_PARENT_POLL_MS = 250;
+const DETAIL_MAX_CHARS = 300;
+export async function runAutostartHealDetached(command, io, deps = {}) {
+    const outcome = await healDetached(command, io, deps);
+    const report = deps.reportInstallEvents ?? reportInstallEventsBestEffort;
+    await report({
+        homeDir: command.homeDir,
+        dashboardUrl: command.dashboardUrl,
+        command: "sync",
+        events: [
+            {
+                step: "autostart_heal",
+                status: outcome.status,
+                ...(outcome.status === "ok" ? {} : { error_code: outcome.reason }),
+                ...(outcome.detail ? { error_detail: outcome.detail } : {}),
+            },
+        ],
+        json: command.json,
+        io,
+    });
+    // Both branches log: "did any Mac in the fleet actually recover today?" has
+    // to be answerable from sync.err.log alone.
+    //
+    // And it has to be written THERE explicitly. This process is spawned with
+    // `stdio: "ignore"` — deliberately, so it holds no descriptor on a log the
+    // tick may be rotating — which means its stderr goes nowhere. Without the
+    // append below the only trace of a failed heal would be the uploaded
+    // receipt, and an operator reading their own machine would see a scheduler
+    // that silently stopped healing.
+    const line = `${outcome.status === "ok"
+        ? "[autostart-heal] launchd agent re-registered"
+        : "[autostart-heal] launchd agent not re-registered"} ${JSON.stringify({
+        label: AUTOSTART_LABEL,
+        status: outcome.status,
+        reason: outcome.reason,
+    })}`;
+    console.error(line);
+    await appendFile(path.join(getCollectorRuntimePaths(command.homeDir).state_dir, "sync.err.log"), `${line}\n`).catch(() => undefined);
+    return outcome.status === "fail" ? 1 : 0;
+}
+async function healDetached(command, io, deps) {
+    const platform = deps.platform ?? process.platform;
+    if (platform !== "darwin") {
+        return { status: "skipped", reason: "not_darwin" };
+    }
+    const exec = deps.exec ?? io.exec ?? createCapturedExecRunner();
+    const waited = await waitForParentExit(command.parentPid, deps);
+    if (!waited) {
+        // Booting the job out while it is still running would SIGTERM it — the
+        // exact hazard this process exists to avoid. Refuse instead.
+        return { status: "fail", reason: "parent_still_running" };
+    }
+    const roots = await savedRoots(command.homeDir);
+    if (roots.length === 0) {
+        return { status: "skipped", reason: "no_saved_roots" };
+    }
+    const before = await autostartStatus({
+        homeDir: command.homeDir,
+        repoRoot: roots[0],
+        repoRoots: roots,
+        dashboardUrl: command.dashboardUrl,
+        exec,
+        platform,
+    });
+    if (before.status === "absent") {
+        // Repair what exists, never create.
+        return { status: "skipped", reason: "autostart_absent" };
+    }
+    let written;
+    try {
+        written = await writeDarwinAutostartPlist({
+            homeDir: command.homeDir,
+            repoRoot: roots[0],
+            repoRoots: roots,
+            dashboardUrl: command.dashboardUrl,
+            exec,
+            platform,
+        });
+    }
+    catch (error) {
+        return {
+            status: "fail",
+            reason: "plist_write_failed",
+            detail: redactedHealthDetail(error instanceof Error ? error.message : String(error)).slice(0, DETAIL_MAX_CHARS),
+        };
+    }
+    const reregistered = await reregisterDarwinAgent({
+        exec,
+        plistPath: written.plist_path,
+    });
+    if (!reregistered.ok) {
+        return {
+            status: "fail",
+            reason: reregistered.reason,
+            detail: redactedHealthDetail(reregistered.detail ?? "").slice(0, DETAIL_MAX_CHARS),
+        };
+    }
+    // Verify against what launchd returns, not against what we sent it
+    // (BLI-2541). A bootstrap that exits 0 and a registration that reads back
+    // healthy are two different claims.
+    const after = await autostartStatus({
+        homeDir: command.homeDir,
+        repoRoot: roots[0],
+        repoRoots: roots,
+        dashboardUrl: command.dashboardUrl,
+        exec,
+        platform,
+    });
+    if (after.status !== "loaded") {
+        return {
+            status: "fail",
+            reason: "reregistered_but_still_broken",
+            detail: redactedHealthDetail(after.message ?? after.status).slice(0, DETAIL_MAX_CHARS),
+        };
+    }
+    return {
+        status: "ok",
+        reason: "autostart_healed",
+        detail: `node_path_reason=${written.node_path_reason}`,
+    };
+}
+async function waitForParentExit(parentPid, deps) {
+    if (!parentPid || parentPid <= 0)
+        return true;
+    const isAlive = deps.isProcessAlive ?? defaultIsProcessAlive;
+    const sleep = deps.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const now = deps.now ?? (() => Date.now());
+    const deadline = now() + HEAL_PARENT_EXIT_TIMEOUT_MS;
+    while (isAlive(parentPid)) {
+        if (now() >= deadline)
+            return false;
+        await sleep(HEAL_PARENT_POLL_MS);
+    }
+    return true;
+}
+function defaultIsProcessAlive(pid) {
+    try {
+        // Signal 0 tests for existence without delivering anything.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means it exists and belongs to someone else — still alive.
+        return error.code === "EPERM";
+    }
+}
+async function savedRoots(homeDir) {
+    const config = await readLocalCollectorConfig(getCollectorRuntimePaths(homeDir)).catch(() => null);
+    return normalizeCollectionRoots(config?.default_repo_paths ?? []);
+}
+export const AUTOSTART_HEAL_DEFAULT_DASHBOARD_URL = DEFAULT_DASHBOARD_URL;

package/dist/commands/brief.js

@@ -59,6 +59,11 @@ export async function runBrief(command, io) {
         visible_because: body.visibleBecause ?? null,
         tldr: Boolean(command.tldr),
         pinned_version: command.version != null,
+        asked_day: command.date != null,
+        day: body.day?.date ?? null,
+        history_count: body.history?.length ?? null,
+        history_truncated: body.historyTruncated ?? null,
+        delta: command.delta ? (body.delta ? "answered" : (body.deltaReason ?? "missing")) : null,
         subject: command.subject ? "selected" : "caller",
         version_count: body.versions?.length ?? null,
         versions_reason: body.versionsReason ?? null,
@@ -127,12 +132,24 @@ function queryFor(command) {
         params.set("p", command.subject);
     if (command.version)
         params.set("v", command.version);
+    if (command.date)
+        params.set("d", command.date);
     if (command.tldr)
         params.set("tldr", "1");
     if (command.versions)
         params.set("versions", "1");
     if (command.claims)
         params.set("claims", "1");
+    if (command.action === "history") {
+        params.set("history", "1");
+        if (command.days !== undefined)
+            params.set("days", String(command.days));
+    }
+    if (command.delta) {
+        params.set("delta", "1");
+        if (command.against)
+            params.set("against", command.against);
+    }
     const query = params.toString();
     return query ? `?${query}` : "";
 }
@@ -145,9 +162,20 @@ function writeHuman(io, command, body) {
     // moment rather than something that failed to update.
     const whose = page.displayName ? `${page.displayName}'s page` : "This page";
     const pinned = page.olderVersionLabel ? ` · version from ${page.olderVersionLabel}` : "";
-    writeLine(io.stdout, dim(`${whose}${pinned}`, styled));
+    // BLI-3484: which day, in the SUBJECT's zone, said with the zone beside it so
+    // nobody has to work out whose midnight this is.
+    const day = body.day?.date ? ` · ${body.day.date}${body.day.zone ? ` ${body.day.zone}` : ""}` : "";
+    writeLine(io.stdout, dim(`${whose}${pinned}${day}`, styled));
+    // `history` lists days and prints no page — a list of dates under a full
+    // brief would bury the thing somebody asked for.
+    if (command.action === "history") {
+        writeHistory(io, body, styled);
+        return;
+    }
     writeLine(io.stdout, "");
     writeLine(io.stdout, body.text ?? "");
+    if (command.delta)
+        writeDelta(io, body, styled);
     if (body.claims && body.claims.length > 0) {
         writeLine(io.stdout, "");
         writeLine(io.stdout, dim("Claim ids — pass one to `cockpit correct --claim`:", styled));
@@ -181,6 +209,72 @@ function writeHuman(io, command, body) {
         }
     }
 }
+/**
+ * `cockpit brief history` — the days there are, newest first (BLI-3484).
+ *
+ * The masthead line beside each date is what makes the list browsable: a column
+ * of dates is a filing cabinet, a column of dates with "Two reviews waiting,
+ * one shipped" beside them is a history somebody can find their way around.
+ *
+ * A short window says so. The oldest date printed is not the oldest date there
+ * is when the index hit its cap, and a person picking through history has to
+ * know which of those they are looking at.
+ */
+function writeHistory(io, body, styled) {
+    const history = body.history ?? [];
+    writeLine(io.stdout, "");
+    if (history.length === 0) {
+        writeLine(io.stdout, dim("No days with a page yet.", styled));
+        return;
+    }
+    writeLine(io.stdout, dim("Days — pass one to `cockpit brief --date`:", styled));
+    for (const entry of history) {
+        const compiles = typeof entry.versionCount === "number" && entry.versionCount > 1
+            ? ` (${entry.versionCount} compiles)`
+            : "";
+        const heading = entry.heading ? ` — ${entry.heading}` : "";
+        writeLine(io.stdout, `${dim(`  ${entry.date ?? "?"}`, styled)}${heading}${dim(compiles, styled)}`);
+    }
+    if (body.historyTruncated) {
+        writeLine(io.stdout, "");
+        writeLine(io.stdout, dim("There are older days than these. Ask for more with `--days <n>`.", styled));
+    }
+}
+/**
+ * `--delta` — what changed between this day and the one before it.
+ *
+ * The headline first, then the lines that moved, because the headline is the
+ * answer and the detail is the evidence for it. A missing delta prints its
+ * reason: silence here would read as "nothing changed", which is a completely
+ * different and much worse claim than "I could not work it out".
+ */
+function writeDelta(io, body, styled) {
+    writeLine(io.stdout, "");
+    if (!body.delta) {
+        writeLine(io.stdout, dim(`No day-over-day comparison (${body.deltaReason ?? "no reason given"}).`, styled));
+        return;
+    }
+    const delta = body.delta;
+    const from = delta.from?.date ?? "the day before";
+    const to = delta.to?.date ?? "this day";
+    writeLine(io.stdout, dim(`What changed, ${from} → ${to}:`, styled));
+    writeLine(io.stdout, `  ${delta.headline ?? "(no headline)"}`);
+    for (const item of delta.detail ?? []) {
+        writeLine(io.stdout, "");
+        if (item.before)
+            writeLine(io.stdout, `${dim("  was:", styled)} ${item.before}`);
+        if (item.after)
+            writeLine(io.stdout, `${dim("  now:", styled)} ${item.after}`);
+        if (item.because)
+            writeLine(io.stdout, `${dim("  why:", styled)} ${item.because}`);
+    }
+    if (delta.storedReason) {
+        // Not a failure and not hidden either: this comparison skips versions, so
+        // it is worked out fresh every time somebody asks for it.
+        writeLine(io.stdout, "");
+        writeLine(io.stdout, dim(`(not kept: ${delta.storedReason})`, styled));
+    }
+}
 function writeFailure(command, io, reason, detail) {
     if (command.json) {
         writeLine(io.stdout, JSON.stringify({ ok: false, error: reason, detail }));

package/dist/commands/collection-roots.js

@@ -11,7 +11,7 @@ import os from "node:os";
 import path from "node:path";
 import { stat } from "node:fs/promises";
 import { isInteractiveStdin, readLine, writeLine, yesByDefault } from "./cli-io.js";
-import { COLLECTION_ROOT_REQUIRED, resolveOnboardingRoots, } from "../onboarding-roots.js";
+import { CollectionRootRequiredError, resolveOnboardingRoots, } from "../onboarding-roots.js";
 import { getCollectorRuntimePaths, installLocalCollector, readLocalCollectorConfig, } from "../local-state.js";
 import { collectionRootPathAliases } from "../repo-identity.js";
 import { normalizeCollectionRoots } from "../root-normalization.js";
@@ -37,7 +37,7 @@ export async function resolveOnboardingRootsForCommand(command, io) {
     const collectionRoots = rootsResult.roots;
     const primaryRoot = collectionRoots[0];
     if (!primaryRoot) {
-        throw new Error(`${COLLECTION_ROOT_REQUIRED}: no collection root confirmed.`);
+        throw new CollectionRootRequiredError(`no collection root confirmed.`);
     }
     const replaceRepoRoots = rootsResult.source === "prompt" &&
         !command.collectionRoots?.length &&
@@ -80,7 +80,7 @@ export async function assertCollectionRootPersisted(homeDir) {
     const config = await readLocalCollectorConfig(getCollectorRuntimePaths(homeDir)).catch(() => null);
     const saved = normalizeCollectionRoots(config?.default_repo_paths ?? []);
     if (saved.length === 0) {
-        throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${collectionRootNotPersistedMessage(homeDir)}`);
+        throw new CollectionRootRequiredError(collectionRootNotPersistedMessage(homeDir));
     }
     // Present in the file is not the same as usable. A root that no longer
     // exists on disk resolves to nothing at sync time, which is the same silent
@@ -91,7 +91,7 @@ export async function assertCollectionRootPersisted(homeDir) {
             usable.push(root);
     }
     if (usable.length === 0) {
-        throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${collectionRootMissingOnDiskMessage(saved, homeDir)}`);
+        throw new CollectionRootRequiredError(collectionRootMissingOnDiskMessage(saved, homeDir));
     }
     return usable;
 }