@bli-cockpit/cli 0.2.1 → 0.2.3

package/README.md

@@ -45,12 +45,12 @@ 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
-recovery and maintenance.
+On a blank Mac, `npm i -g @bli-cockpit/cli && cockpit do-everything` is enough to sign in, choose roots, and converge the machine. `onboard` remains the named setup subset, and 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 a Mac from blank or already-onboarded state: latest CLI, signed-in device token, saved roots, autostart, historical backfill, raw-evidence GC, and fresh sync. Interactive first runs prompt for email OTP and collection roots; headless/`--json` runs explain and exit instead of blocking. `--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. |
@@ -82,12 +82,15 @@ cockpit onboard --no-auth
 
 - `--email` skips the email prompt.
 - `--workspace` pins one collection root; repeat it for multiple unrelated roots.
-- `--allow-home-root` deliberately collects your whole home folder. Use it only on a company machine where that is intended.
+- Interactive onboarding from your home folder asks whether to sync all projects on the machine. Answer `y` only on a company machine where collecting every current and future repo under `$HOME` is intended. `n` or Enter asks for the actual work folder; if no valid non-home folder is chosen, Cockpit captures nothing and tells you to rerun with `--workspace <path-to-your-work-folder>`.
+- `--allow-home-root` is the headless/scripted form of that full-home opt-in.
 - `--device-name` changes only the human label shown in Cockpit.
 - `--dashboard-url` is for staging/custom dashboards only. Production is the default.
 - `--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. On an interactive first run it uses the same email OTP login and root-picker flow as onboarding, then re-checks the machine. In headless, launchd, `--json`, or no-TTY runs it never prompts; missing auth or roots stay red with the repair text. `--dry-run` previews without writing auth or config.
