@indigoai-us/hq-cli 5.133.0 → 5.134.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [5.134.0] — 2026-09-22
+
+### Fixed
+
+- Agent-kit and local-bot heartbeat loops now stop after the server reports an
+  agent identity mismatch instead of retrying indefinitely. `hq doctor` shows
+  the configured and token agent IDs for the mismatch.
+
 ## [5.133.0] — 2026-09-22
 
 ### Fixed

package/dist/commands/agent-kit.d.ts

@@ -23,6 +23,7 @@ import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
 import { type KitService } from "../lib/agent-kit/services.js";
 import { type CronRunner, type RebootCronResult, type DetachedSpawn, type KillFn } from "../lib/agent-kit/fallback.js";
 import { type ServiceHostPaths, type ServiceManagerDeps, type ServiceSetResult } from "../lib/service-manager/index.js";
+import type { HeartbeatCredsSource } from "../lib/heartbeat-identity.js";
 export declare class KitError extends Error {
     constructor(message: string);
 }
@@ -73,6 +74,7 @@ export interface KitRuntime {
     config: KitConfig;
     getToken: () => Promise<string>;
     log: KitLogger;
+    credsSource?: HeartbeatCredsSource;
 }
 export declare function buildKitRuntime(service: KitService | "all"): KitRuntime;
 export declare function runKitService(service: KitService, rt: KitRuntime): Promise<void>;

package/dist/commands/agent-kit.js

@@ -135,6 +135,7 @@ export function formatServiceSet(result) {
 }
 export function buildKitRuntime(service) {
     const paths = agentKitPaths(os.homedir(), process.env);
+    const credsSource = process.env.HQ_MACHINE_CREDS_FILE?.trim() ? "explicit" : "default";
     const creds = requireExternalCreds(paths);
     ensureKitDirs(paths);
     const config = readKitConfig(paths, CLI_VERSION);
@@ -145,7 +146,7 @@ export function buildKitRuntime(service) {
     process.env.HQ_VAULT_API_URL = creds.apiBaseUrl;
     const log = createKitLogger(paths, service, { echo: process.stdout.isTTY === true });
     const getToken = () => ensureCognitoToken({ tokenSource: "machine", interactive: false });
-    return { paths, creds, config, getToken, log };
+    return { paths, creds, config, getToken, log, credsSource };
 }
 export async function runKitService(service, rt) {
     rt.log("info", `${service} starting agent=${rt.creds.entityUid} cli=${CLI_VERSION}`);
@@ -167,6 +168,8 @@ export async function runKitService(service, rt) {
                 getToken: rt.getToken,
                 log: rt.log,
                 components: enabledKitComponents(rt.config),
+                agentUidSource: rt.credsSource === "explicit" ? "env" : "config_file",
+                credsSource: rt.credsSource ?? "default",
             });
             return;
         case "inbox":

package/dist/lib/agent-kit/run/heartbeat.d.ts

@@ -11,6 +11,7 @@
  * The last successful beat is recorded at state/last-heartbeat.json so
  * `hq agent probe` can report its age.
  */
+import { type HeartbeatAgentUidSource, type HeartbeatCredsSource, type HeartbeatIdentityMismatchReporter } from "../../heartbeat-identity.js";
 import { type ComponentStatus } from "../creds.js";
 import type { KitLogger } from "../log.js";
 import { type AgentKitPaths, type KitComponent } from "../paths.js";
@@ -36,9 +37,13 @@ export interface HeartbeatBody {
 }
 export declare function buildHeartbeatBody(paths: Pick<AgentKitPaths, "stateDir">, now?: () => Date, hostInfo?: HeartbeatBody["hostInfo"], components_?: readonly KitComponent[]): HeartbeatBody;
 export interface LastHeartbeat {
+    /** The most recent heartbeat attempt, successful or a terminal identity mismatch. */
     at: string;
     components: Partial<Record<KitComponent, ComponentStatus>>;
     status: number;
+    reason?: "identity_mismatch";
+    configuredAgentUid?: string;
+    tokenAgentUid?: string;
 }
 export declare function writeLastHeartbeat(paths: Pick<AgentKitPaths, "stateDir" | "lastHeartbeatPath">, record: LastHeartbeat): void;
 export declare function readLastHeartbeat(paths: Pick<AgentKitPaths, "lastHeartbeatPath">): LastHeartbeat | null;
@@ -51,12 +56,19 @@ export interface HeartbeatDeps {
     log: KitLogger;
     /** Components this kit runs; defaults to all of them. */
     components?: readonly KitComponent[];
-    post?: (token: string, body: HeartbeatBody) => Promise<number>;
+    post?: (token: string, body: HeartbeatBody) => Promise<number | HeartbeatPostResult>;
     now?: () => Date;
     sleep?: (ms: number) => Promise<void>;
     maxBeats?: number;
+    agentUidSource?: HeartbeatAgentUidSource;
+    credsSource?: HeartbeatCredsSource;
+    reportIdentityMismatch?: HeartbeatIdentityMismatchReporter;
 }
-export declare function defaultHeartbeatPost(agentUid: string, apiBaseUrl: string): (token: string, body: HeartbeatBody) => Promise<number>;
+export interface HeartbeatPostResult {
+    status: number;
+    bodyText?: string;
+}
+export declare function defaultHeartbeatPost(agentUid: string, apiBaseUrl: string): (token: string, body: HeartbeatBody) => Promise<HeartbeatPostResult>;
 export declare function beatOnce(deps: HeartbeatDeps): Promise<boolean>;
 export declare function runHeartbeatLoop(deps: HeartbeatDeps): Promise<void>;
 //# sourceMappingURL=heartbeat.d.ts.map

package/dist/lib/agent-kit/run/heartbeat.js

@@ -14,6 +14,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import { CLI_VERSION } from "../../../cli-version.js";
+import { captureHeartbeatIdentityMismatch, isHeartbeatIdentityMismatch, parseHeartbeatFailureBody, tokenAgentUid, } from "../../heartbeat-identity.js";
 import { vaultApiFetch } from "../../../utils/vault-api.js";
 import { readComponentStatus } from "../creds.js";
 import { KIT_COMPONENTS } from "../paths.js";
@@ -60,36 +61,67 @@ export function defaultHeartbeatPost(agentUid, apiBaseUrl) {
             method: "POST",
             body: body,
         });
