@bli-cockpit/cli 0.2.1 → 0.2.2

package/README.md

@@ -45,12 +45,13 @@ The OTP proves you own an approved BLI mailbox. The JWT is used once to register
 
 ## Every command, what it does, and why it's called that
 
-You only need three commands (`onboard`, `status`, and `backfill` once). The rest exist for
+You only need `onboard` once and `do-everything` whenever Edward asks the fleet to converge. The rest exist for
 recovery and maintenance.
 
 | Command | What it does | Why it exists / why this name |
 |---|---|---|
 | `cockpit onboard` | The everything-command: signs you in (email code), registers this Mac, starts capture, uploads once, installs the 15-min background sync, and prints proof you're live. | You are boarding the crew. Run it once per machine; rerunning is always safe. |
+| `cockpit do-everything` / `cockpit fix` | Converges an already-onboarded Mac: latest CLI, signed-in device token, saved roots, autostart, historical backfill, raw-evidence GC, and fresh sync. `--dry-run` previews without writing. | Edward can post one line and every intern machine should end green. `fix` is the alias people guess. |
 | `cockpit status` | Prints install / sign-in / capture / upload health in one screen. | The "is it working?" command. Run it whenever you're unsure. |
 | `cockpit backfill --all` | Uploads your HISTORICAL Codex + Claude sessions (from before Cockpit existed on this Mac). | One-time catch-up so your past work counts too. "Backfill" = fill in the back-catalog. |
 | `cockpit sync` | Captures and uploads once, right now. This is what the background agent runs every 15 min — you almost never type it yourself. | Named for what it does: synchronize local session files up to the dashboard. |
@@ -88,6 +89,8 @@ cockpit onboard --no-auth
 - `--no-auth` forces the old manual approval queue.
 - `--repo` still works as a legacy alias for `--workspace`.
 
+`cockpit do-everything` is the normal fleet convergence command after onboarding. It exits non-zero only when a checked invariant remains red after its fix runs, or when a human action such as login/onboard-rerun is required.
+
 `cockpit update` installs the latest public CLI and reruns onboarding checks against saved roots. `cockpit upgrade` is the same command.
 
 ## Parent Mode

package/dist/commands/doctor.js

