@indigoai-us/hq-cli 5.133.0 → 5.135.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## [Unreleased]
 
+## [5.135.0] — 2026-09-23
+
+### Added
+
+- Claude lanes now set Claude Code's `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`
+  control on fresh launches and session resumes.
+  `providers.claude.auto_compact_tokens` sets a positive-integer override, and
+  Codex and Grok launch environments are unchanged.
+
+- Added `hq lanes watch` for bounded state and question polling, plus
+  `hq lanes monitor-check` for Claude Monitor coverage with distinct exit codes
+  for uncovered lanes and unreadable evidence. The reminder text is available
+  from `hq lanes monitor-check --reminder`.
+- Corrected watch JSONL output and question status transitions, bounded Monitor
+  recommendations to the watch limit, and made stale or unreadable Monitor
+  evidence fail closed.
+
+- Lanes can opt selected Codex model ids into fast mode with
+  `providers.codex.fast_mode_models`. Matching fresh and resumed runs pass
+  Codex's `service_tier="fast"` and `fast_mode` settings and record the
+  decision in the lane record and `spawn.json`.
+
+## [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/command-catalog.generated.d.ts

@@ -6744,6 +6744,46 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "JSON on stdout (always)";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "watch";
+        readonly description: "Watch lane state and question changes until all lanes are terminal";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] <lane-id...>";
+        readonly arguments: readonly [{
+            readonly name: "lane-id";
+            readonly required: true;
+            readonly variadic: true;
+        }];
+        readonly options: readonly [{
+            readonly flags: "--interval-ms <ms>";
+            readonly description: "Polling interval, bounded to 100ms–30s";
+        }, {
+            readonly flags: "--json";
+            readonly description: "JSON on stdout (always)";
+        }];
+        readonly subcommands: readonly [];
+    }, {
+        readonly name: "monitor-check";
+        readonly description: "Check that active Claude senior lanes have live Monitor watch tasks";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options]";
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--session <id>";
+            readonly description: "Senior session id";
+        }, {
+            readonly flags: "--engine <engine>";
+            readonly description: "claude | codex | grok; defaults to HQ_CONDUCT_ENGINE or claude";
+        }, {
+            readonly flags: "--reminder";
+            readonly description: "Print the senior Monitor reminder text";
+        }, {
+            readonly flags: "--json";
+            readonly description: "JSON on stdout";
+        }];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "show";
         readonly description: "Show one lane";

package/dist/command-catalog.generated.js

