@bli-cockpit/cli 0.2.46 → 0.2.48

package/dist/autostart.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths } from "./local-state.js";
 import { savedDiscoveryLimitArgs } from "./discovery-limits.js";
 import { redactedHealthDetail } from "./health-detail.js";
+import { DARWIN_LOGIN_SHELL, resolveStableNodeExecutable, } from "./autostart-node-path.js";
 /** launchd LaunchAgent label; matches docs/runbooks/cockpit-launchd-sync.md. */
 export const AUTOSTART_LABEL = "com.bli.cockpit.sync";
 export const WINDOWS_AUTOSTART_TASK_NAME = "BLI Cockpit Sync";
@@ -37,6 +38,11 @@ export const DEFAULT_AUTOSTART_INTERVAL_SECONDS = 15 * 60;
  */
 export const DARWIN_NETWORK_CHANGE_SIGNAL = "/private/var/run/resolv.conf";
 const UNSUPPORTED_MESSAGE = "autostart is supported on macOS and Windows only";
+/**
+ * What the tick says to sync.err.log when neither the registered node binary
+ * nor a login-shell node exists. Named, actionable, path-free (BLI-3553).
+ */
+export const DARWIN_NODE_MISSING_MESSAGE = "[autostart] tick skipped: reason=node_binary_missing - the registered node binary is gone and no node is on the login PATH; run cockpit doctor to re-register";
 function plistPathFor(homeDir) {
     return path.join(homeDir, "Library", "LaunchAgents", `${AUTOSTART_LABEL}.plist`);
 }
@@ -61,41 +67,8 @@ export async function installAutostartAgent(options) {
         return installWindowsTask(options);
     if (platform !== "darwin")
         return unsupportedResult(options.homeDir);
-    const homeDir = options.homeDir ?? os.homedir();
-    const workDirs = normalizeWorkDirs(options.repoRoots);
-    const workDir = path.resolve(options.repoRoot ?? workDirs[0] ?? process.cwd());
-    const resolvedWorkDirs = workDirs.length > 0 ? workDirs : [workDir];
-    const dashboardUrl = options.dashboardUrl ?? DEFAULT_DASHBOARD_URL;
-    const intervalSeconds = options.intervalSeconds ?? DEFAULT_AUTOSTART_INTERVAL_SECONDS;
-    const nodeExecutable = path.resolve(options.nodeExecutable ?? process.execPath);
-    const cliEntryPoint = path.resolve(options.cliEntryPoint ?? process.argv[1] ?? "");
-    const paths = getCollectorRuntimePaths(homeDir);
-    const plistPath = plistPathFor(homeDir);
-    const stdoutPath = path.join(paths.state_dir, "sync.log");
-    const stderrPath = path.join(paths.state_dir, "sync.err.log");
-    // launchd will not reliably watch a path that does not exist at load time, so
-    // only feed it the transcript dirs that are present right now. A missing dir
-    // is fine — the StartInterval floor still covers it. The network signal is
-    // appended unconditionally: it always exists on the Macs this plist targets,
-    // and an existence filter would drop it when rendering on another host.
-    const watchPaths = [
-        ...(await existingWatchPaths(homeDir)),
-        DARWIN_NETWORK_CHANGE_SIGNAL,
-    ];
-    await mkdir(path.dirname(plistPath), { recursive: true });
-    await mkdir(paths.state_dir, { recursive: true });
-    await writeFile(plistPath, renderPlist({
-        discoveryArgs: await savedDiscoveryLimitArgs(homeDir),
-        workDir,
-        workDirs: resolvedWorkDirs,
-        dashboardUrl,
-        intervalSeconds,
-        nodeExecutable,
-        cliEntryPoint,
-        stdoutPath,
-        stderrPath,
-        watchPaths,
-    }), "utf8");
+    const written = await writeDarwinAutostartPlist(options);
+    const { plist_path: plistPath, work_dir: workDir, work_dirs: resolvedWorkDirs, dashboard_url: dashboardUrl, interval_seconds: intervalSeconds, watch_path_count: watchPathCount, } = written;
     // Unload first so a changed plist is actually picked up; a not-yet-loaded
     // agent makes unload fail harmlessly, so the error is ignored.
     await options.exec("launchctl", ["unload", plistPath]).catch(() => undefined);
@@ -112,7 +85,8 @@ export async function installAutostartAgent(options) {
         console.error("[autostart] launchd agent loaded", JSON.stringify({
             label: AUTOSTART_LABEL,
             interval_seconds: intervalSeconds,
-            watch_path_count: watchPaths.length,
+            watch_path_count: watchPathCount,
+            node_path_reason: written.node_path_reason,
         }));
     }
     else {
@@ -139,6 +113,74 @@ export async function installAutostartAgent(options) {
             }),
     };
 }