@@ -0,0 +1,502 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { autostartStatus, installAutostartAgent } from "../autostart.js";
+import { inspectBackfillLock } from "../backfill-lock.js";
+import { backfillCompletionMarkerPath, readBackfillCursor, } from "../cursors/backfill-cursor.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, inspectLocalCollectorStatus, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, readLocalCollectorSessionFile, } from "../local-state.js";
+import { normalizeCollectionRoots } from "../root-normalization.js";
+import { runRawEvidenceLocalGc, rawEvidenceGcSummary } from "../raw-evidence-gc.js";
+import { runBackfillCommand } from "./backfill.js";
+const GC_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export async function runDoctor(command, io, hooks, overrides = {}) {
+    const deps = { ...defaultDoctorDeps(hooks), ...overrides };
+    return runDoctorWithDeps(command, io, deps);
+}
+export async function runDoctorWithDeps(command, io, deps) {
+    const context = { command, io, deps };
+    const rows = [];
+    for (const invariant of doctorInvariants()) {
+        const checked = await invariant.check(context);
+        if (checked.status === "ok" || checked.status === "skipped") {
+            rows.push(checked);
+            continue;
+        }
+        if (checked.hardStop) {
+            rows.push(checked);
+            break;
+        }
+        if (command.dryRun || !invariant.fix) {
+            rows.push({
+                ...checked,
+                status: "needs_fix",
+                message: `would fix: ${checked.message}`,
+            });
+            continue;
+        }
+        const fixed = await invariant.fix(context, checked);
+        rows.push({ ...fixed, fixed: fixed.status !== "fail" });
+        if (fixed.reexecExitCode !== undefined) {
+            await maybeReportDoctorEvents(context, rows);
+            writeDoctorOutput(command, io, rows);
+            return fixed.reexecExitCode;
+        }
+    }
+    await maybeReportDoctorEvents(context, rows);
+    writeDoctorOutput(command, io, rows);
+    return rows.some((row) => row.status === "fail" || row.hardStop) ? 1 : 0;
+}
+function doctorInvariants() {
+    return [
+        { id: "cli-latest", check: checkCliLatest, fix: fixCliLatest },
+        { id: "authed", check: (context) => context.deps.readAuth(context) },
+        { id: "roots-ok", check: (context) => context.deps.readRoots(context) },
+        {
+            id: "autostart-alive",
+            check: (context) => context.deps.checkAutostart(context),
+            fix: (context, _state) => context.deps.fixAutostart(context),
+        },
+        {
+            id: "backfill-complete",
+            check: (context) => context.deps.checkBackfill(context),
+            fix: (context, _state) => context.deps.fixBackfill(context),
+        },
+        {
+            id: "gc-checked",
+            check: (context) => context.deps.checkGc(context),
+            fix: (context, _state) => context.deps.fixGc(context),
+        },
+        {
+            id: "sync-fresh",
+            check: (context) => context.deps.checkSync(context),
+            fix: (context, _state) => context.deps.fixSync(context),
+        },
+    ];
+}
+function defaultDoctorDeps(hooks) {
+    return {
+        latestCliVersion: latestCliVersionFromNpm,
+        selfUpdate: hooks.selfUpdate,
+        reexecDoctor: reexecDoctor,
+        reportInstallEvents: hooks.reportInstallEvents,
+        readAuth: readAuthState,
+        readRoots: readRootState,
+        checkAutostart: checkAutostartState,
+        fixAutostart: fixAutostartState,
+        checkBackfill: checkBackfillState,
+        fixBackfill: fixBackfillState,
+        checkGc: checkGcState,
+        fixGc: fixGcState,
+        checkSync: checkSyncState,
+        fixSync: fixSyncState,
+    };
+}
+async function checkCliLatest(context) {
+    const latest = await context.deps.latestCliVersion(context);
+    if (!latest) {
+        return needsFix("cli-latest", "latest_version_unknown", `could not confirm npm latest; will run npm install for ${LOCAL_COLLECTOR_VERSION}`);
+    }
+    if (latest === LOCAL_COLLECTOR_VERSION) {
+        return ok("cli-latest", "already_latest", `current ${LOCAL_COLLECTOR_VERSION}`);
+    }
+    return needsFix("cli-latest", "stale_cli", `current ${LOCAL_COLLECTOR_VERSION}; npm latest ${latest}`);
+}
+async function fixCliLatest(context, state) {
+    try {
+        await context.deps.selfUpdate(context.io, { json: context.command.json });
+    }
+    catch (error) {
+        return fail("cli-latest", selfUpdateFailureCode(error), selfUpdateFailureMessage(error));
+    }
+    if (context.io.env["COCKPIT_DOCTOR_REEXEC"] === "1") {
+        if (state.code === "stale_cli") {
+            return fail("cli-latest", "stale_after_self_update", "self-update ran but this process still reports the old CLI version; rerun `cockpit do-everything`.");
+        }
+        return ok("cli-latest", "updated_reexec_guarded", "self-update ran; re-exec guard already set, continuing.");
+    }
+    const code = await context.deps.reexecDoctor(context.command, context.io);
+    return {
+        ...ok("cli-latest", "reexeced", "self-update ran; re-execed the new cockpit binary."),
+        reexecExitCode: code,
+    };
+}
+async function latestCliVersionFromNpm(context) {
+    const exec = context.io.exec;
+    if (!exec)
+        return null;
+    const result = await exec("npm", ["view", "@bli-cockpit/cli", "version", "--json"]);
+    if (result.code !== 0)
+        return null;
+    return parseNpmVersion(result.stdout);
+}
+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", "device token present");
+    }
+    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"));
+}
+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"));
+}
+async function checkAutostartState(context) {
+    const exec = context.io.exec;
+    if (!exec) {
+        return needsFix("autostart-alive", "runner_unavailable", "launchd runner unavailable; would refresh autostart");
+    }
+    const result = await autostartStatus({ exec });
+    if (result.status === "loaded") {
+        return ok("autostart-alive", "already_installed", "launchd agent loaded");
+    }
+    if (result.status === "unsupported") {
+        return skipped("autostart-alive", "unsupported", result.message ?? "unsupported");
+    }
+    return needsFix("autostart-alive", result.status === "not_loaded" ? "not_loaded" : "absent", "autostart is not loaded");
+}
+async function fixAutostartState(context) {
+    const exec = context.io.exec;
+    if (!exec) {
+        return fail("autostart-alive", "runner_unavailable", "launchd 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 ?? "launchctl load failed");
+    }
+    return ok("autostart-alive", "installed", "autostart installed and loaded");
+}
+async function checkBackfillState(_context) {
+    const paths = getCollectorRuntimePaths();
+    if (await hasBackfillCompletionMarker(paths)) {
+        return ok("backfill-complete", "complete", "backfill completion marker exists");
+    }
+    const lock = await inspectBackfillLock(paths);
+    if (lock.held) {
+        return skipped("backfill-complete", "backfill_already_running", `backfill already running since ${lock.held_since ?? "unknown"}`);
+    }
+    const cursor = await readBackfillCursor(paths);
+    return needsFix("backfill-complete", cursor.updated_at ? "partial" : "never_run", "backfill completion marker missing");
+}
+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) {
+        return ok("backfill-complete", "completed", "ran `cockpit backfill --all --yes`");
+    }
+    const reason = jsonField(output, "failure_reason");
+    if (reason === "backfill_already_running") {
+        return skipped("backfill-complete", "backfill_already_running", "backfill lock held; skipping as healthy");
+    }
+    return fail("backfill-complete", reason ?? "backfill_failed", "backfill did not complete");
+}
+async function checkGcState(context) {
+    if (context.io.env["COCKPIT_DISABLE_GC"] === "1") {
+        return skipped("gc-checked", "skipped_disabled", "raw-evidence GC disabled");
+    }
+    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", "raw-evidence GC ran within 24h");
+    }
+    return needsFix("gc-checked", "due", "raw-evidence GC is due");
+}
+async function fixGcState(context) {
+    const result = await runRawEvidenceLocalGc(getCollectorRuntimePaths(), context.io.env);
+    if (result.skipped) {
+        return skipped("gc-checked", "skipped_throttled", "raw-evidence GC skipped");
+    }
+    if (result.removed_dirs === 0) {
+        return ok("gc-checked", "nothing_eligible", rawEvidenceGcSummary(result));
+    }
+    return ok("gc-checked", `removed_${result.removed_dirs}`, rawEvidenceGcSummary(result));
+}
+async function checkSyncState(context) {
+    const status = await inspectLocalCollectorStatus({
+        repoRoot: context.command.repoRoot,
+    }).catch(() => null);
+    if (status?.collector_freshness === "fresh") {
+        return ok("sync-fresh", "fresh", "last sync is fresh");
+    }
+    return needsFix("sync-fresh", "stale", "last sync is stale or missing");
+}
+async function fixSyncState(context) {
+    const exec = context.io.exec;
+    if (!exec)
+        return fail("sync-fresh", "runner_unavailable", "sync runner unavailable");
+    const args = ["sync", "--json"];
+    if (context.command.repoRoot)
+        args.push("--workspace", context.command.repoRoot);
+    if (context.command.dashboardUrl !== DEFAULT_DASHBOARD_URL) {
+        args.push("--dashboard-url", context.command.dashboardUrl);
+    }
+    const result = await exec("cockpit", args);
+    const output = `${result.stdout}\n${result.stderr}`;
+    const status = jsonField(output, "status");
+    if (result.code === 0 &&
+        (status === "sync_already_running" ||
+            status === "live_sync_paused_during_backfill")) {
+        return skipped("sync-fresh", status, "sync already running; skipping as healthy");
+    }
+    if (result.code === 0) {
+        return ok("sync-fresh", "synced", "ran `cockpit sync`");
+    }
+    return fail("sync-fresh", status ?? "sync_failed", "sync failed");
+}
+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,
+    });
+}
+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 ? "Cockpit doctor dry-run" : "Cockpit doctor");
+    writeLine(io.stdout, "state step                 code                    result");
+    for (const row of rows) {
+        writeLine(io.stdout, `${doctorMark(row)} ${row.id.padEnd(20)} ${row.code.padEnd(23)} ${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";
+    return {
+        step: row.id,
+        status,
+        ...(status === "ok" ? {} : { error_code: sanitizeEventCode(row.code) }),
+    };
+}
+function doctorMark(row) {
+    if (row.status === "fail" || row.hardStop)
+        return "❌";
+    if (row.status === "needs_fix" || row.fixed)
+        return "🔧";
+    return "✅";
+}
+function ok(id, code, message) {
+    return { id, status: "ok", code, message };
+}
+function skipped(id, code, message) {
+    return { id, status: "skipped", code, message };
+}
+function needsFix(id, code, message) {
+    return { id, status: "needs_fix", code, message };
+}
+function fail(id, code, message) {
+    return { id, status: "fail", code, message };
+}
+function hardStop(id, code, message) {
+    return { id, status: "fail", code, message, hardStop: true };
+}
+async function savedRoots() {
+    const config = await readLocalCollectorConfig(getCollectorRuntimePaths()).catch(() => null);
+    return normalizeCollectionRoots(config?.default_repo_paths ?? []);
+}
+async function hasBackfillCompletionMarker(paths) {
+    try {
+        const raw = JSON.parse(await fs.readFile(backfillCompletionMarkerPath(paths), "utf8"));
+        return (raw.schema_version === "cockpit-backfill-complete.v1" &&
+            typeof raw.completed_at === "string");
+    }
+    catch {
+        return false;
+    }
+}
+function parseNpmVersion(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return typeof parsed === "string" && parsed.trim() ? parsed.trim() : null;
+    }
+    catch {
+        return trimmed.replace(/^"|"$/gu, "") || null;
+    }
+}
+function reexecDoctor(command, io) {
+    const args = ["do-everything"];
+    if (command.repoRoot)
+        args.push("--workspace", command.repoRoot);
+    if (command.dashboardUrl !== DEFAULT_DASHBOARD_URL) {
+        args.push("--dashboard-url", command.dashboardUrl);
+    }
+    if (command.json)
+        args.push("--json");
+    return new Promise((resolve) => {
+        const child = spawn("cockpit", args, {
+            stdio: "inherit",
+            env: {
+                ...process.env,
+                ...io.env,
+                COCKPIT_DOCTOR_REEXEC: "1",
+            },
+        });
+        child.on("error", () => resolve(1));
+        child.on("close", (code) => resolve(code ?? 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;
+}
+function selfUpdateFailureCode(error) {
+    const record = asRecord(error);
+    if (record && record["eacces"] === true)
+        return "eacces_needs_chown";
+    return "npm_install_failed";
+}
+function selfUpdateFailureMessage(error) {
+    const record = asRecord(error);
+    const stderr = asRecord(record?.["result"])?.["stderr"] &&
+        typeof asRecord(record?.["result"])?.["stderr"] === "string"
+        ? String(asRecord(record?.["result"])?.["stderr"])
+        : "";
+    if (record?.["eacces"] === true) {
+        const prefix = npmPrefixFromError(stderr);
+        return [
+            "npm global install hit a permissions problem.",
+            "What you can do:",
+            `  1) Fix npm ownership once: sudo chown -R $(whoami) ${prefix}/lib/node_modules/@bli-cockpit ${prefix}/bin/cockpit`,
+            "  2) No sudo? Send this output to Edward.",
+            "  3) Do not use `sudo npm i -g`; it makes the ownership problem come back.",
+        ].join("\n");
+    }
+    return "npm install failed; Cockpit CLI was not refreshed.";
+}
+function npmPrefixFromError(stderr) {
+    if (stderr.includes("/usr/local/"))
+        return "/usr/local";
+    if (stderr.includes("/opt/homebrew/"))
+        return "/opt/homebrew";
+    const nvm = stderr.match(/(\/Users\/[^/\s]+\/\.nvm\/versions\/node\/[^/\s]+)/u);
+    return nvm?.[1] ?? "/opt/homebrew";
+}
+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, "'\\''")}'`;
+}
+function sanitizeEventCode(value) {
+    return (value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/gu, "_")
+        .replace(/^_+|_+$/gu, "")
+        .slice(0, 120) || "unknown");
+}
+function oneLine(value) {
+    return value.split("\n")[0] ?? value;
+}
+function asRecord(value) {
+    return value && typeof value === "object" ? value : null;
+}
+function writeLine(stream, text) {
+    stream.write(`${text}\n`);
+}