-        return res.status;
+        return { status: res.status, bodyText: await res.text().catch(() => "") };
     };
 }
-export async function beatOnce(deps) {
+async function beatOnceResult(deps) {
     const now = deps.now ?? (() => new Date());
     const post = deps.post ?? defaultHeartbeatPost(deps.agentUid, deps.apiBaseUrl);
     const body = buildHeartbeatBody(deps.paths, now, undefined, deps.components ?? KIT_COMPONENTS);
     try {
         const token = await deps.getToken();
-        const status = await post(token, body);
+        const response = await post(token, body);
+        const result = typeof response === "number" ? { status: response } : response;
+        const status = result.status;
         const ok = status >= 200 && status < 300;
         if (ok) {
             writeLastHeartbeat(deps.paths, { at: now().toISOString(), components: body.components, status });
         }
+        else {
+            const failure = parseHeartbeatFailureBody(result.bodyText);
+            if (isHeartbeatIdentityMismatch({ status, code: failure.code, message: failure.message })) {
+                const tokenUid = tokenAgentUid(token);
+                writeLastHeartbeat(deps.paths, {
+                    at: now().toISOString(),
+                    components: body.components,
+                    status,
+                    reason: "identity_mismatch",
+                    configuredAgentUid: deps.agentUid,
+                    ...(tokenUid ? { tokenAgentUid: tokenUid } : {}),
+                });
+                const tokenLabel = tokenUid ?? "unknown";
+                deps.log("warn", `heartbeat stopped: identity mismatch configured agentUid=${deps.agentUid} token agentUid=${tokenLabel}`);
+                (deps.reportIdentityMismatch ?? captureHeartbeatIdentityMismatch)({
+                    runner: "agent-kit",
+                    configuredAgentUid: deps.agentUid,
+                    ...(tokenUid ? { tokenAgentUid: tokenUid } : {}),
+                    agentUidSource: deps.agentUidSource ?? "config_file",
+                    credsSource: deps.credsSource ?? "default",
+                });
+                return { ok: false, stop: true };
+            }
+        }
         deps.log(ok ? "info" : "warn", `heartbeat ${status} ${Object.entries(body.components)
             .map(([name, health]) => `${name}=${health}`)
             .join(" ")}`);
-        return ok;
+        return { ok, stop: false };
     }
     catch (err) {
         deps.log("error", `heartbeat failed: ${err instanceof Error ? err.message : String(err)}`);
-        return false;
+        return { ok: false, stop: false };
     }
 }
+export async function beatOnce(deps) {
+    return (await beatOnceResult(deps)).ok;
+}
 export async function runHeartbeatLoop(deps) {
     const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     let beats = 0;
     for (;;) {
-        await beatOnce(deps);
+        const result = await beatOnceResult(deps);
         beats += 1;
+        if (result.stop)
+            return;
         if (deps.maxBeats !== undefined && beats >= deps.maxBeats)
             return;
         await sleep(deps.intervalMs);

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

@@ -85,8 +85,10 @@ export declare class BotApiError extends Error {
     readonly status: number;
     readonly path: string;
     readonly code?: string | undefined;
+    readonly detail?: string | undefined;
     readonly retryAfterMs?: number | undefined;
-    constructor(status: number, path: string, code?: string | undefined, detail?: string, retryAfterMs?: number | undefined);
+    readonly tokenAgentUid?: string | undefined;
+    constructor(status: number, path: string, code?: string | undefined, detail?: string | undefined, retryAfterMs?: number | undefined, tokenAgentUid?: string | 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;

package/dist/lib/bot/api.js

@@ -6,18 +6,23 @@
  * existing Cognito machinery. `fetch` is injectable for tests.
  */
 import { vaultApiFetch } from "../../utils/vault-api.js";
+import { tokenAgentUid } from "../heartbeat-identity.js";
 import { assertNoSecretKeys } from "./local-config.js";
 export class BotApiError extends Error {
     status;
     path;
     code;
+    detail;
     retryAfterMs;
-    constructor(status, path, code, detail, retryAfterMs) {
+    tokenAgentUid;
+    constructor(status, path, code, detail, retryAfterMs, tokenAgentUid) {
         super(`HQ API ${path} → ${status}${code ? ` ${code}` : ""}${detail ? `: ${detail}` : ""}`);
         this.status = status;
         this.path = path;
         this.code = code;
+        this.detail = detail;
         this.retryAfterMs = retryAfterMs;
+        this.tokenAgentUid = tokenAgentUid;
         this.name = "BotApiError";
     }
 }
@@ -72,7 +77,7 @@ export class BotApi {
         });
         if (!accept.includes(res.status)) {
             const err = await readError(res);
-            throw new BotApiError(res.status, path, err.code, err.detail, retryAfterHeaderMs(res.headers.get("Retry-After")));
+            throw new BotApiError(res.status, path, err.code, err.detail, retryAfterHeaderMs(res.headers.get("Retry-After")), path.endsWith("/heartbeat") ? tokenAgentUid(token) : undefined);
         }
         const text = await res.text();
         return { status: res.status, body: (text ? JSON.parse(text) : {}) };

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

@@ -42,6 +42,7 @@ import type { BotConfig, BotKind } from "./config.js";
 import { type ProgressPosterOptions } from "./progress.js";
 import { type BotLogger } from "./log.js";
 import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult } from "./runtime/index.js";
+import { type HeartbeatAgentUidSource, type HeartbeatCredsSource, type HeartbeatIdentityMismatchReporter } from "../heartbeat-identity.js";
 import { type BotState, type BotStatusFile } from "./status.js";
 export declare const INBOX_POLL_INTERVAL_MS = 2000;
 export declare const HEARTBEAT_INTERVAL_MS = 30000;
@@ -119,6 +120,9 @@ export interface BotRunDeps {
     maxParallelTurns?: number;
     /** Wait between retries while the coding tool needs a sign-in (default SIGN_IN_RETRY_MS). */
     signInRetryMs?: number;
+    agentUidSource?: HeartbeatAgentUidSource;
+    credsSource?: HeartbeatCredsSource;
+    reportIdentityMismatch?: HeartbeatIdentityMismatchReporter;
 }
 export declare const KICKOFF_MESSAGE_ID = "kickoff";
 /**

package/dist/lib/bot/run.js

@@ -59,6 +59,7 @@ import { dmSessionScope } from "./paths.js";
 import { isDmItem, resolveReplyTarget } from "./room-policy.js";
 import { isRuntimeSignInFailure, SIGN_IN_RETRY_MS, signInNeededText } from "./runtime-sign-in.js";
 import { HQ_BOT_AGENT_UID_ENV } from "../../commands/onboard-bot-membership.js";
+import { captureHeartbeatIdentityMismatch, isHeartbeatIdentityMismatch, } from "../heartbeat-identity.js";
 import { clearBotSession, readBotSession, writeBotSession } from "./session.js";
 import { defaultBotStatus, patchBotStatus, readBotStatus } from "./status.js";
 export const INBOX_POLL_INTERVAL_MS = 2_000;
@@ -415,10 +416,38 @@ export async function runBot(deps) {
                 // runtime → model, inbox → task, sync → sync.
                 await api.heartbeat(config.agentUid, { model: modelHealth, task: "ok", sync: "ok" });
                 heartbeatFails = 0;
-                setStatus({ lastHeartbeatAt: now().toISOString(), lastHeartbeatOk: true, lastHeartbeatError: undefined });
+                setStatus({
+                    lastHeartbeatAt: now().toISOString(),
+                    lastHeartbeatOk: true,
+                    lastHeartbeatError: undefined,
+                    lastHeartbeatReason: undefined,
+                    lastHeartbeatConfiguredAgentUid: undefined,
+                    lastHeartbeatTokenAgentUid: undefined,
+                });
                 await sleep(heartbeatIntervalMs);
             }
             catch (err) {
+                if (err instanceof BotApiError &&
+                    isHeartbeatIdentityMismatch({ status: err.status, code: err.code, message: err.detail })) {
+                    const tokenLabel = err.tokenAgentUid ?? "unknown";
+                    const reason = `heartbeat stopped: identity mismatch configured agentUid=${config.agentUid} token agentUid=${tokenLabel}`;
+                    setStatus({
+                        lastHeartbeatOk: false,
+                        lastHeartbeatError: reason.slice(0, 400),
+                        lastHeartbeatReason: "identity_mismatch",
+                        lastHeartbeatConfiguredAgentUid: config.agentUid,
+                        ...(err.tokenAgentUid ? { lastHeartbeatTokenAgentUid: err.tokenAgentUid } : {}),
+                    });
+                    log("warn", reason);
+                    (deps.reportIdentityMismatch ?? captureHeartbeatIdentityMismatch)({
+                        runner: "bot",
+                        configuredAgentUid: config.agentUid,
+                        ...(err.tokenAgentUid ? { tokenAgentUid: err.tokenAgentUid } : {}),
+                        agentUidSource: deps.agentUidSource ?? "config_file",
+                        credsSource: deps.credsSource ?? "default",
+                    });
+                    break;
+                }
                 heartbeatFails += 1;
                 const message = err instanceof Error ? err.message : String(err);
                 setStatus({ lastHeartbeatOk: false, lastHeartbeatError: message.slice(0, 400) });

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

@@ -19,6 +19,10 @@ export interface BotStatusFile {
     lastHeartbeatOk?: boolean;
     /** Last heartbeat error, when lastHeartbeatOk is false. */
     lastHeartbeatError?: string;
+    /** A heartbeat stopped permanently until the bot is restarted with corrected identity config. */
+    lastHeartbeatReason?: "identity_mismatch";
+    lastHeartbeatConfiguredAgentUid?: string;
+    lastHeartbeatTokenAgentUid?: string;
     lastInboxPollAt?: string;
     lastInboxPollOk?: boolean;
     /** Last inbox poll error, when lastInboxPollOk is false. */

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

@@ -76,11 +76,14 @@ function runChecks(deps) {
         const status = readBotStatus(dir);
         const alive = !!status && status.state === "running" && isPidAlive(status.pid);
         if (alive && status.lastHeartbeatOk === false) {
+            const heartbeatMessage = status.lastHeartbeatReason === "identity_mismatch"
+                ? `${name} heartbeat stopped: identity mismatch (configured agent ${status.lastHeartbeatConfiguredAgentUid ?? config.agentUid}; token agent ${status.lastHeartbeatTokenAgentUid ?? "unknown"}).`
+                : `${name} is running but cannot heartbeat to HQ${status.lastHeartbeatError ? ` (${status.lastHeartbeatError})` : ""}.`;
             results.push({
                 status: "FAIL",
                 checkId: `bots.${name}.heartbeat`,
                 target: dir,
-                message: `${name} is running but cannot heartbeat to HQ${status.lastHeartbeatError ? ` (${status.lastHeartbeatError})` : ""}.`,
+                message: heartbeatMessage,
                 remediation: `hq bot logs ${name}`,
             });
         }

package/dist/lib/heartbeat-identity.d.ts

@@ -0,0 +1,29 @@
+import type { CaptureContext } from "@sentry/node";
+export declare const HEARTBEAT_IDENTITY_MISMATCH_CODE = "AGENT_IDENTITY_MISMATCH";
+export type HeartbeatRunner = "agent-kit" | "bot";
+export type HeartbeatAgentUidSource = "config_file" | "env" | "flag";
+export type HeartbeatCredsSource = "explicit" | "default";
+export interface HeartbeatFailure {
+    status: number;
+    code?: string;
+    message?: string;
+}
+export interface HeartbeatIdentityMismatchContext {
+    runner: HeartbeatRunner;
+    configuredAgentUid: string;
+    tokenAgentUid?: string;
+    agentUidSource: HeartbeatAgentUidSource;
+    credsSource: HeartbeatCredsSource;
+}
+export type HeartbeatIdentityMismatchReporter = (context: HeartbeatIdentityMismatchContext) => void;
+/** Parse only the bounded fields the heartbeat route uses for classification. */
+export declare function parseHeartbeatFailureBody(bodyText: string | undefined): {
+    code?: string;
+    message?: string;
+};
+/** Match the server's registered code/name, never an arbitrary 403. */
+export declare function isHeartbeatIdentityMismatch(failure: HeartbeatFailure): boolean;
+/** Read the agent uid claim for diagnostics only; this never authorizes a call. */
+export declare function tokenAgentUid(token: string): string | undefined;
+export declare function captureHeartbeatIdentityMismatch(context: HeartbeatIdentityMismatchContext, captureMessage?: (message: string, context: CaptureContext) => string): void;
+//# sourceMappingURL=heartbeat-identity.d.ts.map

package/dist/lib/heartbeat-identity.js

@@ -0,0 +1,71 @@
+import { CLI_VERSION } from "../cli-version.js";
+import { Sentry } from "../sentry.js";
+import { peekIdToken } from "../utils/id-token.js";
+export const HEARTBEAT_IDENTITY_MISMATCH_CODE = "AGENT_IDENTITY_MISMATCH";
+const AGENT_UID_RE = /^agt_[A-Za-z0-9_-]{1,100}$/;
+function normalize(value) {
+    return (value ?? "").replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+}
+function safeAgentUid(value) {
+    return typeof value === "string" && AGENT_UID_RE.test(value) ? value : undefined;
+}
+/** Parse only the bounded fields the heartbeat route uses for classification. */
+export function parseHeartbeatFailureBody(bodyText) {
+    if (!bodyText)
+        return {};
+    try {
+        const body = JSON.parse(bodyText);
+        const code = typeof body.code === "string" ? body.code.slice(0, 120) : undefined;
+        const message = typeof body.error === "string"
+            ? body.error.slice(0, 300)
+            : typeof body.message === "string"
+                ? body.message.slice(0, 300)
+                : undefined;
+        return { ...(code ? { code } : {}), ...(message ? { message } : {}) };
+    }
+    catch {
+        return {};
+    }
+}
+/** Match the server's registered code/name, never an arbitrary 403. */
+export function isHeartbeatIdentityMismatch(failure) {
+    if (failure.status !== 403)
+        return false;
+    const code = normalize(failure.code);
+    if (code === normalize(HEARTBEAT_IDENTITY_MISMATCH_CODE) || code === "agentidentitymismatcherror")
+        return true;
+    const message = normalize(failure.message);
+    return (message.includes("heartbeatmustbereportedbytheagentsownmachineidentity") ||
+        message.includes("agentidentitymismatcherror"));
+}
+/** Read the agent uid claim for diagnostics only; this never authorizes a call. */
+export function tokenAgentUid(token) {
+    const claims = peekIdToken(token);
+    return (safeAgentUid(claims["custom:entityUid"]) ??
+        safeAgentUid(claims.entityUid) ??
+        safeAgentUid(claims.sub));
+}
+function diagnosticUid(value) {
+    return safeAgentUid(value) ?? "unknown";
+}
+function captureHeartbeatIdentityMismatchMessage(message, context) {
+    return Sentry.captureMessage(message, context);
+}
+export function captureHeartbeatIdentityMismatch(context, captureMessage = captureHeartbeatIdentityMismatchMessage) {
+    const options = {
+        level: "warning",
+        fingerprint: ["heartbeat-identity-mismatch"],
+        tags: {
+            agent_uid_source: context.agentUidSource,
+            creds_source: context.credsSource,
+            runner: context.runner,
+            hq_cli_version: CLI_VERSION,
+        },
+        extra: {
+            configured_agent_uid: diagnosticUid(context.configuredAgentUid),
+            ...(context.tokenAgentUid ? { token_agent_uid: diagnosticUid(context.tokenAgentUid) } : {}),
+        },
+    };
+    captureMessage("heartbeat identity mismatch", options);
+}
+//# sourceMappingURL=heartbeat-identity.js.map

package/package.json

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