@bli-cockpit/cli 0.2.167 → 0.2.170

package/dist/autostart-opt-out.js

@@ -0,0 +1,43 @@
+import { AUTOSTART_OPT_OUT_MARKER_FILE_NAME } from "@bli-cockpit/telemetry-core";
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * BLI-12828. The tick now CREATES a missing scheduler registration (an absent
+ * LaunchAgent / Scheduled Task is how a Mac goes quiet after a reboot), so
+ * "absent" can no longer double as "the operator removed it on purpose". This
+ * marker is that deliberate act: `cockpit autostart uninstall` writes it,
+ * `cockpit autostart install` and `cockpit doctor` clear it, and the tick's
+ * create-when-absent repair refuses while it stands.
+ *
+ * One small file under the state dir; it holds a timestamp, never a path.
+ */
+export const AUTOSTART_OPT_OUT_MARKER = AUTOSTART_OPT_OUT_MARKER_FILE_NAME;
+function markerPath(paths) {
+    return path.join(paths.state_dir, AUTOSTART_OPT_OUT_MARKER);
+}
+export async function isAutostartOptedOut(paths) {
+    return fs
+        .stat(markerPath(paths))
+        .then(() => true)
+        .catch(() => false);
+}
+export async function markAutostartOptedOut(paths, now = new Date()) {
+    try {
+        await fs.mkdir(paths.state_dir, { recursive: true, mode: 0o700 });
+        await fs.writeFile(markerPath(paths), now.toISOString());
+        console.error("[autostart] opt-out recorded; the sync tick will not re-create the scheduler until `cockpit autostart install`", JSON.stringify({ reason: "operator_uninstalled" }));
+    }
+    catch (error) {
+        console.error("[autostart] opt-out could not be recorded; the tick may re-create the scheduler", JSON.stringify({
+            reason: "opt_out_write_failed",
+            error_name: error instanceof Error ? error.name : typeof error,
+        }));
+    }
+}
+export async function clearAutostartOptOut(paths) {
+    const had = await isAutostartOptedOut(paths);
+    await fs.rm(markerPath(paths), { force: true }).catch(() => undefined);
+    if (had) {
+        console.error("[autostart] opt-out cleared; background sync is wanted again", JSON.stringify({ reason: "operator_installed" }));
+    }
+}

package/dist/autostart-self-heal.js

@@ -3,8 +3,12 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { autostartStatus, installAutostartAgent, registeredRuntimePathProblems, } from "./autostart.js";
 import { detectSecondCockpitInstall, secondInstallReason, } from "./second-install.js";
+import { isAutostartOptedOut } from "./autostart-opt-out.js";
 export const AUTOSTART_REPAIR_THROTTLE_MARKER = ".last-autostart-repair";
-const AUTOSTART_REPAIR_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
+// BLI-12828: the FIRST repair of a break never waits. The marker only spaces
+// out RETRIES of a repair that keeps failing, and a healthy reading clears it,
+// so the next break is repaired on the next tick, not a day later.
+const AUTOSTART_REPAIR_RETRY_AFTER_FAILURE_MS = 60 * 60 * 1000;
 const DETAIL_MAX_CHARS = 300;
 export async function runAutostartSelfHeal(paths, options) {
     const platform = options.platform ?? process.platform;
@@ -20,9 +24,12 @@ export async function runAutostartSelfHeal(paths, options) {
         exec: options.exec,
         platform,
     });
-    // Absent means the operator (or onboarding) owns the decision, not this tick.
-    if (status.status === "absent")
+    const absent = status.status === "absent";
+    if (absent && (await isAutostartOptedOut(paths))) {
+        // Said on the tick's own log so "why is this Mac not ticking" is answerable.
+        console.error("[autostart-self-heal] scheduler absent; not re-creating it, the operator uninstalled it on purpose", JSON.stringify({ reason: "autostart_uninstalled_by_operator", platform }));
         return null;
+    }
     // A registration can read as "loaded" and still name a binary that no longer
     // exists — that is precisely what `brew upgrade node` leaves behind. Ask the
     // filesystem about the paths the SCHEDULER holds, not the ones this process
@@ -34,11 +41,16 @@ export async function runAutostartSelfHeal(paths, options) {
             platform,
         })
         : [];
-    if (status.status !== "not_loaded" && runtimeProblems.length === 0) {
-        // Healthy is the steady state and stays silent.
+    const marker = path.join(paths.state_dir, AUTOSTART_REPAIR_THROTTLE_MARKER);
+    if (!absent && status.status !== "not_loaded" && runtimeProblems.length === 0) {
+        // Healthy is the steady state and stays silent. A marker left by an
+        // earlier attempt is spent: that repair worked, so the next break starts
+        // fresh instead of waiting out a retry window.
+        await fs.rm(marker, { force: true }).catch(() => undefined);
         return null;
     }
     const problem = [
+        ...(absent ? ["registration absent"] : []),
         ...(status.message ? [status.message] : []),
         ...runtimeProblems,
     ]
@@ -59,15 +71,16 @@ export async function runAutostartSelfHeal(paths, options) {
             step: platform === "darwin" ? "autostart_heal" : "autostart_repair",
         };
     }
-    // Attempts are throttled (marker mtime, written for the attempt not the
-    // outcome) so a persistently failing repair cannot run every 15 minutes. The
+    // Only a RETRY waits (marker mtime, written for the attempt not the
+    // outcome, cleared by the next healthy reading): a repair that keeps failing
+    // is retried hourly instead of churning the scheduler every 15 minutes. The
     // status probe above still runs every tick — it is one launchctl/schtasks
     // query.
     const now = options.now ?? new Date();
-    const marker = path.join(paths.state_dir, AUTOSTART_REPAIR_THROTTLE_MARKER);
     const lastAttempt = await fs.stat(marker).catch(() => null);
     if (lastAttempt &&
-        now.getTime() - lastAttempt.mtimeMs < AUTOSTART_REPAIR_MIN_INTERVAL_MS) {
+        now.getTime() - lastAttempt.mtimeMs < AUTOSTART_REPAIR_RETRY_AFTER_FAILURE_MS) {
+        console.error("[autostart-self-heal] scheduler still broken; the last repair attempt was under an hour ago, retrying after that", JSON.stringify({ reason: "repair_retry_waiting", platform }));
         return { status: "skipped", reason: "repair_throttled_recent_attempt" };
     }
     await fs.mkdir(paths.state_dir, { recursive: true }).catch(() => undefined);