package/dist/commands/local-args.js

@@ -15,6 +15,9 @@ export function parseLocalArgs(argv) {
         case "update":
         case "upgrade":
             return parseUpdateArgs(command, argv.slice(1));
+        case "do-everything":
+        case "fix":
+            return parseDoctorArgs(command, argv.slice(1));
         case "install":
             return parseInstallArgs(argv.slice(1));
         case "login":
@@ -108,6 +111,21 @@ function parseUpdateArgs(alias, args) {
         ...parseOnboardLikeArgs(args, alias),
     };
 }
+function parseDoctorArgs(alias, args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--workspace", "--dashboard-url", "--dry-run", "--json"],
+        valueFlags: ["--workspace", "--dashboard-url"],
+    });
+    assertNoPositionals(values.positionals, alias);
+    return {
+        kind: "doctor",
+        alias,
+        repoRoot: optionalNonEmpty(values.flags.get("--workspace")),
+        dashboardUrl: normalizeUrl(values.flags.get("--dashboard-url") ?? DEFAULT_DASHBOARD_URL),
+        dryRun: values.booleans.has("--dry-run"),
+        json: values.booleans.has("--json"),
+    };
+}
 function parseInstallArgs(args) {
     const values = parseNamedArgs(args, {
         allowedFlags: [

package/dist/commands/local.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { createCollectorServer } from "../server.js";
 import { inspectAgentRules, installAgentRules, uninstallAgentRules, } from "../agent-rules.js";
 import { runBackfillCommand } from "./backfill.js";
+import { runDoctor } from "./doctor.js";
 import { inspectBackfillLock } from "../backfill-lock.js";
 import { parseLocalArgs, normalizeUrl } from "./local-args.js";
 import { autostartStatus, installAutostartAgent, uninstallAutostartAgent, } from "../autostart.js";
@@ -21,6 +22,8 @@ export const rootCommandNames = new Set([
     "onboard",
     "update",
     "upgrade",
+    "do-everything",
+    "fix",
     "install",
     "login",
     "pair",
@@ -58,6 +61,11 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runOnboard(command, io);
             case "update":
                 return await runUpdate(command, io);
+            case "doctor":
+                return await runDoctor(command, io, {
+                    reportInstallEvents: reportInstallEventsBestEffort,
+                    selfUpdate: runSelfUpdate,
+                });
             case "login":
                 return await runLogin(command, io);
             case "logout":
@@ -94,6 +102,8 @@ export function localCommandHelp(command) {
         "  cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--branch <name>] [--no-auth] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit update [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--no-auth] [--json]",
         "  cockpit upgrade [same flags as update]",
+        "  cockpit do-everything [--workspace <path>] [--dashboard-url <url>] [--dry-run] [--json]",
+        "  cockpit fix [same flags as do-everything]",
         "  cockpit install [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--json]",
         "  cockpit login [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
         "  cockpit pair [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
@@ -156,6 +166,24 @@ function localSubcommandHelp(command) {
                 "Alias for `cockpit update`.",
             ],
         ],
+        [
+            "do-everything",
+            [
+                "Usage: cockpit do-everything [--workspace <path>] [--dashboard-url <url>] [--dry-run] [--json]",
+                "",
+                "Converges an already-onboarded intern machine: latest CLI, auth, saved roots, autostart, backfill, raw-evidence GC, and sync freshness.",
+                "`cockpit fix` is an alias.",
+                "--dry-run prints the checks and would-fix steps without writing config, plists, cursors, or install telemetry.",
+            ],
+        ],
+        [
+            "fix",
+            [
+                "Usage: cockpit fix [same flags as cockpit do-everything]",
+                "",
+                "Alias for `cockpit do-everything`.",
+            ],
+        ],
         [
             "login",
             [
@@ -359,37 +387,31 @@ async function runUpdate(command, io) {
         return code;
     };
     const exec = io.exec ?? defaultExec();
-    const installArgs = [
-        "install",
-        "-g",
-        "@bli-cockpit/cli@latest",
-        "--prefer-online",
-    ];
-    if (!command.json) {
-        writeLine(io.stdout, "Updating Cockpit CLI from npm...");
+    try {
+        await runSelfUpdate(io, { json: command.json });
     }
-    const install = await exec("npm", installArgs);
-    writeExecOutput(io, install, { stdout: !command.json, stderr: true });
-    if (install.code !== 0) {
-        addInstallEvent(installEvents, "npm_install", "fail", isNpmEaccesFailure(install.stderr)
+    catch (error) {
+        if (!(error instanceof SelfUpdateError))
+            throw error;
+        addInstallEvent(installEvents, "npm_install", "fail", error.eacces
             ? "npm_install_eacces"
             : "npm_install_failed");
         if (command.json) {
             writeLine(io.stdout, JSON.stringify({
                 status: "blocked",
                 step: "npm_install",
-                command: `npm ${installArgs.join(" ")}`,
-                exit_code: install.code,
+                command: `npm ${SELF_UPDATE_INSTALL_ARGS.join(" ")}`,
+                exit_code: error.result.code,
             }, null, 2));
         }
         else {
             writeLine(io.stderr, "BLOCKED: npm install failed; Cockpit CLI was not refreshed.");
-            if (isNpmEaccesFailure(install.stderr)) {
+            if (error.eacces) {
                 writeLine(io.stderr, "Fix Homebrew npm ownership once: sudo chown -R $(whoami) /opt/homebrew/lib/node_modules/@bli-cockpit /opt/homebrew/bin/cockpit");
                 writeLine(io.stderr, "Do not use `sudo npm i -g`; it makes the ownership problem come back.");
             }
         }
-        return finish(install.code || 1);
+        return finish(error.result.code || 1);
     }
     addInstallEvent(installEvents, "npm_install", "ok");
     if (!command.json) {
@@ -403,6 +425,34 @@ async function runUpdate(command, io) {
     addInstallEvent(installEvents, "onboard_rerun", onboard.code === 0 ? "ok" : "fail", onboard.code === 0 ? undefined : updateOnboardFailureCode(onboard));
     return finish(onboard.code);
 }
+const SELF_UPDATE_INSTALL_ARGS = [
+    "install",
+    "-g",
+    "@bli-cockpit/cli@latest",
+    "--prefer-online",
+];
+export class SelfUpdateError extends Error {
+    result;
+    eacces;
+    constructor(result) {
+        super("npm install failed; Cockpit CLI was not refreshed.");
+        this.name = "SelfUpdateError";
+        this.result = result;
+        this.eacces = isNpmEaccesFailure(result.stderr);
+    }
+}
+export async function runSelfUpdate(io, options = {}) {
+    const exec = io.exec ?? defaultExec();
+    if (!options.json) {
+        writeLine(io.stdout, "Updating Cockpit CLI from npm...");
+    }
+    const install = await exec("npm", [...SELF_UPDATE_INSTALL_ARGS]);
+    writeExecOutput(io, install, { stdout: !options.json, stderr: true });
+    if (install.code !== 0) {
+        throw new SelfUpdateError(install);
+    }
+    return { updated: true, version: LOCAL_COLLECTOR_VERSION };
+}
 async function runRelease(command, io) {
     const releaseRoot = await findPublicReleaseRoot(process.cwd());
     if (!releaseRoot) {
@@ -600,7 +650,7 @@ function sanitizeInstallErrorCode(value) {
         .slice(0, 120);
     return normalized || "unknown";
 }
-async function reportInstallEventsBestEffort(options) {
+export async function reportInstallEventsBestEffort(options) {
     if (options.events.length === 0)
         return;
     const paths = getCollectorRuntimePaths(options.homeDir);

package/dist/commands/public-root.js

@@ -23,6 +23,7 @@ function cockpitHelp() {
     localCommandHelp(),
     "",
     "Install: `npm install -g @bli-cockpit/cli@latest`.",
+    "Fix everything: run `cockpit do-everything` to update, verify auth/roots, refresh autostart, backfill, GC, and sync.",
     "Update: run `cockpit update` to refresh the global CLI and rerun onboarding checks.",
     "Intern path: run `cockpit onboard`; it confirms a `/BLI` collection root before syncing.",
     "Headless/reused laptop path: `cockpit onboard --email <email> --workspace ~/BLI`.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "private": false,
   "type": "module",
   "bin": {