+/**
+ * Renders and writes the LaunchAgent plist without touching launchd.
+ *
+ * Split out of `installAutostartAgent` for BLI-3553: the detached macOS healer
+ * (autostart-self-heal.ts) has to write the SAME plist this file writes and
+ * then re-register it with `bootout`/`bootstrap` rather than `unload`/`load`,
+ * and two renderers would be two chances to disagree. One writer, two
+ * registration verbs.
+ */
+export async function writeDarwinAutostartPlist(options) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const workDirs = normalizeWorkDirs(options.repoRoots);
+    const workDir = path.resolve(options.repoRoot ?? workDirs[0] ?? process.cwd());
+    const resolvedWorkDirs = workDirs.length > 0 ? workDirs : [workDir];
+    const dashboardUrl = options.dashboardUrl ?? DEFAULT_DASHBOARD_URL;
+    const intervalSeconds = options.intervalSeconds ?? DEFAULT_AUTOSTART_INTERVAL_SECONDS;
+    const node = await schedulerNodeExecutable(options, "darwin");
+    const cliEntryPoint = path.resolve(options.cliEntryPoint ?? process.argv[1] ?? "");
+    const paths = getCollectorRuntimePaths(homeDir);
+    const plistPath = plistPathFor(homeDir);
+    const stdoutPath = path.join(paths.state_dir, "sync.log");
+    const stderrPath = path.join(paths.state_dir, "sync.err.log");
+    // launchd will not reliably watch a path that does not exist at load time, so
+    // only feed it the transcript dirs that are present right now. A missing dir
+    // is fine — the StartInterval floor still covers it. The network signal is
+    // appended unconditionally: it always exists on the Macs this plist targets,
+    // and an existence filter would drop it when rendering on another host.
+    const watchPaths = [
+        ...(await existingWatchPaths(homeDir)),
+        DARWIN_NETWORK_CHANGE_SIGNAL,
+    ];
+    await mkdir(path.dirname(plistPath), { recursive: true });
+    await mkdir(paths.state_dir, { recursive: true });
+    await writeFile(plistPath, renderPlist({
+        discoveryArgs: await savedDiscoveryLimitArgs(homeDir),
+        workDir,
+        workDirs: resolvedWorkDirs,
+        dashboardUrl,
+        intervalSeconds,
+        nodeExecutable: node.path,
+        cliEntryPoint,
+        stdoutPath,
+        stderrPath,
+        watchPaths,
+    }), "utf8");
+    return {
+        plist_path: plistPath,
+        work_dir: workDir,
+        work_dirs: resolvedWorkDirs,
+        dashboard_url: dashboardUrl,
+        interval_seconds: intervalSeconds,
+        node_executable: node.path,
+        node_path_reason: node.reason,
+        cli_entry_point: cliEntryPoint,
+        watch_path_count: watchPaths.length,
+    };
+}
+/**
+ * The node binary the scheduler should name. BOTH the writer and the read-back
+ * validator go through here — if only the writer pinned the stable alias, every
+ * machine would read "does not match the current Tower runtime" forever, which
+ * is BLI-2541 with a new coat of paint.
+ */
+async function schedulerNodeExecutable(options, platform) {
+    const resolver = platform === "win32" ? path.win32.resolve : path.resolve;
+    const given = resolver(options.nodeExecutable ?? process.execPath);
+    return resolveStableNodeExecutable(given, { platform });
+}
 /**
  * What `launchctl` actually said, or an honest account of it saying nothing.
  *
@@ -198,7 +240,7 @@ export async function autostartStatus(options) {
     const resolvedWorkDirs = workDirs.length > 0 ? workDirs : [workDir];
     const dashboardUrl = options.dashboardUrl ?? DEFAULT_DASHBOARD_URL;
     const intervalSeconds = options.intervalSeconds ?? DEFAULT_AUTOSTART_INTERVAL_SECONDS;
-    const nodeExecutable = path.resolve(options.nodeExecutable ?? process.execPath);
+    const nodeExecutable = (await schedulerNodeExecutable(options, "darwin")).path;
     const cliEntryPoint = path.resolve(options.cliEntryPoint ?? process.argv[1] ?? "");
     const plist = await readFile(plistPath, "utf8").catch(() => "");
     const registrationProblems = darwinAgentRegistrationProblems(plist, {
@@ -238,7 +280,8 @@ async function installWindowsTask(options) {
     const scriptPath = path.join(getCollectorRuntimePaths(homeDir).state_dir, WINDOWS_AUTOSTART_SCRIPT_NAME);
     const registrationPath = path.join(getCollectorRuntimePaths(homeDir).state_dir, WINDOWS_AUTOSTART_REGISTRATION_SCRIPT_NAME);
     const launcherPath = windowsAutostartLauncherPath(homeDir);
-    const nodeExecutable = path.win32.resolve(options.nodeExecutable ?? process.execPath);
+    const node = await schedulerNodeExecutable(options, "win32");
+    const nodeExecutable = node.path;
     const cliEntryPoint = path.win32.resolve(options.cliEntryPoint ?? process.argv[1] ?? "");
     await mkdir(path.dirname(scriptPath), { recursive: true });
     await writeFile(scriptPath, `${UTF8_BOM}${renderWindowsSyncScript({
@@ -414,7 +457,7 @@ async function windowsTaskStatus(options) {
             discoveryArgs: await savedDiscoveryLimitArgs(options.homeDir),
             workDirs: normalizeWindowsWorkDirs(options.repoRoots),
             dashboardUrl: options.dashboardUrl ?? DEFAULT_DASHBOARD_URL,
-            nodeExecutable: path.win32.resolve(options.nodeExecutable ?? process.execPath),
+            nodeExecutable: (await schedulerNodeExecutable(options, "win32")).path,
             cliEntryPoint: path.win32.resolve(options.cliEntryPoint ?? process.argv[1] ?? ""),
             syncLogPath: windowsSyncLogPath(options.homeDir),
         })}`;
@@ -954,8 +997,42 @@ function renderDarwinSyncCommand(options) {
         ? ""
         : ` --dashboard-url ${shellQuote(options.dashboardUrl)}`;
     const discoveryArg = options.discoveryArgs.length > 0 ? ` ${options.discoveryArgs.join(" ")}` : "";
-    const commands = options.workDirs.map((root) => `${shellQuote(options.nodeExecutable)} ${shellQuote(options.cliEntryPoint)} sync --workspace ${shellQuote(root)}${dashboardArg}${discoveryArg} --json || exit_code=1`);
-    return ["exit_code=0", ...commands, 'exit "$exit_code"'].join("; ");
+    const commands = options.workDirs.map((root) => `"$node_bin" ${shellQuote(options.cliEntryPoint)} sync --workspace ${shellQuote(root)}${dashboardArg}${discoveryArg} --json || exit_code=1`);
+    return [
+        "exit_code=0",
+        ...darwinNodeResolutionPreamble(options.nodeExecutable),
+        ...commands,
+        'exit "$exit_code"',
+    ].join("; ");
+}
+/**
+ * The registered node path first, a login-shell PATH lookup second, a named
+ * failure third (BLI-3553).
+ *
+ * The hardcoded absolute path stays FIRST and stays the normal case — launchd
+ * hands the tick `PATH=/usr/bin:/bin:/usr/sbin:/sbin` and nothing this fleet
+ * runs lives there, which is the whole reason the plist names absolutes
+ * (scheduled-self-update.ts:55-62). The fallback only fires when that path is
+ * gone: `brew upgrade node` deleted the Cellar directory, `nvm uninstall`
+ * removed a version, someone moved a prefix. Before this, that state was a
+ * silent `exit 127` every 15 minutes forever, on every tick, with nothing in
+ * sync.err.log naming it.
+ *
+ * `/bin/zsh -lc` because a login shell is where Homebrew's `brew shellenv` and
+ * a machine's own PATH edits live; `command -v` because it is a builtin and
+ * cannot itself be missing. Recovering here is deliberately temporary: running
+ * under a node the plist does not name makes the next status read disagree,
+ * which is exactly what wakes the self-heal up to re-register the new path.
+ * A machine whose node is only on an INTERACTIVE shell's PATH (nvm sourced from
+ * .zshrc) still fails — but now it fails with a reason in the log instead of a
+ * bare 127.
+ */
+function darwinNodeResolutionPreamble(nodeExecutable) {
+    return [
+        `node_bin=${shellQuote(nodeExecutable)}`,
+        `[ -x "$node_bin" ] || node_bin="$(${DARWIN_LOGIN_SHELL} -lc 'command -v node' 2>/dev/null)"`,
+        `[ -x "$node_bin" ] || { echo ${shellQuote(DARWIN_NODE_MISSING_MESSAGE)} >&2; exit 127; }`,
+    ];
 }
 function darwinAgentRegistrationProblems(plist, expected) {
     if (!plist)
@@ -1031,6 +1108,101 @@ function watchPathsBlock(watchPaths) {
         "  </array>",
     ];
 }
