@bli-cockpit/cli 0.2.53 → 0.2.55

package/dist/commands/doctor-access.js

@@ -0,0 +1,129 @@
+import { describeError } from "../health-detail.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, readLocalCollectorSessionFile, } from "../local-state.js";
+import { normalizeCollectionRoots } from "../root-normalization.js";
+import { detectSecondCockpitInstall } from "../second-install.js";
+import { hardStop, needsFix, ok, skipped } from "./doctor-report.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
+ * automatic fix beyond re-running login/onboarding — a machine cannot repair
+ * its own consent boundary. Single-install has no fix at all (see the
+ * function's own comment); it only names the second install and lets the
+ * operator decide.
+ */
+export async function fixAuthState(context, state) {
+    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
+        // ran and was declined (BLI-3238).
+        console.error("[cockpit-doctor] login repair threw", JSON.stringify({
+            reason: "auth_repair_failed",
+            ...describeError(error),
+        }));
+        return 1;
+    });
+    if (code !== 0)
+        return state;
+    const checked = await context.deps.readAuth(context);
+    return checked.status === "ok" ? checked : state;
+}
+export async function fixRootState(context, state) {
+    await context.deps.resolveAndSaveRoots(context).catch((error) => {
+        // Roots ARE the collection boundary. If saving them throws and nothing
+        // says so, the machine converges to "no approved root" and collects
+        // nothing — a green-looking doctor run over an empty boundary, which is
+        // the failure mode this whole ticket exists for.
+        console.error("[cockpit-doctor] collection roots could not be resolved or saved", JSON.stringify({
+            reason: "roots_repair_failed",
+            ...describeError(error),
+        }));
+    });
+    const checked = await context.deps.readRoots(context);
+    return checked.status === "ok" ? checked : state;
+}
+export async function readAuthState(context) {
+    const paths = getCollectorRuntimePaths();
+    const session = await readLocalCollectorSessionFile(paths).catch(() => null);
+    if (session?.session_state === "valid" &&
+        typeof session.device_token === "string" &&
+        session.device_token) {
+        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"));
+}
+export async function readRootState(context) {
+    const paths = getCollectorRuntimePaths();
+    const config = await readLocalCollectorConfig(paths).catch(() => null);
+    const roots = normalizeCollectionRoots(config?.default_repo_paths ?? []);
+    if (roots.length > 0) {
+        return {
+            ...ok("roots-ok", "saved_roots_present", `saved roots: ${roots.join(", ")}`),
+            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) There is no `--repair` flag; the onboard-rerun is the repair path.",
+    ].join("\n"));
+}
+/**
+ * BLI-3218/BLI-3553. Two Tower installs on one machine make each one's tick
+ * call the other's registration stale and re-register itself, so the plist
+ * flaps every 15 minutes and the device reports two CLI versions the same
+ * morning. Doctor OFFERS the removal and never performs it: an operator may
+ * have a second prefix on purpose, and `npm uninstall -g` of something nobody
+ * asked to remove is not a repair. The row therefore has no `fix` — it is
+ * information, and doctor still exits 0.
+ */
+export async function checkSingleInstallState(context) {
+    const exec = context.io.exec;
+    if (!exec) {
+        return skipped("single-install", "runner_unavailable", "could not look for a second Tower install");
+    }
+    const finding = await detectSecondCockpitInstall({ exec });
+    if (!finding.detected) {
+        return ok("single-install", finding.reason, finding.install_count === 1
+            ? "one Tower install on this machine"
+            : "no second Tower install found");
+    }
+    // The full paths go to the operator's own screen; redactedHealthDetail
+    // masks them again before any of this is uploaded.
+    return needsFix("single-install", "second_install_detected", [
+        `${finding.install_count} Tower installs are on this machine's PATH:`,
+        ...finding.paths.map((entry) => `  - ${entry}`),
+        "Both will fight over the background scheduler, re-registering it against each other.",
+        "Keep one. To remove the other:",
+        `  npm uninstall -g @bli-cockpit/cli   # run it with the node that owns ${finding.other_bin ?? "the other bin"}`,
+        "Nothing was uninstalled — that is your call.",
+    ].join("\n"));
+}
+export async function doctorRoots(context) {
+    if (context.command.repoRoot)
+        return [context.command.repoRoot];
+    return savedRoots();
+}
+export async function savedRoots() {
+    const config = await readLocalCollectorConfig(getCollectorRuntimePaths()).catch(() => null);
+    return normalizeCollectionRoots(config?.default_repo_paths ?? []);
+}
+function onboardOneLiner(command) {
+    const workspace = command.repoRoot ?? "$PWD";
+    const dashboard = command.dashboardUrl === DEFAULT_DASHBOARD_URL
+        ? ""
+        : ` --dashboard-url ${shellQuote(command.dashboardUrl)}`;
+    return `cockpit onboard --workspace ${shellQuote(workspace)}${dashboard}`;
+}
+function shellQuote(value) {
+    if (value === "$PWD")
+        return '"$PWD"';
+    return `'${value.replace(/'/gu, "'\\''")}'`;
+}