@@ -8716,6 +8716,58 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "watch",
+                "description": "Watch lane state and question changes until all lanes are terminal",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] <lane-id...>",
+                "arguments": [
+                    {
+                        "name": "lane-id",
+                        "required": true,
+                        "variadic": true
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--interval-ms <ms>",
+                        "description": "Polling interval, bounded to 100ms–30s"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "JSON on stdout (always)"
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "monitor-check",
+                "description": "Check that active Claude senior lanes have live Monitor watch tasks",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--session <id>",
+                        "description": "Senior session id"
+                    },
+                    {
+                        "flags": "--engine <engine>",
+                        "description": "claude | codex | grok; defaults to HQ_CONDUCT_ENGINE or claude"
+                    },
+                    {
+                        "flags": "--reminder",
+                        "description": "Print the senior Monitor reminder text"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "JSON on stdout"
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "show",
                 "description": "Show one lane",

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/commands/lanes.d.ts

@@ -1,13 +1,14 @@
 /**
  * `hq lanes` — worker lane management and decision queue (spec §5–§7, §10–§11).
  *
- * Every command prints JSON on stdout and takes no interactive input, except
+ * Existing commands print JSON on stdout and take no interactive input, except
  * `accounts login`, which hands the terminal to the vendor's own sign-in.
+ * `watch` and the monitor reminder are the line-oriented text surfaces.
  */
 import { Command } from "commander";
 import { type OutpostDispatchResult } from "../lib/lanes/outpost-dispatch.js";
 import { emitLaneDecisionEvents, type LaneMesh } from "../lib/lanes/mesh-events.js";
-import { MAX_LANE_DEPTH, type LaneCompanyRef, type LaneRecord, type QuestionRecord, type ResolvedLaneWorker, type SeniorRef, type LivenessDeps, type MachineIdentity, type RunCommand, type ThrottleDeps } from "../lib/lanes/index.js";
+import { MAX_LANE_DEPTH, type LaneCompanyRef, type LaneRecord, type QuestionRecord, type ResolvedLaneWorker, type SeniorRef, type LivenessDeps, type MachineIdentity, type MonitorEvidenceReader, type RunCommand, type ThrottleDeps } from "../lib/lanes/index.js";
 import { questionBodyAbsPath } from "../lib/lanes/questions.js";
 import { type RunCompactionFn } from "../lib/lanes/compaction.js";
 import { type KnownModelsDeps, type ProbeCommand } from "../lib/lanes/models.js";
@@ -76,6 +77,7 @@ export interface LanesCommandDeps {
     fetchText?: (url: string) => Promise<string>;
     runCompaction?: RunCompactionFn;
     locateTranscript?: (home: string, sessionId: string) => string | null;
+    monitorEvidence?: MonitorEvidenceReader;
 }
 export declare function readOutpostIdentity(existsSync?: (p: string) => boolean, readFileSync?: (p: string) => string): OutpostIdentity;
 export declare function parseSeniorRef(raw: string): SeniorRef;

package/dist/commands/lanes.js

@@ -1,8 +1,9 @@
 /**
  * `hq lanes` — worker lane management and decision queue (spec §5–§7, §10–§11).
  *
- * Every command prints JSON on stdout and takes no interactive input, except
+ * Existing commands print JSON on stdout and take no interactive input, except
  * `accounts login`, which hands the terminal to the vendor's own sign-in.
+ * `watch` and the monitor reminder are the line-oriented text surfaces.
  */
 import { spawn, spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
@@ -17,7 +18,7 @@ import { vaultApiFetch } from "../utils/vault-api.js";
 import { openMeshTransport } from "../lib/mesh/client.js";
 import { createLaneMesh, emitLaneDecisionEvents, } from "../lib/lanes/mesh-events.js";
 import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
-import { AccountResolutionError, DEFAULT_ACCOUNT_HOMES, LANE_PROVIDERS, LANE_STATES, PROVIDER_HOME_ENV, QUESTION_STATUSES, SENIOR_KINDS, accountMaxRunning, accountStatus, appendCappedHistory, canonicalizeHome, createLane, decideAdmission, defaultLivenessDeps, defaultSystemdUserDir, defaultThrottleDeps, installDrainHook, installReconcileTimer, providerPathEnv, probeDrainHookRegistration, isLanesError, isLaneVersionConflict, isTerminalLaneState, listAccountStatuses, listLaneIds, listQuestionIds, listSessionLiveness, loadLanesConfig, MAX_LANE_DEPTH, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, parseLaneState, parseLivenessState, parseQuestionStatus, parseSeniorKind, readDaemonPresenceConnected, readLane, retryUpdateLane, readQuestion, resolveAccount, resolveLaneWorker, isLoggedOut, runReconcilePass, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, writeLanesConfig, appendDropboxMessage, answerDropboxMessage, deliveryRefusalReason, resumeCommandRefusal, dropboxDir, dropboxInboxPath, laneAcceptsDropboxDelivery, laneAcceptsOperatorMessage, laneDeliveryMechanism, hasRecordedSessionId, providerSupportsSessionResume, laneIdForAnswerDelivery, operatorMessageRefusalReason, raiseLaneQuestion, sha256Text, writeQuestionBody, } from "../lib/lanes/index.js";
+import { AccountResolutionError, coveredLaneIds, DEFAULT_ACCOUNT_HOMES, LANE_PROVIDERS, LANE_STATES, PROVIDER_HOME_ENV, QUESTION_STATUSES, SENIOR_KINDS, accountMaxRunning, accountStatus, appendCappedHistory, canonicalizeHome, createLane, decideAdmission, defaultLivenessDeps, defaultSystemdUserDir, defaultThrottleDeps, installDrainHook, installReconcileTimer, providerPathEnv, probeDrainHookRegistration, isLanesError, isLaneVersionConflict, isTerminalLaneState, listAccountStatuses, listLaneIds, listQuestionIds, listSessionLiveness, loadLanesConfig, MAX_LANE_DEPTH, MONITOR_ERROR_EXIT_CODE, MONITOR_ENGINES, MONITOR_MAX_TIMEOUT_MS, MONITOR_UNCOVERED_EXIT_CODE, MAX_WATCHED_LANES, monitorReminderText, readLiveMonitorEvidence, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, parseLaneState, parseLivenessState, parseQuestionStatus, parseSeniorKind, readDaemonPresenceConnected, readLane, retryUpdateLane, readQuestion, resolveAccount, resolveLaneWorker, isLoggedOut, runReconcilePass, runLaneWatch, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, writeLanesConfig, appendDropboxMessage, answerDropboxMessage, deliveryRefusalReason, resumeCommandRefusal, dropboxDir, dropboxInboxPath, laneAcceptsDropboxDelivery, laneAcceptsOperatorMessage, laneDeliveryMechanism, hasRecordedSessionId, providerSupportsSessionResume, laneIdForAnswerDelivery, operatorMessageRefusalReason, raiseLaneQuestion, sha256Text, writeQuestionBody, } from "../lib/lanes/index.js";
 import { questionBodyAbsPath } from "../lib/lanes/questions.js";
 import { compactionAfterUsage, } from "../lib/lanes/compaction.js";
 import { providerCompactAfterMs } from "../lib/lanes/config.js";
@@ -62,6 +63,24 @@ function wrap(action) {
         }
     };
 }
+function failText(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`hq lanes: ${message}\n`);
+    process.exit(MONITOR_ERROR_EXIT_CODE);
+}
+function wrapText(action) {
+    return async (...args) => {
+        let code;
+        try {
+            code = await action(...args);
+        }
+        catch (err) {
+            failText(err);
+        }
+        if (code !== 0)
+            process.exit(code);
+    };
+}
 function collectRepeatable(value, previous = []) {
     return previous.concat(value);
 }