+/**
+ * What the platform says it will run, parsed out of the registration itself
+ * (BLI-3553). Deliberately NOT rebuilt from `process.execPath` — the whole
+ * failure this ticket exists for is the registered path outliving the binary,
+ * and a check built from our own current values cannot see that.
+ */
+export async function readRegisteredRuntimePaths(options) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "darwin") {
+        const plist = await readFile(plistPathFor(options.homeDir ?? os.homedir()), "utf8").catch(() => "");
+        const command = decodeXmlEntities(plist);
+        return {
+            node_executable: /node_bin='([^']*)'/u.exec(command)?.[1] ?? null,
+            cli_entry_point: /"\$node_bin" '([^']*)' sync /u.exec(command)?.[1] ?? null,
+        };
+    }
+    if (platform === "win32") {
+        const script = await readFile(windowsAutostartScriptPath(options.homeDir), "utf8").catch(() => "");
+        return {
+            node_executable: /\$nodeExecutable = '([^']*)'/u.exec(script)?.[1] ?? null,
+            cli_entry_point: /\$cliEntryPoint = '([^']*)'/u.exec(script)?.[1] ?? null,
+        };
+    }
+    return { node_executable: null, cli_entry_point: null };
+}
+/**
+ * Named problems with the registered runtime, or an empty list. Path-free
+ * strings: safe to log, safe to upload as an install-event detail.
+ */
+export async function registeredRuntimePathProblems(options) {
+    // A real-host check by nature: this stats paths. A suite simulating win32 on
+    // a Mac (which every Windows test here does) would be asking the wrong
+    // filesystem about `C:\...`, and "missing" would mean nothing. Say nothing
+    // rather than something false.
+    const platform = options.platform ?? process.platform;
+    if (platform !== (options.hostPlatform ?? process.platform))
+        return [];
+    const registered = await readRegisteredRuntimePaths(options);
+    const problems = [];
+    if (registered.node_executable === null) {
+        problems.push("registration names no node binary");
+    }
+    else if (!(await fileExists(registered.node_executable))) {
+        problems.push("registered node binary is missing");
+    }
+    if (registered.cli_entry_point === null) {
+        problems.push("registration names no Tower CLI entry point");
+    }
+    else if (!(await fileExists(registered.cli_entry_point))) {
+        problems.push("registered Tower CLI entry point is missing");
+    }
+    return problems;
+}
+/** `gui/<uid>` — the per-user launchd domain the LaunchAgent lives in. */
+export function launchdUserDomain(uid = process.getuid?.() ?? 0) {
+    return `gui/${uid}`;
+}
+/**
+ * Re-registers the LaunchAgent with the modern verbs (BLI-3553).
+ *
+ * `unload`/`load` is what the interactive install path uses and it stays there;
+ * this exists for the DETACHED healer, where the difference matters:
+ * `bootstrap` reports a rejected plist with a real error, whereas `load` is
+ * documented-deprecated and exits nonzero with empty output for several
+ * unrelated states (see launchctlDetail). The healer gets one shot and has no
+ * human watching, so it uses the verb that says what went wrong.
+ *
+ * `bootout` on a service that is not loaded exits nonzero (`3: No such
+ * process`); that is the expected steady state after the job that spawned us
+ * exited, so it is not treated as a failure. Only `bootstrap` decides the
+ * outcome. If it fails, the agent is left unloaded — recoverable, because
+ * launchd bootstraps everything in ~/Library/LaunchAgents at the next login,
+ * and the plist file itself was already rewritten before this call.
+ */
+export async function reregisterDarwinAgent(options) {
+    const domain = launchdUserDomain(options.uid);
+    const bootout = await options
+        .exec("launchctl", ["bootout", `${domain}/${AUTOSTART_LABEL}`])
+        .catch(() => ({ code: 1, stdout: "", stderr: "" }));
+    const bootstrap = await options
+        .exec("launchctl", ["bootstrap", domain, options.plistPath])
+        .catch(() => ({ code: 1, stdout: "", stderr: "" }));
+    if (bootstrap.code === 0) {
+        return {
+            ok: true,
+            reason: "agent_rebootstrapped",
+            detail: `bootout exit ${bootout.code}`,
+        };
+    }
+    return {
+        ok: false,
+        reason: "bootstrap_failed",
+        detail: `launchctl bootstrap exited ${bootstrap.code}: ${launchctlDetail(bootstrap)}`,
+    };
+}
 function shellQuote(value) {
     return `'${value.replace(/'/g, "'\\''")}'`;
 }

