@indigoai-us/hq-cli 5.122.0 → 5.122.2

package/CHANGELOG.md

@@ -2,8 +2,32 @@
 
 ## [Unreleased]
 
+## [5.122.2] — 2026-09-19
+
 ### Fixed
 
+- Local bots no longer retry inbox polls and heartbeats every couple of seconds
+  after HQ returns 429. They honour Retry-After when present and otherwise back
+  off, so a rate limit can clear instead of being held forever. `hq bot status`
+  now says unreachable / cannot receive when those calls are failing, instead of
+  HQ online from the last attempt, and `hq doctor` checks the same.
+
+- `hq bot start` / `restart` rewrites a LaunchAgent that still points at the
+  old toolchain `node/bin/hq` path after an HQ update moved the CLI to
+  `npm-global/bin/hq`, which previously failed with MODULE_NOT_FOUND until
+  someone ran `hq bot daemon install` by hand.
+
+## [5.122.1] — 2026-09-19
+
+### Fixed
+
+- `hq cloud provision company` no longer silently accepts a server-suffixed
+  slug. When another owner already holds the requested name, the vault assigns
+  `<slug>-<tag>` and used to write local config as if the original name had
+  been granted — sync then cannot push, because it looks for a folder matching
+  the cloud slug. Provision now fails before writing, and retires the
+  just-created entity so it does not leave a suffixed orphan.
+
 - Work Mesh now keeps the company you selected when its session context is
   acknowledged or recovered after a restart. Mesh activity stays attached to
   the right company instead of being held for missing attribution.

package/dist/commands/bot.d.ts

@@ -24,6 +24,9 @@ export interface BotRow {
     } | null;
     online: boolean | null;
     lastHeartbeatAt: string | null;
+    lastHeartbeatOk: boolean | null;
+    lastInboxPollAt: string | null;
+    lastInboxPollOk: boolean | null;
     /** Present while the coding tool needs a new sign-in before the bot can work. */
     runtimeSignIn: RuntimeSignInIssue | null;
     daemonInstalled: boolean;

package/dist/commands/bot.js

@@ -36,7 +36,7 @@ import { peekHqApiKey } from "../utils/resolve-vault-credential.js";
 import { getCompanyUid, resolveCallerPersonUid } from "../utils/vault-api.js";
 import { resolveHqBinary } from "../lib/mesh/live/daemon/install.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, 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, } 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, 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, } from "../lib/bot/index.js";
 function collectRepeated(value, previous) {
     return [...previous, value];
 }
