@indigoai-us/hq-cli 5.171.0 → 5.173.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [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
+
+- The `hq daemon` updater keeps hq-cloud current as well. Every 6 hours it
+  installs the newest hq-cloud with the same major version into
+  `~/.hq/daemon/hq-cloud`, and it restarts sync and the outpost heartbeat
+  right after an update. The daemon runs sync, and the heartbeat when that
+  hq-cloud has `hq-outpost-heartbeat`, from whichever copy is newer: this one
+  or the one bundled with the CLI.
+- `hq daemon` sync pushes local changes as they happen (`--event-push`), the
+  same as outpost sync does today.
+
 ## [5.171.0] — 2026-09-24
 
 ### Fixed

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/commands/daemon.js

@@ -16,7 +16,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { DEFAULT_SERVICES, SERVICE_DESCRIPTIONS, enabledServices } from "../lib/daemon/catalog.js";
+import { DEFAULT_SERVICES, SERVICE_DESCRIPTIONS, enabledServices, hqCloudUnits } from "../lib/daemon/catalog.js";
 import { applyServiceToggle, readDaemonConfig, writeDaemonConfig } from "../lib/daemon/config.js";
 import { daemonUnitInstalled } from "../lib/daemon/handoff.js";
 import { adoptLegacyUnits, readAdoptedUnits, restoreLegacyUnits } from "../lib/daemon/migrate.js";
@@ -418,19 +418,23 @@ async function runMigrate(d, opts) {
     d.out("Nothing was changed. `hq daemon migrate --apply` takes them over.");
 }
 async function runServiceSelfUpdate(d) {
-    const [{ daemonSelfUpdate }, { hostToolUpdater, runDaemonUpdater, updaterEnv }, { TOOL_NAMES }, { cliSelfUpdatable }] = await Promise.all([
+    const [{ daemonSelfUpdate }, { hostToolUpdater, runDaemonUpdater, updaterEnv }, { TOOL_NAMES }, { cliSelfUpdatable }, { updateManagedHqCloud },] = await Promise.all([
         import("../utils/self-update.js"),
         import("../lib/daemon/updater.js"),
         import("../lib/daemon/tools.js"),
         import("../lib/daemon/run.js"),
+        import("../lib/daemon/hq-cloud.js"),
     ]);
-    const { paths } = currentHost(d);
+    const { paths, detected } = currentHost(d);
     const env = updaterEnv(d.env);
     const result = await runDaemonUpdater({
         // Same guard as every self-update: never replace a dev checkout or a project's copy with a global install.
         updateCli: cliSelfUpdatable() ? () => daemonSelfUpdate({ env }) : null,
         tools: TOOL_NAMES.map((name) => hostToolUpdater(name, env, d.home)),
+        updateHqCloud: async () => updateManagedHqCloud(paths.root, env),
+        hqCloudUnits: hqCloudUnits(detected.type),
         requestDaemonRestart: () => writeControlRequest(paths.requestsDir, { action: "restart-daemon" }),
+        requestRestart: (unit) => writeControlRequest(paths.requestsDir, { action: "restart", unit }),
         log: d.out,
     });
     if (!result.ok)

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