package/dist/commands/autostart-heal.js

@@ -0,0 +1,162 @@
+import path from "node:path";
+import { appendFile } from "node:fs/promises";
+import { AUTOSTART_LABEL, autostartStatus, reregisterDarwinAgent, writeDarwinAutostartPlist, } from "../autostart.js";
+import { redactedHealthDetail } from "../health-detail.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
+import { normalizeCollectionRoots } from "../root-normalization.js";
+import { createCapturedExecRunner } from "../process-runner.js";
+import { reportInstallEventsBestEffort } from "./install-receipts.js";
+/** How long to wait for the launchd job that spawned us to exit. */
+export const HEAL_PARENT_EXIT_TIMEOUT_MS = 120_000;
+const HEAL_PARENT_POLL_MS = 250;
+const DETAIL_MAX_CHARS = 300;
+export async function runAutostartHealDetached(command, io, deps = {}) {
+    const outcome = await healDetached(command, io, deps);
+    const report = deps.reportInstallEvents ?? reportInstallEventsBestEffort;
+    await report({
+        homeDir: command.homeDir,
+        dashboardUrl: command.dashboardUrl,
+        command: "sync",
+        events: [
+            {
+                step: "autostart_heal",
+                status: outcome.status,
+                ...(outcome.status === "ok" ? {} : { error_code: outcome.reason }),
+                ...(outcome.detail ? { error_detail: outcome.detail } : {}),
+            },
+        ],
+        json: command.json,
+        io,
+    });
+    // Both branches log: "did any Mac in the fleet actually recover today?" has
+    // to be answerable from sync.err.log alone.
+    //
+    // And it has to be written THERE explicitly. This process is spawned with
+    // `stdio: "ignore"` — deliberately, so it holds no descriptor on a log the
+    // tick may be rotating — which means its stderr goes nowhere. Without the
+    // append below the only trace of a failed heal would be the uploaded
+    // receipt, and an operator reading their own machine would see a scheduler
+    // that silently stopped healing.
+    const line = `${outcome.status === "ok"
+        ? "[autostart-heal] launchd agent re-registered"
+        : "[autostart-heal] launchd agent not re-registered"} ${JSON.stringify({
+        label: AUTOSTART_LABEL,
+        status: outcome.status,
+        reason: outcome.reason,
+    })}`;
+    console.error(line);
+    await appendFile(path.join(getCollectorRuntimePaths(command.homeDir).state_dir, "sync.err.log"), `${line}\n`).catch(() => undefined);
+    return outcome.status === "fail" ? 1 : 0;
+}
+async function healDetached(command, io, deps) {
+    const platform = deps.platform ?? process.platform;
+    if (platform !== "darwin") {
+        return { status: "skipped", reason: "not_darwin" };
+    }
+    const exec = deps.exec ?? io.exec ?? createCapturedExecRunner();
+    const waited = await waitForParentExit(command.parentPid, deps);
+    if (!waited) {
+        // Booting the job out while it is still running would SIGTERM it — the
+        // exact hazard this process exists to avoid. Refuse instead.
+        return { status: "fail", reason: "parent_still_running" };
+    }
+    const roots = await savedRoots(command.homeDir);
+    if (roots.length === 0) {
+        return { status: "skipped", reason: "no_saved_roots" };
+    }
+    const before = await autostartStatus({
+        homeDir: command.homeDir,
+        repoRoot: roots[0],
+        repoRoots: roots,
+        dashboardUrl: command.dashboardUrl,
+        exec,
+        platform,
+    });
+    if (before.status === "absent") {
+        // Repair what exists, never create.
+        return { status: "skipped", reason: "autostart_absent" };
+    }
+    let written;
+    try {
+        written = await writeDarwinAutostartPlist({
+            homeDir: command.homeDir,
+            repoRoot: roots[0],
+            repoRoots: roots,
+            dashboardUrl: command.dashboardUrl,
+            exec,
+            platform,
+        });
+    }
+    catch (error) {
+        return {
+            status: "fail",
+            reason: "plist_write_failed",
+            detail: redactedHealthDetail(error instanceof Error ? error.message : String(error)).slice(0, DETAIL_MAX_CHARS),
+        };
+    }
+    const reregistered = await reregisterDarwinAgent({
+        exec,
+        plistPath: written.plist_path,
+    });
+    if (!reregistered.ok) {
+        return {
+            status: "fail",
+            reason: reregistered.reason,
+            detail: redactedHealthDetail(reregistered.detail ?? "").slice(0, DETAIL_MAX_CHARS),
+        };
+    }
+    // Verify against what launchd returns, not against what we sent it
+    // (BLI-2541). A bootstrap that exits 0 and a registration that reads back
+    // healthy are two different claims.
+    const after = await autostartStatus({
+        homeDir: command.homeDir,
+        repoRoot: roots[0],
+        repoRoots: roots,
+        dashboardUrl: command.dashboardUrl,
+        exec,
+        platform,
+    });
+    if (after.status !== "loaded") {
+        return {
+            status: "fail",
+            reason: "reregistered_but_still_broken",
+            detail: redactedHealthDetail(after.message ?? after.status).slice(0, DETAIL_MAX_CHARS),
+        };
+    }
+    return {
+        status: "ok",
+        reason: "autostart_healed",
+        detail: `node_path_reason=${written.node_path_reason}`,
+    };
+}
+async function waitForParentExit(parentPid, deps) {
+    if (!parentPid || parentPid <= 0)
+        return true;
+    const isAlive = deps.isProcessAlive ?? defaultIsProcessAlive;
+    const sleep = deps.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const now = deps.now ?? (() => Date.now());
+    const deadline = now() + HEAL_PARENT_EXIT_TIMEOUT_MS;
+    while (isAlive(parentPid)) {
+        if (now() >= deadline)
+            return false;
+        await sleep(HEAL_PARENT_POLL_MS);
+    }
+    return true;
+}
+function defaultIsProcessAlive(pid) {
+    try {
+        // Signal 0 tests for existence without delivering anything.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means it exists and belongs to someone else — still alive.
+        return error.code === "EPERM";
+    }
+}
+async function savedRoots(homeDir) {
+    const config = await readLocalCollectorConfig(getCollectorRuntimePaths(homeDir)).catch(() => null);
+    return normalizeCollectionRoots(config?.default_repo_paths ?? []);
+}
+export const AUTOSTART_HEAL_DEFAULT_DASHBOARD_URL = DEFAULT_DASHBOARD_URL;

