@indigoai-us/hq-cli 5.132.0 → 5.134.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## [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
+
+- Lane follow-ups now probe all enabled, logged-in accounts for an unpinned
+  model, preserve the later quota reset and its source, expire abandoned pickup
+  validation markers with a terminal reason, and parse Codex's ordinal
+  `try again at` reset time.
+
+- `hq sync push` no longer fails every file when the target vault was
+  provisioned on or after 2026-09-19. Those vaults carry an S3 Object Lock
+  default retention rule, and S3 refuses a PutObject into them unless the
+  request carries a content checksum; the CLI's declared `@indigoai-us/hq-cloud`
+  range still allowed a client that sends none, so an affected push reported
+  `400 InvalidRequest: Content-MD5 OR x-amz-checksum- HTTP header is required
+  for Put Object requests with Object Lock parameters` on every file. The
+  dependency floor now starts at the release that attaches the checksum, so no
+  install can resolve a client that cannot write to a locked vault. A CI guard
+  holds the floor.
+
+- Lane creation and re-parenting now allow depth 3. A depth-3 caller and any
+  derived depth 4 lane are refused with `max_lane_depth`.
+
+- Question ageing now derives its two-advance cap from the depth-3 lane cap, so
+  an unanswered worker-lane question reaches the user after two hourly hops.
+
 ## [5.132.0] — 2026-09-22
 
 ### Added
@@ -104,6 +138,16 @@
 
 ## [Unreleased]
 
+- `hq mesh daemon install` and `hq mesh daemon run` unload and remove the
+  legacy `ai.getindigo.hq-work-mesh-listen` unit (LaunchAgent, systemd user
+  unit, or Scheduled Task) so only the daemon subscribes. The daemon writes
+  `~/.hq/work-mesh/live-cache.json` and bumps its cursor once per project-view
+  push. MQTT reconnect logs once per transition into reconnecting instead of
+  on every close. `hq mesh daemon doctor` reports "legacy listener still
+  installed" while that unit remains (US-006).
+
+## [Unreleased]
+
 - Held-event repair no longer treats a later event timestamp as proof that
   metadata belongs to the current session instance. A reused session id stays
   unresolved when the held event's binding episode does not match the current

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

@@ -7,14 +7,14 @@
 import { Command } from "commander";
 import { type OutpostDispatchResult } from "../lib/lanes/outpost-dispatch.js";
 import { emitLaneDecisionEvents, type LaneMesh } from "../lib/lanes/mesh-events.js";
