@bli-cockpit/cli 0.2.54 → 0.2.55

package/dist/commands/doctor.js

@@ -1,21 +1,8 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { autostartStatus, installAutostartAgent, registeredRuntimePathProblems, } from "../autostart.js";
-import { savedDiscoveryLimitArgs } from "../discovery-limits.js";
-import { describeError, redactedHealthDetail } from "../health-detail.js";
-import { inspectBackfillLock } from "../backfill-lock.js";
-import { backfillCompletionCovers, readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
-import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, readLocalCollectorSessionFile, } from "../local-state.js";
-import { normalizeCollectionRoots } from "../root-normalization.js";
-import { detectSecondCockpitInstall } from "../second-install.js";
-import { runRawEvidenceLocalGc, rawEvidenceGcSummary } from "../raw-evidence-gc.js";
-import { runStagingPrune } from "../disk-prune.js";
-import { retentionOptionsFromEnv } from "../disk-retention.js";
-import { readDiskFootprint } from "../disk-usage.js";
-import { runBackfillCommand } from "./backfill.js";
-import { installMemoryIntegration, inspectMemoryIntegration, } from "./memory-install.js";
-import { createInteractiveExecRunner } from "../process-runner.js";
-const GC_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
+import { checkSingleInstallState, fixAuthState, fixRootState, readAuthState, readRootState, } from "./doctor-access.js";
+import { backfillCompletionStepState, checkBackfillState, checkDiskState, checkGcState, checkSyncState, fixBackfillState, fixDiskState, fixGcState, fixSyncState, syncBacklogDrainingVerdict, } from "./doctor-pipeline.js";
+import { checkAutostartState, checkMemoryState, fixAutostartState, fixMemoryState, } from "./doctor-registration.js";
+import { dryRunPreview, isInteractiveDoctorFix, maybeReportDoctorEvents, writeDoctorOutput, } from "./doctor-report.js";
+import { checkCliLatest, fixCliLatest, latestCliVersionFromNpm, reexecDoctor, } from "./doctor-update.js";
 export async function runDoctor(command, io, hooks, overrides = {}) {
     const deps = { ...defaultDoctorDeps(hooks), ...overrides };
     return runDoctorWithDeps(command, io, deps);
@@ -144,738 +131,6 @@ function defaultDoctorDeps(hooks) {
         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,
-            tag: context.command.updateTag,
-        });
-    }
-    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((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;
-}
-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;
-}
-async function latestCliVersionFromNpm(context) {
-    const exec = context.io.exec;
-    if (!exec)
-        return null;
-    const packageSpec = context.command.updateTag
-        ? `@bli-cockpit/cli@${context.command.updateTag}`
-        : "@bli-cockpit/cli";
-    const result = await exec("npm", ["view", packageSpec, "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", "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"));
-}
-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.
- */
-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"));
-}
-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");
-}
-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.
- */
-async function checkMemoryState(context) {
-    const outcome = await inspectMemoryIntegration(memoryCommandFor(context), context.io);
-    return memoryStepState(outcome, "check");
-}
-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");
-}
-/**
- * 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");
-}
-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");
-}
-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");
-}
-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");
-}
-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.
- */
-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);
-}
-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);
-}
-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;
-}
-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`);
-}
-async function doctorRoots(context) {
-    if (context.command.repoRoot)
-        return [context.command.repoRoot];
-    return savedRoots();
-}
-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 ? "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 "✅";
-}
-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 ?? []);
-}
-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 {
-        // Deliberately silent (BLI-3238). `npm view ... version` prints a bare
-        // `1.2.3` without `--json` and a quoted `"1.2.3"` with it; the parse is
-        // the test for which one this npm produced, and the unquoted fallback is
-        // the intended handling of the other form, not a failure.
-        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.updateTag)
-        args.push("--update-tag", command.updateTag);
-    if (command.json)
-        args.push("--json");
-    const exec = io.interactiveExec ?? createInteractiveExecRunner();
-    return exec("cockpit", args, {
-        env: {
-            ...process.env,
-            ...io.env,
-            COCKPIT_DOCTOR_REEXEC: "1",
-        },
-    }).then((result) => result.code);
-}
-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; Tower 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`);
-}
+// Re-exported so every consumer keeps importing from `./doctor.js` regardless
+// of which sibling a symbol now lives in.
+export { backfillCompletionStepState, syncBacklogDrainingVerdict };