package/dist/commands/collection-roots.js

@@ -11,7 +11,7 @@ import os from "node:os";
 import path from "node:path";
 import { stat } from "node:fs/promises";
 import { isInteractiveStdin, readLine, writeLine, yesByDefault } from "./cli-io.js";
-import { COLLECTION_ROOT_REQUIRED, resolveOnboardingRoots, } from "../onboarding-roots.js";
+import { CollectionRootRequiredError, resolveOnboardingRoots, } from "../onboarding-roots.js";
 import { getCollectorRuntimePaths, installLocalCollector, readLocalCollectorConfig, } from "../local-state.js";
 import { collectionRootPathAliases } from "../repo-identity.js";
 import { normalizeCollectionRoots } from "../root-normalization.js";
@@ -37,7 +37,7 @@ export async function resolveOnboardingRootsForCommand(command, io) {
     const collectionRoots = rootsResult.roots;
     const primaryRoot = collectionRoots[0];
     if (!primaryRoot) {
-        throw new Error(`${COLLECTION_ROOT_REQUIRED}: no collection root confirmed.`);
+        throw new CollectionRootRequiredError(`no collection root confirmed.`);
     }
     const replaceRepoRoots = rootsResult.source === "prompt" &&
         !command.collectionRoots?.length &&
@@ -80,7 +80,7 @@ export async function assertCollectionRootPersisted(homeDir) {
     const config = await readLocalCollectorConfig(getCollectorRuntimePaths(homeDir)).catch(() => null);
     const saved = normalizeCollectionRoots(config?.default_repo_paths ?? []);
     if (saved.length === 0) {
-        throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${collectionRootNotPersistedMessage(homeDir)}`);
+        throw new CollectionRootRequiredError(collectionRootNotPersistedMessage(homeDir));
     }
     // Present in the file is not the same as usable. A root that no longer
     // exists on disk resolves to nothing at sync time, which is the same silent
@@ -91,7 +91,7 @@ export async function assertCollectionRootPersisted(homeDir) {
             usable.push(root);
     }
     if (usable.length === 0) {
-        throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${collectionRootMissingOnDiskMessage(saved, homeDir)}`);
+        throw new CollectionRootRequiredError(collectionRootMissingOnDiskMessage(saved, homeDir));
     }
     return usable;
 }