@@ -85,7 +98,7 @@ export async function runAutostartSelfHeal(paths, options) {
     if (repaired.loaded) {
         return {
             status: "ok",
-            reason: "autostart_repaired",
+            reason: absent ? "autostart_created" : "autostart_repaired",
             detail: problem,
             step: "autostart_repair",
         };

package/dist/commands/autostart-command.js

@@ -1,6 +1,7 @@
 import { defaultExec, writeLine } from "./cli-io.js";
 import { runAutostartHealDetached } from "./autostart-heal.js";
 import { autostartStatus, installAutostartAgent, uninstallAutostartAgent, } from "../autostart.js";
+import { clearAutostartOptOut, markAutostartOptedOut, } from "../autostart-opt-out.js";
 import { getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
 export async function runAutostart(command, io) {
     if (command.action === "heal-detached") {
@@ -37,6 +38,15 @@ export async function runAutostart(command, io) {
                 intervalSeconds: command.intervalSeconds,
                 exec,
             });
+    // BLI-12828: the tick re-creates an absent scheduler, so a deliberate
+    // uninstall has to leave a mark the tick can read.
+    const optOutPaths = getCollectorRuntimePaths(command.homeDir);
+    if (command.action === "uninstall" && result.status !== "unsupported") {
+        await markAutostartOptedOut(optOutPaths);
+    }
+    else if (command.action === "install" && result.loaded !== false) {
+        await clearAutostartOptOut(optOutPaths);
+    }
     if (command.json) {
         writeLine(io.stdout, JSON.stringify(result, null, 2));
         return autostartExitCode(command.action, result);

package/dist/commands/autostart-heal.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { appendFile } from "node:fs/promises";
 import { AUTOSTART_LABEL, autostartStatus, reregisterDarwinAgent, writeDarwinAutostartPlist, } from "../autostart.js";
+import { isAutostartOptedOut } from "../autostart-opt-out.js";
 import { redactedHealthDetail } from "../health-detail.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
 import { normalizeCollectionRoots } from "../root-normalization.js";
@@ -72,9 +73,10 @@ async function healDetached(command, io, deps) {
         exec,
         platform,
     });
-    if (before.status === "absent") {
-        // Repair what exists, never create.
-        return { status: "skipped", reason: "autostart_absent" };
+    if (before.status === "absent" &&
+        (await isAutostartOptedOut(getCollectorRuntimePaths(command.homeDir)))) {
+        // BLI-12828: absent is created now; only a deliberate uninstall stops it.
+        return { status: "skipped", reason: "autostart_uninstalled_by_operator" };
     }
     let written;
     try {
@@ -125,7 +127,7 @@ async function healDetached(command, io, deps) {
     }
     return {
         status: "ok",
-        reason: "autostart_healed",
+        reason: before.status === "absent" ? "autostart_created" : "autostart_healed",
         detail: `node_path_reason=${written.node_path_reason}`,
     };
 }

package/dist/commands/doctor-access.js

@@ -8,6 +8,7 @@ import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConf
 import { normalizeCollectionRoots } from "../root-normalization.js";
 import { detectSecondCockpitInstall } from "../second-install.js";
 import { hardStop, needsFix, ok, skipped } from "./doctor-report.js";
+import { SIGN_IN_ACTION } from "../sign-in-action.js";
 /**
  * The `authed`, `roots-ok`, and `single-install` check family: who is this
  * machine and where does it collect. Auth and roots are hard stops with no
@@ -31,7 +32,7 @@ export async function fixAuthState(context, state) {
             return checked;
     }
     if (!isInteractiveDoctorFix(context))
-        return { ...state, nextAction: "cockpit login" };
+        return { ...state, nextAction: SIGN_IN_ACTION };
     const code = await context.deps.runLogin(context).catch((error) => {
         // Exit code 1 with no reason at all is what an operator saw when doctor
         // tried and failed to repair their auth — the same output as a login that
@@ -73,13 +74,10 @@ export async function readAuthState(context) {
         }
         return ok("authed", "device_token_present", "this machine is signed in");
     }
-    return hardStop("authed", "pairing_required", [
-        "device is not signed in.",
-        "What you can do:",
-        "  1) Run `cockpit login` and complete the email/device approval.",
-        `  2) If this is a reused machine, run \`${onboardOneLiner(context.command)}\` to refresh onboarding.`,
-        "  3) Send this output to Edward if approval is blocked.",
-    ].join("\n"));
+    return {
+        ...hardStop("authed", "pairing_required", `this machine is signed out. ${SIGN_IN_ACTION}`),
+        nextAction: SIGN_IN_ACTION,
+    };
 }
 export async function readRootState(context) {
     const paths = getCollectorRuntimePaths(context.command.homeDir);
@@ -92,13 +90,11 @@ export async function readRootState(context) {
             roots,
         };
     }
-    return hardStop("roots-ok", "no_roots", [
-        "no saved collection roots were found.",
-        "What you can do:",
-        `  1) Run \`${onboardOneLiner(context.command)}\` to save the workspace roots again.`,
-        "  2) If this is the wrong folder, rerun from the BLI workspace or pass `--workspace <path>`.",
-        "  3) Run `cockpit doctor` interactively to choose approved roots.",
-    ].join("\n"));
+    const action = `Run \`${onboardOneLiner(context.command)}\` in a terminal from the folder where you work.`;
+    return {
+        ...hardStop("roots-ok", "no_roots", `no collection folders are saved yet. ${action}`),
+        nextAction: action,
+    };
 }
 /**
  * BLI-3218/BLI-3553. Two Tower installs on one machine make each one's tick
@@ -164,10 +160,10 @@ function shellQuote(value) {
  * a gate on it, so a session sitting outside one is not a defect doctor found
  * and cannot repair. This row is therefore always informational (`ok`): it
  * reports how many of this scan's sessions were inside vs. outside, never
- * asks for approval, and attempts no fix. Widening the boundary still buys
- * the redacted transcript BYTES for those outside directories (those stay
- * root-gated), so the message still names `cockpit roots add` as something an
- * operator can choose to do, never something doctor is stuck waiting on. The
+ * asks for approval, and attempts no fix. Widening a root only adds the redacted transcript BYTES for those
+ * directories, so the message names `cockpit roots add` as an OPTIONAL step an
+ * operator can choose, never something doctor, or any person, is waiting on to
+ * approve. The
  * row only turns red the ordinary way every other doctor check does: the scan
  * itself throwing (`work_directory_scan_incomplete` from unreadable session
  * folders), which `runDoctorWithDeps`'s existing `check_threw` handling
@@ -182,9 +178,9 @@ export async function readRootsCoverWork(context) {
     const outsideCount = outside.reduce((sum, entry) => sum + entry.count, 0);
     const insideCount = scan.observed - outsideCount;
     if (!outsideCount)
-        return ok("roots-cover-work", "work_covered", `${scan.observed} sessions seen; no known working directories outside approved roots. ${sessionCoverageLine(scan, outsideCount)}`);
+        return ok("roots-cover-work", "work_covered", `${scan.observed} sessions seen; no working folders outside your saved roots. ${sessionCoverageLine(scan, outsideCount)}`);
     return {
-        ...ok("roots-cover-work", "work_outside_roots_labelled", `${insideCount} of ${scan.observed} sessions inside approved roots, ${outsideCount} outside — every one already reached the server, the outside ones carrying an outside label. Their redacted transcript content stays unuploaded until a root widens (scan ${scan.generated_at}):\n${outside.map(entry => `${entry.count}: ${entry.directory}\n  ${rootsAddCommand(entry.directory, process.platform, homeDir)}`).join("\n")}\n\n${sessionCoverageLine(scan, outsideCount)}`),
+        ...ok("roots-cover-work", "work_outside_roots_labelled", `${insideCount} of ${scan.observed} sessions inside your saved roots, ${outsideCount} outside — every one already reached the server, the outside ones carrying an outside label. Nothing needs approving. Optional: add a folder as a root to also upload its redacted transcript text (scan ${scan.generated_at}):\n${outside.map(entry => `${entry.count}: ${entry.directory}\n  ${rootsAddCommand(entry.directory, process.platform, homeDir)}`).join("\n")}\n\n${sessionCoverageLine(scan, outsideCount)}`),
         nextAction: rootsAddCommand(outside[0].directory, process.platform, homeDir),
     };
 }

package/dist/commands/doctor-mcp.js

@@ -30,6 +30,12 @@
  *             ledger with its reason label (`doctor-report.ts`'s `doctorEvent`
  *             maps every other status to `ok`).
  *
+ * BLI-12828: a `fail` (nothing answered) now has a repair. The server ships
+ * inside the CLI and is wired in by `memory install`, so the fix re-registers,
+ * takes the newest CLI if that alone did not wake it, and asks again; the row's
+ * receipt shows the before and after. A `needs_fix` (Tower refused) has none:
+ * the refusal is the sign-in's, and the `authed` row owns that.
+ *
  * `skipped` when the bin is not on this machine at all, for the same reason
  * `memory-registered` skips: nothing to probe is not a broken machine.
  */
@@ -95,4 +101,25 @@ function probeEnv(context) {
     if (context.command.dashboardUrl)
         base[TOWER_DASHBOARD_URL_ENV] = context.command.dashboardUrl;
     return base;
+}
+/**
+ * The `mcp-answers` repair (BLI-12828): re-register, then take the newest CLI,
+ * asking the server again after each. Heavy (it spawns the server and may run
+ * the updater), so doctor runs it only on a `fail` and the tick leaves it to
+ * the daily memory install and the CLI floor, which do the same two things.
+ */
+export async function fixMcpAnswersState(context, state) {
+    if (state.status !== "fail") {
+        console.error("[doctor] mcp-answers not repaired; Tower refused the call and the sign-in row owns that", JSON.stringify({ reason: state.code }));
+        return state;
+    }
+    await context.deps.fixMemory(context);
+    let checked = await context.deps.checkMcpAnswers(context);
+    console.error("[doctor] mcp-answers re-registered and asked again", JSON.stringify({ reason: checked.code, status: checked.status }));
+    if (checked.status === "fail") {
+        await context.deps.selfUpdate(context.io, { json: true, tag: context.command.updateTag });
+        checked = await context.deps.checkMcpAnswers(context);
+        console.error("[doctor] mcp-answers updated the CLI and asked again", JSON.stringify({ reason: checked.code, status: checked.status }));
+    }
+    return checked;
 }

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-mail.js

@@ -16,7 +16,12 @@
  *   stores.
  * - **The message body.** `cockpit mail send` and `cockpit mail draft` take it
  *   from stdin or `--file`, the same discipline `cockpit issue comment` and
- *   `cockpit docs update` keep.
+ *   `cockpit docs update` keep. `--file` is the BODY and nothing else.
+ *
+ * `--attach <path>` (BLI-12661, repeatable, `send` and `draft` only) names a
+ * file to ride along. It is a PATH on argv, never the file's bytes: the bytes
+ * are read in `mail-attachments.ts`, screened there, and posted in the JSON
+ * body like the text is.
  *
  * `draft` (BLI-12530) takes `send`'s flags exactly — `--account`, `--to`,
  * `--cc`, `--subject`, `--reply-to`, `--file` — and is refused the same two
@@ -60,6 +65,7 @@ export function parseMailArgs(args) {
             "--subject",
             "--reply-to",
             "--file",
+            "--attach",
             "--body-stdin",
             "--out",
             "--json",
@@ -78,6 +84,7 @@ export function parseMailArgs(args) {
             "--subject",
             "--reply-to",
             "--file",
+            "--attach",
             "--out",
         ],
     });
@@ -87,7 +94,8 @@ export function parseMailArgs(args) {
     const { to, cc } = readMailRecipients(action, values);
     const outPath = readAttachmentPath(action, values);
     const limit = readMailLimit(action, values);
-    return buildMailCommand(values, action, subject, query, address, to, cc, outPath, limit);
+    const attachPaths = readAttachPaths(action, values);
+    return buildMailCommand(values, action, subject, query, address, to, cc, outPath, limit, attachPaths);
 }
 function readMailAction(values) {
     const first = values.positionals[0];
@@ -152,6 +160,24 @@ function readAttachmentPath(action, values) {
     }
     return outPath;
 }
+/**
+ * `--attach <path>`, repeatable (BLI-12661): files that ride along with a
+ * `send` or a `draft`. Collected here and read, screened and refused by name in
+ * `mail-attachments.ts`, so a missing file or a fifth too many answers as a
+ * door refusal with a reason label (and under --json as one object) rather than
+ * as a usage error. `--file` is untouched and still means the BODY.
+ */
+function readAttachPaths(action, values) {
+    const named = values.flagValues.get("--attach") ?? [];
+    if (named.length > 0 && !MAIL_ACTIONS_COMPOSING.has(action)) {
+        throw new Error("--attach belongs to `cockpit mail send` and `cockpit mail draft`: a file to attach to the message.");
+    }
+    // A blank path is a mistake to name, never a file to drop without a word.
+    const paths = named.map((value) => optionalNonEmpty(value));
+    if (paths.some((value) => value === undefined))
+        throw new Error("--attach needs a file path, not a blank value.");
+    return paths;
+}
 function readMailLimit(action, values) {
     const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
     if (limit !== undefined && action !== "inbox" && action !== "search") {
@@ -159,7 +185,7 @@ function readMailLimit(action, values) {
     }
     return limit;
 }
-function buildMailCommand(values, action, subject, query, address, to, cc, outPath, limit) {
+function buildMailCommand(values, action, subject, query, address, to, cc, outPath, limit, attachPaths) {
     return {
         kind: "mail",
         action,
@@ -179,6 +205,7 @@ function buildMailCommand(values, action, subject, query, address, to, cc, outPa
         subjectLine: optionalNonEmpty(values.flags.get("--subject")),
         replyTo: optionalNonEmpty(values.flags.get("--reply-to")),
         filePath: optionalNonEmpty(values.flags.get("--file")),
+        ...(attachPaths.length > 0 ? { attachPaths } : {}),
         bodyStdin: values.booleans.has("--body-stdin"),
         outPath,
         json: values.booleans.has("--json"),

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

@@ -133,8 +133,9 @@ export const TOWER_COMMAND_HELP = [
             "inbox [--account <id>] [--unread] [--label <l>] [--limit <n>] [--before <iso>] — everything across every mailbox, newest first. * is unread, @ has an attachment. Every row (text or --json) carries the thread id — `[thread <id>]` in text — so `mail read <thread>` never costs a second --json call to learn it (BLI-10450).",
             "read <thread> — one conversation with its bodies. Thread ids come from `cockpit mail inbox` or `cockpit mail search`, in either --json or plain text.",
             "search \"<words>\" [--account <id>] [--limit <n>] — full text over subject and body. Quotes and OR work the way they do in a search box. Every row (text or --json) carries the thread id.",
-            "send --account <id> --to <a[,b]> [--cc <c>] --subject \"<s>\" [--reply-to <message id>] [--file <path>] — the BODY comes from --file or stdin. --account is required: which address this goes out from is yours to say.",
-            "draft --account <id> --to <a[,b]> [--cc <c>] --subject \"<s>\" [--reply-to <message id>] [--file <path>] — saves the message as a DRAFT in that mailbox for a person to read, edit and send themselves. NOTHING IS SENT and nobody is notified, so there is no confirmation step. Same flags and same body rule as send (--file or stdin). Only the mailbox's owner can draft into it. --reply-to threads the draft into that conversation the way send does; Gmail files it there only when the subject matches the original's, and the answer says whether it did. Gmail mailboxes only: an IMAP mailbox is refused as imap_drafts_unsupported. --json answers { ok, draft: { account_id, address, provider_draft_id, provider_thread_id, threaded } } (BLI-12530).",
+            "send --account <id> --to <a[,b]> [--cc <c>] --subject \"<s>\" [--reply-to <message id>] [--file <path>] [--attach <path>]... — the BODY comes from --file or stdin. --account is required: which address this goes out from is yours to say.",
+            "draft --account <id> --to <a[,b]> [--cc <c>] --subject \"<s>\" [--reply-to <message id>] [--file <path>] [--attach <path>]... — saves the message as a DRAFT in that mailbox for a person to read, edit and send themselves. NOTHING IS SENT and nobody is notified, so there is no confirmation step. Same flags and same body rule as send (--file or stdin). Only the mailbox's owner can draft into it. --reply-to threads the draft into that conversation the way send does; Gmail files it there only when the subject matches the original's, and the answer says whether it did. Gmail mailboxes only: an IMAP mailbox is refused as imap_drafts_unsupported. --json answers { ok, draft: { account_id, address, provider_draft_id, provider_thread_id, threaded } } (BLI-12530).",
+            "--attach <path> (send and draft; repeat it for each file) — a file that rides along with the message: up to 10, and 3,000,000 bytes together (about 3 MB: a request to Tower is capped at 4.5 MB and a file travels as base64, a third bigger than itself). The type comes from the extension (.docx .pdf .png .jpg .jpeg .txt .csv .md .zip and more; anything else goes as application/octet-stream), the name is the file's own. --file is still the BODY and only the body. Refused BEFORE anything is sent, by name and with the numbers: too_many_attachments, attachment_unreadable (a path that is missing, a folder or empty), attachment_too_large. A reply (--reply-to) keeps its thread with files in it. Works on Gmail mailboxes and on IMAP mailboxes for send; a draft is Gmail only. --json adds { attachments: { count, bytes, content_types } } to the answer. The terminal reports from Tower's own answer, not from what it posted: if Tower does not confirm the files (an older Tower), it exits 1 with attachments_not_confirmed and says whether the message went. Names, paths and contents are never logged; a refusal says \"Attachment 2\", not which file (BLI-12661).",
             "attachment <id> --out <path> — downloads one attachment to a file. Attachments are pointers until you ask; nothing is stored in Tower.",
             "sync <account> — reads that mailbox now instead of waiting for the cron. Prints what landed, or the reason it did not.",
             "sync-status [<account>] — every mailbox's health, or one's: last successful sync, the last pass's own reason, how many messages it carried, failures in the last 24h, and the lag between a message's own clock and when Tower stored it (ticket 10730).",

package/dist/commands/local-help.js

@@ -124,7 +124,7 @@ export function localCommandHelp(command) {
         "  cockpit docs [list|tree|read <id|slug>|create --title <t>|update <id>|delete <id|slug>] [--parent <id>|root|--clear-parent] [--query <text> [--word]] [--limit <n>] [--visibility org|private] [--file <path>|--body-stdin] [--allow-empty] [--dashboard-url <url>] [--json]",
         "  cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>] [--private] [--members a@x,b@y] [--description <text>] [--thread <id>] [--limit <n>] [--dashboard-url <url>] [--json]",
         "  cockpit issue [list|show <BLI-id>|create --title <t>|update <BLI-id>|move <BLI-id> <state>|comment <BLI-id>|history <BLI-id>] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] [--priority 0-4] [--size S|M|L] [--parent <BLI-id>] [--file <path>|--body-stdin] [--dashboard-url <url>] [--json]",
-        "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|draft --account <id> --to <a> --subject <s> [--reply-to <message id>]|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--dashboard-url <url>] [--json]",
+        "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|draft --account <id> --to <a> --subject <s> [--reply-to <message id>]|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--attach <path>]... [--dashboard-url <url>] [--json]",
         "  cockpit cal [today|week|next|find \"<words>\"|calendars|add-ical|create --calendar <id> --title <t> --at <iso> --until <iso>|share <id> --org-visible|--private|sync <id> [--full]|detach <id>] [--tz <zone>] [--offset <n>] [--hours <n>] [--from <d> --to <d>] [--calendar <id>] [--limit <n>] [--all] [--dashboard-url <url>] [--json]",
         "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
         "  cockpit github <pr|merge|retitle|rerun> <owner/repo> <n> [--claim <state>] [--method squash|merge|rebase] [--title \"<text>\"] [--run <id>] [--confirm <code>] [--dashboard-url <url>] [--json]",

package/dist/commands/mail-attachments.js

@@ -0,0 +1,207 @@
+/**
+ * `--attach <path>` for `cockpit mail send` and `cockpit mail draft` (BLI-12661):
+ * read the files on THIS machine, screen them, and turn them into the
+ * `attachments` the two doors take. Nothing here talks to Tower, and nothing is
+ * read from a disk that is not the person's own: the server is never handed a
+ * path.
+ *
+ * **Everything that can be refused is refused before a byte leaves the
+ * machine**, each with a named reason and its numbers (the server holds the same
+ * caps and says the same words, `lib/mail/outbound-attachments.ts`):
+ *
+ *   too_many_attachments   more than 10 `--attach`
+ *   attachment_unreadable  a path that is missing, is not a regular file, cannot
+ *                          be read, or is empty
+ *   attachment_too_large   more than 3,000,000 bytes together, or a whole
+ *                          request that would not fit the platform's body cap
+ *
+ * **Why 3,000,000 bytes.** Vercel caps a function REQUEST body at 4.5 MB (413
+ * `FUNCTION_PAYLOAD_TOO_LARGE`, before Tower's code runs), and a file travels as
+ * base64, a third bigger than itself. 3,000,000 bytes is 4,000,000 characters of
+ * base64, which leaves about half a megabyte for the JSON around it. Gmail's own
+ * 25 MB is not the binding limit. `MAIL_REQUEST_MAX_BYTES` is the second check:
+ * a 3 MB file next to a very long body is still too big for one request, and a
+ * platform 413 says nothing about why.
+ *
+ * **Sizes are read off `stat` first.** Every file is stat'ed, the total is
+ * checked, and only then is a single byte read, so a 5 GB file named by mistake
+ * costs one system call and no memory.
+ *
+ * **The type comes from the extension and nothing else.** Unknown is
+ * `application/octet-stream`. The table is copied, on purpose, into
+ * `packages/bli-cockpit-mcp/src/mail-attachments.ts` (that package depends on
+ * neither this one nor `cockpit-cli`), and `mail-attachment-parity.test.ts` in
+ * the MCP package fails when the two drift.
+ *
+ * **Names are never logged, and nor are paths.** The one success line says how
+ * many files, how big and of what type (`describeMailAttachments`). A refusal
+ * names the file by POSITION ("Attachment 2") and the file system's own error
+ * CODE, never its path or its name (the message standard: no local path in an
+ * operator-facing string): the person who typed the command is looking at it.
+ *
+ * No secret-name refusal lives here (`notes upload` has one): a person who names
+ * a file here has decided to send it, and the outbound guard masks text, not
+ * files. See the doc.
+ */
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { isSecretLikePathSegment } from "@bli-cockpit/telemetry-core";
+export const MAIL_ATTACHMENT_MAX_COUNT = 10;
+export const MAIL_ATTACHMENTS_MAX_TOTAL_BYTES = 3_000_000;
+/** The whole JSON request, under Vercel's 4.5 MB function-body cap with room for the headers. */
+export const MAIL_REQUEST_MAX_BYTES = 4_400_000;
+// BEGIN content types: identical in packages/bli-cockpit-mcp/src/mail-attachments.ts
+export const MAIL_ATTACHMENT_CONTENT_TYPES = {
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    doc: "application/msword",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    xls: "application/vnd.ms-excel",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ppt: "application/vnd.ms-powerpoint",
+    pdf: "application/pdf",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    txt: "text/plain",
+    csv: "text/csv",
+    md: "text/markdown",
+    json: "application/json",
+    html: "text/html",
+    rtf: "application/rtf",
+    zip: "application/zip",
+};
+// END content types
+// BEGIN secret-like names: identical in the CLI and MCP mail-attachments.ts
+/**
+ * A name a person almost never means to email: the repo's own secret-name rule
+ * (`isSecretLikePathSegment`, the one `notes upload` uses: `.env*`, anything with
+ * secret, credential, private_key or service_role in it), with `.env.example`
+ * let through (a template, no values), plus the private-key names that rule does
+ * not know: id_rsa and its siblings, `*.pem`, `*.key`.
+ */
+export function attachmentLooksSecret(fileName) {
+    if (/^\.env\.example$/i.test(fileName))
+        return false;
+    return isSecretLikePathSegment(fileName) || /^id_(rsa|dsa|ecdsa|ed25519)$/i.test(fileName) || /\.(pem|key)$/i.test(fileName);
+}
+// END secret-like names
+const FALLBACK_CONTENT_TYPE = "application/octet-stream";
+/** The type a file name's extension says it is. Case-insensitive; anything unknown is octet-stream. */
+export function mailAttachmentContentType(fileName) {
+    const extension = path.extname(fileName).slice(1).toLowerCase();
+    return MAIL_ATTACHMENT_CONTENT_TYPES[extension] ?? FALLBACK_CONTENT_TYPE;
+}
+const NOTHING_SENT = "Nothing was sent.";
+function refuse(reason, detail) {
+    return { ok: false, reason, detail };
+}
+function bytesLabel(count) {
+    return `${count.toLocaleString("en-US")} byte${count === 1 ? "" : "s"}`;
+}
+/** The verdict on a set of sizes, or null when it may go. Shared by the stat pass and the read pass. */
+function totalTooLarge(total) {
+    if (total <= MAIL_ATTACHMENTS_MAX_TOTAL_BYTES)
+        return null;
+    return refuse("attachment_too_large", `The attachments come to ${bytesLabel(total)} and one message carries at most ${bytesLabel(MAIL_ATTACHMENTS_MAX_TOTAL_BYTES)} `
+        + "(about 3 MB: the most one request to Tower holds once the files are encoded). "
+        + `Share a link for anything bigger. ${NOTHING_SENT}`);
+}
+/**
+ * Reads every `--attach` path, or says which one cannot go and why. Never throws.
+ * Order: the count, then each file's `stat` (missing, not a file, empty), then the
+ * total, and only then the bytes.
+ */
+export async function readMailAttachments(paths) {
+    if (paths.length === 0)
+        return { ok: true, attachments: [], summary: { count: 0, bytes: 0, sizes: [], content_types: [] } };
+    if (paths.length > MAIL_ATTACHMENT_MAX_COUNT) {
+        return refuse("too_many_attachments", `${paths.length} files were named with --attach and one message carries at most ${MAIL_ATTACHMENT_MAX_COUNT}. ${NOTHING_SENT}`);
+    }
+    // Names first, before a single stat or read: a secret-looking file is never opened.
+    const secret = paths.findIndex((filePath) => attachmentLooksSecret(path.basename(filePath)));
+    if (secret !== -1) {
+        return refuse("attachment_secret_like", `Attachment ${secret + 1} has a name that looks like a key or credential file, so it was not opened. ${NOTHING_SENT}`);
+    }
+    const sizes = [];
+    for (const [index, filePath] of paths.entries()) {
+        const label = `Attachment ${index + 1}`;
+        let size;
+        try {
+            const info = await stat(filePath);
+            if (!info.isFile())
+                return refuse("attachment_unreadable", `${label} is not a regular file: a folder or a device cannot be attached. ${NOTHING_SENT}`);
+            size = info.size;
+        }
+        catch (error) {
+            const code = error.code;
+            return refuse("attachment_unreadable", code === "ENOENT"
+                ? `${label} does not exist. ${NOTHING_SENT}`
+                : `${label} could not be read (${code ?? "unknown error"}). ${NOTHING_SENT}`);
+        }
+        if (size === 0)
+            return refuse("attachment_unreadable", `${label} is empty, and an empty file is not worth sending. ${NOTHING_SENT}`);
+        sizes.push(size);
+    }
+    const tooLarge = totalTooLarge(sizes.reduce((sum, size) => sum + size, 0));
+    if (tooLarge)
+        return tooLarge;
+    const attachments = [];
+    const actual = [];
+    for (const [index, filePath] of paths.entries()) {
+        let bytes;
+        try {
+            bytes = await readFile(filePath);
+        }
+        catch (error) {
+            const code = error.code;
+            return refuse("attachment_unreadable", `Attachment ${index + 1} could not be read (${code ?? "unknown error"}). ${NOTHING_SENT}`);
+        }
+        actual.push(bytes.length);
+        const filename = path.basename(filePath);
+        attachments.push({
+            filename,
+            content_type: mailAttachmentContentType(filename),
+            content_base64: bytes.toString("base64"),
+        });
+    }
+    // A file that grew between the stat and the read is the file as it is now.
+    const total = actual.reduce((sum, size) => sum + size, 0);
+    const grew = totalTooLarge(total);
+    if (grew)
+        return grew;
+    if (actual.includes(0)) {
+        return refuse("attachment_unreadable", `Attachment ${actual.indexOf(0) + 1} is empty, and an empty file is not worth sending. ${NOTHING_SENT}`);
+    }
+    return {
+        ok: true,
+        attachments,
+        summary: {
+            count: attachments.length,
+            bytes: total,
+            sizes: actual,
+            content_types: attachments.map((attachment) => attachment.content_type),
+        },
+    };
+}
+/**
+ * The second check: the whole request, not just the files. Called with the JSON
+ * body about to be posted, and only when it carries files.
+ */
+export function mailRequestFits(body) {
+    const bytes = Buffer.byteLength(JSON.stringify(body), "utf8");
+    if (bytes <= MAIL_REQUEST_MAX_BYTES)
+        return { ok: true, bytes };
+    return refuse("attachment_too_large", `The whole request would be ${bytesLabel(bytes)} (the message, the files encoded as base64, and the JSON around them) `
+        + `and Tower takes at most ${bytesLabel(MAIL_REQUEST_MAX_BYTES)}: a request over 4.5 MB is refused by the platform before Tower sees it. `
+        + `Shorten the message or send fewer or smaller files. ${NOTHING_SENT}`);
+}
+/** The single stderr line for a send or a draft that carries files: count, bytes, sizes, types. */
+export function describeMailAttachments(summary) {
+    return `[mail cli] attaching ${JSON.stringify(summary)}`;
+}
+/** The sentence a person reads after a send or a draft that carried files. */
+export function attachmentSentence(summary) {
+    return `${summary.count} attachment${summary.count === 1 ? "" : "s"} went with it (${bytesLabel(summary.bytes)}).`;
+}

package/dist/commands/mail-compose.js

@@ -18,9 +18,16 @@
  * `send`, `issue comment` and `docs update` already keep — argv is world-
  * readable on a shared machine and is captured by this product's own session
  * harvester.
+ *
+ * FILES RIDE ALONG WITH `--attach <path>` (BLI-12661), repeatable, on `send` and
+ * `draft` alike. `composeMessage` reads them through `mail-attachments.ts` and
+ * puts them in the one request body both verbs post, so a field added for one
+ * cannot be forgotten by the other. `--file` still means the body and only the
+ * body; a path on argv is a path, not the file's contents.
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor, } from "./agent-door.js";
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { attachmentSentence, describeMailAttachments, mailRequestFits, readMailAttachments, } from "./mail-attachments.js";
 import { readNoteFile } from "./notes-file.js";
 // One spelling per surface: the same tag `mail.ts` uses.
 const TAG = "[mail cli]";
@@ -51,18 +58,86 @@ export async function readMailBody(command, door) {
 /**
  * The JSON that `send` and `draft` post. One shape on purpose: the two doors
  * take the same fields, and a message that can be sent can be saved unsent.
+ * `attachments` is present only when there are files (BLI-12661), so a message
+ * without any is the same bytes it always was.
  */
-export function composedMessageBody(command, text) {
+export function composedMessageBody(command, text, attachments = []) {
     return {
         account_id: command.accountId,
         to: command.to.map((address) => ({ address })),
         ...(command.cc.length > 0 ? { cc: command.cc.map((address) => ({ address })) } : {}),
         subject: command.subjectLine ?? "",
         text,
+        ...(attachments.length > 0 ? { attachments } : {}),
         ...(command.replyTo ? { in_reply_to_message_id: command.replyTo } : {}),
     };
 }
-/** `draft --account <id> --to <a[,b]> [--cc <c>] --subject "<s>" [--reply-to <message id>] [--file <path>]` */
+const NO_ATTACHMENTS = { json: {}, sentence: null, posted: null };
+/**
+ * Did the door SAY it carried the files that were posted? Claim only what the
+ * receipt shows: a Tower that predates attachments answers an ordinary 201,
+ * because its schema strips the key it does not know, and the message goes out
+ * or is saved WITHOUT its files while a terminal that reported from what it
+ * posted would say they went. Only the door's own `attachments` receipt (count
+ * and bytes, both) says they did.
+ *
+ * Returns the sentence to print when the answer does not say so, else null.
+ */
+export function unconfirmedAttachments(receipt, carried, verb) {
+    if (!receipt.posted)
+        return null;
+    const said = carried !== null && typeof carried === "object" ? carried : {};
+    if (said.count === receipt.posted.count && said.bytes === receipt.posted.bytes)
+        return null;
+    const files = `${receipt.posted.count} attachment${receipt.posted.count === 1 ? "" : "s"}`;
+    return verb === "send"
+        ? `Tower accepted the message but did not confirm that its ${files} ${receipt.posted.count === 1 ? "was" : "were"} in it. `
+            + "That usually means this Tower deployment predates attachments, in which case the message went out WITHOUT them. "
+            + "It was sent once: look in that mailbox's Sent folder before doing anything else."
+        : `Tower saved the draft but did not confirm that its ${files} ${receipt.posted.count === 1 ? "was" : "were"} in it. `
+            + "That usually means this Tower deployment predates attachments, in which case the draft has NO file. "
+            + "Open that mailbox's Drafts, delete it, and try again once Tower is updated.";
+}
+/** The failure for a send or a draft whose files the door did not confirm. The message DID go, so the answer rides along. */
+export function failAttachmentsUnconfirmed(door, verb, detail, answer) {
+    writeLine(door.io.stderr, `${TAG} not confirmed ${JSON.stringify({ reason: "attachments_not_confirmed" })}`);
+    if (door.json) {
+        writeLine(door.io.stdout, JSON.stringify({ ok: false, error: "attachments_not_confirmed", detail, [verb === "send" ? "sent" : "draft"]: answer }));
+    }
+    else {
+        writeLine(door.io.stderr, detail);
+    }
+    return 1;
+}
+/**
+ * The request `send` and `draft` post: the body, plus the files named with
+ * `--attach`, read and screened HERE, before any request is made (BLI-12661).
+ * A refusal is the named reason and its numbers (`mail-attachments.ts`).
+ *
+ * The one stderr line it writes says how many files, how big and of what type;
+ * never a name, never a byte. Under `--json` stdout still carries one object.
+ */
+export async function composeMessage(command, door, text) {
+    const read = await readMailAttachments(command.attachPaths ?? []);
+    if (!read.ok)
+        return read;
+    if (read.attachments.length === 0)
+        return { ok: true, body: composedMessageBody(command, text), receipt: NO_ATTACHMENTS };
+    const body = composedMessageBody(command, text, read.attachments);
+    const fits = mailRequestFits(body);
+    if (!fits.ok)
+        return fits;
+    writeLine(door.io.stderr, describeMailAttachments(read.summary));
+    return { ok: true, body, receipt: attachmentReceipt(read.summary) };
+}
+function attachmentReceipt(summary) {
+    return {
+        json: { attachments: { count: summary.count, bytes: summary.bytes, content_types: summary.content_types } },
+        sentence: attachmentSentence(summary),
+        posted: { count: summary.count, bytes: summary.bytes },
+    };
+}
+/** `draft --account <id> --to <a[,b]> [--cc <c>] --subject "<s>" [--reply-to <message id>] [--file <path>] [--attach <path>]...` */
 export async function runMailDraft(command, door) {
     const body = await readMailBody(command, door);
     if (!body.ok)
@@ -70,20 +145,29 @@ export async function runMailDraft(command, door) {
     if (body.text.trim() === "") {
         return failAgentDoor(door, TAG, "body_required", 'A draft needs a body: `echo "Tuesday works for me." | cockpit mail draft --account <id> --to someone@example.com --subject "Re: lunch"`.');
     }
+    const message = await composeMessage(command, door, body.text);
+    if (!message.ok)
+        return failAgentDoor(door, TAG, message.reason, message.detail);
     const answer = await askAgentDoor(door, {
         path: "/api/mail/drafts",
         method: "POST",
         label: "mail draft",
         timeoutMs: WRITE_DEADLINE_MS,
-        body: composedMessageBody(command, body.text),
+        body: message.body,
     });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
     const draft = answer.body.draft;
+    // Report only what the door's receipt shows (BLI-12661), never what was posted.
+    const unconfirmed = unconfirmedAttachments(message.receipt, draft?.attachments, "draft");
+    if (unconfirmed)
+        return failAttachmentsUnconfirmed(door, "draft", unconfirmed, draft);
     if (door.json)
-        return emitAgentDoor(door, { ok: true, draft });
+        return emitAgentDoor(door, { ok: true, draft, ...message.receipt.json });
     writeLine(door.io.stdout, `Saved a draft in ${draft?.address ?? "that mailbox"} for ${command.to.join(", ")}. `
         + "Nothing was sent: it is in Drafts for a person to read, edit and send.");
+    if (message.receipt.sentence)
+        writeLine(door.io.stdout, message.receipt.sentence);
     if (command.replyTo) {
         // `threaded` is what Gmail answered, not what was asked: a reply is only
         // filed in its conversation when the subject still matches the original's.

package/dist/commands/mail.js

@@ -25,7 +25,7 @@
 import { writeFile } from "node:fs/promises";
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
-import { composedMessageBody, readMailBody, runMailDraft } from "./mail-compose.js";
+import { composeMessage, failAttachmentsUnconfirmed, readMailBody, runMailDraft, unconfirmedAttachments, } from "./mail-compose.js";
 import { cacheAgeLabel, readThroughCache } from "./read-cache.js";
 import { towerRequest } from "../tower-client.js";
 const TAG = "[mail cli]";
@@ -259,19 +259,29 @@ async function send(command, door) {
     if (body.text.trim() === "") {
         return failAgentDoor(door, TAG, "body_required", 'A message needs a body: `echo "on my way" | cockpit mail send --account <id> --to someone@example.com --subject "Re: lunch"`.');
     }
+    // The files named with --attach are read and refused HERE, by name, before any request.
+    const message = await composeMessage(command, door, body.text);
+    if (!message.ok)
+        return failAgentDoor(door, TAG, message.reason, message.detail);
     const answer = await askAgentDoor(door, {
         path: "/api/mail/send",
         method: "POST",
         label: "mail send",
         timeoutMs: WRITE_DEADLINE_MS,
-        body: composedMessageBody(command, body.text),
+        body: message.body,
     });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
     const sent = answer.body.sent;
+    // Report only what the door's receipt shows (BLI-12661), never what was posted.
+    const unconfirmed = unconfirmedAttachments(message.receipt, sent?.attachments, "send");
+    if (unconfirmed)
+        return failAttachmentsUnconfirmed(door, "send", unconfirmed, sent);
     if (door.json)
-        return emitAgentDoor(door, { ok: true, sent });
+        return emitAgentDoor(door, { ok: true, sent, ...message.receipt.json });
     writeLine(door.io.stdout, `Sent from ${sent?.address ?? "that mailbox"} to ${command.to.join(", ")}${sent?.threaded ? " (as a reply)" : ""}.`);
+    if (message.receipt.sentence)
+        writeLine(door.io.stdout, message.receipt.sentence);
     return 0;
 }
 async function attachment(command, door) {

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.167");
+    writeLine(io?.stdout ?? process.stdout, "0.2.170");
     return 0;
   }
 

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;
+}

package/dist/commands/sync.js

@@ -11,7 +11,7 @@
  *   collect behind both locks         sync-receipt.ts
  *   check in with the heartbeat door  sync-heartbeat.ts
  *   say how the tick went             reportTickOutcome / reportTickThrew
- *   converge the rest of the machine  sync-followups.ts
+ *   converge the rest of the machine  sync-followups.ts, sync-heal.ts
  *
  * The supporting modules each own one thing those steps share:
  *
@@ -39,13 +39,18 @@ import { createInteractiveExecRunner } from "../process-runner.js";
 import { envWithNodeRuntimeOnPath } from "../scheduled-self-update.js";
 import { runMemoryExperienceAfterSync } from "./memory-log.js";
 import { classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
+import { runMachineHealAfterSync } from "./sync-heal.js";
 import { sendSyncHeartbeat } from "./sync-heartbeat.js";
 import { runSyncWithHealthReceipt } from "./sync-receipt.js";
 import { runAutostartSelfHealAfterSync, runMemoryInstallAfterSync, runScheduledSelfUpdateAfterSync, runStagingPruneAfterSync, } from "./sync-followups.js";
 import { rotateCollectorLogsBestEffort } from "../log-rotation.js";
+import { stampSyncTick } from "../sync-tick-stamp.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
 export async function runSync(command, io) {
     const paths = getCollectorRuntimePaths(command.homeDir);
+    // Ticket 12831: the memory prompt hook reads this stamp to tell a scheduler
+    // that stopped firing from one that is merely quiet.
+    await stampSyncTick(paths);
     // BLI-3553, first thing in the tick: cap the scheduler's own logs. Nothing
     // rotated them before, and two months of a 15-minute tick left 211 MB of
     // sync.log on the reference Mac. Best-effort by construction — a rotation
@@ -165,5 +170,8 @@ async function reportTickThrew(command, io, dashboardUrl, error, errorCode) {
 async function convergeAfterTick(command, io, dashboardUrl) {
     await runAutostartSelfHealAfterSync(command, io, dashboardUrl);
     await runMemoryInstallAfterSync(command, io, dashboardUrl);
+    // BLI-12828: the repairs `cockpit doctor` also makes (agent rules, a lapsed
+    // sign-in), so nobody has to be told to run it.
+    await runMachineHealAfterSync(command, io, dashboardUrl);
     await runMemoryExperienceAfterSync({ ...command, dashboardUrl }, io);
 }

package/dist/sign-in-action.js

@@ -0,0 +1,7 @@
+/**
+ * The ONE sentence a person gets when only a browser can fix their sign-in
+ * (BLI-12828). Doctor's `authed` row, doctor's exit-code receipt and the sync
+ * tick's once-a-day note all say these exact words, so nobody is told two
+ * different things for the same problem.
+ */
+export const SIGN_IN_ACTION = "Run `cockpit login` and approve the sign-in in your browser.";

package/dist/sync-tick-stamp.js

@@ -0,0 +1,22 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { SYNC_TICK_STAMP_FILE_NAME } from "@bli-cockpit/telemetry-core";
+/**
+ * Ticket 12831. Touched first thing in every `cockpit sync`, so "when did this
+ * machine last tick" is one file stat. The memory prompt hook reads it
+ * (`@bli-cockpit/memory-mcp` `hooks/sync-revive.ts`) and revives a scheduler
+ * that stopped firing. Best-effort: a stamp that cannot be written says so and
+ * never fails the tick (the worst case is one extra hourly revive attempt).
+ */
+export async function stampSyncTick(paths, now = new Date()) {
+    try {
+        await fs.mkdir(paths.state_dir, { recursive: true, mode: 0o700 });
+        await fs.writeFile(path.join(paths.state_dir, SYNC_TICK_STAMP_FILE_NAME), now.toISOString());
+    }
+    catch (error) {
+        console.error("[sync-tick-stamp] tick stamp not written; the prompt hook may attempt a revive", JSON.stringify({
+            reason: "tick_stamp_write_failed",
+            error_name: error instanceof Error ? error.name : typeof error,
+        }));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.167",
+  "version": "0.2.170",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,9 +27,9 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.mjs && node ../../scripts/assert-public-cli-surface-doors.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-exit-contract.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-cli-doctor-json.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/memory-mcp": "0.1.45",
-    "@bli-cockpit/mcp": "0.1.85",
-    "@bli-cockpit/telemetry-core": "0.1.57"
+    "@bli-cockpit/memory-mcp": "0.1.46",
+    "@bli-cockpit/mcp": "0.1.87",
+    "@bli-cockpit/telemetry-core": "0.1.58"
   },
   "repository": {
     "type": "git",