-import { 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 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";
 import { spawnLaneWorker, type KillProcessFn, type ProveDetachedFn, type SpawnProcessFn } from "../lib/lanes/spawn.js";
 export { spawnLaneWorker };
 export { questionBodyAbsPath };
-export declare const MAX_LANE_DEPTH = 2;
+export { MAX_LANE_DEPTH };
 export declare const OUTPOST_ID_PATH = "/etc/outpost/outpost-id";
 export declare const OUTPOST_DIR = "/etc/outpost";
 export declare const LANES_RUNS_REL: string;

package/dist/commands/lanes.js

@@ -17,7 +17,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, 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, 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 { questionBodyAbsPath } from "../lib/lanes/questions.js";
 import { compactionAfterUsage, } from "../lib/lanes/compaction.js";
 import { providerCompactAfterMs } from "../lib/lanes/config.js";
@@ -29,7 +29,7 @@ import { defaultProbe, validateLaneModel, } from "../lib/lanes/models.js";
 import { parseCliModel, refuseOutpostSelfTarget, resolveLaneModel, FOREGROUND_ONLY_RULE, STANDING_AUTHORIZATION, spawnLaneWorker, stopLaneProcesses, } from "../lib/lanes/spawn.js";
 export { spawnLaneWorker };
 export { questionBodyAbsPath };
-export const MAX_LANE_DEPTH = 2;
+export { MAX_LANE_DEPTH };
 export const OUTPOST_ID_PATH = "/etc/outpost/outpost-id";
 export const OUTPOST_DIR = "/etc/outpost";
 export const LANES_RUNS_REL = path.join("workspace", "lanes-runs");
@@ -1092,6 +1092,7 @@ export function pickupFailureUpdater(reasonRaw, details) {
             state: "failed",
             queued_reason: undefined,
             pickup_validation_pending: undefined,
+            pickup_validation_pending_since: undefined,
             terminal_reason: reason,
             terminal_details: details,
         };
@@ -1166,7 +1167,12 @@ export function applyOutpostAccountPickup(hqRoot, laneId, modelDeps = {}) {
             if (current.account === resolved.id && current.pickup_validation_pending === undefined) {
                 return current;
             }
-            return { ...current, account: resolved.id, pickup_validation_pending: undefined };
+            return {
+                ...current,
+                account: resolved.id,
+                pickup_validation_pending: undefined,
+                pickup_validation_pending_since: undefined,
+            };
         });
     }
     catch (err) {
@@ -1315,8 +1321,8 @@ async function runCreate(ctx, opts) {
     // creates wait on. A pinned create checks the pinned account's home. An
     // unpinned create is not bound to an account here (persist re-resolves the
     // balanced account under the lock, so overlapping creates still spread),
-    // so it checks the balanced candidate first and then every other enabled
-    // account the locked selection could land on (codex catalogs are per home
+    // so it checks the balanced candidate first and then every other enabled,
+    // logged-in account the locked selection could land on (codex catalogs are per home
     // and can differ). `validatedAccounts` records which accepted the model
     // or had no readable list, and the balanced pick under the lock is
     // restricted to that set (resolveAccount's allowedAccounts): an account
@@ -1344,26 +1350,68 @@ async function runCreate(ctx, opts) {
             : [
                 candidate,
                 ...Object.keys(accounts)
-                    .filter((id) => id !== candidate && accounts[id]?.enabled)
+                    .filter((id) => id !== candidate &&
+                    accounts[id]?.enabled &&
+                    accountStatus(provider, id, config, { existsSync: ctx.existsSync }).logged_in === true)
                     .sort(),
             ];
+        const checkedAccounts = [];
+        const unsupported = [];
+        const quotaBlocked = [];
+        const quota = loadQuotaState(hqRoot);
         for (const id of toValidate) {
             const home = accounts[id]?.home;
             if (home === undefined)
                 continue;
+            checkedAccounts.push(id);
             try {
                 validateLaneModel(provider, cliModel, home, modelDeps);
-                validatedAccounts.add(id);
             }
             catch (err) {
                 if (!(isLanesError(err) && err.error === "model_unsupported"))
                     throw err;
-                // The account that would run the lane refuses it: refuse now, before
-                // the other lists are read. Another account's refusal only drops it
-                // from the locked selection.
-                if (id === candidate)
-                    throw err;
+                unsupported.push({ account: id, error: err });
+                continue;
+            }
+            const block = quotaBlockFor(quota, provider, id, cliModel, now);
+            if (block.blocked) {
+                quotaBlocked.push({ account: id, block });
+                continue;
+            }
+            validatedAccounts.add(id);
+        }
+        if (validatedAccounts.size === 0 && quotaBlocked.length > 0) {
+            const blocked = quotaBlocked[0];
+            const model = blocked.block.model ?? cliModel;
+            const checkedSuffix = ` Checked accounts: ${checkedAccounts.join(", ")}`;
+            if (blocked.block.reason === "account_model_unavailable") {
+                throw new AccountResolutionError("account_model_unavailable", `Account ${JSON.stringify(blocked.account)} cannot run model ${model ?? "(no model)"}: ${blocked.block.marker ?? "needs credits"}${checkedSuffix}`, {
+                    provider,
+                    account: blocked.account,
+                    model: model ?? null,
+                    marker: blocked.block.marker ?? null,
+                    checked_accounts: checkedAccounts,
+                });
             }
+            throw new AccountResolutionError("account_quota_exhausted", `Account ${JSON.stringify(blocked.account)} is out of quota${blocked.block.quota_reset_at ? ` until ${blocked.block.quota_reset_at}` : ""} for model ${model ?? "(no model)"}${checkedSuffix}`, {
+                provider,
+                account: blocked.account,
+                model: model ?? null,
+                quota_reset_at: blocked.block.quota_reset_at ?? null,
+                checked_accounts: checkedAccounts,
+            });
+        }
+        if (validatedAccounts.size === 0 && unsupported.length > 0) {
+            const first = unsupported[0].error;
+            throw new LanesError(first.error, `${first.message} Checked accounts: ${checkedAccounts.join(", ")}`, {
+                ...first.details,
+                checked_accounts: checkedAccounts,
+                account_errors: unsupported.map(({ account, error }) => ({
+                    account,
+                    accepted: error.details.accepted,
+                    source: error.details.source,
+                })),
+            });
         }
     }
     const threadId = company
@@ -1637,7 +1685,7 @@ function parseRemotePickupJson(stdout) {
     }
     return null;
 }
-function ingestPickupPayload(hqRoot, payload) {
+function ingestPickupPayload(hqRoot, payload, now) {
     const laneId = payload.lane.lane_id;
     if (!laneId) {
         throw new LanesError("outpost_payload_invalid", "Pickup payload lane.lane_id is required", {});
@@ -1646,9 +1694,20 @@ function ingestPickupPayload(hqRoot, payload) {
     // The lane is stored ineligible for admission until the account bind
     // clears the marker (see LaneRecord.pickup_validation_pending).
     const lane = existing === null
-        ? createLane(hqRoot, { ...payload.lane, pickup_validation_pending: true })
-        : existing.state === "queued" && existing.pickup_validation_pending === undefined
-            ? retryUpdateLane(hqRoot, laneId, "command", (current) => current.state === "queued" ? { ...current, pickup_validation_pending: true } : current)
+        ? createLane(hqRoot, {
+            ...payload.lane,
+            updated_at: now.toISOString(),
+            pickup_validation_pending: true,
+            pickup_validation_pending_since: now.toISOString(),
+        })
+        : existing.state === "queued"
+            ? retryUpdateLane(hqRoot, laneId, "command", (current) => current.state === "queued"
+                ? {
+                    ...current,
+                    pickup_validation_pending: true,
+                    pickup_validation_pending_since: now.toISOString(),
+                }
+                : current)
             : existing;
     const dest = runDir(hqRoot, lane.lane_id);
     ensureDir(path.join(dest, "logs"));
@@ -1692,7 +1751,7 @@ async function runPickup(ctx, opts) {
         throw new LanesError("outpost_payload_invalid", `Pickup payload is not JSON: ${err instanceof Error ? err.message : String(err)}`, {});
     }
     const payload = parseOutpostPickupPayload(parsedJson);
-    const ingested = ingestPickupPayload(hqRoot, payload);
+    const ingested = ingestPickupPayload(hqRoot, payload, ctx.now());
     if (ingested.host.kind === "outpost") {
         try {
             refuseOutpostSelfTarget(hqRoot, ingested, {
@@ -2373,15 +2432,26 @@ async function runReparent(ctx, laneId, opts) {
         throw new LanesError("demotion_with_pending_questions", "Cannot increase a lane's depth while it has pending questions", { lane_id: laneId, from_depth: oldDepth, to_depth: newDepth });
     }
     const override = { laneId, senior: nextSenior, depth: newDepth };
+    const descendants = [];
     for (const other of loadAllLanes(hqRoot)) {
         if (other.lane_id === laneId)
             continue;
         if (!walkHitsLane(hqRoot, other.senior, laneId, ctx))
             continue;
-        const d = derivedLaneDepth(hqRoot, other.senior, ctx, override);
-        if (d > MAX_LANE_DEPTH) {
-            throw new LanesError("max_lane_depth", `Re-parent would put descendant ${other.lane_id} at depth ${d}`, { lane_id: other.lane_id, depth: d, max: MAX_LANE_DEPTH });
+        const oldDescendantDepth = derivedLaneDepth(hqRoot, other.senior, ctx);
+        const descendantDepth = derivedLaneDepth(hqRoot, other.senior, ctx, override);
+        if (descendantDepth > MAX_LANE_DEPTH) {
+            throw new LanesError("max_lane_depth", `Re-parent would put descendant ${other.lane_id} at depth ${descendantDepth}`, { lane_id: other.lane_id, depth: descendantDepth, max: MAX_LANE_DEPTH });
         }
+        if (descendantDepth > oldDescendantDepth &&
+            pendingQuestionsForLane(hqRoot, other.lane_id).length > 0) {
+            throw new LanesError("demotion_with_pending_questions", "Cannot increase a lane's depth while it has pending questions", {
+                lane_id: other.lane_id,
+                from_depth: oldDescendantDepth,
+                to_depth: descendantDepth,
+            });
+        }
+        descendants.push({ laneId: other.lane_id, depth: descendantDepth });
     }
     const at = ctx.now().toISOString();
     const updated = casUpdateLane(hqRoot, laneId, (current) => {
@@ -2401,6 +2471,13 @@ async function runReparent(ctx, laneId, opts) {
             }),
         };
     });
+    for (const descendant of descendants) {
+        casUpdateLane(hqRoot, descendant.laneId, (current) => {
+            if (current.depth === descendant.depth)
+                return current;
+            return { ...current, depth: descendant.depth };
+        });
+    }
     for (const question of pending) {
         casUpdateQuestion(hqRoot, question.question_id, (current) => {
             const already = current.routing_history.some((entry) => entry.reason === "reparented" && entry.at === at);
@@ -3019,6 +3096,7 @@ async function runReconcile(ctx, opts) {
         throttleDeps: ctx.throttleDeps,
         livenessDeps: livenessDepsFromCtx(ctx),
         presenceConnected: ctx.presenceConnected,
+        mesh: ctx.mesh,
         env: ctx.env,
     });
     printJson(summary);

package/dist/commands/mesh.js

@@ -1545,7 +1545,10 @@ export function registerMeshCommand(program) {
 }
 async function runDaemonRun(opts = {}) {
     const hqRoot = opts.hqRoot?.trim() || undefined;
-    const handle = await runMeshDaemon(hqRoot ? { hqRoot } : {});
+    const handle = await runMeshDaemon({
+        ...(hqRoot ? { hqRoot } : {}),
+        enableWorkCache: true,
+    });
     // Stay alive until signal handlers call stop + exit.
     await new Promise(() => {
         void handle;

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}`,
             });
         }