@@ -144,6 +144,9 @@ function rowFor(name, opts = {}) {
         promotionHold: promotionHoldSummary(dir, config.agentUid, config.ownerUid),
         online: null,
         lastHeartbeatAt: status?.lastHeartbeatAt ?? null,
+        lastHeartbeatOk: status?.lastHeartbeatOk ?? null,
+        lastInboxPollAt: status?.lastInboxPollAt ?? null,
+        lastInboxPollOk: status?.lastInboxPollOk ?? null,
         runtimeSignIn: status?.runtimeSignIn ?? null,
         daemonInstalled,
         daemonLoaded,
@@ -184,6 +187,8 @@ async function decorateOnline(rows) {
     }));
 }
 function humanOnline(row) {
+    if (row.lastHeartbeatOk === false)
+        return chalk.red("unreachable");
     if (row.online === true)
         return chalk.green("online");
     if (row.online === false)
@@ -241,6 +246,7 @@ async function startBot(name, dir, config, output, extra = {}) {
     const d = botDaemonStatus(paths, daemonDeps());
     let how;
     if (d.installed && process.platform === "darwin") {
+        repairBotDaemonIfStale(paths, daemonDeps());
         const r = startBotDaemon(paths, daemonDeps());
         how = r.message;
     }
@@ -710,7 +716,13 @@ async function runBotStatus(nameArg, opts) {
         console.log(`  worker:     ${row.workerId}${row.companySlug ? ` (company ${row.companySlug})` : ""}  ${chalk.dim(row.workerDir)}`);
     console.log(`  memory:     ${row.memory}  ${chalk.dim(row.memoryDir)}`);
     console.log(`  process:    ${row.processAlive ? chalk.green(`running (pid ${row.pid})`) : chalk.gray(row.state)}`);
-    console.log(`  HQ online:  ${humanOnline(row)}${row.lastHeartbeatAt ? chalk.dim(`  last heartbeat ${row.lastHeartbeatAt}`) : ""}`);
+    console.log(`  HQ online:  ${humanOnline(row)}${row.lastHeartbeatAt ? chalk.dim(`  last heartbeat ${row.lastHeartbeatAt}`) : ""}${row.lastHeartbeatOk === false && status?.lastHeartbeatError ? chalk.dim(`  (${status.lastHeartbeatError})`) : ""}`);
+    if (status?.lastInboxPollOk === false) {
+        console.log(`  inbox:      ${chalk.red("cannot receive")}${status.lastInboxError ? chalk.dim(`  ${status.lastInboxError}`) : ""}`);
+    }
+    else if (status?.lastInboxPollAt) {
+        console.log(`  inbox:      last poll ${status.lastInboxPollAt}`);
+    }
     console.log(`  launchd:    ${row.daemonInstalled ? (row.daemonLoaded ? "installed, loaded" : "installed, not loaded") : "not installed"}`);
     console.log(`  creds:      ${creds ? `present for ${creds.entityUid}` : chalk.red("missing")}`);
     if (status) {

package/dist/commands/cloud-provision.js

@@ -513,6 +513,52 @@ export async function provisionCompany(options) {
         createdEntity = true;
         log(`created vault entity uid=${entity.uid}`);
     }
+    // hq-pro auto-suffixes a company slug when another owner already holds the
+    // bare name (`<slug>-<ownerTag>`). `/entity/check-slug/me` only looks at the
+    // caller's namespace, so it reports "available" and we POST; the server then
+    // returns a different slug. Writing companies/<requested>/.hq/config.json
+    // with the requested slug (or syncing with --company <assigned>) leaves the
+    // local folder and the cloud slug pointing at two different paths — share()
+    // derives syncRoot from ctx.slug, so the company can never be pushed.
+    // Fail before any local write. Retire a just-created entity so we do not
+    // leave a suffixed orphan.
+    if (entity.slug !== options.slug) {
+        const assigned = entity.slug || "(missing)";
+        let retired = false;
+        if (createdEntity) {
+            try {
+                await vaultClient.softDeleteCompany(entity.uid);
+                retired = true;
+                log(`retired vault entity uid=${entity.uid} — assigned slug ${assigned} differs from requested ${options.slug}`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log(`failed to retire mismatched vault entity uid=${entity.uid}: ${msg}`);
+            }
+        }
+        const retireNote = retired
+            ? `The just-created entity ${entity.uid} was retired.`
+            : createdEntity
+                ? `Retire entity ${entity.uid} with \`hq cloud retire company\`, then retry after the original slug is free.`
+                : `Existing entity ${entity.uid} was not modified.`;
+        throw new ProvisionError(1, `Cloud assigned slug "${assigned}" instead of requested "${options.slug}". ` +
+            `Local folder is companies/${options.slug}; sync derives the company folder from the cloud slug, so this company cannot be pushed. ` +
+            `${retireNote} Ask an admin to release the original slug, or rename the local folder to "${assigned}" and re-run.`, {
+            ok: false,
+            company_slug: options.slug,
+            cloud_uid: entity.uid,
+            bucket_name: entity.bucketName ?? "",
+            vault_api_url: options.vaultApiUrl,
+            kms_key_id: entity.kmsKeyId ?? null,
+            created_entity: createdEntity,
+            manifest_patched: false,
+            config_written: false,
+            initial_sync: {
+                ok: false,
+                error: `assigned slug "${assigned}" differs from requested "${options.slug}"`,
+            },
+        });
+    }
     if (!entity.bucketName) {
         // Vault returned an entity without a bucket — this would happen if the
         // provisioning Lambda asynchronously failed. We have a `cloud_uid` but

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

@@ -85,8 +85,11 @@ export declare class BotApiError extends Error {
     readonly status: number;
     readonly path: string;
     readonly code?: string | undefined;
-    constructor(status: number, path: string, code?: string | undefined, detail?: string);
+    readonly retryAfterMs?: number | undefined;
+    constructor(status: number, path: string, code?: string | undefined, detail?: string, retryAfterMs?: number | undefined);
 }
+/** Parse a Retry-After header (delta-seconds or HTTP-date) to milliseconds. */
+export declare function retryAfterHeaderMs(value: string | null | undefined, nowMs?: number): number | undefined;
 export interface BotApiOptions {
     token: TokenSupplier;
     baseUrl?: string;

package/dist/lib/bot/api.js

@@ -11,14 +11,32 @@ export class BotApiError extends Error {
     status;
     path;
     code;
-    constructor(status, path, code, detail) {
+    retryAfterMs;
+    constructor(status, path, code, detail, retryAfterMs) {
         super(`HQ API ${path} → ${status}${code ? ` ${code}` : ""}${detail ? `: ${detail}` : ""}`);
         this.status = status;
         this.path = path;
         this.code = code;
+        this.retryAfterMs = retryAfterMs;
         this.name = "BotApiError";
     }
 }
+/** Parse a Retry-After header (delta-seconds or HTTP-date) to milliseconds. */
+export function retryAfterHeaderMs(value, nowMs = Date.now()) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    const seconds = Number(trimmed);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.round(seconds * 1000);
+    }
+    const dateMs = Date.parse(trimmed);
+    if (!Number.isNaN(dateMs))
+        return Math.max(0, dateMs - nowMs);
+    return undefined;
+}
 async function readError(res) {
     try {
         const body = (await res.json());
@@ -54,7 +72,7 @@ export class BotApi {
         });
         if (!accept.includes(res.status)) {
             const err = await readError(res);
-            throw new BotApiError(res.status, path, err.code, err.detail);
+            throw new BotApiError(res.status, path, err.code, err.detail, retryAfterHeaderMs(res.headers.get("Retry-After")));
         }
         const text = await res.text();
         return { status: res.status, body: (text ? JSON.parse(text) : {}) };

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

@@ -81,7 +81,17 @@ export interface BotDaemonDeps {
      */
     announce?: (result: BotDaemonResult) => void;
 }
-/** Write the unit and load it (RunAtLoad starts the bot immediately). */
+export declare function launchdPlistProgramArguments(plist: string): string[];
+/** The hq script path baked into an installed unit, or null if none. */
+export declare function installedDaemonHqBinary(p: BotDaemonPaths, io?: {
+    existsSync(path: string): boolean;
+    readFileSync(path: string, encoding: "utf8"): string;
+}): string | 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.
+ */
+export declare function repairBotDaemonIfStale(p: BotDaemonPaths, deps?: BotDaemonDeps): BotDaemonResult | 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

@@ -13,7 +13,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { spawn } from "node:child_process";
-import { resolveHqBinary, resolveNodeBinary } from "../mesh/live/daemon/install.js";
+import { resolveHqBinary, resolveNodeBinary, preferStableHqBinary } from "../mesh/live/daemon/install.js";
 import { botLogPath, launchdLabel } from "./paths.js";
 export function detectBotPlatform(platform = process.platform) {
     if (platform === "darwin")
@@ -192,7 +192,49 @@ function launchdLoaded(p, deps) {
         return false;
     return deps.launchctl(["print", `${launchdDomain(deps.uid)}/${p.label}`]).ok;
 }
-/** Write the unit and load it (RunAtLoad starts the bot immediately). */
+export function launchdPlistProgramArguments(plist) {
+    const block = plist.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    if (!block)
+        return [];
+    return [...block[1].matchAll(/<string>([^<]*)<\/string>/g)].map((m) => m[1]);
+}
+/** The hq script path baked into an installed unit, or null if none. */
+export function installedDaemonHqBinary(p, io = fs) {
+    if (io.existsSync(p.plistPath)) {
+        const args = launchdPlistProgramArguments(io.readFileSync(p.plistPath, "utf8"));
+        return args[1] ?? null;
+    }
+    if (io.existsSync(p.systemdUnitPath)) {
+        const unit = io.readFileSync(p.systemdUnitPath, "utf8");
+        const m = unit.match(/^ExecStart=\S+\s+(\S+)/m);
+        return m?.[1] ?? null;
+    }
+    return 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.
+ */
+export function repairBotDaemonIfStale(p, deps = {}) {
+    const io = deps.fsImpl ?? fs;
+    let current;
+    try {
+        current = installedDaemonHqBinary(p, {
+            existsSync: (q) => io.existsSync(q),
+            readFileSync: (q) => fs.readFileSync(q, "utf8"),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!current)
+        return null;
+    const missing = !io.existsSync(current);
+    const stale = preferStableHqBinary(current) !== current;
+    if (!missing && !stale)
+        return null;
+    return installBotDaemon(p, deps);
+}
 export function installBotDaemon(p, deps = {}) {
     const platform = deps.platform ?? detectBotPlatform();
     const io = deps.fsImpl ?? fs;

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

@@ -38,7 +38,7 @@
  * Everything with a side effect is injectable so the loop is unit-testable.
  */
 import { type OwnerContext } from "./owner-context.js";
-import type { BotApi, InboxItem } from "./api.js";
+import { type BotApi, type InboxItem } from "./api.js";
 import type { BotConfig, BotKind } from "./config.js";
 import { type ProgressPosterOptions } from "./progress.js";
 import { type BotLogger } from "./log.js";
@@ -46,6 +46,24 @@ import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult } from "
 import { type BotState, type BotStatusFile } from "./status.js";
 export declare const INBOX_POLL_INTERVAL_MS = 2000;
 export declare const HEARTBEAT_INTERVAL_MS = 30000;
+/** First 429/5xx wait when Retry-After is absent (inbox polls at 2s). */
+export declare const API_BACKOFF_BASE_MS = 4000;
+/** Ceiling for exponential poll/heartbeat backoff. */
+export declare const API_BACKOFF_CAP_MS: number;
+/** Honor Retry-After up to this; a bogus 30-day header must not park the bot. */
+export declare const API_RETRY_AFTER_CAP_MS: number;
+export declare const API_RETRY_AFTER_FLOOR_MS = 1000;
+/**
+ * How long to wait after a failed inbox poll or heartbeat.
+ * 429/5xx (and transport errors) back off exponentially, honouring Retry-After
+ * when present. Other 4xx keep the normal interval so a 401 is not stretched.
+ */
+export declare function apiPollDelayMs(opts: {
+    err: unknown;
+    attempt: number;
+    intervalMs: number;
+    random?: () => number;
+}): number;
 export declare const FAILURE_WINDOW_MS: number;
 export declare const FAILURE_LIMIT = 5;
 export declare const MAX_ATTEMPTS_PER_MESSAGE = 3;

package/dist/lib/bot/run.js

@@ -44,6 +44,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fullJitterDelayMs } from "../mesh/live/backoff.js";
 import { acquirePidLock, defaultPidLockDeps, releasePidLock } from "../mesh/live/daemon/pid-lock.js";
+import { BotApiError } from "./api.js";
 import { effectiveBotCompanies, effectiveBotKind, patchBotConfig, readBotConfig, SETUP_BOT_WORKER_ID } from "./config.js";
 import { ensureBotSessionMeta } from "./company-bind.js";
 import { readBotCredsIdentity } from "./creds.js";
@@ -62,6 +63,35 @@ import { clearBotSession, readBotSession, writeBotSession } from "./session.js";
 import { defaultBotStatus, patchBotStatus, readBotStatus } from "./status.js";
 export const INBOX_POLL_INTERVAL_MS = 2_000;
 export const HEARTBEAT_INTERVAL_MS = 30_000;
+/** First 429/5xx wait when Retry-After is absent (inbox polls at 2s). */
+export const API_BACKOFF_BASE_MS = 4_000;
+/** Ceiling for exponential poll/heartbeat backoff. */
+export const API_BACKOFF_CAP_MS = 5 * 60_000;
+/** Honor Retry-After up to this; a bogus 30-day header must not park the bot. */
+export const API_RETRY_AFTER_CAP_MS = 15 * 60_000;
+export const API_RETRY_AFTER_FLOOR_MS = 1_000;
+/**
+ * How long to wait after a failed inbox poll or heartbeat.
+ * 429/5xx (and transport errors) back off exponentially, honouring Retry-After
+ * when present. Other 4xx keep the normal interval so a 401 is not stretched.
+ */
+export function apiPollDelayMs(opts) {
+    const intervalMs = Math.max(0, opts.intervalMs);
+    const status = opts.err instanceof BotApiError ? opts.err.status : undefined;
+    const retryable = status === 429 || (typeof status === "number" && status >= 500) || !(opts.err instanceof BotApiError);
+    if (!retryable)
+        return intervalMs;
+    const retryAfter = opts.err instanceof BotApiError ? opts.err.retryAfterMs : undefined;
+    const header = typeof retryAfter === "number" && Number.isFinite(retryAfter)
+        ? Math.min(API_RETRY_AFTER_CAP_MS, Math.max(API_RETRY_AFTER_FLOOR_MS, retryAfter))
+        : 0;
+    const base = Math.max(intervalMs * 2, API_BACKOFF_BASE_MS);
+    const attempt = Math.max(0, opts.attempt);
+    const exp = Math.min(API_BACKOFF_CAP_MS, base * 2 ** attempt);
+    const random = opts.random ?? Math.random;
+    const jittered = Math.floor(exp * (1 + 0.2 * random()));
+    return Math.min(API_BACKOFF_CAP_MS, Math.max(intervalMs, exp, header, jittered));
+}
 export const FAILURE_WINDOW_MS = 10 * 60 * 1000;
 export const FAILURE_LIMIT = 5;
 export const MAX_ATTEMPTS_PER_MESSAGE = 3;
@@ -187,6 +217,7 @@ export function preflightCreds(dir, config) {
 export async function runBot(deps) {
     const now = deps.now ?? (() => new Date());
     const sleep = deps.sleep ?? defaultSleep;
+    const random = deps.random ?? Math.random;
     const log = deps.log ?? createBotLogger(deps.dir, now);
     const pid = deps.pid ?? process.pid;
     const { dir, config, api, runtime } = deps;
@@ -374,18 +405,23 @@ export async function runBot(deps) {
         }
     };
     const heartbeatLoop = (async () => {
+        let heartbeatFails = 0;
         while (!stopping && state === "running") {
             try {
                 // The server's component vocabulary is the fleet one (sync/model/task…);
                 // runtime → model, inbox → task, sync → sync.
                 await api.heartbeat(config.agentUid, { model: modelHealth, task: "ok", sync: "ok" });
-                setStatus({ lastHeartbeatAt: now().toISOString(), lastHeartbeatOk: true });
+                heartbeatFails = 0;
+                setStatus({ lastHeartbeatAt: now().toISOString(), lastHeartbeatOk: true, lastHeartbeatError: undefined });
+                await sleep(heartbeatIntervalMs);
             }
             catch (err) {
-                setStatus({ lastHeartbeatAt: now().toISOString(), lastHeartbeatOk: false });
-                log("warn", `heartbeat failed: ${err instanceof Error ? err.message : String(err)}`);
+                heartbeatFails += 1;
+                const message = err instanceof Error ? err.message : String(err);
+                setStatus({ lastHeartbeatOk: false, lastHeartbeatError: message.slice(0, 400) });
+                log("warn", `heartbeat failed: ${message}`);
+                await sleep(apiPollDelayMs({ err, attempt: heartbeatFails - 1, intervalMs: heartbeatIntervalMs, random }));
             }
-            await sleep(heartbeatIntervalMs);
         }
     })();
     // ── Inbox loop ─────────────────────────────────────────────────────────────
@@ -1000,6 +1036,7 @@ export async function runBot(deps) {
             }
         }
         await kickoff;
+        let inboxFails = 0;
         while (!stopping && state === "running") {
             if (hasPromotionHold(dir))
                 break;
@@ -1015,13 +1052,21 @@ export async function runBot(deps) {
             }
             try {
                 const items = await api.pullInbox(config.agentUid);
-                setStatus({ lastInboxPollAt: now().toISOString() });
+                inboxFails = 0;
+                setStatus({ lastInboxPollAt: now().toISOString(), lastInboxPollOk: true, lastInboxError: undefined });
                 for (const item of items)
                     enqueue(item);
                 pump();
             }
             catch (err) {
-                log("warn", `inbox poll failed: ${err instanceof Error ? err.message : String(err)}`);
+                inboxFails += 1;
+                const message = err instanceof Error ? err.message : String(err);
+                setStatus({ lastInboxPollOk: false, lastInboxError: message.slice(0, 400) });
+                log("warn", `inbox poll failed: ${message}`);
+                if (stopping || state !== "running")
+                    break;
+                await sleep(apiPollDelayMs({ err, attempt: inboxFails - 1, intervalMs: inboxIntervalMs, random }));
+                continue;
             }
             if (stopping || state !== "running")
                 break;

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

@@ -17,7 +17,12 @@ export interface BotStatusFile {
     recentFailures: number;
     lastHeartbeatAt?: string;
     lastHeartbeatOk?: boolean;
+    /** Last heartbeat error, when lastHeartbeatOk is false. */
+    lastHeartbeatError?: string;
     lastInboxPollAt?: string;
+    lastInboxPollOk?: boolean;
+    /** Last inbox poll error, when lastInboxPollOk is false. */
+    lastInboxError?: string;
     /** Bounded, redacted stderr excerpt of the last model-CLI failure. */
     lastError?: string;
     /** Inbound DMs answered since start. */

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

@@ -0,0 +1,10 @@
+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;
+}
+export declare const botsFamily: CheckFamily;
+export declare function checkBots(_context: CheckContext, deps?: BotsDoctorDeps): CheckResult[];
+//# sourceMappingURL=bots.d.ts.map

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

@@ -0,0 +1,149 @@
+/**
+ * Local-bot doctor family: a running bot that cannot poll its inbox or
+ * heartbeat still looked healthy (`hq bot status` said online, `hq doctor`
+ * had no bot check). Offline, from ~/.hq/bots and installed LaunchAgents.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+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";
+export const BOTS_FAMILY_ID = "bots";
+export const BOTS_FAMILY_TITLE = "Local bots";
+const DEFAULT_DEPS = {
+    home: () => os.homedir(),
+    root: (home) => botsRoot(home ?? os.homedir()),
+};
+export const botsFamily = {
+    id: BOTS_FAMILY_ID,
+    title: BOTS_FAMILY_TITLE,
+    run: (context) => Promise.resolve(checkBots(context)),
+};
+export function checkBots(_context, deps = DEFAULT_DEPS) {
+    try {
+        return runChecks(deps);
+    }
+    catch (error) {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId: "bots.error",
+                message: `local bot checks could not run: ${error.message}`,
+            },
+        ];
+    }
+}
+function launchdPlistHqBinary(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;
+}
+function runChecks(deps) {
+    const home = deps.home();
+    const root = deps.root(home);
+    if (!fs.existsSync(root)) {
+        return [
+            {
+                status: "NA",
+                checkId: "bots.none",
+                message: "No local bots on this computer.",
+            },
+        ];
+    }
+    const names = fs
+        .readdirSync(root, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && readBotConfig(path.join(root, d.name)) !== null)
+        .map((d) => d.name)
+        .sort();
+    if (names.length === 0) {
+        return [
+            {
+                status: "NA",
+                checkId: "bots.none",
+                message: "No local bots on this computer.",
+            },
+        ];
+    }
+    const results = [];
+    for (const name of names) {
+        const dir = botDir(name, root);
+        const config = readBotConfig(dir);
+        if (!config)
+            continue;
+        const status = readBotStatus(dir);
+        const alive = !!status && status.state === "running" && isPidAlive(status.pid);
+        if (alive && status.lastHeartbeatOk === false) {
+            results.push({
+                status: "FAIL",
+                checkId: `bots.${name}.heartbeat`,
+                target: dir,
+                message: `${name} is running but cannot heartbeat to HQ${status.lastHeartbeatError ? ` (${status.lastHeartbeatError})` : ""}.`,
+                remediation: `hq bot logs ${name}`,
+            });
+        }
+        else if (alive) {
+            results.push({
+                status: "PASS",
+                checkId: `bots.${name}.heartbeat`,
+                target: dir,
+                message: `${name} last heartbeat succeeded.`,
+            });
+        }
+        if (alive && status.lastInboxPollOk === false) {
+            results.push({
+                status: "FAIL",
+                checkId: `bots.${name}.inbox`,
+                target: dir,
+                message: `${name} is running but cannot receive messages${status.lastInboxError ? ` (${status.lastInboxError})` : ""}.`,
+                remediation: `hq bot logs ${name}`,
+            });
+        }
+        else if (alive) {
+            results.push({
+                status: "PASS",
+                checkId: `bots.${name}.inbox`,
+                target: dir,
+                message: `${name} last inbox poll succeeded.`,
+            });
+        }
+        const plistPath = path.join(home, "Library", "LaunchAgents", `${launchdLabel(name)}.plist`);
+        if (fs.existsSync(plistPath)) {
+            let hqPath;
+            try {
+                hqPath = launchdPlistHqBinary(fs.readFileSync(plistPath, "utf8"));
+            }
+            catch {
+                hqPath = null;
+            }
+            if (hqPath && !fs.existsSync(hqPath)) {
+                results.push({
+                    status: "FAIL",
+                    checkId: `bots.${name}.daemon-binary`,
+                    target: hqPath,
+                    message: `${name} startup agent points at a missing hq binary.`,
+                    remediation: `hq bot daemon install ${name}`,
+                });
+            }
+            else if (hqPath) {
+                results.push({
+                    status: "PASS",
+                    checkId: `bots.${name}.daemon-binary`,
+                    target: hqPath,
+                    message: `${name} startup agent hq binary is present.`,
+                });
+            }
+        }
+    }
+    if (results.length === 0) {
+        results.push({
+            status: "NA",
+            checkId: "bots.idle",
+            message: `${names.length} local bot(s) are installed and not running.`,
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=bots.js.map

package/dist/lib/doctor/registry.js

@@ -22,6 +22,7 @@ import { runtimeHealthFamily } from "./checks/runtime-health.js";
 import { integrationsFamily } from "./checks/integrations.js";
 import { syncHealthFamily } from "./checks/sync-health.js";
 import { workContextFamily } from "./checks/work-context.js";
+import { botsFamily } from "./checks/bots.js";
 import { fixtureCoverageFamily } from "./fixtures/discover.js";
 import { checkClaudeWiring } from "./checks/claude-wiring.js";
 /**
@@ -256,6 +257,9 @@ export function createDefaultRegistry() {
     // Work context (US-007A): session state files, outbox depth/quarantine,
     // and default-company mode. Local-only reads under ~/.hq/work-context.
     registry.register(workContextFamily);
+    // Local bots: inbox/heartbeat reachability and a LaunchAgent whose hq
+    // path survived an HQ toolchain move. Local-only reads.
+    registry.register(botsFamily);
     return registry;
 }
 //# sourceMappingURL=registry.js.map

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

@@ -34,6 +34,13 @@ export interface InstallResult {
     message: string;
 }
 export declare function detectPlatform(platform?: NodeJS.Platform): DaemonInstallPlatform;
+/**
+ * HQ updates moved the CLI from toolchain/node/bin/hq to
+ * toolchain/npm-global/bin/hq. A LaunchAgent that still names the old path
+ * dies with MODULE_NOT_FOUND on the next restart. Prefer the live npm-global
+ * binary when both exist.
+ */
+export declare function preferStableHqBinary(entry: string): string;
 /** Resolve the hq binary the current shell uses (argv[1] or PATH). */
 export declare function resolveHqBinary(argv?: string[], env?: NodeJS.ProcessEnv): string;
 export declare function resolveNodeBinary(execPath?: string, env?: NodeJS.ProcessEnv): string;

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

@@ -21,11 +21,27 @@ export function detectPlatform(platform = process.platform) {
         return "linux";
     return "other";
 }
+/**
+ * HQ updates moved the CLI from toolchain/node/bin/hq to
+ * toolchain/npm-global/bin/hq. A LaunchAgent that still names the old path
+ * dies with MODULE_NOT_FOUND on the next restart. Prefer the live npm-global
+ * binary when both exist.
+ */
+export function preferStableHqBinary(entry) {
+    const stale = `${path.sep}toolchain${path.sep}node${path.sep}bin${path.sep}`;
+    const stable = `${path.sep}toolchain${path.sep}npm-global${path.sep}bin${path.sep}`;
+    if (!entry.includes(stale))
+        return entry;
+    const candidate = entry.replace(stale, stable);
+    if (candidate !== entry && fs.existsSync(candidate))
+        return path.resolve(candidate);
+    return entry;
+}
 /** Resolve the hq binary the current shell uses (argv[1] or PATH). */
 export function resolveHqBinary(argv = process.argv, env = process.env) {
     const entry = argv[1];
     if (entry && fs.existsSync(entry)) {
-        return path.resolve(entry);
+        return preferStableHqBinary(path.resolve(entry));
     }
     const pathEnv = env.PATH ?? "";
     for (const dir of pathEnv.split(path.delimiter)) {

package/package.json

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