@@ -206,6 +225,12 @@ function resolveDeps(deps = {}) {
         probeProvider: deps.probeProvider ?? defaultProbe,
         runCompaction: deps.runCompaction,
         locateTranscript: deps.locateTranscript,
+        monitorEvidence: deps.monitorEvidence ??
+            ((sessionId) => readLiveMonitorEvidence(sessionId, {
+                homedir: () => deps.homedir?.() ?? os.homedir(),
+                env,
+                now: deps.now ?? (() => new Date()),
+            })),
         stageOutpostPayload: deps.stageOutpostPayload ?? defaultStageOutpostPayload,
         dispatchOutpostExec: deps.dispatchOutpostExec ?? defaultDispatchOutpostExec,
         fetchText: deps.fetchText ?? defaultFetchText,
@@ -387,6 +412,115 @@ function loadAllLanes(hqRoot) {
 function loadAllQuestions(hqRoot) {
     return listQuestionIds(hqRoot).map((id) => readQuestion(hqRoot, id));
 }
+const MONITOR_ACTIVE_LANE_STATES = new Set([
+    "running",
+    "queued",
+    "awaiting_input",
+    "blocked",
+]);
+function resolveMonitorEngine(requested, env) {
+    const value = requested?.trim().toLowerCase() ||
+        env.HQ_CONDUCT_ENGINE?.trim().toLowerCase() ||
+        "claude";
+    if (!MONITOR_ENGINES.includes(value)) {
+        throw new LanesError("monitor_invalid_engine", `Unknown monitor-check engine ${JSON.stringify(value)}. Accepted: ${MONITOR_ENGINES.join(", ")}`, { accepted: [...MONITOR_ENGINES], value });
+    }
+    return value;
+}
+async function runWatch(ctx, laneIds, opts) {
+    const rawInterval = opts.intervalMs === undefined ? undefined : Number(opts.intervalMs);
+    await runLaneWatch(ctx.hqRoot(), laneIds, {
+        intervalMs: rawInterval,
+        sleep: ctx.sleep,
+        writeLine: (line) => console.log(opts.json ? JSON.stringify({ event: line }) : line),
+        writeError: (line) => process.stderr.write(`${line}\n`),
+    });
+    return 0;
+}
+function monitorCallsForLaneIds(laneIds) {
+    const calls = [];
+    for (let offset = 0; offset < laneIds.length; offset += MAX_WATCHED_LANES) {
+        const chunk = laneIds.slice(offset, offset + MAX_WATCHED_LANES);
+        calls.push({
+            command: `hq lanes watch ${chunk.join(" ")}`,
+            timeout_ms: MONITOR_MAX_TIMEOUT_MS,
+            persistent: true,
+        });
+    }
+    return calls;
+}
+async function runMonitorCheck(ctx, opts) {
+    if (opts.reminder) {
+        console.log(monitorReminderText());
+        return 0;
+    }
+    const sessionId = opts.session?.trim();
+    if (!sessionId) {
+        throw new LanesError("monitor_session_required", "hq lanes monitor-check requires --session <id> unless --reminder is used");
+    }
+    const engine = resolveMonitorEngine(opts.engine, ctx.env);
+    const activeLanes = loadAllLanes(ctx.hqRoot()).filter((lane) => lane.senior.kind === "session" &&
+        lane.senior.id === sessionId &&
+        MONITOR_ACTIVE_LANE_STATES.has(lane.state));
+    if (engine !== "claude") {
+        if (opts.json) {
+            printJson({
+                ok: true,
+                action: "monitor-check",
+                session_id: sessionId,
+                engine,
+                active_lane_ids: activeLanes.map((lane) => lane.lane_id),
+                covered_lane_ids: [],
+                uncovered_lane_ids: [],
+                skipped: "engine_has_no_claude_monitor",
+            });
+        }
+        return 0;
+    }
+    if (activeLanes.length === 0) {
+        if (opts.json) {
+            printJson({
+                ok: true,
+                action: "monitor-check",
+                session_id: sessionId,
+                engine,
+                active_lane_ids: [],
+                covered_lane_ids: [],
+                uncovered_lane_ids: [],
+            });
+        }
+        return 0;
+    }
+    const evidence = await ctx.monitorEvidence(sessionId);
+    if (evidence.sessionId !== sessionId) {
+        throw new LanesError("monitor_evidence_session_mismatch", `Monitor evidence was for ${JSON.stringify(evidence.sessionId)}, expected ${JSON.stringify(sessionId)}`);
+    }
+    const covered = coveredLaneIds(evidence, ctx.now());
+    const activeIds = activeLanes.map((lane) => lane.lane_id);
+    const uncovered = activeIds.filter((laneId) => !covered.has(laneId));
+    const monitorCalls = monitorCallsForLaneIds(uncovered);
+    if (opts.json) {
+        printJson({
+            ok: uncovered.length === 0,
+            action: "monitor-check",
+            session_id: sessionId,
+            engine,
+            active_lane_ids: activeIds,
+            covered_lane_ids: activeIds.filter((laneId) => covered.has(laneId)),
+            uncovered_lane_ids: uncovered,
+            monitor_call: monitorCalls.length === 1 ? monitorCalls[0] : null,
+            monitor_calls: monitorCalls,
+        });
+    }
+    else if (uncovered.length > 0) {
+        for (const laneId of uncovered)
+            console.log(`uncovered lane: ${laneId}`);
+        for (const monitorCall of monitorCalls) {
+            console.log(`Monitor(command=${JSON.stringify(monitorCall.command)}, timeout_ms=${monitorCall.timeout_ms}, persistent=true)`);
+        }
+    }
+    return uncovered.length > 0 ? MONITOR_UNCOVERED_EXIT_CODE : 0;
+}
 function sessionMetaPath(hqRoot, sessionId) {
     return path.join(hqRoot, "workspace", "sessions", sessionId, "meta.yaml");
 }
@@ -3193,6 +3327,20 @@ export function registerLanesCommand(parent, deps = {}) {
         .action(wrap(async (opts) => {
         await runList(ctx, opts);
     }));
+    lanes
+        .command("watch")
+        .description("Watch lane state and question changes until all lanes are terminal")
+        .argument("<lane-id...>", "Lane ids to watch")
+        .option("--interval-ms <ms>", "Polling interval, bounded to 100ms–30s", "5000")
+        .action(wrapText(async (laneIds, opts) => runWatch(ctx, laneIds, opts)));
+    lanes
+        .command("monitor-check")
+        .description("Check that active Claude senior lanes have live Monitor watch tasks")
+        .option("--session <id>", "Senior session id")
+        .option("--engine <engine>", "claude | codex | grok; defaults to HQ_CONDUCT_ENGINE or claude")
+        .option("--reminder", "Print the senior Monitor reminder text")
+        .option("--json", "JSON on stdout")
+        .action(wrapText(async (opts) => runMonitorCheck(ctx, opts)));
     lanes
         .command("show")
         .description("Show one lane")

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. */