@indigoai-us/hq-cli 5.171.0 → 5.173.0

package/dist/lib/daemon/catalog.d.ts

@@ -62,6 +62,8 @@ export interface PlanContext {
     hqRoot: string | undefined;
     /** hq-cloud's sync-runner.js, or null when it cannot be found. */
     syncRunnerPath: string | null;
+    /** hq-cloud's `hq-outpost-heartbeat` bin, when the hq-cloud in use has one. */
+    heartbeatRunnerPath: string | null;
     signedIn: boolean;
     /** ~/.hq-agent/kit.json exists. */
     kitConfigured: boolean;
@@ -86,6 +88,12 @@ export interface PlanContext {
     /** The box's Codex remote-control runner script, when it has one. */
     codexRunnerScript: string | null;
 }
+/**
+ * The units that run hq-cloud's code on a machine type, restarted after the
+ * updater installs a new hq-cloud. Only outposts and self-hosted machines run
+ * the outpost heartbeat; agent machines run the agent kit's own.
+ */
+export declare function hqCloudUnits(machineType: MachineType): ServiceName[];
 /** Written by outpost provisioning; the daemon runs it rather than re-implementing Codex login and relay setup. */
 export declare const CODEX_RUNNER_SCRIPT = "/usr/local/bin/outpost-codex-runner.sh";
 /** The outpost's Claude runner script, read for the session name it uses. */

package/dist/lib/daemon/catalog.js

@@ -96,6 +96,14 @@ function firstBlock(checks) {
     const hit = checks.find(([blocked]) => blocked);
     return hit ? { state: "waiting", reason: hit[1] } : undefined;
 }
+/**
+ * The units that run hq-cloud's code on a machine type, restarted after the
+ * updater installs a new hq-cloud. Only outposts and self-hosted machines run
+ * the outpost heartbeat; agent machines run the agent kit's own.
+ */
+export function hqCloudUnits(machineType) {
+    return machineType === "outpost" || machineType === "self-hosted" ? ["sync", "heartbeat"] : ["sync"];
+}
 /** Written by outpost provisioning; the daemon runs it rather than re-implementing Codex login and relay setup. */
 export const CODEX_RUNNER_SCRIPT = "/usr/local/bin/outpost-codex-runner.sh";
 /** The outpost's Claude runner script, read for the session name it uses. */
@@ -113,7 +121,7 @@ function planService(service, ctx) {
                 command: {
                     type: "node",
                     script: ctx.syncRunnerPath,
-                    args: ["--companies", "--direction", "both", "--on-conflict", "keep", "--hq-root", ctx.hqRoot ?? "", "--watch"],
+                    args: ["--companies", "--direction", "both", "--on-conflict", "keep", "--hq-root", ctx.hqRoot ?? "", "--watch", "--event-push"],
                 },
             });
             unit.blocked = firstBlock([
@@ -141,7 +149,10 @@ function planService(service, ctx) {
             }
             return [
                 base(service, {
-                    command: { type: "hq", args: ["outposts", "heartbeat", "--home", ctx.home] },
+                    // hq-cloud's own heartbeat picks up hq-cloud updates without a CLI release.
+                    command: ctx.heartbeatRunnerPath
+                        ? { type: "node", script: ctx.heartbeatRunnerPath, args: ["--home", ctx.home] }
+                        : { type: "hq", args: ["outposts", "heartbeat", "--home", ctx.home] },
                     blocked: firstBlock([[!ctx.signedIn, NOT_SIGNED_IN]]),
                 }),
             ];

package/dist/lib/daemon/hq-cloud.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Which hq-cloud the daemon runs sync and the outpost heartbeat from.
+ *
+ * The hq CLI ships with a copy of hq-cloud, but hq-cloud releases more often
+ * than the CLI. The updater keeps a newer copy of the same major version in
+ * `<daemon dir>/hq-cloud`, and the daemon runs whichever of the two is newer.
+ * A different major version is never used: it may not match this CLI.
+ */
+export declare const HQ_CLOUD_PACKAGE = "@indigoai-us/hq-cloud";
+export interface HqCloudCopy {
+    /** The package folder (the one holding its package.json). */
+    root: string;
+    version: string;
+}
+export interface PickedHqCloud extends HqCloudCopy {
+    source: "bundled" | "managed";
+}
+export declare function managedHqCloudDir(daemonRoot: string): string;
+/** The package folder inside the updater's install prefix. */
+export declare function managedHqCloudRoot(daemonRoot: string): string;
+/**
+ * `usable` says whether a copy has what the daemon runs; a newer managed copy
+ * that fails it (an interrupted or damaged install) is passed over.
+ */
+export declare function pickHqCloud(bundled: HqCloudCopy | null, managed: HqCloudCopy | null, usable?: (copy: HqCloudCopy) => boolean): PickedHqCloud | null;
+export interface HqCloudRunners {
+    syncRunner: string | null;
+    /** `hq-outpost-heartbeat`, which older hq-cloud releases do not have. */
+    heartbeat: string | null;
+}
+export declare function hqCloudRunners(root: string, exists?: (p: string) => boolean): HqCloudRunners;
+/** Install the newest release of the bundled major version, never older than the bundled copy. */
+export declare function hqCloudInstallCommand(prefix: string, bundledVersion: string, platform?: NodeJS.Platform): {
+    file: string;
+    args: string[];
+    shell: boolean;
+};
+export declare function readHqCloudCopy(root: string): HqCloudCopy | null;
+/** The copy bundled with this CLI. */
+export declare function bundledHqCloud(): HqCloudCopy | null;
+/** The hq-cloud the daemon should run right now. */
+export declare function currentHqCloud(daemonRoot: string): PickedHqCloud | null;
+export interface HqCloudUpdateOutcome {
+    ok: boolean;
+    from: string | null;
+    to: string | null;
+    detail?: string;
+}
+/** Install or update the updater's copy, as this (the login) user. */
+export declare function updateManagedHqCloud(daemonRoot: string, env: NodeJS.ProcessEnv): HqCloudUpdateOutcome;
+//# sourceMappingURL=hq-cloud.d.ts.map

package/dist/lib/daemon/hq-cloud.js

@@ -0,0 +1,110 @@
+/**
+ * Which hq-cloud the daemon runs sync and the outpost heartbeat from.
+ *
+ * The hq CLI ships with a copy of hq-cloud, but hq-cloud releases more often
+ * than the CLI. The updater keeps a newer copy of the same major version in
+ * `<daemon dir>/hq-cloud`, and the daemon runs whichever of the two is newer.
+ * A different major version is never used: it may not match this CLI.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { buildSpawnPlan } from "../../utils/windows-spawn.js";
+export const HQ_CLOUD_PACKAGE = "@indigoai-us/hq-cloud";
+export function managedHqCloudDir(daemonRoot) {
+    return path.join(daemonRoot, "hq-cloud");
+}
+/** The package folder inside the updater's install prefix. */
+export function managedHqCloudRoot(daemonRoot) {
+    return path.join(managedHqCloudDir(daemonRoot), "node_modules", ...HQ_CLOUD_PACKAGE.split("/"));
+}
+function parseVersion(v) {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(v.trim());
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function newer(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return false;
+}
+/**
+ * `usable` says whether a copy has what the daemon runs; a newer managed copy
+ * that fails it (an interrupted or damaged install) is passed over.
+ */
+export function pickHqCloud(bundled, managed, usable = () => true) {
+    if (!bundled)
+        return null;
+    const b = parseVersion(bundled.version);
+    const m = managed ? parseVersion(managed.version) : null;
+    if (managed && b && m && m[0] === b[0] && newer(m, b) && usable(managed))
+        return { ...managed, source: "managed" };
+    return { ...bundled, source: "bundled" };
+}
+export function hqCloudRunners(root, exists = fs.existsSync) {
+    const bin = (name) => {
+        const p = path.join(root, "dist", "bin", name);
+        return exists(p) ? p : null;
+    };
+    return { syncRunner: bin("sync-runner.js"), heartbeat: bin("outpost-heartbeat.js") };
+}
+/** Install the newest release of the bundled major version, never older than the bundled copy. */
+export function hqCloudInstallCommand(prefix, bundledVersion, platform = process.platform) {
+    // npm is a .cmd on Windows and needs the shell, so every argument is quoted for it.
+    const plan = buildSpawnPlan("npm", ["install", "--prefix", prefix, "--no-audit", "--no-fund", "--omit=dev", `${HQ_CLOUD_PACKAGE}@^${bundledVersion}`], platform);
+    return { file: plan.cmd, args: plan.args, shell: plan.shell };
+}
+export function readHqCloudCopy(root) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+        return typeof pkg.version === "string" ? { root, version: pkg.version } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The copy bundled with this CLI. */
+export function bundledHqCloud() {
+    try {
+        const require = createRequire(import.meta.url);
+        return readHqCloudCopy(path.dirname(require.resolve(`${HQ_CLOUD_PACKAGE}/package.json`)));
+    }
+    catch {
+        return null;
+    }
+}
+/** The hq-cloud the daemon should run right now. */
+export function currentHqCloud(daemonRoot) {
+    return pickHqCloud(bundledHqCloud(), readHqCloudCopy(managedHqCloudRoot(daemonRoot)), (copy) => hqCloudRunners(copy.root).syncRunner !== null);
+}
+/** Install or update the updater's copy, as this (the login) user. */
+export function updateManagedHqCloud(daemonRoot, env) {
+    const bundled = bundledHqCloud();
+    const from = currentHqCloud(daemonRoot)?.version ?? null;
+    if (!bundled)
+        return { ok: false, from, to: null, detail: "this CLI install has no bundled hq-cloud to match" };
+    const prefix = managedHqCloudDir(daemonRoot);
+    try {
+        fs.mkdirSync(prefix, { recursive: true, mode: 0o700 });
+    }
+    catch (err) {
+        return { ok: false, from, to: null, detail: `could not create ${prefix}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const cmd = hqCloudInstallCommand(prefix, bundled.version);
+    const r = spawnSync(cmd.file, cmd.args, {
+        encoding: "utf8",
+        env,
+        timeout: 10 * 60_000,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        shell: cmd.shell,
+    });
+    if (r.status !== 0) {
+        const tail = `${r.stderr ?? ""}\n${r.stdout ?? ""}`.trim().split("\n").slice(-3).join(" ").slice(0, 400);
+        return { ok: false, from, to: null, detail: tail || (r.error ? r.error.message : `npm exited ${r.status ?? "by signal"}`) };
+    }
+    return { ok: true, from, to: currentHqCloud(daemonRoot)?.version ?? null };
+}
+//# sourceMappingURL=hq-cloud.js.map

package/dist/lib/daemon/run.js

@@ -23,6 +23,7 @@ import { daemonRootRefusal } from "./install.js";
 import { detectMachineType } from "./machine-type.js";
 import { appendPrivate, daemonPaths, ensurePrivateDir, openPrivateAppend } from "./paths.js";
 import { takeControlRequests } from "./requests.js";
+import { currentHqCloud, hqCloudRunners } from "./hq-cloud.js";
 import { runnerSessionName } from "./remote-control.js";
 import { STOP_ESCALATION_MS, createSupervisor } from "./supervisor.js";
 import { userToolDirs } from "./tools.js";
@@ -230,8 +231,7 @@ export async function runDaemon(opts) {
         return 1;
     }
     log("info", `starting hq daemon (pid ${process.pid}) as ${machineType} (${detected.detail})`);
-    const syncRunnerPath = resolveSyncRunnerPath();
-    if (!syncRunnerPath)
+    if (!resolveSyncRunnerPath())
         log("warn", "the hq-cloud sync runner was not found in this CLI install; sync is unavailable");
     const updatable = cliSelfUpdatable();
     const hostName = os.hostname().split(".")[0] || "hq-host";
@@ -247,12 +247,16 @@ export async function runDaemon(opts) {
         const legacy = legacyUnits();
         const configured = config.hqRoot ?? env.HQ_ROOT?.trim() ?? undefined;
         const hqRoot = configured && fs.existsSync(configured) ? configured : undefined;
+        // Re-picked every reconcile, so a newer hq-cloud from the updater is used as soon as it lands.
+        const hqCloud = currentHqCloud(paths.root);
+        const runners = hqCloud ? hqCloudRunners(hqCloud.root) : { syncRunner: null, heartbeat: null };
         return planUnits(enabledServices(machineType, config), {
             machineType,
             platform,
             home,
             hqRoot,
-            syncRunnerPath,
+            syncRunnerPath: runners.syncRunner,
+            heartbeatRunnerPath: runners.heartbeat,
             signedIn: signedIn(env, home, log),
             kitConfigured: fs.existsSync(agentKitPaths(home, env).kitConfigPath),
             desktopAppManagesSync: machineType === "desktop" &&

package/dist/lib/daemon/updater.d.ts

@@ -8,11 +8,15 @@
  * 2. Update the Claude, Codex and Grok CLIs the login user installed, each
  *    through its own update route. A copy this user cannot write (root's
  *    under /usr) is reported and left alone.
- * 3. After a CLI update, ask the daemon to restart itself so the supervisor and
+ * 3. Install or update the daemon's own hq-cloud (sync and the outpost
+ *    heartbeat run from it when it is newer than the CLI's bundled copy), and
+ *    restart sync and the heartbeat right after it changes.
+ * 4. After a CLI update, ask the daemon to restart itself so the supervisor and
  *    every service run the new version. The remote-control hosts notice an
  *    updated Claude or Codex on disk themselves and restart once idle.
  */
 import type { SelfUpdateOutcome } from "../../utils/self-update.js";
+import type { HqCloudUpdateOutcome } from "./hq-cloud.js";
 import { type ToolInstall, type ToolName } from "./tools.js";
 export type { ToolInstall } from "./tools.js";
 export interface ToolUpdater {
@@ -27,7 +31,13 @@ export interface UpdaterDeps {
     /** Null when this CLI is not a global install the updater may replace. */
     updateCli: (() => Promise<Pick<SelfUpdateOutcome, "action" | "latest">>) | null;
     tools: readonly ToolUpdater[];
+    /** Install or update the daemon's own hq-cloud; null where it has none. */
+    updateHqCloud: (() => Promise<HqCloudUpdateOutcome>) | null;
+    /** The units on this machine that run hq-cloud code, restarted after it updates. */
+    hqCloudUnits: readonly string[];
     requestDaemonRestart: () => void;
+    /** Restart one unit (a restart request to the running daemon). */
+    requestRestart: (unit: string) => void;
     log: (line: string) => void;
 }
 export interface UpdaterResult {

package/dist/lib/daemon/updater.js

@@ -8,7 +8,10 @@
  * 2. Update the Claude, Codex and Grok CLIs the login user installed, each
  *    through its own update route. A copy this user cannot write (root's
  *    under /usr) is reported and left alone.
- * 3. After a CLI update, ask the daemon to restart itself so the supervisor and
+ * 3. Install or update the daemon's own hq-cloud (sync and the outpost
+ *    heartbeat run from it when it is newer than the CLI's bundled copy), and
+ *    restart sync and the heartbeat right after it changes.
+ * 4. After a CLI update, ask the daemon to restart itself so the supervisor and
  *    every service run the new version. The remote-control hosts notice an
  *    updated Claude or Codex on disk themselves and restart once idle.
  */
@@ -39,6 +42,26 @@ export async function runDaemonUpdater(deps) {
                 deps.log(`hq CLI: ${cli.action === "current" ? "up to date" : cli.action}`);
         }
     }
+    if (deps.updateHqCloud) {
+        const cloud = await deps.updateHqCloud().catch((err) => ({
+            ok: false,
+            from: null,
+            to: null,
+            detail: err instanceof Error ? err.message : String(err),
+        }));
+        if (!cloud.ok) {
+            deps.log(`hq-cloud update failed: ${cloud.detail ?? "unknown error"}`);
+            ok = false;
+        }
+        else if (cloud.to && cloud.to !== cloud.from) {
+            deps.log(`hq-cloud updated ${cloud.from ?? "(none)"} -> ${cloud.to}; restarting ${deps.hqCloudUnits.join(" and ")} onto it`);
+            for (const unit of deps.hqCloudUnits)
+                deps.requestRestart(unit);
+        }
+        else {
+            deps.log(`hq-cloud ${cloud.to ?? cloud.from ?? "unknown version"}: up to date`);
+        }
+    }
     const updated = [];
     for (const tool of deps.tools) {
         const outcome = updateTool(tool, deps.log);

package/dist/lib/doctor/checks/bots.d.ts

@@ -1,9 +1,12 @@
+import { type NodeBinaryIo } from "../../node-binary.js";
 import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
 export declare const BOTS_FAMILY_ID = "bots";
 export declare const BOTS_FAMILY_TITLE = "Local bots";
 export interface BotsDoctorDeps {
     home: () => string;
     root: (home?: string) => string;
+    /** Filesystem view used to judge the startup agent's node path (tests). */
+    nodeIo?: NodeBinaryIo;
 }
 export declare const botsFamily: CheckFamily;
 export declare function checkBots(_context: CheckContext, deps?: BotsDoctorDeps): CheckResult[];

package/dist/lib/doctor/checks/bots.js

@@ -9,6 +9,7 @@ import * as path from "node:path";
 import { botsRoot, botDir, launchdLabel } from "../../bot/paths.js";
 import { readBotConfig } from "../../bot/config.js";
 import { isPidAlive, readBotStatus } from "../../bot/status.js";
+import { nodeBinaryProblem } from "../../node-binary.js";
 export const BOTS_FAMILY_ID = "bots";
 export const BOTS_FAMILY_TITLE = "Local bots";
 const DEFAULT_DEPS = {
@@ -34,12 +35,14 @@ export function checkBots(_context, deps = DEFAULT_DEPS) {
         ];
     }
 }
-function launchdPlistHqBinary(plist) {
+function launchdPlistArgs(plist) {
     const block = plist.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
     if (!block)
-        return null;
-    const args = [...block[1].matchAll(/<string>([^<]*)<\/string>/g)].map((m) => m[1]);
-    return args[1] ?? null;
+        return [];
+    return [...block[1].matchAll(/<string>([^<]*)<\/string>/g)].map((m) => m[1]);
+}
+function launchdPlistHqBinary(plist) {
+    return launchdPlistArgs(plist)[1] ?? null;
 }
 function runChecks(deps) {
     const home = deps.home();
@@ -115,11 +118,45 @@ function runChecks(deps) {
         const plistPath = path.join(home, "Library", "LaunchAgents", `${launchdLabel(name)}.plist`);
         if (fs.existsSync(plistPath)) {
             let hqPath;
+            let nodePath;
             try {
-                hqPath = launchdPlistHqBinary(fs.readFileSync(plistPath, "utf8"));
+                const text = fs.readFileSync(plistPath, "utf8");
+                hqPath = launchdPlistHqBinary(text);
+                nodePath = launchdPlistArgs(text)[0] ?? null;
             }
             catch {
                 hqPath = null;
+                nodePath = null;
+            }
+            // The node the startup agent runs. A versioned Homebrew/nvm path
+            // (…/Cellar/node/26.0.0/bin/node) is deleted by the next upgrade, and
+            // launchd cannot start the bot after that.
+            const nodeProblem = nodePath ? nodeBinaryProblem(nodePath, deps.nodeIo ? { io: deps.nodeIo } : {}) : null;
+            if (nodePath && nodeProblem === "missing") {
+                results.push({
+                    status: "FAIL",
+                    checkId: `bots.${name}.daemon-node`,
+                    target: name,
+                    message: `${name} startup agent runs a node binary that no longer exists (${nodePath}); launchd cannot start it.`,
+                    remediation: `hq bot start ${name}`,
+                });
+            }
+            else if (nodePath && nodeProblem === "versioned") {
+                results.push({
+                    status: "WARN",
+                    checkId: `bots.${name}.daemon-node`,
+                    target: name,
+                    message: `${name} startup agent runs node from a versioned folder (${nodePath}) that the next node upgrade deletes.`,
+                    remediation: `hq bot start ${name}`,
+                });
+            }
+            else if (nodePath) {
+                results.push({
+                    status: "PASS",
+                    checkId: `bots.${name}.daemon-node`,
+                    target: name,
+                    message: `${name} startup agent node path is upgrade-safe.`,
+                });
             }
             if (hqPath && !fs.existsSync(hqPath)) {
                 results.push({

package/dist/lib/doctor/fix/apply.d.ts

@@ -70,6 +70,15 @@ export interface ApplyFixesOptions {
      * so `--fix` never hits the network.
      */
     refreshSync?: (target: RefreshSyncTarget) => Promise<RefreshSyncResult>;
+    /**
+     * File-only rewrite used by the `bot-node-path` class. Default rewrites
+     * ~/Library/LaunchAgents/ai.getindigo.hq-bot.<name>.plist and never calls
+     * launchctl. Tests inject a stub.
+     */
+    rewriteBotNodePath?: (name: string) => {
+        from: string;
+        to: string;
+    } | null;
 }
 /** One company the `refresh-sync` class will pull. */
 export interface RefreshSyncTarget {
@@ -138,6 +147,11 @@ export declare function defaultRefreshSync(target: RefreshSyncTarget): Promise<R
  * the backup still covers the write.
  */
 export declare function uncommittedHookConfigChanges(hqRoot: string): string[];
+/** Default `bot-node-path` repair against the real bot state and LaunchAgents. */
+export declare function defaultRewriteBotNodePath(name: string): {
+    from: string;
+    to: string;
+} | null;
 /**
  * Insert a new `case` arm allowlisting `hookId` (leading to `return 0`) at the
  * top of each named profile function's `case "$1" in` block. Additive: it never

package/dist/lib/doctor/fix/apply.js

@@ -37,6 +37,9 @@ import { gateMembership, parseHookGateProfiles, } from "../hook-gate-profiles.js
 import { createBackup } from "./backup.js";
 import { removeStrayGateEntries } from "../stray-gate-entries.js";
 import { deriveRemediation } from "./remediation.js";
+import { botDir } from "../../bot/paths.js";
+import { readBotConfig } from "../../bot/config.js";
+import { buildBotDaemonPaths, rewriteBotDaemonNodePath } from "../../bot/daemon.js";
 /** The tree subtrees whose uncommitted changes block a `--fix` run. */
 export const HOOK_CONFIG_DIRS = [".claude", ".codex", ".grok"];
 /** Per-company bound for the default `hq sync pull` repair. */
@@ -75,6 +78,7 @@ export async function applyFixes(options) {
     }
     const collect = options.runChecks ?? defaultRunChecks;
     const refreshSync = options.refreshSync ?? defaultRefreshSync;
+    const rewriteBotNodePath = options.rewriteBotNodePath ?? defaultRewriteBotNodePath;
     // 2. Collect findings and keep only the allowlisted auto-fixable ones.
     const findings = await collect(hqRoot);
     const fixable = [];
@@ -88,7 +92,7 @@ export async function applyFixes(options) {
         return empty();
     }
     const plans = fixable
-        .map(({ result, rem }) => planFix(hqRoot, result, rem, refreshSync))
+        .map(({ result, rem }) => planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath))
         .filter((plan) => plan !== null);
     if (plans.length === 0) {
         write("hq doctor --fix: nothing to repair — no auto-fixable findings.\n");
@@ -232,8 +236,10 @@ export function uncommittedHookConfigChanges(hqRoot) {
 }
 // --- Fix planning --------------------------------------------------------------
 /** Build the concrete plan for one auto-fixable finding, or null if unplannable. */
-function planFix(hqRoot, result, rem, refreshSync) {
+function planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath = defaultRewriteBotNodePath) {
     switch (rem.fixClass) {
+        case "bot-node-path":
+            return planBotNodePath(result, rem, rewriteBotNodePath);
         case "executable-bit":
             return planExecutableBit(hqRoot, result, rem);
         case "gate-profile":
@@ -246,6 +252,36 @@ function planFix(hqRoot, result, rem, refreshSync) {
             return null;
     }
 }
+/** Rewrite one bot LaunchAgent's node path (file only; launchd untouched). */
+function planBotNodePath(result, rem, rewrite) {
+    const name = rem.fixTarget;
+    if (!name)
+        return null;
+    return {
+        checkId: result.checkId,
+        fixClass: "bot-node-path",
+        target: name,
+        relpath: "",
+        preview: `  ~/Library/LaunchAgents/ai.getindigo.hq-bot.${name}.plist\n` +
+            `    ~ node path -> upgrade-stable alias of the same node\n` +
+            `      file only: the bot is not stopped or started; the new path loads at its next start`,
+        summary: `rewrite ${name} startup agent node path`,
+        apply: () => {
+            rewrite(name);
+        },
+        postStatus: (results) => results.find((entry) => entry.checkId === result.checkId)?.status ?? null,
+    };
+}
+/** Default `bot-node-path` repair against the real bot state and LaunchAgents. */
+export function defaultRewriteBotNodePath(name) {
+    if (process.platform !== "darwin")
+        return null;
+    const dir = botDir(name);
+    const config = readBotConfig(dir);
+    if (!config)
+        return null;
+    return rewriteBotDaemonNodePath(buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot, hqBinary: "hq" }), { platform: "darwin" });
+}
 /** Pull one company to refresh a stale or never-synced journal. */
 function planRefreshSync(hqRoot, result, rem, refreshSync) {
     const slug = rem.fixTarget;

package/dist/lib/doctor/fix/remediation.d.ts

@@ -38,7 +38,7 @@
  */
 import type { CheckResult } from "../types.js";
 /** The allowlisted safe repair classes `--fix` is permitted to apply. */
-export type FixClass = "executable-bit" | "gate-profile" | "remove-stray-gate-entries" | "refresh-sync";
+export type FixClass = "executable-bit" | "gate-profile" | "remove-stray-gate-entries" | "refresh-sync" | "bot-node-path";
 /**
  * A finding's structured remediation. `autoFixable`, `action`, and `command`
  * are the `--json` surface (AC1); `fixTarget`/`fixClass` are the internal handle

package/dist/lib/doctor/fix/remediation.js

@@ -104,6 +104,19 @@ export function deriveRemediation(result) {
             command: remediation ?? `Remove the matcher-less hook-gate.sh entries from ${target}.`,
         };
     }
+    // bot-node-path — a bot LaunchAgent that names node by a versioned path
+    // (…/Cellar/node/<v>/bin/node) that an upgrade removed or will remove.
+    // The repair rewrites only the plist file; it never reloads launchd, so it
+    // cannot cut a running turn short or start a stopped bot.
+    if (checkId.endsWith(".daemon-node") && checkId.startsWith("bots.") && target) {
+        return {
+            autoFixable: true,
+            fixClass: "bot-node-path",
+            fixTarget: target,
+            action: `Rewrite the ${target} startup agent to run node from its upgrade-stable path (applies at the bot's next start).`,
+            command: remediation ?? `hq bot start ${target}`,
+        };
+    }
     // refresh-sync — a company journal that is stale or never-synced. Only
     // company slugs: personal shards have no companies/<slug> tree and a
     // SessionStart `--fix --yes` must not pull the personal vault unprompted.

package/dist/lib/mesh/live/daemon/install.d.ts

@@ -125,7 +125,12 @@ export declare function preferStableHqBinary(entry: string): string;
  * realpath of argv[1] only — never a PATH lookup of `hq`.
  */
 export declare function resolveRunningCliEntry(argv?: string[]): string;
-/** Absolute node binary (realpath of process.execPath). No PATH lookup. */
+/**
+ * Absolute node binary for a service unit: the realpath of process.execPath,
+ * then its upgrade-stable alias (/opt/homebrew/bin/node rather than
+ * /opt/homebrew/Cellar/node/<version>/bin/node) when one resolves to the same
+ * binary. No PATH lookup of `node` by name.
+ */
 export declare function resolveAbsoluteNodeBinary(execPath?: string): string;
 /** Resolve the hq binary the current shell uses (argv[1] or PATH). */
 export declare function resolveHqBinary(argv?: string[], env?: NodeJS.ProcessEnv): string;
@@ -161,7 +166,17 @@ export declare function installDaemonIfStale(opts: {
         stderr: string;
     };
     windowsLegacyTaskPresent?: boolean;
+    /** Reads the installed unit (tests); defaults to the file on disk. */
+    readUnit?: (file: string) => string | null;
+    /** Checks the installed unit's node path (tests); defaults to the real filesystem. */
+    nodeProblem?: (nodePath: string) => "missing" | "versioned" | null;
 }): InstallIfStaleResult;
+/**
+ * The node binary baked into the installed daemon unit (darwin plist or linux
+ * user unit), or null when there is no unit or it cannot be read. Used to
+ * reinstall a unit whose node was a versioned path an upgrade removed.
+ */
+export declare function installedDaemonNodeBinary(paths: Pick<InstallPaths, "plistPath" | "systemdUnitPath">, platform: DaemonInstallPlatform, readUnit?: (file: string) => string | null): string | null;
 export declare function resolveNodeBinary(execPath?: string, env?: NodeJS.ProcessEnv): string;
 export declare function buildInstallPaths(opts: {
     home?: string;