package/dist/commands/doctor.js

@@ -1,12 +1,13 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { autostartStatus, installAutostartAgent } from "../autostart.js";
+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 { runBackfillCommand } from "./backfill.js";
 import { createInteractiveExecRunner } from "../process-runner.js";
@@ -71,6 +72,10 @@ function doctorInvariants() {
             fix: fixRootState,
             requiresInteractiveFix: true,
         },
+        // Deliberately has NO fix: uninstalling software the operator did not ask
+        // to have uninstalled is not a repair (BLI-3218/BLI-3553). Doctor names the
+        // other install and the exact command; the person decides.
+        { id: "single-install", check: (context) => context.deps.checkSingleInstall(context) },
         {
             id: "autostart-alive",
             check: (context) => context.deps.checkAutostart(context),
@@ -103,6 +108,7 @@ function defaultDoctorDeps(hooks) {
         runLogin: (context) => hooks.runLogin(context.command, context.io),
         readRoots: readRootState,
         resolveAndSaveRoots: (context) => hooks.resolveAndSaveRoots(context.command, context.io),
+        checkSingleInstall: checkSingleInstallState,
         checkAutostart: checkAutostartState,
         fixAutostart: fixAutostartState,
         checkBackfill: checkBackfillState,
@@ -221,6 +227,37 @@ async function readRootState(context) {
         "  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) {
@@ -234,6 +271,15 @@ async function checkAutostartState(context) {
         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") {