+
 `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,546 @@
+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 (command.dryRun && invariant.fix) {
+            rows.push(dryRunPreview(checked));
+            continue;
+        }
+        const canFix = Boolean(invariant.fix) &&
+            (!invariant.requiresInteractiveFix || isInteractiveDoctorFix(context));
+        if (!canFix) {
+            rows.push(checked.hardStop ? checked : { ...checked, status: "needs_fix" });
+            if (checked.hardStop)
+                break;
+            continue;
+        }
+        if (!invariant.fix) {
+            rows.push(checked.hardStop ? checked : { ...checked, status: "needs_fix" });
+            if (checked.hardStop)
+                break;
+            continue;
+        }
+        const fixed = await invariant.fix(context, checked);
+        rows.push({ ...fixed, fixed: fixed.status !== "fail" });
+        if (fixed.hardStop)
+            break;
+        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),
+            fix: fixAuthState,
+            requiresInteractiveFix: true,
+        },
+        {
+            id: "roots-ok",
+            check: (context) => context.deps.readRoots(context),
+            fix: fixRootState,
+            requiresInteractiveFix: true,
+        },
+        {
+            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,
+        runLogin: (context) => hooks.runLogin(context.command, context.io),
+        readRoots: readRootState,
+        resolveAndSaveRoots: (context) => hooks.resolveAndSaveRoots(context.command, context.io),
+        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 fixAuthState(context, state) {
+    const code = await context.deps.runLogin(context).catch(() => 1);
+    if (code !== 0)
+        return state;
+    const checked = await context.deps.readAuth(context);
+    return checked.status === "ok" ? checked : state;
+}
+async function fixRootState(context, state) {
+    await context.deps.resolveAndSaveRoots(context).catch(() => undefined);
+    const checked = await context.deps.readRoots(context);
+    return checked.status === "ok" ? checked : state;
+}
+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 };
+}
+function dryRunPreview(state) {
+    const preview = { ...state };
+    delete preview.hardStop;
+    return {
+        ...preview,
+        status: "needs_fix",
+        message: `would fix: ${oneLine(state.message)}`,
+    };
+}
+function isInteractiveDoctorFix(context) {
+    return !context.command.json && Boolean(context.io.stdin.isTTY);
+}
+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,13 @@ 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,
+                    runLogin: runDoctorLogin,
+                    resolveAndSaveRoots: resolveAndSaveDoctorRoots,
+                });
             case "login":
                 return await runLogin(command, io);
             case "logout":
@@ -94,6 +104,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 +168,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 +389,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 +427,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 +652,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);
@@ -1003,6 +1055,64 @@ function backgroundSyncLine(result) {
     }
     return result.status;
 }
+async function resolveOnboardingRootsForCommand(command, io) {
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const existingConfig = await readLocalCollectorConfig(paths).catch(() => null);
+    const interactive = !command.json && isInteractiveStdin(io);
+    const rootsResult = await resolveOnboardingRoots({
+        homeDir: command.homeDir,
+        explicitRoots: command.collectionRoots ?? (command.repoRoot ? [command.repoRoot] : []),
+        config: existingConfig,
+        interactive,
+        allowHomeRoot: command.allowHomeRoot,
+        prompt: interactive ? onboardingRootPrompt(io) : undefined,
+    });
+    const collectionRoots = rootsResult.roots;
+    const primaryRoot = collectionRoots[0];
+    if (!primaryRoot) {
+        throw new Error(`${COLLECTION_ROOT_REQUIRED}: no collection root confirmed.`);
+    }
+    const replaceRepoRoots = rootsResult.source === "prompt" &&
+        !command.collectionRoots?.length &&
+        (existingConfig?.default_repo_paths.length ?? 0) > 0;
+    return {
+        existingConfig,
+        rootsResult,
+        collectionRoots,
+        primaryRoot,
+        replaceRepoRoots,
+    };
+}
+async function persistOnboardingRootConfig(command, resolution) {
+    return installLocalCollector({
+        homeDir: command.homeDir,
+        repoRoot: resolution.primaryRoot,
+        repoRoots: resolution.collectionRoots,
+        replaceRepoRoots: resolution.replaceRepoRoots,
+        dashboardUrl: command.dashboardUrl,
+        deviceName: command.deviceName,
+    });
+}
+async function runDoctorLogin(command, io) {
+    return runLogin({
+        kind: "login",
+        dashboardUrl: command.dashboardUrl,
+        json: command.json,
+        noAuth: false,
+    }, io);
+}
+async function resolveAndSaveDoctorRoots(command, io) {
+    const rootCommand = {
+        repoRoot: command.repoRoot,
+        dashboardUrl: command.dashboardUrl,
+        json: command.json,
+    };
+    const resolution = await resolveOnboardingRootsForCommand(rootCommand, io);
+    await persistOnboardingRootConfig(rootCommand, resolution);
+    if (!command.json) {
+        writeLine(io.stdout, `Saved collection roots: ${resolution.collectionRoots.join(", ")}`);
+    }
+}
 async function runOnboard(command, io) {
     const installEvents = [];
     const finish = async (code) => {
@@ -1030,31 +1140,17 @@ async function runOnboard(command, io) {
             writeLine(io.stdout, `Dashboard: ${command.dashboardUrl}`);
             writeLine(io.stdout, `Ticket: ${command.activeTicketId ?? "general ambient"}`);
         }
-        const paths = getCollectorRuntimePaths(command.homeDir);
         backfillHint = await onboardBackfillHint(command.homeDir);
-        const existingConfig = await readLocalCollectorConfig(paths).catch(() => null);
-        const interactive = !command.json && isInteractiveStdin(io);
-        rootsResult = await resolveOnboardingRoots({
-            homeDir: command.homeDir,
-            explicitRoots: command.collectionRoots ?? (command.repoRoot ? [command.repoRoot] : []),
-            config: existingConfig,
-            interactive,
-            allowHomeRoot: command.allowHomeRoot,
-            prompt: interactive ? onboardingRootPrompt(io) : undefined,
-        });
+        const resolvedRoots = await resolveOnboardingRootsForCommand(command, io);
+        const existingConfig = resolvedRoots.existingConfig;
+        rootsResult = resolvedRoots.rootsResult;
         const collectionRoots = rootsResult.roots;
-        const primaryRoot = collectionRoots[0];
-        if (!primaryRoot) {
-            throw new Error(`${COLLECTION_ROOT_REQUIRED}: no collection root confirmed.`);
-        }
+        const primaryRoot = resolvedRoots.primaryRoot;
         const resolvedCommand = {
             ...command,
             repoRoot: primaryRoot,
             collectionRoots,
         };
-        const replaceRepoRoots = rootsResult.source === "prompt" &&
-            !command.collectionRoots?.length &&
-            (existingConfig?.default_repo_paths.length ?? 0) > 0;
         if (!command.json) {
             writeLine(io.stdout, `Collecting from: ${collectionRoots.join(", ")}`);
         }
@@ -1062,14 +1158,7 @@ async function runOnboard(command, io) {
             addInstallEvent(installEvents, "home_root_optin", "ok");
         }
         const claimedOwnerEmail = await resolveOnboardEmail(resolvedCommand, collectionRoots, existingConfig, io);
-        install = await installLocalCollector({
-            homeDir: command.homeDir,
-            repoRoot: primaryRoot,
-            repoRoots: collectionRoots,
-            replaceRepoRoots,
-            dashboardUrl: command.dashboardUrl,
-            deviceName: command.deviceName,
-        });
+        install = await persistOnboardingRootConfig(command, resolvedRoots);
         addInstallEvent(installEvents, "install", "ok");
         if (!command.json) {
             writeLine(io.stdout, "1/5 Installed local collector.");

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/dist/onboarding-roots.js

@@ -1,10 +1,15 @@
 import fs from "node:fs/promises";
+import { realpathSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { discoverGitWorktrees } from "./repo-identity.js";
 import { normalizeCollectionRoots } from "./root-normalization.js";
 export const COLLECTION_ROOT_REQUIRED = "collection_root_required";
-export const HOME_ROOT_CONSENT_PROMPT = "Collect your ENTIRE home folder? Any git repo you ever create under it will be collected automatically. Type 'everything' to confirm: ";
+export function homeRootConsentPrompt(homeDirInput) {
+    const homeDir = path.resolve(homeDirInput ?? os.homedir());
+    return `You're in your home folder (${homeDir}).\n  Sync ALL projects on this machine? Every git repo under here gets captured now and in the future.\n  This is a work machine — exclude personal projects yourself if needed.  [y/N]: `;
+}
+export const HOME_ROOT_DECLINE_PATH_PROMPT = "Okay — which folder should I sync? Enter the full path to your work directory: ";
+export const HOME_ROOT_NO_FOLDER_CHOSEN_MESSAGE = "No folder chosen. Re-run: cockpit onboard --workspace <path-to-your-work-folder>";
 export async function resolveOnboardingRoots(options) {
     const explicitInput = options.explicitRoots ?? [];
     const explicit = normalizeRootsDetailed(explicitInput, {
@@ -19,10 +24,7 @@ export async function resolveOnboardingRoots(options) {
         if (!options.interactive) {
             throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${rootRejectionExplanation(explicit.rejected[0], options)}`);
         }
-        explainRejectedRoots(options, explicit.rejected);
-        const homeOffer = await counterOfferHomeDirectoryRepos(options, explicit.rejected);
-        if (homeOffer)
-            return homeOffer;
+        explainRejectedRoots(options, withoutHomeRejections(explicit.rejected));
         const homeOptIn = await promptForHomeRootOptIn(options, explicit.rejected);
         if (homeOptIn)
             return homeOptIn;
@@ -45,10 +47,24 @@ export async function resolveOnboardingRoots(options) {
         }
         return promptForRoots(options, "Collection root(s), comma-separated: ");
     }
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    if (isHomeRoot(cwd, options.homeDir)) {
+        const homeDir = path.resolve(options.homeDir ?? os.homedir());
+        if (options.allowHomeRoot) {
+            return resolvedRoots(options, [homeDir], "cwd_likely_root", true);
+        }
+        if (!options.interactive) {
+            throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${homeRootTutorial(homeDir)}`);
+        }
+        const homeOptIn = await promptForHomeRootOptIn(options, [
+            { input: homeDir, reason: "home_dir" },
+        ]);
+        if (homeOptIn)
+            return homeOptIn;
+    }
     if (!options.interactive) {
         throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${missingCollectionRootMessage(options)}`);
     }
-    const cwd = path.resolve(options.cwd ?? process.cwd());
     const cwdRoot = likelyBliRootFromCwd(cwd);
     if (cwdRoot) {
         const confirmed = await requirePrompt(options).confirm(`Collect from ${cwdRoot}? [Y/n] `);
@@ -115,10 +131,7 @@ async function promptForRoots(options, message) {
             return resolvedRoots(options, detailed.roots, "prompt", true);
         }
         if (detailed.rejected.length > 0) {
-            explainRejectedRoots(options, detailed.rejected);
-            const homeOffer = await counterOfferHomeDirectoryRepos(options, detailed.rejected);
-            if (homeOffer)
-                return homeOffer;
+            explainRejectedRoots(options, withoutHomeRejections(detailed.rejected));
             const homeOptIn = await promptForHomeRootOptIn(options, detailed.rejected);
             if (homeOptIn)
                 return homeOptIn;
@@ -164,6 +177,9 @@ export function rootRejectionExplanation(rejection, options = {}) {
             return filesystemRootTutorial(options.homeDir);
     }
 }
+function withoutHomeRejections(rejections) {
+    return rejections.filter((rejection) => rejection.reason !== "home_dir");
+}
 function rootRejectionPromptHint(rejection, options = {}) {
     switch (rejection.reason) {
         case "home_dir":
@@ -172,45 +188,63 @@ function rootRejectionPromptHint(rejection, options = {}) {
             return filesystemRootTutorial(options.homeDir);
     }
 }
-async function counterOfferHomeDirectoryRepos(options, rejections) {
-    const homeRejection = rejections.find((rejection) => rejection.reason === "home_dir");
-    if (!homeRejection)
-        return null;
-    const prompt = requirePrompt(options);
-    const homeDir = path.resolve(options.homeDir ?? os.homedir());
-    const discover = options.discoverGitWorktrees ?? discoverGitWorktrees;
-    const worktrees = await discover(homeDir, {
-        maxDepth: 3,
-        maxWorktrees: 50,
-    }).catch(() => []);
-    const roots = normalizeCollectionRoots([...new Set(worktrees.map((worktree) => path.resolve(worktree.repo_root)))]);
-    if (roots.length === 0)
-        return null;
-    const confirmed = await prompt.confirm([
-        "Your home folder can't be a collection root by default:",
-        `  I found ${roots.length} git repos under ${homeDir} that are safer to collect.`,
-        "Discovered repos:",
-        ...roots.map((root) => `- ${root}`),
-        "What you can do:",
-        "  1) Use these repos: answer y",
-        "  2) Pick different folders: answer n, then paste specific paths",
-        "  3) Collect everything anyway: answer n, then type everything at the next prompt",
-        "Collect from these? [Y/n] ",
-    ].join("\n"));
-    return confirmed ? resolvedRoots(options, roots, "prompt", true) : null;
-}
 async function promptForHomeRootOptIn(options, rejections) {
     if (!rejections.some((rejection) => rejection.reason === "home_dir"))
         return null;
-    const answer = await requirePrompt(options).input(HOME_ROOT_CONSENT_PROMPT);
-    if (answer.trim().toLowerCase() !== "everything")
-        return null;
-    return {
-        roots: [path.resolve(options.homeDir ?? os.homedir())],
-        source: "prompt",
-        confirmed: true,
-        homeRootOptIn: true,
-    };
+    const homeDir = path.resolve(options.homeDir ?? os.homedir());
+    const answer = await requirePrompt(options).input(homeRootConsentPrompt(homeDir));
+    if (isHomeRootYes(answer)) {
+        return {
+            roots: [homeDir],
+            source: "prompt",
+            confirmed: true,
+            homeRootOptIn: true,
+        };
+    }
+    return promptForDeclinedHomeRoot(options, homeDir);
+}
+function isHomeRootYes(raw) {
+    const answer = raw.trim().split(/\s+/u)[0]?.toLowerCase() ?? "";
+    return answer === "y" || answer === "yes";
+}
+async function promptForDeclinedHomeRoot(options, homeDir) {
+    const prompt = requirePrompt(options);
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+        const answer = await prompt.input(HOME_ROOT_DECLINE_PATH_PROMPT);
+        const requestedRoot = answer.trim();
+        if (!requestedRoot) {
+            if (attempt < 2)
+                continue;
+            break;
+        }
+        const resolvedRoot = resolveRootInputPath(requestedRoot, homeDir, cwd);
+        if (isHomeRoot(resolvedRoot, homeDir))
+            break;
+        if (!(await directoryExists(resolvedRoot))) {
+            prompt.message?.(`That folder doesn't exist: ${resolvedRoot}`);
+            if (attempt < 2)
+                continue;
+            break;
+        }
+        const detailed = normalizeRootsDetailed([resolvedRoot], {
+            homeDir,
+            allowHomeRoot: options.allowHomeRoot,
+        });
+        if (detailed.roots.length > 0) {
+            return resolvedRoots(options, detailed.roots, "prompt", true);
+        }
+        explainRejectedRoots(options, withoutHomeRejections(detailed.rejected));
+        break;
+    }
+    prompt.message?.(HOME_ROOT_NO_FOLDER_CHOSEN_MESSAGE);
+    throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${HOME_ROOT_NO_FOLDER_CHOSEN_MESSAGE}`);
+}
+function resolveRootInputPath(input, homeDir, cwd) {
+    const expanded = input === "~" || input.startsWith("~/")
+        ? path.join(homeDir, input.slice(2))
+        : input;
+    return path.resolve(cwd, expanded);
 }
 function resolvedRoots(options, roots, source, confirmed) {
     const result = { roots, source, confirmed };
@@ -219,8 +253,21 @@ function resolvedRoots(options, roots, source, confirmed) {
     }
     return result;
 }
+// Canonicalize through realpath so a symlink pointing at $HOME can't slip past
+// the home-root guard on the decline path (e.g. `~/home-link -> /Users/me`).
+// Non-existent paths (or realpath errors) fall back to the lexical resolve so
+// behavior is unchanged for the retry branch and for tests using fake homedirs.
+function canonicalPath(input) {
+    const resolved = path.resolve(input);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
 function isHomeRoot(root, homeDir) {
-    return path.resolve(root) === path.resolve(homeDir ?? os.homedir());
+    return canonicalPath(root) === canonicalPath(homeDir ?? os.homedir());
 }
 function homeRootTutorial(homeDirInput) {
     const homeDir = path.resolve(homeDirInput ?? os.homedir());

package/package.json

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