package/dist/commands/doctor-pipeline.js

@@ -0,0 +1,326 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { inspectBackfillLock } from "../backfill-lock.js";
+import { backfillCompletionCovers, readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
+import { savedDiscoveryLimitArgs } from "../discovery-limits.js";
+import { describeError } from "../health-detail.js";
+import { runStagingPrune } from "../disk-prune.js";
+import { retentionOptionsFromEnv } from "../disk-retention.js";
+import { readDiskFootprint } from "../disk-usage.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths } from "../local-state.js";
+import { runRawEvidenceLocalGc, rawEvidenceGcSummary } from "../raw-evidence-gc.js";
+import { runBackfillCommand } from "./backfill.js";
+import { doctorRoots } from "./doctor-access.js";
+import { asRecord, fail, needsFix, ok, skipped } from "./doctor-report.js";
+/**
+ * The `backfill-complete`, `gc-checked`, `disk-bounded`, and `sync-fresh`
+ * check family: does the collection pipeline itself have everything it
+ * should. These four run in that order because each answers a question the
+ * one before it cannot — GC only removes a whole pack once every file in it
+ * is committed, disk-bounded reads per-file against the upload ledger
+ * (BLI-3619), and sync-fresh is the one check whose "fix" is a live proof
+ * (`cockpit sync`) rather than a local computation.
+ */
+const GC_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Pure so it can be unit-tested without touching the real machine's home
+ * directory (`getCollectorRuntimePaths()` defaults to `os.homedir()` and
+ * doctor never threads `--home` through the backfill steps). Returns `null`
+ * when the marker does not cover the roots/sources — the caller falls
+ * through to the lock/never-run diagnosis in that case.
+ *
+ * BLI-2727: a marker whose only outstanding entries are deterministic
+ * oversized-file skips is still a completed backfill — it reads green with a
+ * named note, never a red `needs_fix`/`fail`, so an unliftable file cap never
+ * reads as "backfill never completed" on repeat doctor runs.
+ */
+export function backfillCompletionStepState(marker, roots) {
+    if (!backfillCompletionCovers(marker, roots, ["codex", "claude_code"])) {
+        return null;
+    }
+    const oversized = marker?.oversized_skips;
+    if (oversized && oversized.count > 0) {
+        return ok("backfill-complete", "complete_with_oversized_skips", `caught up on old Codex and Claude sessions in every saved folder ` +
+            `(complete_with_oversized_skips · ${oversized.count} file${oversized.count === 1 ? "" : "s"} too big to upload)`);
+    }
+    return ok("backfill-complete", "complete", "caught up on old Codex and Claude sessions in every saved folder");
+}
+export async function checkBackfillState(context) {
+    const paths = getCollectorRuntimePaths();
+    const roots = await doctorRoots(context);
+    const marker = await readBackfillCompletionMarker(paths);
+    const covered = backfillCompletionStepState(marker, roots);
+    if (covered)
+        return covered;
+    const lock = await inspectBackfillLock(paths);
+    if (lock.held) {
+        return needsFix("backfill-complete", "backfill_already_running", `another catch-up run is still going, and this one has not finished yet (running since ${lock.held_since ?? "unknown"})`);
+    }
+    const cursor = await readBackfillCursor(paths);
+    return needsFix("backfill-complete", cursor.updated_at ? "partial" : "never_run", "the catch-up over your old sessions has not finished");
+}
+export async function fixBackfillState(context) {
+    const capture = capturedIo(context.io, !context.command.json);
+    const code = await runBackfillCommand({
+        repoRoot: context.command.repoRoot,
+        all: true,
+        dryRun: false,
+        yes: true,
+        json: true,
+    }, capture.io);
+    const output = capture.stdout() + "\n" + capture.stderr();
+    if (code === 0) {
+        // Re-read the marker this run just wrote instead of hand-rolling a second
+        // message: `checkBackfillState`'s pure core already knows how to say
+        // "complete" vs "complete_with_oversized_skips" (BLI-2727), and this way
+        // the two can never say something different for the same marker.
+        const recheck = await checkBackfillState(context);
+        if (recheck.status === "ok")
+            return recheck;
+        return ok("backfill-complete", "completed", "ran `cockpit backfill --all --yes`");
+    }
+    const reason = jsonField(output, "failure_reason");
+    if (reason === "backfill_already_running") {
+        return fail("backfill-complete", "backfill_already_running", "backfill lock is still held and no scope-valid completion marker exists");
+    }
+    return fail("backfill-complete", reason ?? "backfill_failed", "backfill did not complete");
+}
+export async function checkGcState(context) {
+    if (context.io.env["COCKPIT_DISABLE_GC"] === "1") {
+        return skipped("gc-checked", "skipped_disabled", "cleanup is switched off");
+    }
+    const paths = getCollectorRuntimePaths();
+    const marker = path.join(paths.state_dir, ".last-raw-evidence-gc");
+    const info = await fs.stat(marker).catch(() => null);
+    if (info && Date.now() - info.mtimeMs < GC_MIN_INTERVAL_MS) {
+        return skipped("gc-checked", "skipped_throttled", "cleanup already ran today");
+    }
+    return needsFix("gc-checked", "due", "cleanup is due");
+}
+export async function fixGcState(context) {
+    const result = await runRawEvidenceLocalGc(getCollectorRuntimePaths(), context.io.env);
+    if (result.skipped) {
+        return skipped("gc-checked", "skipped_throttled", "cleanup already ran today");
+    }
+    if (result.removed_dirs === 0) {
+        return ok("gc-checked", "nothing_eligible", rawEvidenceGcSummary(result));
+    }
+    return ok("gc-checked", `removed_${result.removed_dirs}`, rawEvidenceGcSummary(result));
+}
+/**
+ * BLI-3619: what Cockpit is holding on this machine, in one line.
+ *
+ * Green means the staging tree fits under the cap. Over the cap is `needs_fix`
+ * and the fix is the same prune the tick runs, forced past its daily throttle;
+ * if it is still over afterwards, the message names the one command that goes
+ * further. Every number here is metadata — byte counts and file counts, never
+ * a path.
+ */
+export async function checkDiskState(context) {
+    const footprint = await readDiskFootprint(getCollectorRuntimePaths(context.command.homeDir));
+    const { capBytes } = retentionOptionsFromEnv(context.io.env);
+    const message = diskRowMessage(footprint, capBytes);
+    return footprint.staging.total_bytes > capBytes
+        ? needsFix("disk-bounded", "over_staging_cap", message)
+        : ok("disk-bounded", "within_staging_cap", message);
+}
+export async function fixDiskState(context) {
+    const paths = getCollectorRuntimePaths(context.command.homeDir);
+    const pruned = await runStagingPrune(paths, {
+        env: context.io.env,
+        force: true,
+    });
+    if (pruned.status === "fail") {
+        return fail("disk-bounded", pruned.reason, "the prune could not run; nothing was deleted");
+    }
+    if (pruned.status === "skipped") {
+        return skipped("disk-bounded", pruned.reason, "cleanup is switched off");
+    }
+    const footprint = await readDiskFootprint(paths);
+    const message = diskRowMessage(footprint, pruned.cap_bytes);
+    if (!pruned.cap_blocked_by_uncommitted) {
+        return ok("disk-bounded", `freed_${pruned.deleted_files}`, `freed ${mib(pruned.deleted_bytes)} MB; ${message}`);
+    }
+    // Deliberately still `ok`: staging over the cap because evidence has not been
+    // accepted yet is the collector working, not a machine to repair. The row
+    // names the blockage and the one command that goes further.
+    return ok("disk-bounded", "staging_cap_blocked_by_uncommitted", `freed ${mib(pruned.deleted_bytes)} MB; ${message}; ${pruned.cap_blocked_count} object(s) the upload ledger cannot vouch for are holding the rest — run \`cockpit sync\` to deliver them, or \`cockpit clean --all-committed\` to drop every accepted copy now`);
+}
+function diskRowMessage(footprint, capBytes) {
+    const staging = footprint.staging;
+    const parts = [
+        `staging ${mib(staging.total_bytes)} MB (${mib(staging.committed_bytes)} committed / ${mib(staging.uncommitted_bytes)} uncommitted / ${mib(staging.unknown_bytes)} unknown) against a ${mib(capBytes)} MB cap`,
+    ];
+    // BLI-3619's second half: "unknown" means the local ledger's own capped
+    // memory cannot say, never that delivery failed — and the one command that
+    // actually answers it is named right here, not left for a person to find.
+    if (staging.unknown_count > 0) {
+        parts.push(`${staging.unknown_count} object(s) unknown to this laptop's own ledger — run \`cockpit clean --reconcile\` to ask the server`);
+    }
+    parts.push(`logs ${mib(footprint.logs.total_bytes)} MB`, `spool ${mib(footprint.spool_bytes)} MB`);
+    for (const vault of footprint.vaults) {
+        parts.push(`${vault.name} ${mib(vault.byte_size)} MB (a one-off; \`cockpit clean --all-committed\` removes it only if every file in it is accepted)`);
+    }
+    return parts.join("; ");
+}
+function mib(bytes) {
+    return (bytes / (1024 * 1024)).toFixed(1);
+}
+function capturedIo(io, forward) {
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    return {
+        io: {
+            ...io,
+            stdout: captureStream(io.stdout, stdoutChunks, forward),
+            stderr: captureStream(io.stderr, stderrChunks, forward),
+        },
+        stdout: () => stdoutChunks.join(""),
+        stderr: () => stderrChunks.join(""),
+    };
+}
+function captureStream(target, chunks, forward) {
+    return {
+        write(chunk, encoding, callback) {
+            const text = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
+            chunks.push(text);
+            if (forward) {
+                if (typeof encoding === "function") {
+                    target.write(chunk, encoding);
+                }
+                else {
+                    target.write(chunk, encoding, callback);
+                }
+            }
+            else if (typeof encoding === "function") {
+                encoding();
+            }
+            else {
+                callback?.();
+            }
+            return true;
+        },
+    };
+}
+function jsonField(output, field) {
+    const escaped = field.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const match = output.match(new RegExp(`"${escaped}"\\s*:\\s*"([^"]+)"`, "u"));
+    return match?.[1] ?? null;
+}
+export async function checkSyncState(context) {
+    const roots = await doctorRoots(context);
+    if (roots.length === 0) {
+        return needsFix("sync-fresh", "no_roots", "sync has no saved workspace roots");
+    }
+    // Upload state is currently device-global, so it cannot prove that every
+    // saved root succeeded. Doctor therefore performs one explicit sync per root
+    // and only turns green from those command receipts.
+    return needsFix("sync-fresh", "per_root_verification_required", `fresh upload proof is required for ${roots.length} saved root${roots.length === 1 ? "" : "s"}`);
+}
+/**
+ * `cockpit sync --json` prints exactly one JSON document to stdout (stderr is
+ * for human text; see AGENTS.md logging conventions), so this is a real parse
+ * rather than the doctor module's usual regex field-scrape — which cannot
+ * disambiguate same-named fields nested under `codex_sessions.codex` vs
+ * `codex_sessions.claude` (BLI-2728).
+ */
+function parseDoctorSyncJson(stdout) {
+    try {
+        const parsed = JSON.parse(stdout.trim());
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch (error) {
+        // `null` sends doctor back to its regex field-scrape, quietly losing the
+        // BLI-2728 disambiguation. Something wrote to stdout that was not the one
+        // JSON document the contract promises — a stray console.log in the
+        // collector would do exactly this and look like nothing at all.
+        console.error("[cockpit-doctor] sync --json stdout was not one JSON document", JSON.stringify({
+            reason: "sync_json_unparseable",
+            byte_size: stdout.length,
+            ...describeError(error),
+        }));
+        return null;
+    }
+}
+/**
+ * BLI-2728: a tick that only deferred objects past the per-tick raw-evidence
+ * object budget (`RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET`, adapters/raw-evidence.ts)
+ * is a backlog that is draining, not a failure — `attributedSyncRunStatus`
+ * marks the run not-fully-`ok` (so `cockpit sync` exits non-zero and doctor's
+ * exec sees `code !== 0`) purely because objects remain queued, with the
+ * per-repo upload itself still having succeeded. A genuine failure (auth,
+ * server rejection, network, a real upload_failed outcome, an unposted
+ * session report) must still read red — this only fires when NOTHING else in
+ * the tick's own summary looks wrong. Pure so it is unit-testable without a
+ * live exec/fs harness; the remaining-object count is read straight from the
+ * tick's own summary, never recomputed.
+ */
+export function syncBacklogDrainingVerdict(parsed) {
+    if (!parsed)
+        return null;
+    const deferredObjects = positiveNumberOrZero(parsed.raw_evidence_deferred_object_budget);
+    if (deferredObjects <= 0)
+        return null;
+    const deferredBytes = positiveNumberOrZero(parsed.raw_evidence_deferred_byte_budget);
+    const failedCount = positiveNumberOrZero(parsed.raw_evidence_failed_count);
+    const retryReasons = Array.isArray(parsed.raw_evidence_retry_reasons)
+        ? parsed.raw_evidence_retry_reasons.length
+        : 0;
+    const sessions = asRecord(parsed.codex_sessions);
+    const reportPosted = sessions?.["report_posted"];
+    const codexReadFailures = positiveNumberOrZero(asRecord(sessions?.["codex"])?.["read_failures"]);
+    const claudeSessions = asRecord(sessions?.["claude"]);
+    const claudeReadFailures = positiveNumberOrZero(claudeSessions?.["read_failures"]);
+    const claudeSidecarsFailed = positiveNumberOrZero(claudeSessions?.["sidecars_failed"]);
+    const onlyDeferredObjectBudget = deferredBytes === 0 &&
+        failedCount === 0 &&
+        retryReasons === 0 &&
+        reportPosted === true &&
+        codexReadFailures === 0 &&
+        claudeReadFailures === 0 &&
+        claudeSidecarsFailed === 0;
+    return onlyDeferredObjectBudget ? { remainingObjects: deferredObjects } : null;
+}
+function positiveNumberOrZero(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? value
+        : 0;
+}
+export async function fixSyncState(context) {
+    const exec = context.io.exec;
+    if (!exec)
+        return fail("sync-fresh", "runner_unavailable", "sync runner unavailable");
+    const roots = await doctorRoots(context);
+    if (roots.length === 0) {
+        return fail("sync-fresh", "no_roots", "sync has no saved workspace roots");
+    }
+    // The remembered limits have to ride along, or the doctor's own verification
+    // sync scans differently from every other run and can fail closed on a
+    // machine the operator already fixed by hand (BLI-2362).
+    const discoveryArgs = await savedDiscoveryLimitArgs(context.command.homeDir);
+    for (const repoRoot of roots) {
+        const args = ["sync", "--json", "--workspace", repoRoot, ...discoveryArgs];
+        if (context.command.dashboardUrl !== DEFAULT_DASHBOARD_URL) {
+            args.push("--dashboard-url", context.command.dashboardUrl);
+        }
+        const result = await exec("cockpit", args);
+        const parsed = parseDoctorSyncJson(result.stdout);
+        const output = `${result.stdout}\n${result.stderr}`;
+        const status = jsonField(output, "status");
+        if (result.code !== 0) {
+            const draining = syncBacklogDrainingVerdict(parsed);
+            if (draining) {
+                return needsFix("sync-fresh", "backlog_draining", `${repoRoot}: still catching up (${draining.remainingObjects} ` +
+                    `file${draining.remainingObjects === 1 ? "" : "s"} left for later this run); ` +
+                    "rerun `cockpit sync` to continue");
+            }
+            return fail("sync-fresh", status ?? "sync_failed", `sync failed for ${repoRoot}`);
+        }
+        if (status !== "uploaded") {
+            return fail("sync-fresh", status ?? "sync_unverified", `sync did not return an uploaded receipt for ${repoRoot}`);
+        }
+    }
+    return ok("sync-fresh", "synced", roots.length === 1
+        ? "ran `cockpit sync` and received an uploaded receipt"
+        : `received uploaded receipts for ${roots.length} saved roots`);
+}

package/dist/commands/doctor-registration.js

@@ -0,0 +1,105 @@
+import { autostartStatus, installAutostartAgent, registeredRuntimePathProblems, } from "../autostart.js";
+import { fail, needsFix, ok, skipped } from "./doctor-report.js";
+import { doctorRoots, savedRoots } from "./doctor-access.js";
+import { installMemoryIntegration, inspectMemoryIntegration, } from "./memory-install.js";
+/**
+ * The `autostart-alive` and `memory-registered` check family: registrations
+ * this machine should carry with nobody having to ask for them — the
+ * background sync scheduler and BLI Memory's MCP/hook wiring. Both fixes
+ * write host configuration only; neither installs software.
+ */
+export async function checkAutostartState(context) {
+    const exec = context.io.exec;
+    if (!exec) {
+        return needsFix("autostart-alive", "runner_unavailable", "autostart runner unavailable; would refresh autostart");
+    }
+    const roots = await doctorRoots(context);
+    const result = await autostartStatus({
+        repoRoot: roots[0],
+        repoRoots: roots,
+        dashboardUrl: context.command.dashboardUrl,
+        exec,
+    });
+    if (result.status === "loaded") {
+        // BLI-3553: "loaded" only means the scheduler accepted the registration.
+        // It says nothing about whether the binary that registration names still
+        // exists — and `brew upgrade node` deletes exactly that. Ask the
+        // filesystem about the paths the PLATFORM holds, not the ones this process
+        // happens to be running under.
+        const missing = await registeredRuntimePathProblems({ exec });
+        if (missing.length > 0) {
+            return needsFix("autostart-alive", "runtime_path_missing", `background sync is registered but cannot run: ${missing.join("; ")}`);
+        }
+        return ok("autostart-alive", "already_installed", "background sync is running");
+    }
+    if (result.status === "unsupported") {
+        return skipped("autostart-alive", "unsupported", result.message ?? "unsupported");
+    }
+    return needsFix("autostart-alive", result.status === "not_loaded" ? "not_loaded" : "absent", "background sync is not running");
+}
+export async function fixAutostartState(context) {
+    const exec = context.io.exec;
+    if (!exec) {
+        return fail("autostart-alive", "runner_unavailable", "autostart runner unavailable");
+    }
+    const roots = await savedRoots();
+    const result = await installAutostartAgent({
+        repoRoot: context.command.repoRoot ?? roots[0],
+        repoRoots: context.command.repoRoot ? [context.command.repoRoot] : roots,
+        dashboardUrl: context.command.dashboardUrl,
+        exec,
+    });
+    if (result.status === "unsupported") {
+        return skipped("autostart-alive", "unsupported", result.message ?? "unsupported");
+    }
+    if (result.loaded === false) {
+        return fail("autostart-alive", "autostart_load_failed", result.message ?? "operating-system scheduler load failed");
+    }
+    return ok("autostart-alive", "installed", "background sync installed and running");
+}
+/**
+ * BLI Memory's registration on this machine (BLI-3580).
+ *
+ * The step owns the CONFIG, never the software: it writes the MCP entry, the
+ * hooks and the Codex table only when `bli-memory-mcp` actually resolves. With
+ * no server it writes NOTHING and reads `skipped bin_missing` — registering
+ * hooks that point at an absent binary would make every Claude Code turn print
+ * a hook failure, which is worse than waiting a day.
+ */
+export async function checkMemoryState(context) {
+    const outcome = await inspectMemoryIntegration(memoryCommandFor(context), context.io);
+    return memoryStepState(outcome, "check");
+}
+export async function fixMemoryState(context) {
+    const outcome = await installMemoryIntegration(memoryCommandFor(context), context.io);
+    return memoryStepState(outcome, "fix");
+}
+function memoryCommandFor(context) {
+    return {
+        kind: "memory",
+        action: "install",
+        homeDir: context.command.homeDir,
+        dashboardUrl: context.command.dashboardUrl,
+        dryRun: false,
+        json: context.command.json,
+    };
+}
+function memoryStepState(outcome, phase) {
+    const broken = outcome.targets.filter((target) => target.target !== "bin" && target.status === "failed");
+    if (broken.length > 0) {
+        const first = broken[0];
+        const message = `${first?.target ?? "memory"}: ${first?.reason ?? "failed"}`;
+        return phase === "fix"
+            ? fail("memory-registered", first?.reason ?? "memory_install_failed", message)
+            : needsFix("memory-registered", first?.reason ?? "memory_install_failed", message);
+    }
+    const pending = outcome.targets.filter((target) => target.target !== "bin" &&
+        (target.status === "missing" || target.status === "mismatch"));
+    if (pending.length > 0) {
+        return needsFix("memory-registered", "registration_incomplete", `BLI Memory is not registered with ${pending.map((target) => target.target).join(", ")}`);
+    }
+    if (!outcome.bin_found) {
+        return skipped("memory-registered", "bin_missing", "bli-memory-mcp is not on this machine yet; nothing was written and the next run will try again");
+    }
+    return ok("memory-registered", phase === "fix" ? "installed" : "already_installed", "BLI Memory is registered with both agent hosts");
+}

package/dist/commands/doctor-report.js

@@ -0,0 +1,111 @@
+import { redactedHealthDetail } from "../health-detail.js";
+export function ok(id, code, message) {
+    return { id, status: "ok", code, message };
+}
+export function skipped(id, code, message) {
+    return { id, status: "skipped", code, message };
+}
+export function needsFix(id, code, message) {
+    return { id, status: "needs_fix", code, message };
+}
+export function fail(id, code, message) {
+    return { id, status: "fail", code, message };
+}
+export function hardStop(id, code, message) {
+    return { id, status: "fail", code, message, hardStop: true };
+}
+export function dryRunPreview(state) {
+    const preview = { ...state };
+    delete preview.hardStop;
+    return {
+        ...preview,
+        status: "needs_fix",
+        message: `would fix: ${oneLine(state.message)}`,
+    };
+}
+export function isInteractiveDoctorFix(context) {
+    return !context.command.json && Boolean(context.io.stdin.isTTY);
+}
+export async function maybeReportDoctorEvents(context, rows) {
+    if (context.command.dryRun)
+        return;
+    await context.deps.reportInstallEvents({
+        dashboardUrl: context.command.dashboardUrl,
+        command: "doctor",
+        events: rows.map(doctorEvent),
+        json: context.command.json,
+        io: context.io,
+    });
+}
+export function writeDoctorOutput(command, io, rows) {
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            status: rows.some((row) => row.status === "fail" || row.hardStop)
+                ? "blocked"
+                : "pass",
+            dry_run: command.dryRun,
+            steps: rows,
+        }, null, 2));
+        return;
+    }
+    writeLine(io.stdout, command.dryRun ? "Tower doctor dry-run" : "Tower doctor");
+    // The machine `code` stays in `--json`; a human reading the table wants the
+    // sentence, not the label (BLI-3194).
+    writeLine(io.stdout, "state step                 result");
+    for (const row of rows) {
+        writeLine(io.stdout, `${doctorMark(row)} ${row.id.padEnd(20)} ${oneLine(row.message)}`);
+    }
+    const explanations = rows.filter((row) => (row.hardStop || row.status === "fail") && row.message.includes("\n"));
+    for (const row of explanations) {
+        writeLine(io.stderr, "");
+        writeLine(io.stderr, `${row.id}:`);
+        writeLine(io.stderr, row.message);
+    }
+}
+function doctorEvent(row) {
+    const status = row.status === "fail" || row.hardStop
+        ? "fail"
+        : row.status === "skipped"
+            ? "skipped"
+            : "ok";
+    if (status === "ok")
+        return { step: row.id, status };
+    // BLI-2542. The step already computed why it failed and already printed it to
+    // the operator; before this, only the bucket travelled. `autostart-alive`
+    // reports two distinct problems at once on Windows, so the detail carries the
+    // whole message rather than a first line.
+    const detail = redactedHealthDetail(row.message);
+    return {
+        step: row.id,
+        status,
+        error_code: sanitizeEventCode(row.code),
+        // A detail that only repeats the bucket is noise, not a reason.
+        ...(detail && detail !== sanitizeEventCode(row.code)
+            ? { error_detail: detail }
+            : {}),
+    };
+}
+function doctorMark(row) {
+    if (row.status === "fail" || row.hardStop)
+        return "❌";
+    if (row.status === "needs_fix" || row.fixed)
+        return "🔧";
+    return "✅";
+}
+export function sanitizeEventCode(value) {
+    return (value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/gu, "_")
+        .replace(/^_+|_+$/gu, "")
+        .slice(0, 120) || "unknown");
+}
+export function oneLine(value) {
+    return value.split("\n")[0] ?? value;
+}
+export function asRecord(value) {
+    return value && typeof value === "object" ? value : null;
+}
+export function writeLine(stream, text) {
+    stream.write(`${text}\n`);
+}