@indigoai-us/hq-cli 5.172.0 → 5.173.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [5.173.0] — 2026-09-24
+
+### Fixed
+
+- `hq bot stop <name>` run from inside that bot's own turn now lets the turn finish: it signals the bot to drain (finish the running turn, post the reply, exit 0), which launchd leaves stopped. Before, it booted out the bot's own launchd job, which killed the bot, the turn, and the stop command itself (exit 137), so no reply was posted. `hq bot restart <name>` from inside the bot's own turn is refused with instructions, and `hq bot start` from inside the bot skips the agent reload.
+- Bot LaunchAgents and systemd units, the Work Mesh daemon unit, the `hq daemon` unit, and the lanes and agent-kit units now name node by its upgrade-stable path (`/opt/homebrew/bin/node` or `/opt/homebrew/opt/<formula>/bin/node`, or nvm's `current` link) instead of the versioned `/opt/homebrew/Cellar/node/<version>/bin/node`. Before, `brew upgrade node` deleted that path and launchd could no longer start the bots. The stable path is used only when it resolves to the same node binary; otherwise the unit keeps the resolved path as before.
+- Installed bot LaunchAgents that still name a versioned or missing node are repaired: `hq bot start` rewrites and reloads the agent, a bot started by launchd rewrites its own agent and reloads it from a detached shell before it takes any message, and `hq doctor` reports it (`bots.<name>.daemon-node`), with `hq doctor --fix` rewriting only the plist file and not reloading launchd. `hq bot list` and `hq bot status` flag a missing node binary. `hq mesh daemon install --if-stale` also reinstalls a same-version unit whose node path is missing or versioned.
+
 ## [5.172.0] — 2026-09-24
 
 ### Changed

package/dist/commands/bot.d.ts

@@ -41,6 +41,11 @@ export interface BotRow {
     runtimeSignIn: RuntimeSignInIssue | null;
     daemonInstalled: boolean;
     daemonLoaded: boolean;
+    /**
+     * The startup agent's node binary is gone (a node upgrade removed the
+     * versioned path it names), so launchd cannot start the bot. Null when fine.
+     */
+    daemonNodeMissing: string | null;
     dir: string;
     introSentAt?: string;
     /** "personal" acts as its owner everywhere; "company" acts as itself. */
@@ -63,6 +68,19 @@ export declare function listBotNames(root: string): string[];
 export declare function botTokenSupplier(dir: string): () => Promise<string>;
 /** Spawn `hq bot run <name>` detached (no launchd). */
 export declare function spawnDetachedRun(name: string, dir: string): number;
+/**
+ * `output`: "json" | "text" print a result; "silent" prints nothing — used
+ * when stop is a step inside rm/restart, whose own JSON must be the only
+ * document on stdout (the desktop app parses it; a second object made it
+ * "unreadable output: trailing characters").
+ */
+/** Seams for the self-stop path, replaced in tests. */
+export declare const botStopSeams: {
+    /** True when this process runs inside the bot process `botPid` (one of its turns). */
+    isInsideBot: (botPid: number) => boolean;
+    /** Ask the bot to finish its running turns and exit 0 (the drain signal). */
+    signalDrain: (botPid: number) => boolean;
+};
 /**
  * The kind a new bot gets, before anything is provisioned. Personal unless
  * `--kind company` is given (the desktop app always passes --kind). A company

package/dist/commands/bot.js

@@ -42,8 +42,10 @@ import { getCompanyUid, resolveCallerPersonUid } from "../utils/vault-api.js";
 import { resolveHqBinary } from "../lib/mesh/live/daemon/install.js";
 import { askDaemonToStart, askDaemonToStop, daemonOwnsProcess, daemonSupervises, daemonWillSupervise, handOffInstallHere, } from "../lib/daemon/handoff.js";
 import { daemonPaths } from "../lib/daemon/paths.js";
+import { launchdLabel } from "../lib/bot/paths.js";
+import { isAncestorProcess } from "../lib/bot/self-process.js";
 import { runtimeDisplayName } from "../lib/bot/runtime-sign-in.js";
-import { BotApi, BotApiError, BOT_RESTORE_DEFAULTS, buildBotLocalConfig, describeBotLocalConfig, orphanBotRunMessage, parseBotLocalConfig, removeOrphanBotDaemon, botDaemonStatus, botDir, botCredsPath, botLogPath, botsRoot, botTokenStateDir, botWorkerRelDir, buildBotDaemonPaths, createBotLogger, deleteBotCreds, installBotDaemon, repairBotDaemonIfStale, introDmText, isBotMemoryMode, botLocalMemoryDir, botMemoryMode, resolveBotMemoryDir, validateBotIntro, validateBotKickoff, validateBotEffort, validateBotModel, effectiveBotEffort, BOT_EFFORT_LEVELS, DEFAULT_BOT_EFFORT, BOT_MEMORY_MODES, BOT_KINDS, isBotKind, effectiveBotKind, effectiveBotCompanies, normalizeBotCompanies, SETUP_BOT_WORKER_ID, isBotRuntimeId, localNameForRemoteBot, remoteBotRunnability, isPidAlive, listBotWorkerOptions, patchBotConfig, readBotConfig, readBotCredsIdentity, readBotStatus, resolveBotWorker, runBot, runtimeFor, scaffoldBotMemory, scaffoldBotWorker, startBotDaemon, stopBotDaemon, uninstallBotDaemon, validateBotName, writeBotConfig, writeBotCreds, BOT_RUNTIMES, BOT_INTRO_MAX_CHARS, BOT_KICKOFF_MAX_CHARS, detectBotPlatform, } from "../lib/bot/index.js";
+import { BotApi, BotApiError, BOT_RESTORE_DEFAULTS, buildBotLocalConfig, describeBotLocalConfig, orphanBotRunMessage, parseBotLocalConfig, removeOrphanBotDaemon, botDaemonStatus, botDir, botCredsPath, botLogPath, botsRoot, botTokenStateDir, botWorkerRelDir, buildBotDaemonPaths, createBotLogger, deleteBotCreds, installBotDaemon, repairBotDaemonIfStale, healBotDaemonNodeFromJob, introDmText, isBotMemoryMode, botLocalMemoryDir, botMemoryMode, resolveBotMemoryDir, validateBotIntro, validateBotKickoff, validateBotEffort, validateBotModel, effectiveBotEffort, BOT_EFFORT_LEVELS, DEFAULT_BOT_EFFORT, BOT_MEMORY_MODES, BOT_KINDS, isBotKind, effectiveBotKind, effectiveBotCompanies, normalizeBotCompanies, SETUP_BOT_WORKER_ID, isBotRuntimeId, localNameForRemoteBot, remoteBotRunnability, isPidAlive, listBotWorkerOptions, patchBotConfig, readBotConfig, readBotCredsIdentity, readBotStatus, resolveBotWorker, runBot, runtimeFor, scaffoldBotMemory, scaffoldBotWorker, startBotDaemon, stopBotDaemon, uninstallBotDaemon, validateBotName, writeBotConfig, writeBotCreds, BOT_RUNTIMES, BOT_INTRO_MAX_CHARS, BOT_KICKOFF_MAX_CHARS, detectBotPlatform, } from "../lib/bot/index.js";
 function collectRepeated(value, previous) {
     return [...previous, value];
 }
@@ -135,11 +137,14 @@ function rowFor(name, opts = {}) {
     const inflightTurns = readInflightTurns(dir);
     let daemonInstalled = false;
     let daemonLoaded = false;
+    let daemonNodeMissing = null;
     if (opts.withDaemon !== false) {
         try {
             const d = botDaemonStatus(buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot }), daemonDeps());
             daemonInstalled = d.installed;
             daemonLoaded = d.loaded;
+            if (d.nodeProblem === "missing" && d.nodeBinary)
+                daemonNodeMissing = d.nodeBinary;
         }
         catch {
             /* hq binary unresolvable in odd environments — daemon status unknown */
@@ -168,6 +173,7 @@ function rowFor(name, opts = {}) {
         runtimeSignIn: status?.runtimeSignIn ?? null,
         daemonInstalled,
         daemonLoaded,
+        daemonNodeMissing,
         dir,
         introSentAt: config.introSentAt,
         kind: effectiveBotKind(config),
@@ -278,7 +284,11 @@ async function startBot(name, dir, config, output, extra = {}) {
         }
     }
     else if (d.installed && process.platform === "darwin") {
-        repairBotDaemonIfStale(paths, daemonDeps());
+        // A repair reloads the job; from inside one of the bot's own turns that
+        // bootout would kill the turn and this command with it.
+        const self = readBotStatus(dir);
+        if (!(self && isPidAlive(self.pid) && selfStopProbe(self.pid)))
+            repairBotDaemonIfStale(paths, daemonDeps());
         const r = startBotDaemon(paths, daemonDeps());
         how = r.message;
     }
@@ -318,6 +328,32 @@ async function startBot(name, dir, config, output, extra = {}) {
  * document on stdout (the desktop app parses it; a second object made it
  * "unreadable output: trailing characters").
  */
+/** Seams for the self-stop path, replaced in tests. */
+export const botStopSeams = {
+    /** True when this process runs inside the bot process `botPid` (one of its turns). */
+    isInsideBot: (botPid) => isAncestorProcess(botPid),
+    /** Ask the bot to finish its running turns and exit 0 (the drain signal). */
+    signalDrain: (botPid) => {
+        try {
+            process.kill(botPid, "SIGUSR2");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+};
+function selfStopProbe(botPid) {
+    try {
+        return botStopSeams.isInsideBot(botPid);
+    }
+    catch {
+        return false;
+    }
+}
+function requestSelfStopDrain(botPid) {
+    return botStopSeams.signalDrain(botPid);
+}
 async function stopBot(name, dir, config, output) {
     if (hasPromotionHold(dir))
         throw new Error("This bot is held for cloud promotion. Continue its promotion before changing local settings or lifecycle.");
@@ -326,6 +362,25 @@ async function stopBot(name, dir, config, output) {
     const before = readBotStatus(dir);
     const wasRunning = !!before && isPidAlive(before.pid);
     const supervised = daemonSupervises(hqDaemon, `bots:${name}`);
+    // Stopping itself from inside one of its own turns: a bootout or a kill would
+    // take down this command and the turn with it, so the reply is lost and the
+    // job is left unloaded. Ask the bot to drain instead — finish the running
+    // turn (reply and ack included), then exit 0, which launchd's
+    // KeepAlive{SuccessfulExit:false} leaves down. `hq bot start` brings it back.
+    if (!supervised && wasRunning && selfStopProbe(before.pid)) {
+        const drained = requestSelfStopDrain(before.pid);
+        if (output === "silent")
+            return;
+        const how = drained ? "stops after this turn finishes" : "could not signal the bot";
+        if (output === "json") {
+            console.log(JSON.stringify({ ok: drained, name, signalled: drained, stopped: false, how, self: true }, null, 2));
+            return;
+        }
+        console.log(drained
+            ? chalk.green(`${name} will stop once this turn finishes`) + chalk.dim(` (stopping itself; start again with: hq bot start ${name})`)
+            : chalk.yellow(`${name} could not be asked to stop (pid ${before.pid})`));
+        return;
+    }
     // Keep the daemon's copy down either way, so it does not start one as soon as this bot is gone.
     if (supervised)
         askDaemonToStop(hqDaemon, `bots:${name}`);
@@ -732,6 +787,8 @@ async function runBotResident(nameArg) {
             console.log(orphanBotRunMessage(name, outcome));
         return;
     }
+    if (healNodePathFromJob(name, dir, config))
+        return;
     const token = botTokenSupplier(dir);
     const api = new BotApi({ token });
     const owner = new OwnerContextCache(() => lookupOwnerContext(config.ownerUid), Date.now, undefined, config.ownerUid);
@@ -756,6 +813,30 @@ async function runBotResident(nameArg) {
     await handle.done;
     void name;
 }
+/**
+ * When this run IS the bot's launchd job and its plist names node by a
+ * versioned path (/opt/homebrew/Cellar/node/<v>/bin/node, removed by the next
+ * `brew upgrade node`), rewrite it to the stable alias and reload the job from
+ * a detached shell. Returns true when the caller should exit now (0, so
+ * KeepAlive leaves it alone) and let the reloaded job take over.
+ */
+function healNodePathFromJob(name, dir, config) {
+    // Only the job's own main process (launchd, pid 1, is its parent): a copy
+    // spawned by the bot inherits XPC_SERVICE_NAME but is not the job.
+    if (process.platform !== "darwin" || process.env.XPC_SERVICE_NAME !== launchdLabel(name) || process.ppid !== 1)
+        return false;
+    try {
+        const healed = healBotDaemonNodeFromJob(buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot }), daemonDeps());
+        if (!healed)
+            return false;
+        createBotLogger(dir)("info", `startup agent ran node from ${healed.from}, which the next node upgrade removes; rewrote it to ${healed.to} and reloading`);
+        return true;
+    }
+    catch (err) {
+        createBotLogger(dir)("warn", `could not rewrite the startup agent's node path: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
 // ── list / status / logs ─────────────────────────────────────────────────────
 async function runBotList(opts) {
     if (opts.remote) {
@@ -773,7 +854,7 @@ async function runBotList(opts) {
         return;
     }
     for (const r of rows) {
-        console.log(`${chalk.bold(r.name.padEnd(16))} ${r.agentUid}  ${r.runtime.padEnd(6)}  ${humanOnline(r).padEnd(8)}  ${r.processAlive ? chalk.green(`pid ${r.pid}`) : chalk.gray(r.state)}${chalk.dim(`  ${r.kind === "company" ? `company bot: ${r.companies.join(", ") || "no company"}` : "personal"}`)}${r.daemonInstalled ? chalk.dim("  launchd") : ""}${r.workerId ? chalk.dim(`  worker ${r.workerId}${r.companySlug ? ` (${r.companySlug})` : ""}`) : ""}`);
+        console.log(`${chalk.bold(r.name.padEnd(16))} ${r.agentUid}  ${r.runtime.padEnd(6)}  ${humanOnline(r).padEnd(8)}  ${r.processAlive ? chalk.green(`pid ${r.pid}`) : chalk.gray(r.state)}${chalk.dim(`  ${r.kind === "company" ? `company bot: ${r.companies.join(", ") || "no company"}` : "personal"}`)}${r.daemonInstalled ? chalk.dim("  launchd") : ""}${r.daemonNodeMissing ? chalk.red(`  node missing (hq bot start ${r.name})`) : ""}${r.workerId ? chalk.dim(`  worker ${r.workerId}${r.companySlug ? ` (${r.companySlug})` : ""}`) : ""}`);
     }
 }
 async function runBotStatus(nameArg, opts) {
@@ -802,6 +883,9 @@ async function runBotStatus(nameArg, opts) {
     }
     console.log(`  answering:  ${row.busy ? chalk.green(`yes${row.busySince ? `, since ${row.busySince}` : ""}`) : chalk.gray("no")}`);
     console.log(`  launchd:    ${row.daemonInstalled ? (row.daemonLoaded ? "installed, loaded" : "installed, not loaded") : "not installed"}`);
+    if (row.daemonNodeMissing) {
+        console.log(`  ${chalk.red(`node missing: ${row.daemonNodeMissing}`)} — launchd cannot start ${name}; fix with: hq bot start ${name}`);
+    }
     console.log(`  creds:      ${creds ? `present for ${creds.entityUid}` : chalk.red("missing")}`);
     if (status) {
         console.log(`  started:    ${status.startedAt}   restarts: ${status.restarts}   replies: ${status.repliesSent}`);
@@ -1712,6 +1796,12 @@ export function registerBotCommand(program) {
         .option("--json", "Print machine-readable JSON")
         .action((name, opts) => wrap(async () => {
         const b = requireBot(name);
+        const running = readBotStatus(b.dir);
+        if (running && isPidAlive(running.pid) && selfStopProbe(running.pid)) {
+            // The stop half would end this turn (and this command) before the
+            // start half ran, leaving the bot down. Say so instead.
+            throw new Error(`${b.name} cannot restart itself from inside one of its own turns: the stop would end this turn before the start ran. Run \`hq bot restart ${b.name}\` from outside the bot, or \`hq bot stop ${b.name}\` to stop it after this turn.`);
+        }
         await stopBot(b.name, b.dir, b.config, "silent");
         await startBot(b.name, b.dir, b.config, opts.json ? "json" : "text");
     })());

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

@@ -10,6 +10,7 @@
  * `launchctl` is injected so tests never touch the real service manager.
  */
 import * as fs from "node:fs";
+import { type NodeBinaryIo } from "../node-binary.js";
 export type BotDaemonPlatform = "darwin" | "linux" | "other";
 export interface BotDaemonPaths {
     home: string;
@@ -54,6 +55,9 @@ export interface BotDaemonResult {
     installed: boolean;
     loaded: boolean;
     dest?: string;
+    /** Set when the installed unit's node path is missing or versioned. */
+    nodeBinary?: string;
+    nodeProblem?: "missing" | "versioned";
     message: string;
 }
 export interface BotDaemonDeps {
@@ -87,11 +91,74 @@ export declare function installedDaemonHqBinary(p: BotDaemonPaths, io?: {
     existsSync(path: string): boolean;
     readFileSync(path: string, encoding: "utf8"): string;
 }): string | null;
+/** The node binary baked into an installed unit, or null if none. */
+export declare function installedDaemonNodeBinary(p: BotDaemonPaths, io?: {
+    existsSync(path: string): boolean;
+    readFileSync(path: string, encoding: "utf8"): string;
+}): string | null;
+/**
+ * What is wrong with the node path baked into the bot's installed unit:
+ * "missing" (launchd can no longer start the bot — a `brew upgrade node`
+ * removed the versioned Cellar directory), "versioned" (it still exists, but
+ * the next upgrade removes it; a stable alias for the same binary exists), or
+ * null when the unit is fine or not installed.
+ */
+export declare function botDaemonNodeProblem(p: BotDaemonPaths, deps?: {
+    fsImpl?: Pick<typeof fs, "existsSync">;
+    readFile?: (file: string) => string;
+    nodeIo?: NodeBinaryIo;
+}): {
+    nodeBinary: string;
+    problem: "missing" | "versioned";
+    replacement: string | null;
+} | null;
 /**
  * Rewrite the unit when its hq path is missing or is the pre-move
- * toolchain/node/bin/hq while toolchain/npm-global/bin/hq exists.
+ * toolchain/node/bin/hq while toolchain/npm-global/bin/hq exists, or when its
+ * node path is missing or a versioned directory an upgrade will remove.
+ *
+ * A node-only repair keeps the hq script the unit already runs, so repairing
+ * from a worktree or a one-off build never repoints the bot at that build.
+ */
+export declare function repairBotDaemonIfStale(p: BotDaemonPaths, deps?: BotDaemonDeps & {
+    readFile?: (file: string) => string;
+    nodeIo?: NodeBinaryIo;
+}): BotDaemonResult | null;
+/**
+ * The in-job half of the node-path self-heal, run by `hq bot run` when it is
+ * itself the launchd job. A `bootout` from inside the job kills the caller,
+ * so this only rewrites the plist and hands the reload to a detached shell in
+ * its own session; the caller then exits 0, which KeepAlive{SuccessfulExit:
+ * false} leaves alone, and the shell boots the old definition out and
+ * bootstraps the rewritten one (RunAtLoad starts the bot again). Runs before
+ * the bot takes any message, so no turn is cut short.
+ *
+ * Returns null (and changes nothing) unless the unit's node path is a
+ * versioned directory with a stable alias for the same binary.
+ */
+export declare function healBotDaemonNodeFromJob(p: BotDaemonPaths, deps?: BotDaemonDeps & {
+    readFile?: (file: string) => string;
+    nodeIo?: NodeBinaryIo;
+}): {
+    from: string;
+    to: string;
+} | null;
+/** `program = …` of the loaded job (`launchctl print`), or null when not loaded or unknown. */
+export declare function loadedLaunchdProgram(p: BotDaemonPaths, deps: Pick<BotDaemonDeps, "launchctl" | "uid">): string | null;
+/**
+ * Rewrite the plist's node path to the stable alias WITHOUT touching launchd:
+ * no bootout, no bootstrap, so a running bot's turn is never cut short and a
+ * stopped bot is not started. The new path applies at the next login, the next
+ * `hq bot start`, or the bot's next start (which reloads its own job). This is
+ * what `hq doctor --fix` runs, including unattended at session start.
  */
-export declare function repairBotDaemonIfStale(p: BotDaemonPaths, deps?: BotDaemonDeps): BotDaemonResult | null;
+export declare function rewriteBotDaemonNodePath(p: BotDaemonPaths, deps?: Pick<BotDaemonDeps, "fsImpl" | "platform"> & {
+    readFile?: (file: string) => string;
+    nodeIo?: NodeBinaryIo;
+}): {
+    from: string;
+    to: string;
+} | null;
 export declare function installBotDaemon(p: BotDaemonPaths, deps?: BotDaemonDeps): BotDaemonResult;
 export declare function uninstallBotDaemon(p: BotDaemonPaths, deps?: BotDaemonDeps): BotDaemonResult;
 export declare function botDaemonStatus(p: BotDaemonPaths, deps?: BotDaemonDeps): BotDaemonResult;

package/dist/lib/bot/daemon.js

@@ -15,6 +15,7 @@ import * as path from "node:path";
 import { spawn } from "node:child_process";
 import { resolveHqBinary, resolveNodeBinary, preferStableHqBinary } from "../mesh/live/daemon/install.js";
 import { botLogPath, launchdLabel } from "./paths.js";
+import { nodeBinaryProblem, preferStableNodeBinary } from "../node-binary.js";
 export function detectBotPlatform(platform = process.platform) {
     if (platform === "darwin")
         return "darwin";
@@ -211,17 +212,65 @@ export function installedDaemonHqBinary(p, io = fs) {
     }
     return null;
 }
+/** The node binary baked into an installed unit, or null if none. */
+export function installedDaemonNodeBinary(p, io = fs) {
+    if (io.existsSync(p.plistPath)) {
+        const args = launchdPlistProgramArguments(io.readFileSync(p.plistPath, "utf8"));
+        return args[0] ?? null;
+    }
+    if (io.existsSync(p.systemdUnitPath)) {
+        const unit = io.readFileSync(p.systemdUnitPath, "utf8");
+        const m = unit.match(/^ExecStart=(\S+)/m);
+        return m?.[1] ?? null;
+    }
+    return null;
+}
+/**
+ * What is wrong with the node path baked into the bot's installed unit:
+ * "missing" (launchd can no longer start the bot — a `brew upgrade node`
+ * removed the versioned Cellar directory), "versioned" (it still exists, but
+ * the next upgrade removes it; a stable alias for the same binary exists), or
+ * null when the unit is fine or not installed.
+ */
+export function botDaemonNodeProblem(p, deps = {}) {
+    const io = deps.fsImpl ?? fs;
+    let node;
+    try {
+        node = installedDaemonNodeBinary(p, {
+            existsSync: (q) => io.existsSync(q),
+            readFileSync: (q) => (deps.readFile ?? ((f) => fs.readFileSync(f, "utf8")))(q),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!node)
+        return null;
+    const nodeOpts = deps.nodeIo ? { io: deps.nodeIo } : {};
+    const problem = nodeBinaryProblem(node, nodeOpts);
+    if (!problem)
+        return null;
+    // Prefer the stable alias of the node the unit already ran (same install),
+    // so a repair run from another node (an nvm shell) does not switch runtimes.
+    const stable = preferStableNodeBinary(node, nodeOpts);
+    return { nodeBinary: node, problem, replacement: stable !== node ? stable : null };
+}
 /**
  * Rewrite the unit when its hq path is missing or is the pre-move
- * toolchain/node/bin/hq while toolchain/npm-global/bin/hq exists.
+ * toolchain/node/bin/hq while toolchain/npm-global/bin/hq exists, or when its
+ * node path is missing or a versioned directory an upgrade will remove.
+ *
+ * A node-only repair keeps the hq script the unit already runs, so repairing
+ * from a worktree or a one-off build never repoints the bot at that build.
  */
 export function repairBotDaemonIfStale(p, deps = {}) {
     const io = deps.fsImpl ?? fs;
+    const readFile = deps.readFile ?? ((f) => fs.readFileSync(f, "utf8"));
     let current;
     try {
         current = installedDaemonHqBinary(p, {
             existsSync: (q) => io.existsSync(q),
-            readFileSync: (q) => fs.readFileSync(q, "utf8"),
+            readFileSync: (q) => readFile(q),
         });
     }
     catch {
@@ -229,11 +278,107 @@ export function repairBotDaemonIfStale(p, deps = {}) {
     }
     if (!current)
         return null;
-    const missing = !io.existsSync(current);
-    const stale = preferStableHqBinary(current) !== current;
-    if (!missing && !stale)
+    const hqStale = !io.existsSync(current) || preferStableHqBinary(current) !== current;
+    const found = botDaemonNodeProblem(p, { fsImpl: io, readFile, ...(deps.nodeIo ? { nodeIo: deps.nodeIo } : {}) });
+    // Rewriting only helps when it changes the node path.
+    const nodeTarget = found ? (found.replacement ?? p.nodeBinary) : p.nodeBinary;
+    const node = found && found.nodeBinary !== nodeTarget ? found : null;
+    // A plist already rewritten on disk (`hq doctor --fix`) whose loaded job still
+    // runs the versioned or missing node needs a reload all the same.
+    const loaded = loadedLaunchdProgram(p, deps);
+    const loadedStale = !!loaded && loaded !== nodeTarget && nodeBinaryProblem(loaded, deps.nodeIo ? { io: deps.nodeIo } : {}) !== null;
+    if (!hqStale && !node && !loadedStale)
+        return null;
+    return installBotDaemon({ ...p, nodeBinary: nodeTarget, ...(hqStale ? {} : { hqBinary: current }) }, deps);
+}
+/**
+ * The in-job half of the node-path self-heal, run by `hq bot run` when it is
+ * itself the launchd job. A `bootout` from inside the job kills the caller,
+ * so this only rewrites the plist and hands the reload to a detached shell in
+ * its own session; the caller then exits 0, which KeepAlive{SuccessfulExit:
+ * false} leaves alone, and the shell boots the old definition out and
+ * bootstraps the rewritten one (RunAtLoad starts the bot again). Runs before
+ * the bot takes any message, so no turn is cut short.
+ *
+ * Returns null (and changes nothing) unless the unit's node path is a
+ * versioned directory with a stable alias for the same binary.
+ */
+export function healBotDaemonNodeFromJob(p, deps = {}) {
+    const platform = deps.platform ?? detectBotPlatform();
+    if (platform !== "darwin")
+        return null;
+    const io = deps.fsImpl ?? fs;
+    const readFile = deps.readFile ?? ((f) => fs.readFileSync(f, "utf8"));
+    const nodeOpts = deps.nodeIo ? { io: deps.nodeIo } : {};
+    const file = botDaemonNodeProblem(p, { fsImpl: io, readFile, ...(deps.nodeIo ? { nodeIo: deps.nodeIo } : {}) });
+    const fileTarget = file?.replacement ?? null;
+    const fileNeedsRewrite = !!file && file.problem === "versioned" && !!fileTarget;
+    // The plist may already be stable (rewritten by `hq doctor --fix`) while the
+    // loaded definition — what launchd execs on the next respawn — is not.
+    const loaded = loadedLaunchdProgram(p, deps);
+    const loadedTarget = loaded ? preferStableNodeBinary(loaded, nodeOpts) : null;
+    const loadedStale = !!loaded && !!loadedTarget && loadedTarget !== loaded && nodeBinaryProblem(loaded, nodeOpts) === "versioned";
+    if (!fileNeedsRewrite && !loadedStale)
+        return null;
+    if (fileNeedsRewrite) {
+        let hq;
+        try {
+            hq = installedDaemonHqBinary(p, { existsSync: (q) => io.existsSync(q), readFileSync: (q) => readFile(q) });
+        }
+        catch {
+            return null;
+        }
+        // Rewrite only the file here (no launchctl: a bootout would kill us).
+        installBotDaemon({ ...p, nodeBinary: fileTarget, hqBinary: hq ?? p.hqBinary }, { ...deps, platform, launchctl: undefined });
+    }
+    const domain = launchdDomain(deps.uid);
+    const target = `${domain}/${p.label}`;
+    const script = [
+        "sleep 1",
+        `launchctl bootout ${shQuote(target)} >/dev/null 2>&1`,
+        `i=0; while launchctl print ${shQuote(target)} >/dev/null 2>&1 && [ $i -lt 40 ]; do sleep 0.25; i=$((i+1)); done`,
+        `for d in 0 1 2 4; do sleep $d; launchctl bootstrap ${shQuote(domain)} ${shQuote(p.plistPath)} >/dev/null 2>&1 && exit 0; done`,
+        "exit 1",
+    ].join("; ");
+    (deps.spawnDetached ?? defaultSpawnDetached)("/bin/sh", ["-c", script]);
+    return fileNeedsRewrite ? { from: file.nodeBinary, to: fileTarget } : { from: loaded, to: loadedTarget };
+}
+/** `program = …` of the loaded job (`launchctl print`), or null when not loaded or unknown. */
+export function loadedLaunchdProgram(p, deps) {
+    if (!deps.launchctl)
+        return null;
+    const r = deps.launchctl(["print", `${launchdDomain(deps.uid)}/${p.label}`]);
+    if (!r.ok)
         return null;
-    return installBotDaemon(p, deps);
+    const m = /^\s*program = (.+?)\s*$/m.exec(r.stdout);
+    return m?.[1] ?? null;
+}
+/**
+ * Rewrite the plist's node path to the stable alias WITHOUT touching launchd:
+ * no bootout, no bootstrap, so a running bot's turn is never cut short and a
+ * stopped bot is not started. The new path applies at the next login, the next
+ * `hq bot start`, or the bot's next start (which reloads its own job). This is
+ * what `hq doctor --fix` runs, including unattended at session start.
+ */
+export function rewriteBotDaemonNodePath(p, deps = {}) {
+    const platform = deps.platform ?? detectBotPlatform();
+    if (platform !== "darwin")
+        return null;
+    const io = deps.fsImpl ?? fs;
+    const readFile = deps.readFile ?? ((f) => fs.readFileSync(f, "utf8"));
+    const file = botDaemonNodeProblem(p, { fsImpl: io, readFile, ...(deps.nodeIo ? { nodeIo: deps.nodeIo } : {}) });
+    const to = file ? (file.replacement ?? p.nodeBinary) : null;
+    if (!file || !to || file.nodeBinary === to)
+        return null;
+    let hq;
+    try {
+        hq = installedDaemonHqBinary(p, { existsSync: (q) => io.existsSync(q), readFileSync: (q) => readFile(q) });
+    }
+    catch {
+        return null;
+    }
+    installBotDaemon({ ...p, nodeBinary: to, hqBinary: hq ?? p.hqBinary }, { fsImpl: deps.fsImpl, platform });
+    return { from: file.nodeBinary, to };
 }
 export function installBotDaemon(p, deps = {}) {
     const platform = deps.platform ?? detectBotPlatform();
@@ -341,14 +486,19 @@ export function botDaemonStatus(p, deps = {}) {
     if (platform === "darwin") {
         const installed = io.existsSync(p.plistPath);
         const loaded = installed && launchdLoaded(p, deps);
+        const node = installed ? botDaemonNodeProblem(p, { fsImpl: io }) : null;
+        const nodeNote = node?.problem === "missing"
+            ? `; node binary missing (${node.nodeBinary}) — launchd cannot start it; run: hq bot start ${p.name}`
+            : "";
         return {
             platform,
             action: "status",
             installed,
             loaded,
             dest: p.plistPath,
+            ...(node ? { nodeBinary: node.nodeBinary, nodeProblem: node.problem } : {}),
             message: installed
-                ? `LaunchAgent ${p.label}: ${loaded ? "loaded" : "installed (not loaded)"}`
+                ? `LaunchAgent ${p.label}: ${loaded ? "loaded" : "installed (not loaded)"}${nodeNote}`
                 : `LaunchAgent ${p.label}: not installed`,
         };
     }

package/dist/lib/bot/run.js

@@ -1565,7 +1565,7 @@ export async function runBot(deps) {
             for (const turn of currentTurns)
                 turn.abort();
         await Promise.allSettled([heartbeatLoop, inboxLoop]);
-        await finish("stopped", 0, mode === "drain" ? "promotion drain completed" : "stop requested");
+        await finish("stopped", 0, mode === "drain" ? "drain completed (running turns finished)" : "stop requested");
     };
     const onSignal = () => {
         void stop();

package/dist/lib/bot/self-process.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Is this `hq` command running inside a bot's own turn?
+ *
+ * A bot's model turn is a child of the bot process, and the tools it runs are
+ * children of that. When the turn runs `hq bot stop <itself>`, the stop used
+ * to `launchctl bootout` the bot's own job. launchd then kills the whole job —
+ * the bot, the model turn, and the very `hq bot stop` asking — so the reply
+ * the turn was writing is lost (exit 137) and the job is left unloaded.
+ * Seen on 2026-09-24: george stopped itself mid-turn to break a bot-to-bot
+ * loop, and nothing was posted after the stop.
+ *
+ * The caller walks its own parent chain; `parentOf` is injectable for tests.
+ */
+export type ParentPidLookup = (pid: number) => number | null;
+/** Parent pid via `ps` (macOS and Linux), or null when it cannot be read. */
+export declare const defaultParentOf: ParentPidLookup;
+/** True when `ancestorPid` is `startPid` itself or one of its ancestors. */
+export declare function isAncestorProcess(ancestorPid: number, startPid?: number, parentOf?: ParentPidLookup, maxDepth?: number): boolean;
+//# sourceMappingURL=self-process.d.ts.map

package/dist/lib/bot/self-process.js

@@ -0,0 +1,35 @@
+/**
+ * Is this `hq` command running inside a bot's own turn?
+ *
+ * A bot's model turn is a child of the bot process, and the tools it runs are
+ * children of that. When the turn runs `hq bot stop <itself>`, the stop used
+ * to `launchctl bootout` the bot's own job. launchd then kills the whole job —
+ * the bot, the model turn, and the very `hq bot stop` asking — so the reply
+ * the turn was writing is lost (exit 137) and the job is left unloaded.
+ * Seen on 2026-09-24: george stopped itself mid-turn to break a bot-to-bot
+ * loop, and nothing was posted after the stop.
+ *
+ * The caller walks its own parent chain; `parentOf` is injectable for tests.
+ */
+import { spawnSync } from "node:child_process";
+/** Parent pid via `ps` (macOS and Linux), or null when it cannot be read. */
+export const defaultParentOf = (pid) => {
+    const r = spawnSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8" });
+    if (r.status !== 0 || typeof r.stdout !== "string")
+        return null;
+    const n = Number.parseInt(r.stdout.trim(), 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+};
+/** True when `ancestorPid` is `startPid` itself or one of its ancestors. */
+export function isAncestorProcess(ancestorPid, startPid = process.pid, parentOf = defaultParentOf, maxDepth = 64) {
+    if (!Number.isInteger(ancestorPid) || ancestorPid <= 1)
+        return false;
+    let pid = startPid;
+    for (let depth = 0; pid !== null && pid > 1 && depth < maxDepth; depth++) {
+        if (pid === ancestorPid)
+            return true;
+        pid = parentOf(pid);
+    }
+    return false;
+}
+//# sourceMappingURL=self-process.js.map

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;

package/dist/lib/mesh/live/daemon/install.js

@@ -24,6 +24,7 @@ import { retireLegacyListen } from "./legacy-listen.js";
 import { readDaemonState } from "./state.js";
 import { activateLaunchd, launchdPlistProgramArguments, launchdProgramArgumentsDiffer, parseLaunchctlPrintArguments, } from "../../../service-manager/launchd.js";
 import { activateSystemd } from "../../../service-manager/systemd.js";
+import { nodeBinaryProblem, preferStableNodeBinary } from "../../../node-binary.js";
 /**
  * `schtasks /End` terminates the task's root process only. The daemon is
  * launched through `conhost.exe --headless`, so ending the task kills conhost
@@ -113,7 +114,7 @@ function migrateLegacyDaemonUnit(opts) {
         env: opts.env,
         hqRoot: verified,
         hqBinary: "/usr/bin/hq",
-        nodeBinary: process.execPath || "/usr/bin/node",
+        nodeBinary: process.execPath ? resolveNodeBinary(process.execPath, opts.env ?? process.env) : "/usr/bin/node",
     });
     try {
         paths.hqBinary = resolveHqBinary(process.argv, opts.env ?? process.env);
@@ -264,18 +265,25 @@ export function resolveRunningCliEntry(argv = process.argv) {
         throw new Error(`Cannot resolve hq binary: ${entry} is not a real path`);
     }
 }
-/** 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 function resolveAbsoluteNodeBinary(execPath = process.execPath) {
     if (!execPath)
         throw new Error("Cannot resolve node binary: execPath is empty");
+    let real;
     try {
-        return fs.realpathSync(execPath);
+        real = fs.realpathSync(execPath);
     }
     catch {
         if (path.isAbsolute(execPath))
             return execPath;
         throw new Error(`Cannot resolve node binary: ${execPath} is not a real path`);
     }
+    return preferStableNodeBinary(real);
 }
 /** Resolve the hq binary the current shell uses (argv[1] or PATH). */
 export function resolveHqBinary(argv = process.argv, env = process.env) {
@@ -312,7 +320,14 @@ export function isNewerCliVersion(current, recorded) {
  */
 export function installDaemonIfStale(opts) {
     const recorded = readDaemonState(opts.paths.daemonDir)?.cliVersion;
-    if (!isNewerCliVersion(opts.currentVersion, recorded)) {
+    const platformForUnit = opts.platform ?? detectPlatform();
+    const installedNode = installedDaemonNodeBinary(opts.paths, platformForUnit, opts.readUnit);
+    // Only a rewrite that changes the node path helps: a unit whose node is gone
+    // or versioned, while this install resolves a different (stable) one.
+    const nodeProblem = installedNode && installedNode !== opts.paths.nodeBinary
+        ? (opts.nodeProblem ?? nodeBinaryProblem)(installedNode)
+        : null;
+    if (!isNewerCliVersion(opts.currentVersion, recorded) && !nodeProblem) {
         return {
             reinstalled: false,
             message: `daemon already records hq ${recorded}; not reinstalling`,
@@ -350,9 +365,42 @@ export function installDaemonIfStale(opts) {
         message: `${installed.message} Restarted with ${opts.paths.nodeBinary} ${opts.paths.hqBinary}.`,
     };
 }
+/**
+ * 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 function installedDaemonNodeBinary(paths, platform, readUnit = (file) => {
+    try {
+        return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null;
+    }
+    catch {
+        return null;
+    }
+}) {
+    if (platform === "darwin") {
+        const text = readUnit(paths.plistPath);
+        if (!text)
+            return null;
+        const block = text.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+        const first = block?.[1]?.match(/<string>([^<]*)<\/string>/);
+        return first?.[1] ?? null;
+    }
+    if (platform === "linux") {
+        const text = readUnit(paths.systemdUnitPath);
+        if (!text)
+            return null;
+        const m = text.match(/^ExecStart=('(?:[^']|'\\'')*'|\S+)/m);
+        if (!m)
+            return null;
+        const raw = m[1];
+        return raw.startsWith("'") ? raw.slice(1, -1).replace(/'\\''/g, "'") : raw;
+    }
+    return null;
+}
 export function resolveNodeBinary(execPath = process.execPath, env = process.env) {
     if (execPath && fs.existsSync(execPath))
-        return execPath;
+        return preferStableNodeBinary(execPath, { env });
     const pathEnv = env.PATH ?? "";
     for (const dir of pathEnv.split(path.delimiter)) {
         const candidate = path.join(dir, "node");

package/dist/lib/node-binary.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A node path that survives a node upgrade, for service units (LaunchAgents,
+ * systemd user units) that name node by absolute path.
+ *
+ * `process.execPath` is the resolved binary, e.g.
+ * /opt/homebrew/Cellar/node/26.0.0/bin/node. `brew upgrade node` deletes that
+ * directory, and every unit that baked it in stops launching (launchd cannot
+ * exec a missing program, so KeepAlive never brings the job back).
+ *
+ * The fix is to write the stable name the package manager keeps pointing at
+ * the current version (/opt/homebrew/bin/node, /opt/homebrew/opt/node/bin/node)
+ * instead of the versioned directory it points at today. A candidate is only
+ * used when it resolves to the SAME binary this process runs, so the unit
+ * keeps running the exact node it was installed with; a machine where no such
+ * alias exists (nvm without a `current` link, a hand-built node) keeps the
+ * execPath, as before.
+ */
+export interface NodeBinaryIo {
+    existsSync(p: string): boolean;
+    realpathSync(p: string): string;
+}
+/** True when `p` is a node binary inside a version-specific directory. */
+export declare function isVersionedNodePath(p: string): boolean;
+/**
+ * Stable names that may point at `execPath`, most specific first:
+ * the Homebrew prefix's bin/ and opt/<formula>/ links, a `current` link under
+ * nvm, then the usual global bins and every PATH entry.
+ */
+export declare function stableNodeCandidates(execPath: string, env?: NodeJS.ProcessEnv, home?: string): string[];
+/**
+ * The stable name for `execPath` when it sits in a versioned directory and an
+ * alias resolving to the same binary exists; otherwise `execPath` unchanged.
+ */
+export declare function preferStableNodeBinary(execPath: string, opts?: {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    io?: NodeBinaryIo;
+}): string;
+/**
+ * Why a unit's node path needs rewriting, or null when it is fine:
+ * "missing" — the binary is gone (launchd can no longer start the job);
+ * "versioned" — it still exists but the next upgrade will remove it, and a
+ * stable alias for the same binary exists.
+ */
+export declare function nodeBinaryProblem(nodePath: string, opts?: {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    io?: NodeBinaryIo;
+}): "missing" | "versioned" | null;
+//# sourceMappingURL=node-binary.d.ts.map

package/dist/lib/node-binary.js

@@ -0,0 +1,133 @@
+/**
+ * A node path that survives a node upgrade, for service units (LaunchAgents,
+ * systemd user units) that name node by absolute path.
+ *
+ * `process.execPath` is the resolved binary, e.g.
+ * /opt/homebrew/Cellar/node/26.0.0/bin/node. `brew upgrade node` deletes that
+ * directory, and every unit that baked it in stops launching (launchd cannot
+ * exec a missing program, so KeepAlive never brings the job back).
+ *
+ * The fix is to write the stable name the package manager keeps pointing at
+ * the current version (/opt/homebrew/bin/node, /opt/homebrew/opt/node/bin/node)
+ * instead of the versioned directory it points at today. A candidate is only
+ * used when it resolves to the SAME binary this process runs, so the unit
+ * keeps running the exact node it was installed with; a machine where no such
+ * alias exists (nvm without a `current` link, a hand-built node) keeps the
+ * execPath, as before.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+const defaultIo = {
+    existsSync: (p) => fs.existsSync(p),
+    realpathSync: (p) => fs.realpathSync(p),
+};
+/**
+ * Install layouts whose node lives in a per-version directory that an upgrade
+ * or version switch removes or abandons.
+ */
+const VERSIONED_NODE_PATTERNS = [
+    // Homebrew: <prefix>/Cellar/node/26.0.0/bin/node, <prefix>/Cellar/node@22/22.9.0/bin/node
+    /\/Cellar\/node(?:@[^/]+)?\/[^/]+\/bin\/node$/,
+    // nvm
+    /\/\.nvm\/versions\/node\/[^/]+\/bin\/node$/,
+    // Volta
+    /\/\.volta\/tools\/image\/node\/[^/]+\/bin\/node$/,
+    // fnm (installed versions and the per-shell multishell links)
+    /\/fnm\/node-versions\/[^/]+\/installation\/bin\/node$/,
+    /\/fnm_multishells\/[^/]+\/bin\/node$/,
+    // asdf / mise
+    /\/\.asdf\/installs\/nodejs\/[^/]+\/bin\/node$/,
+    /\/mise\/installs\/node\/[^/]+\/bin\/node$/,
+    // n
+    /\/n\/versions\/node\/[^/]+\/bin\/node$/,
+];
+/** True when `p` is a node binary inside a version-specific directory. */
+export function isVersionedNodePath(p) {
+    const normalized = p.split(path.sep).join("/");
+    return VERSIONED_NODE_PATTERNS.some((re) => re.test(normalized));
+}
+/**
+ * Stable names that may point at `execPath`, most specific first:
+ * the Homebrew prefix's bin/ and opt/<formula>/ links, a `current` link under
+ * nvm, then the usual global bins and every PATH entry.
+ */
+export function stableNodeCandidates(execPath, env = process.env, home = os.homedir()) {
+    const normalized = execPath.split(path.sep).join("/");
+    const out = [];
+    const brew = /^(.*)\/Cellar\/(node(?:@[^/]+)?)\/[^/]+\/bin\/node$/.exec(normalized);
+    if (brew) {
+        const prefix = brew[1];
+        out.push(`${prefix}/bin/node`, `${prefix}/opt/${brew[2]}/bin/node`);
+    }
+    const nvmDir = env.NVM_DIR?.trim() || path.join(home, ".nvm");
+    if (/\/\.nvm\/versions\/node\//.test(normalized))
+        out.push(path.join(nvmDir, "current", "bin", "node"));
+    out.push("/opt/homebrew/bin/node", "/usr/local/bin/node", "/usr/bin/node");
+    for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+        if (dir && path.isAbsolute(dir))
+            out.push(path.join(dir, "node"));
+    }
+    return [...new Set(out)];
+}
+/**
+ * The stable name for `execPath` when it sits in a versioned directory and an
+ * alias resolving to the same binary exists; otherwise `execPath` unchanged.
+ */
+export function preferStableNodeBinary(execPath, opts = {}) {
+    if (!execPath || !isVersionedNodePath(execPath))
+        return execPath;
+    const io = opts.io ?? defaultIo;
+    let target;
+    try {
+        target = io.realpathSync(execPath);
+    }
+    catch {
+        // A versioned node that is already gone (a stale unit being repaired):
+        // there is no binary to match, so any working stable node is the answer.
+        return firstWorkingStableNode(execPath, opts, io) ?? execPath;
+    }
+    for (const candidate of stableNodeCandidates(execPath, opts.env ?? process.env, opts.home ?? os.homedir())) {
+        if (isVersionedNodePath(candidate))
+            continue;
+        try {
+            if (!io.existsSync(candidate))
+                continue;
+            if (io.realpathSync(candidate) === target)
+                return candidate;
+        }
+        catch {
+            /* dangling link — not a candidate */
+        }
+    }
+    return execPath;
+}
+function firstWorkingStableNode(execPath, opts, io) {
+    for (const candidate of stableNodeCandidates(execPath, opts.env ?? process.env, opts.home ?? os.homedir())) {
+        if (isVersionedNodePath(candidate))
+            continue;
+        try {
+            if (io.existsSync(candidate) && io.existsSync(io.realpathSync(candidate)))
+                return candidate;
+        }
+        catch {
+            /* dangling link */
+        }
+    }
+    return null;
+}
+/**
+ * Why a unit's node path needs rewriting, or null when it is fine:
+ * "missing" — the binary is gone (launchd can no longer start the job);
+ * "versioned" — it still exists but the next upgrade will remove it, and a
+ * stable alias for the same binary exists.
+ */
+export function nodeBinaryProblem(nodePath, opts = {}) {
+    const io = opts.io ?? defaultIo;
+    if (!nodePath)
+        return null;
+    if (!io.existsSync(nodePath))
+        return "missing";
+    return preferStableNodeBinary(nodePath, opts) !== nodePath ? "versioned" : null;
+}
+//# sourceMappingURL=node-binary.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.172.0",
+  "version": "5.173.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {