@bli-cockpit/cli 0.2.168 → 0.2.173

package/dist/commands/doctor-registration.js

@@ -1,6 +1,8 @@
 import { inspectAgentRules, installAgentRules } from "../agent-rules.js";
 import { doctorRoots } from "./doctor-access.js";
 import { installAutostartAgent } from "../autostart.js";
+import { clearAutostartOptOut } from "../autostart-opt-out.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
 import { fail, needsFix, ok, skipped } from "./doctor-report.js";
 import { autostartDoctorStatus, autostartRegistrationRoots, readAutostartRegistration, } from "./autostart-reading.js";
 import { installMemoryIntegration, inspectMemoryIntegration, } from "./memory-install.js";
@@ -41,7 +43,7 @@ export async function fixAutostartState(context) {
     // leave the row red forever (BLI-3793).
     const roots = await autostartRegistrationRoots(context.command.homeDir, context.command.repoRoot);
     if (roots.length === 0)
-        return needsFix("autostart-alive", "no_roots", "Run `cockpit doctor` to choose approved collection roots first.");
+        return needsFix("autostart-alive", "no_roots", "Run `cockpit doctor` in a terminal and pick the folders where you work.");
     const result = await installAutostartAgent({
         ...(roots[0] ? { repoRoot: roots[0] } : {}),
         repoRoots: roots,
@@ -52,6 +54,10 @@ export async function fixAutostartState(context) {
     if (result.status === "unsupported") {
         return skipped("autostart-alive", "unsupported", result.message ?? "unsupported");
     }
+    if (result.loaded !== false) {
+        // BLI-12828: a person asked for background sync again; the tick may keep it.
+        await clearAutostartOptOut(getCollectorRuntimePaths(context.command.homeDir));
+    }
     if (result.loaded === false) {
         return fail("autostart-alive", "autostart_load_failed", result.message ?? "operating-system scheduler load failed");
     }
@@ -111,12 +117,12 @@ function memoryStepState(outcome, phase) {
 }
 export async function checkDoctorAgentRules(context) {
     const result = await inspectAgentRules({ homeDir: context.command.homeDir, scopePaths: await doctorRoots(context) });
-    return result.installed ? ok("agent-rules", "installed", "agent rules are installed for both hosts") : needsFix("agent-rules", "missing", "run `cockpit agent-rules install`");
+    return result.installed ? ok("agent-rules", "installed", "agent rules are installed for both hosts") : needsFix("agent-rules", "missing", "agent rules are missing; `cockpit agent-rules install` writes them");
 }
 export async function fixDoctorAgentRules(context) {
     const roots = await doctorRoots(context);
     if (roots.length === 0)
-        return needsFix("agent-rules", "no_roots", "Run `cockpit doctor` to choose approved roots first.");
+        return needsFix("agent-rules", "no_roots", "Run `cockpit doctor` in a terminal and pick the folders where you work.");
     await installAgentRules({ homeDir: context.command.homeDir, scopePaths: roots });
     return checkDoctorAgentRules(context);
 }

package/dist/commands/doctor-report.js

@@ -70,6 +70,8 @@ setupReceipt, repairs = []) {
         writeLine(io.stderr, `${row.id}:`);
         writeLine(io.stderr, row.message.replaceAll("—", ";"));
     }
+    for (const line of repairReceiptLines(repairs))
+        writeLine(io.stdout, line);
     // BLI-3731. The invariant table says whether collection is healthy; this
     // says whether the machine is CONNECTED — the browser sign-in, the device
     // session, both agent hosts and the scheduler, every word read back off this
@@ -132,6 +134,32 @@ export function asRecord(value) {
 export function writeLine(stream, text) {
     stream.write(`${text}\n`);
 }
+/** Fills each repair's before -> after receipt from the diagnosis and the final rows. */
+export function finalizeDoctorRepairs(repairs, diagnosed, rows, attempted) {
+    for (const repair of repairs) {
+        const found = diagnosed.get(repair.step);
+        const final = rows.find((row) => row.id === repair.step);
+        if (found) {
+            repair.before = `${found.status}:${found.code}`;
+            repair.before_message = oneLine(found.message);
+        }
+        if (final) {
+            repair.after = `${final.status}:${final.code}`;
+            repair.after_message = oneLine(final.message);
+        }
+        repair.fix_attempted = attempted.has(repair.step);
+    }
+}
+/** The "Repairs:" block of the human table; empty when no fix ran. */
+export function repairReceiptLines(repairs) {
+    const ran = repairs.filter((repair) => repair.fix_attempted);
+    if (ran.length === 0)
+        return [];
+    return [
+        "Repairs (before -> after):",
+        ...ran.map((repair) => `  ${repair.after?.startsWith("ok:") ? "fixed" : "still needs you"} ${repair.step}: ${repair.before_message ?? ""} -> ${repair.after_message ?? ""}`.replaceAll("—", ";")),
+    ];
+}
 export function doctorNeedsPerson(rows, receipt) {
     const defaults = {
         "cli-latest": "npm i -g @bli-cockpit/cli && cockpit doctor",

package/dist/commands/doctor.js

@@ -4,11 +4,11 @@ import { describeError } from "../health-detail.js";
 import { withStage } from "../crash-guard.js";
 import { checkSingleInstallState, readRootsCoverWork, fixAuthState, fixRootState, readAuthState, readRootState, } from "./doctor-access.js";
 import { backfillCompletionStepState, backfillFixVerdict, checkBackfillState, checkDiskState, checkGcState, checkSyncState, fixBackfillState, fixDiskState, fixGcState, fixSyncState, syncBacklogDrainingVerdict, syncStandAsideVerdict, } from "./doctor-pipeline.js";
-import { checkMcpAnswersState } from "./doctor-mcp.js";
+import { checkMcpAnswersState, fixMcpAnswersState } from "./doctor-mcp.js";
 import { budgetSpentRow, doctorRunDeadline, DOCTOR_JSON_BUDGET_SECONDS } from "./doctor-budget.js";
 import { checkMemoryDaemonState } from "./doctor-memory-daemon.js";
 import { checkDoctorAgentRules, fixDoctorAgentRules, checkAutostartState, checkMemoryState, fixAutostartState, fixMemoryState, } from "./doctor-registration.js";
-import { dryRunPreview, isInteractiveDoctorFix, maybeReportDoctorEvents, writeDoctorOutput, doctorNeedsPerson, } from "./doctor-report.js";
+import { dryRunPreview, isInteractiveDoctorFix, maybeReportDoctorEvents, writeDoctorOutput, doctorNeedsPerson, finalizeDoctorRepairs, } from "./doctor-report.js";
 import { buildSetupReceipt, refreshSetupReceipt } from "./setup-receipt.js";
 import { checkCliLatest, fixCliLatest, latestCliVersionFromNpm, reexecDoctor, } from "./doctor-update.js";
 export async function runDoctor(command, io, hooks, overrides = {}) {
@@ -24,6 +24,7 @@ export async function runDoctorWithDeps(command, io, deps) {
     const repairs = [];
     const diagnoseOnly = command.dryRun || command.checkOnly;
     const diagnosed = new Map();
+    const attempted = new Set();
     // BLI-11101: every row says how long it took, so the next slow run names
     // the row without a profiler. A killed run still leaves every finished row.
     const checkMs = new Map();
@@ -54,6 +55,7 @@ export async function runDoctorWithDeps(command, io, deps) {
                 repairs.push({ step: invariant.id, outcome: "needs_person", reason: row.code });
             }
             else if (row.status !== "ok" && row.status !== "skipped" && canFix && invariant.fix) {
+                attempted.add(invariant.id);
                 row = await withStage(`doctor:fix:${invariant.id}`, () => invariant.fix(context, row));
                 repairs.push({ step: invariant.id, outcome: row.status === "ok" ? "repaired" : "needs_person", reason: row.code });
                 // The replacement process owns the one final receipt, including JSON.
@@ -106,6 +108,8 @@ export async function runDoctorWithDeps(command, io, deps) {
             }
         }
     }
+    // BLI-12828: every repair's receipt says what it found and what it left.
+    finalizeDoctorRepairs(repairs, diagnosed, rows, attempted);
     const floor = await maybeReportDoctorEvents(context, rows);
     if (floor && isSemverBelow(LOCAL_COLLECTOR_VERSION, floor)) {
         const index = rows.findIndex((row) => row.id === "cli-latest");
@@ -127,6 +131,15 @@ export async function runDoctorWithDeps(command, io, deps) {
     writeDoctorOutput(command, io, rows, receipt, repairs);
     return needsPerson === 0 ? 0 : 1;
 }
+/**
+ * The table's row ids in order, and whether each one carries a repair.
+ * `doctor-repair-classes.test.ts` pins this against the runbook's audit table
+ * (`docs/runbooks/cockpit-doctor-repairs.md`) so a row cannot be added without
+ * either a repair or a named reason it has none.
+ */
+export function doctorInvariantTable() {
+    return doctorInvariants().map((invariant) => ({ id: invariant.id, hasFix: Boolean(invariant.fix) }));
+}
 function doctorInvariants() {
     return [
         { id: "cli-latest", check: checkCliLatest, fix: fixCliLatest },
@@ -166,12 +179,14 @@ function doctorInvariants() {
         // BLI-3804. Right after the registration row, because it asks the second
         // half of the same question: `memory-registered` proves the entry exists
         // and names a bin, this one proves the server behind it starts, speaks the
-        // protocol and reaches Tower. Deliberately has NO fix — re-registering a
-        // server that is already registered repairs nothing, and the row names the
-        // command a person should run instead (`doctor-mcp.ts`).
+        // protocol and reaches Tower. BLI-12828 gave it the repair the row always
+        // named in words: re-register, take the newest CLI, ask again. A Tower
+        // refusal is the sign-in row's, so that outcome is returned untouched
+        // (`doctor-mcp.ts`).
         {
             id: "mcp-answers",
             check: (context) => context.deps.checkMcpAnswers(context),
+            fix: fixMcpAnswersState,
         },
         // BLI-3884. Beside the two rows above because it is the same family — what
         // this machine's agents can reach — and, like `mcp-answers`, it has NO fix:

package/dist/commands/heartbeat-token.js

@@ -77,4 +77,18 @@ async function readTokenExpiry(response) {
     catch {
         return null;
     }
+}
+/**
+ * BLI-12828. The one fact the tick's sign-in heal needs from the check-in it
+ * just made: did the DOOR refuse this machine's token (401/403), as opposed to
+ * the network being down or the build being a checkout? A lapsed local date
+ * alone proves nothing offline. Process-scoped on purpose: one tick is one
+ * process, and `null` means "no refusal observed", never "accepted".
+ */
+let lastRefusalStatus = null;
+export function noteHeartbeatRefusal(status) {
+    lastRefusalStatus = status;
+}
+export function heartbeatRefusalStatus() {
+    return lastRefusalStatus;
 }

package/dist/commands/heartbeat.js

@@ -29,7 +29,7 @@ import { readStagingInventory } from "../disk-usage.js";
 import { describeError } from "../health-detail.js";
 import { shouldSuppressFleetReceipts, } from "../dev-build.js";
 import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
-import { readHeartbeatSession, recordHeartbeatTokenExpiry, } from "./heartbeat-token.js";
+import { noteHeartbeatRefusal, readHeartbeatSession, recordHeartbeatTokenExpiry, } from "./heartbeat-token.js";
 import { classifySyncHealthError } from "../sync-health-class.js";
 import { readMemoryReceiptFile } from "./memory-install-receipt.js";
 import { readMemoryHookCounts } from "./memory-hook-counts.js";
@@ -284,6 +284,7 @@ export async function sendCollectorHeartbeatBestEffort(options) {
             body: JSON.stringify(heartbeat),
             signal: controller.signal,
         });
+        noteHeartbeatRefusal(response.ok ? null : response.status);
         if (!response.ok) {
             // A heartbeat is not retried, so the reason has to be said once, here.
             // BLI-4019: the CLASS comes from `sync-health-class.ts`, the one place

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

@@ -0,0 +1,53 @@
+/**
+ * `cockpit logs` argument parsing (BLI-12833).
+ *
+ *   cockpit logs <source> [--since 15m|1h|2d|<iso>] [--raw <template-id>] [--limit <n>]
+ *                [--all-levels] [--table <file>] [--json]
+ *
+ * <source> is `collector`, `dashboard`, `railway`, `railway:<service>` or `-`
+ * (lines on stdin). Read-only: the digest is computed on this machine from the
+ * source's own CLI or files; nothing is sent to Tower and no dashboard is
+ * called, so there is no `--dashboard-url`.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, parseNamedArgs } from "./local-arg-values.js";
+/** The source spellings, for the usage line and the refusal. `railway:<service>` takes any service name. */
+export const LOGS_SOURCES = ["collector", "dashboard", "railway", "railway:<service>", "-"];
+const SOURCE_PATTERN = /^(collector|dashboard|railway|railway:[A-Za-z0-9][A-Za-z0-9._-]{0,63}|-)$/;
+const SINCE_PATTERN = /^(\d{1,4}[smhd]|\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?)?)$/;
+export function parseLogsArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--since", "--raw", "--limit", "--table", "--all-levels", "--json"],
+        valueFlags: ["--home", "--since", "--raw", "--limit", "--table"],
+    });
+    const source = values.positionals[0];
+    if (!source || !SOURCE_PATTERN.test(source)) {
+        throw new Error(`logs needs a source: ${LOGS_SOURCES.join(", ")}. Example: \`cockpit logs dashboard --since 1h\`.`);
+    }
+    if (values.positionals.length > 1)
+        throw new Error("logs takes one source; put the window in --since.");
+    const since = optionalNonEmpty(values.flags.get("--since"));
+    if (since && !SINCE_PATTERN.test(since)) {
+        throw new Error(`--since wants 15m, 1h, 2d or an ISO time like 2026-10-07T03:00Z; got ${JSON.stringify(since.slice(0, 40))}.`);
+    }
+    const raw = optionalNonEmpty(values.flags.get("--raw"));
+    if (raw && !/^[0-9a-f]{8}$/.test(raw)) {
+        throw new Error("--raw wants the 8 hex characters a digest line starts with.");
+    }
+    const rawLimit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    if (rawLimit !== undefined && !raw)
+        throw new Error("--limit counts the original lines --raw prints.");
+    if (values.booleans.has("--all-levels") && source !== "dashboard") {
+        throw new Error("--all-levels belongs to `cockpit logs dashboard`.");
+    }
+    return {
+        kind: "logs",
+        source,
+        ...(since ? { since } : {}),
+        ...(raw ? { raw } : {}),
+        ...(rawLimit === undefined ? {} : { rawLimit }),
+        ...(values.flags.get("--table") ? { tableFile: values.flags.get("--table") } : {}),
+        allLevels: values.booleans.has("--all-levels"),
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        json: values.booleans.has("--json"),
+    };
+}

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

@@ -38,5 +38,6 @@ export { parseModelsArgs } from "./local-args-tower-models.js";
 export { parseMailArgs } from "./local-args-tower-mail.js";
 export { parseCalArgs } from "./local-args-tower-cal.js";
 export { parseUsageArgs } from "./local-args-tower-usage.js";
+export { parseLogsArgs } from "./local-args-tower-logs.js";
 export { parseCareersArgs } from './local-args-tower-careers.js';
 export { parseRenameArgs } from './local-args-tower-rename.js';

package/dist/commands/local-args.js

@@ -18,7 +18,7 @@
 import { parseRootsArgs } from "./roots.js";
 import { SURFACE_ALIASES } from "./local-help.js";
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseSourcesArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseLogsArgs, parseCareersArgs, parseRenameArgs, } 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
 // even though it now lives next door. The same goes for the four names the
@@ -133,6 +133,8 @@ export function parseLocalArgs(argv) {
             return parseRenameArgs(argv.slice(1));
         case "usage":
             return parseUsageArgs(argv.slice(1));
+        case "logs":
+            return parseLogsArgs(argv.slice(1));
         default:
             throw new Error(`Unknown local command: ${command ?? ""}`);
     }

package/dist/commands/local-command-shapes-logs.js

@@ -0,0 +1,6 @@
+/**
+ * `cockpit logs` command shape (BLI-12833), beside `local-command-shapes.ts` for
+ * the same reason `local-command-shapes-github.ts` is: that file sits at the
+ * readability ceiling.
+ */
+export {};

package/dist/commands/local-help-commands-tower-ops.js

@@ -10,6 +10,32 @@
  * something breaks, so it is a user-visible contract like any other.
  */
 export const TOWER_OPS_COMMAND_HELP = [
+    [
+        "logs",
+        [
+            "Usage: cockpit logs <collector|dashboard|railway|railway:<service>|-> [--since 15m|1h|2d|<iso>] [--raw <template-id> [--limit <n>]] [--all-levels] [--table <file>] [--json]",
+            "",
+            "A token-cheap digest of Tower's own logs, read on THIS machine (nothing is uploaded). Variable parts of",
+            "each line are masked into a template, equal templates are counted, routine runs become counts, and every",
+            "template is classified: our_bug and unknown first, then capacity, config_drift, rate_pushback, hiccup,",
+            "and one COUNTED line for dead_source and benign (counted, never alerted). About 2 KB.",
+            "  collector           this machine's sync.log, sync.err.log and their rotated archives (hook logs go to sync.err.log).",
+            "                      These logs have no per-line time, so the window is approximate (the digest says so).",
+            "  dashboard           Vercel runtime logs of bli-cockpit-dashboard (team bli-inc) through the `vercel` CLI.",
+            "                      Reads what Vercel marks error, warning or fatal plus every 5xx; --all-levels reads everything (slow).",
+            "  railway             every service of the bli-cockpit-inference project through the `railway` CLI;",
+            "  railway:<service>   one service (ladder, runner, linear-sync, ...). Project and environment are always passed",
+            "                      explicitly: this repo's `railway link` points at the runner service.",
+            "  -                   lines on stdin: plain text, `journalctl -o json`, `railway logs --json` or `vercel logs --json`.",
+            "--raw <template-id>   the original lines behind one template id from a digest (redacted, newest last; --limit n, default 20).",
+            "--table <file>        a class table JSON (same shape as the packaged one) to try a new pattern before committing it.",
+            "A source that cannot be read is a named refusal, never a stack trace: vercel_cli_missing, vercel_not_logged_in,",
+            "railway_cli_missing, railway_not_logged_in, railway_service_unknown, collector_logs_missing, stdin_is_terminal, ...",
+            "--json writes one object to stdout: { ok, kind, source, window, lines, templates[], routine, notes, text, measure };",
+            "a refusal is { ok: false, error, detail } and exits 1. Run list and teaching: docs/runbooks/tower-logs.md.",
+            "The bli-tower MCP server has the twin: logs_digest.",
+        ],
+    ],
     [
         "github",
         [

package/dist/commands/local-help.js

@@ -78,6 +78,7 @@ export const rootCommandNames = new Set([
     "careers",
     "rename",
     "usage",
+    "logs",
     ...SURFACE_ALIASES.keys(),
 ]);
 /** Public names omit compatibility spellings while the router keeps accepting them. */
@@ -132,6 +133,7 @@ export function localCommandHelp(command) {
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
         "  cockpit careers [list|show <id>|rescreen <id>|send-takehome <id>|decide <id> --decision <passed_on|archived|reopen>|followup <id> [--record-sent-at <iso>]|interview <id> <--at <iso>|--clear>|grade <id> [--now]|resume <id> [--out <path>]|takehome show <role>|takehome set <role> --body-file <path>|settings show|settings set --enabled <true|false> --followup-enabled <true|false> --followup-after-days <n> --takehome-window-hours <n>] [--role <slug>] [--min-score <n>] [--since <date>] [--stage <s>] [--force] [--json]",
         "  cockpit rename [list|resolve <id> --scope <page|everywhere|undo>] [--dashboard-url <url>] [--json]",
+        "  cockpit logs <collector|dashboard|railway|railway:<service>|-> [--since 15m|1h|2d|<iso>] [--raw <template-id> [--limit <n>]] [--all-levels] [--table <file>] [--json]",
         "  cockpit usage sessions [--task <BLI-NNNN> | --subject <name>] [--repo <label>] [--since <window>] [--json]",
         "  cockpit usage sessions --session <id> [--from-window <n>] [--json]",
         "  --by-topic groups work types; --by-subject groups open subjects from session summaries.",

package/dist/commands/local.js

@@ -49,6 +49,7 @@ import { runSearch } from "./search.js";
 import { runCareers } from "./careers.js";
 import { runRename } from "./rename-scope.js";
 import { runUsage } from "./usage.js";
+import { runLogs } from "./logs.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
@@ -242,6 +243,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runRename(command, io);
             case "usage":
                 return await runUsage(command, io);
+            case "logs":
+                return await runLogs(command, io);
         }
     }
     catch (error) {

package/dist/commands/logs.js

@@ -0,0 +1,68 @@
+/**
+ * `cockpit logs <source>` — a token-cheap digest of Tower's own logs (BLI-12833).
+ *
+ * Read-only and local: the source's own CLI or files are read on THIS machine,
+ * masked into templates, counted and classified by `@bli-cockpit/telemetry-core/log-digest`,
+ * and printed in about 2 KB with real bugs (`our_bug`, `unknown`) first. Nothing
+ * is uploaded and no Tower door is called. The MCP server's `logs_digest` tool
+ * calls the same `digestSource`, so the two print the same thing.
+ *
+ * A source that cannot be read is a NAMED refusal (`vercel_cli_missing`,
+ * `railway_not_logged_in`, ...): one line on stderr, `{ ok: false, error,
+ * detail }` on stdout under `--json`, exit 1. Never a stack trace.
+ */
+import { readFile } from "node:fs/promises";
+import { ClassTable, digestSource } from "@bli-cockpit/telemetry-core/log-digest";
+import { getCollectorRuntimePaths } from "../local-state-paths.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+const TAG = "[logs cli]";
+const MAX_STDIN_CHARS = 64 * 1024 * 1024;
+function refuse(io, json, reason, detail) {
+    writeLine(io.stderr, `${TAG} refused ${JSON.stringify({ reason })}`);
+    if (json)
+        writeLine(io.stdout, JSON.stringify({ ok: false, error: reason, detail }));
+    else
+        writeLine(io.stderr, detail);
+    return 1;
+}
+export async function runLogs(command, io, deps = {}) {
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    let table;
+    if (command.tableFile) {
+        try {
+            table = ClassTable.fromJson(await readFile(command.tableFile, "utf8"));
+        }
+        catch (error) {
+            return refuse(io, command.json, "table_unreadable", `--table ${command.tableFile} is not a readable class table: ${error instanceof Error ? error.message.slice(0, 160) : "unknown error"}`);
+        }
+    }
+    let stdinText;
+    const stdinIsTerminal = command.source === "-" && isInteractiveStdin(io);
+    if (command.source === "-" && !stdinIsTerminal) {
+        try {
+            stdinText = await readPipedText(io.stdin, { maxChars: MAX_STDIN_CHARS, overflowMessage: "logs - reads at most 64 MB of piped lines." });
+        }
+        catch (error) {
+            return refuse(io, command.json, "stdin_too_large", error instanceof Error ? error.message : "stdin could not be read");
+        }
+    }
+    const outcome = await digestSource({
+        source: command.source,
+        since: command.since,
+        raw: command.raw,
+        rawLimit: command.rawLimit,
+        table,
+        allLevels: command.allLevels,
+    }, {
+        stateDir: paths.state_dir,
+        stdinText,
+        stdinIsTerminal,
+        run: deps.run,
+        nowMs: deps.nowMs,
+        log: (message, fields) => writeLine(io.stderr, `${message} ${JSON.stringify(fields)}`),
+    });
+    if (!outcome.ok)
+        return refuse(io, command.json, outcome.reason, outcome.detail);
+    writeLine(io.stdout, command.json ? JSON.stringify(outcome) : outcome.text);
+    return 0;
+}

package/dist/commands/public-root.js

@@ -21,7 +21,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.168");
+    writeLine(io?.stdout ?? process.stdout, "0.2.173");
     return 0;
   }
 

package/dist/commands/sync-followups-staging.js

@@ -1,6 +1,7 @@
 import { redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
 import { getCollectorRuntimePaths } from "../local-state.js";
-import { runStagingPrune } from "../disk-prune.js";
+import { runStagingPrune, terminalReclaimDetail } from "../disk-prune.js";
+import { runGateFollowUp } from "../staging-gate-receipt.js";
 import { runEvidenceReconcile, } from "../evidence-reconcile-client.js";
 import { runEvidenceRedelivery, } from "../evidence-redelivery.js";
 /** How many reconcile batches (of up to 500 hashes each) one sync tick may spend. */
@@ -67,6 +68,11 @@ export async function runStagingPruneAfterSync(command, io, dashboardUrl, option
     if (result.reason !== "nothing_to_prune") {
         events.push(stagingPruneEvent(result));
     }
+    // BLI-12832: bound the two disposable caches, then say what the staging gate
+    // is doing, once per change. Neither can fail the tick.
+    const gateEvent = await runGateFollowUp(getCollectorRuntimePaths(command.homeDir), io.env, options.now ?? new Date());
+    if (gateEvent)
+        events.push(gateEvent);
     if (events.length === 0)
         return;
     await reportInstallEventsBestEffort({
@@ -179,6 +185,7 @@ function stagingPruneEvent(result) {
         result.failed_deletions > 0
             ? `failed_deletions ${result.failed_deletions}`
             : null,
+        terminalReclaimDetail(result),
     ]
         .filter((part) => Boolean(part))
         .join("; ");

package/dist/commands/sync-heal.js

@@ -0,0 +1,144 @@
+/**
+ * The tick's machine-heal follow-ups that `cockpit doctor` also performs
+ * (BLI-12828). Doctor and the tick are meant to be the same repairs run by a
+ * person and run by the clock; `docs/runbooks/cockpit-doctor-repairs.md` is the
+ * table of which row each one answers.
+ *
+ *   agent rules missing     re-install them        inspected every tick, a
+ *                                                  failed install retried hourly
+ *   sign-in lapsed          record the ONE human   written when the heartbeat
+ *                           action, stop nagging   could not renew, reported daily
+ *
+ * The rest of the table is already on the tick elsewhere: the CLI floor
+ * (`sync-followups-self-update.ts`), the scheduler incl. an ABSENT one
+ * (`sync-followups-autostart.ts` over `../autostart-self-heal.ts`), BLI Memory
+ * (`sync-followups-memory.ts`) and staging (`sync-followups-staging.ts`).
+ *
+ * Same rule as every follow-up: it runs after collection's outcome is decided,
+ * never throws, and its outcome is its own named receipt, never a sync failure.
+ * A new sibling must also join `scripts/build-public-cli.mjs` `runtimeFiles`.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
+import { heartbeatRefusalStatus } from "./heartbeat-token.js";
+import { SIGN_IN_ACTION } from "../sign-in-action.js";
+import { inspectAgentRules, installAgentRules } from "../agent-rules.js";
+import { getCollectorRuntimePaths, readLocalCollectorConfig, readLocalCollectorSessionFile, toSessionReference, } from "../local-state.js";
+import { normalizeCollectionRoots } from "../root-normalization.js";
+export const AGENT_RULES_REPAIR_MARKER = ".last-agent-rules-repair";
+export const SESSION_NEEDS_LOGIN_MARKER = "session-needs-login.json";
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Only a RETRY of a failed install waits; the first install never does. */
+const AGENT_RULES_RETRY_AFTER_FAILURE_MS = 60 * 60 * 1000;
+export async function runMachineHealAfterSync(command, io, dashboardUrl, options = {}) {
+    const now = options.now ?? new Date();
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const events = [];
+    for (const heal of [
+        () => healAgentRules(command, paths, now),
+        () => noteSessionState(paths, heartbeatRefusalStatus(), now),
+    ]) {
+        try {
+            const event = await heal();
+            if (event)
+                events.push(event);
+        }
+        catch (error) {
+            console.error("[sync-heal] a machine-heal step threw and was dropped", JSON.stringify({ reason: "heal_step_threw", detail: redactedSyncErrorDetail(error) }));
+        }
+    }
+    if (events.length === 0)
+        return;
+    await reportInstallEventsBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        command: "sync",
+        events,
+        json: command.json,
+        io,
+    });
+}
+/** Agent rules: cheap to read, so read every tick; write only when missing. */
+async function healAgentRules(command, paths, now) {
+    const config = await readLocalCollectorConfig(paths).catch(() => null);
+    const roots = normalizeCollectionRoots(config?.default_repo_paths ?? []);
+    if (roots.length === 0) {
+        console.error("[sync-heal] agent rules not checked; no saved roots to scope them to", JSON.stringify({ reason: "no_saved_roots" }));
+        return null;
+    }
+    const scope = { ...(command.homeDir ? { homeDir: command.homeDir } : {}), scopePaths: roots };
+    const marker = path.join(paths.state_dir, AGENT_RULES_REPAIR_MARKER);
+    const before = await inspectAgentRules(scope);
+    if (before.installed) {
+        // A marker from an earlier attempt is spent; the next removal is
+        // reinstalled on the next tick, not after a retry window.
+        await fs.rm(marker, { force: true }).catch(() => undefined);
+        return null;
+    }
+    const last = await fs.stat(marker).catch(() => null);
+    if (last && now.getTime() - last.mtimeMs < AGENT_RULES_RETRY_AFTER_FAILURE_MS) {
+        console.error("[sync-heal] agent rules still missing; the last install attempt was under an hour ago, retrying after that", JSON.stringify({ reason: "agent_rules_repair_throttled" }));
+        return null;
+    }
+    await fs.mkdir(paths.state_dir, { recursive: true }).catch(() => undefined);
+    await fs.writeFile(marker, now.toISOString()).catch(() => undefined);
+    await installAgentRules(scope);
+    const after = await inspectAgentRules(scope);
+    console.error(after.installed
+        ? "[sync-heal] agent rules were missing and are installed"
+        : "[sync-heal] agent rules install ran but they still read missing", JSON.stringify({ reason: after.installed ? "agent_rules_installed" : "agent_rules_still_missing", before: "missing", after: after.installed ? "installed" : "missing" }));
+    return after.installed
+        ? { step: "agent_rules_install", status: "ok", error_detail: "before=missing; after=installed" }
+        : { step: "agent_rules_install", status: "fail", error_code: "agent_rules_still_missing", error_detail: "before=missing; after=missing" };
+}
+/**
+ * Sign-in: the heartbeat (which ran just before this) renews a lapsed token
+ * inside the server's grace window without a browser. If this machine is STILL
+ * signed out or the door refused the token (401/403), only a browser can fix
+ * it, so record the one action and say it once a day instead of every fifteen
+ * minutes. A lapsed local date with no refusal (offline, a checkout build)
+ * proves nothing, so it says nothing.
+ */
+async function noteSessionState(paths, refusedStatus, now) {
+    const marker = path.join(paths.state_dir, SESSION_NEEDS_LOGIN_MARKER);
+    const session = await readLocalCollectorSessionFile(paths).catch(() => null);
+    const state = session ? toSessionReference(session).session_state : "missing";
+    const noted = await readMarker(marker);
+    const refused = refusedStatus === 401 || refusedStatus === 403;
+    if (state === "valid" && !refused) {
+        if (!noted)
+            return null;
+        await fs.rm(marker, { force: true }).catch(() => undefined);
+        console.error("[sync-heal] sign-in is valid again; the needs-login note is cleared", JSON.stringify({ reason: "session_renewed", before: "needs_login", after: "valid" }));
+        return { step: "session_renewal", status: "ok", error_detail: "before=needs_login; after=valid" };
+    }
+    if (state !== "missing" && !refused)
+        return null;
+    const nowIso = now.toISOString();
+    if (noted && now.getTime() - Date.parse(noted.last_reported_at) < DAY_MS) {
+        return null;
+    }
+    const record = { since: noted?.since ?? nowIso, last_reported_at: nowIso, session_state: state, action: SIGN_IN_ACTION };
+    await fs.mkdir(paths.state_dir, { recursive: true }).catch(() => undefined);
+    await fs.writeFile(marker, JSON.stringify(record)).catch(() => undefined);
+    console.error("[sync-heal] this machine is signed out and a browser sign-in is the only fix; saying so once a day", JSON.stringify({ reason: "browser_sign_in_required", session_state: state, next_action: SIGN_IN_ACTION }));
+    return {
+        step: "session_renewal",
+        status: "fail",
+        error_code: "browser_sign_in_required",
+        error_detail: `${state}; ${SIGN_IN_ACTION}`,
+    };
+}
+async function readMarker(file) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+        if (typeof parsed["since"] === "string" && typeof parsed["last_reported_at"] === "string") {
+            return { since: parsed["since"], last_reported_at: parsed["last_reported_at"] };
+        }
+    }
+    catch {
+        // No marker, or an unreadable one, reads as "never said".
+    }
+    return null;
+}