@indigoai-us/hq-cli 5.225.0 → 5.226.0

package/dist/lib/doctor/client-health-flag-token.js

@@ -0,0 +1,66 @@
+import { ensureCognitoIdToken } from "../../utils/cognito-session.js";
+export const CLIENT_HEALTH_FLAG_TOKEN_TIMEOUT_MS = 1_000;
+export class MissingFlagTokenError extends Error {
+    constructor() {
+        super("No cached HQ identity token is available");
+        this.name = "MissingFlagTokenError";
+    }
+}
+export class ClientHealthFlagTokenTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Client-health flag token acquisition exceeded its ${timeoutMs} ms bound`);
+        this.name = "ClientHealthFlagTokenTimeoutError";
+    }
+}
+/**
+ * Obtain a non-interactive ID token, separately bounded from the flag read.
+ * ensureCognitoIdToken refreshes expired person sessions and selects machine
+ * identity credentials when the current installation is a machine.
+ */
+export async function getClientHealthFlagToken(provider, timeoutMs = CLIENT_HEALTH_FLAG_TOKEN_TIMEOUT_MS, callerSignal) {
+    if (callerSignal?.aborted) {
+        throw callerSignal.reason ?? new Error("Token acquisition was aborted");
+    }
+    const controller = new AbortController();
+    const signal = callerSignal ? AbortSignal.any([callerSignal, controller.signal]) : controller.signal;
+    const timeout = new ClientHealthFlagTokenTimeoutError(timeoutMs);
+    const timer = setTimeout(() => controller.abort(timeout), timeoutMs);
+    let onAbort;
+    const aborted = new Promise((_resolve, reject) => {
+        onAbort = () => reject(signal.reason ?? new Error("Token acquisition was aborted"));
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+        const acquire = provider ?? ((requestSignal) => ensureCognitoIdToken({ interactive: false, signal: requestSignal }));
+        const acquisition = Promise.resolve().then(() => {
+            if (signal.aborted) {
+                throw signal.reason ?? new Error("Token acquisition was aborted");
+            }
+            return acquire(signal);
+        });
+        const token = await Promise.race([acquisition, aborted]);
+        if (signal.aborted) {
+            throw signal.reason ?? new Error("Token acquisition was aborted");
+        }
+        if (typeof token !== "string" || token.trim().length === 0) {
+            throw new MissingFlagTokenError();
+        }
+        return token;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message.startsWith("No valid HQ session and interactive login is disabled")) {
+            throw new MissingFlagTokenError();
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        if (onAbort)
+            signal.removeEventListener("abort", onAbort);
+    }
+}
+//# sourceMappingURL=client-health-flag-token.js.map

package/dist/lib/doctor/client-health-reason-codes-flag.d.ts

@@ -7,6 +7,7 @@ export interface ClientHealthReasonCodesFlagDependencies {
     env?: NodeJS.ProcessEnv;
     createClient?: (options: FlagClientOptions) => ClientHealthFlagClient;
     getToken?: FlagClientOptions["getToken"];
+    tokenTimeoutMs?: number;
     fetch?: typeof fetch;
     reportFailure?: (error: unknown) => void;
 }

package/dist/lib/doctor/client-health-reason-codes-flag.js

@@ -1,6 +1,6 @@
-import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { createFlagClient, } from "@indigoai-us/hq-flags-client";
 import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
+import { getClientHealthFlagToken } from "./client-health-flag-token.js";
 export const CLIENT_HEALTH_REASON_CODES_FLAG = "client-health-sync-reason-codes";
 export const CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK = false;
 export const CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS = 150;
@@ -39,9 +39,8 @@ export async function clientHealthReasonCodesEnabledForCompany(company, dependen
         return CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
     }
     const companySlug = company.companySlug?.trim() || "";
-    const deadline = AbortSignal.timeout(CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS);
-    const signal = callerSignal ? AbortSignal.any([callerSignal, deadline]) : deadline;
-    const doFetch = dependencies.fetch ?? globalThis.fetch;
+    if (callerSignal?.aborted)
+        return CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
     let client;
     let failed = false;
     let failureReported = false;
@@ -53,6 +52,18 @@ export async function clientHealthReasonCodesEnabledForCompany(company, dependen
         failureReported = true;
         (dependencies.reportFailure ?? reportFlagFailure)(error);
     };
+    let token;
+    try {
+        token = await getClientHealthFlagToken(dependencies.getToken, dependencies.tokenTimeoutMs, callerSignal);
+    }
+    catch (error) {
+        if (!callerSignal?.aborted)
+            reportFailureOnce(error);
+        return CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
+    }
+    const deadline = AbortSignal.timeout(CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS);
+    const signal = callerSignal ? AbortSignal.any([callerSignal, deadline]) : deadline;
+    const doFetch = dependencies.fetch ?? globalThis.fetch;
     try {
         client = (dependencies.createClient ?? createFlagClient)({
             endpoint,
@@ -61,7 +72,7 @@ export async function clientHealthReasonCodesEnabledForCompany(company, dependen
                 ? { companyIdentifiers: [companySlug] }
                 : {}),
             env: {},
-            getToken: dependencies.getToken ?? (() => loadCachedTokens()?.idToken ?? ""),
+            getToken: () => token,
             fetch: (input, init) => doFetch(input, {
                 ...init,
                 signal: combineSignals(init?.signal ?? undefined, signal),

package/dist/lib/doctor/client-health-sentry-flag.d.ts

@@ -7,6 +7,7 @@ export interface ClientHealthSentryFlagDependencies {
     env?: NodeJS.ProcessEnv;
     createClient?: (options: FlagClientOptions) => ClientHealthFlagClient;
     getToken?: FlagClientOptions["getToken"];
+    tokenTimeoutMs?: number;
     fetch?: typeof fetch;
     reportFailure?: (error: unknown) => void;
 }

package/dist/lib/doctor/client-health-sentry-flag.js

@@ -1,6 +1,6 @@
-import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { createFlagClient, } from "@indigoai-us/hq-flags-client";
 import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
+import { getClientHealthFlagToken } from "./client-health-flag-token.js";
 export const CLIENT_HEALTH_SENTRY_DIRECT_FLAG = "client-health.sentry-direct";
 export const CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK = false;
 export const CLIENT_HEALTH_SENTRY_DIRECT_TIMEOUT_MS = 150;
@@ -31,10 +31,8 @@ export async function clientHealthSentryDirectEnabledForCompany(company, depende
     if (!/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid)) {
         return CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK;
     }
-    const companySlug = company.companySlug?.trim() || "";
-    const deadline = AbortSignal.timeout(CLIENT_HEALTH_SENTRY_DIRECT_TIMEOUT_MS);
-    const signal = callerSignal ? AbortSignal.any([callerSignal, deadline]) : deadline;
-    const doFetch = dependencies.fetch ?? globalThis.fetch;
+    if (callerSignal?.aborted)
+        return CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK;
     let client;
     let failed = false;
     let failureReported = false;
@@ -46,6 +44,19 @@ export async function clientHealthSentryDirectEnabledForCompany(company, depende
         failureReported = true;
         (dependencies.reportFailure ?? reportFlagFailure)(error);
     };
+    let token;
+    try {
+        token = await getClientHealthFlagToken(dependencies.getToken, dependencies.tokenTimeoutMs, callerSignal);
+    }
+    catch (error) {
+        if (!callerSignal?.aborted)
+            reportFailureOnce(error);
+        return CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK;
+    }
+    const companySlug = company.companySlug?.trim() || "";
+    const deadline = AbortSignal.timeout(CLIENT_HEALTH_SENTRY_DIRECT_TIMEOUT_MS);
+    const signal = callerSignal ? AbortSignal.any([callerSignal, deadline]) : deadline;
+    const doFetch = dependencies.fetch ?? globalThis.fetch;
     try {
         client = (dependencies.createClient ?? createFlagClient)({
             endpoint: resolveFlagRegistryEndpoint(undefined, env),
@@ -54,7 +65,7 @@ export async function clientHealthSentryDirectEnabledForCompany(company, depende
                 ? { companyIdentifiers: [companySlug] }
                 : {}),
             env: {},
-            getToken: dependencies.getToken ?? (() => loadCachedTokens()?.idToken ?? ""),
+            getToken: () => token,
             fetch: (input, init) => doFetch(input, {
                 ...init,
                 signal: combineSignals(init?.signal ?? undefined, signal),

package/dist/lib/lanes/dropbox.d.ts

@@ -50,6 +50,8 @@ export interface DrainDeps {
     afterRead?: () => void;
     /** Prefix marks archives that belong to one provider turn. */
     archivePrefix?: string;
+    /** Terminal messages with no permitted delivery path are kept separately. */
+    archiveDirectory?: "delivered" | "undeliverable";
 }
 export interface LaneDrainHookInput {
     transcript_path?: string | null;
@@ -68,6 +70,13 @@ export declare function mintClaimId(): string;
 export declare function assertSafeLaneId(laneId: string): void;
 export declare function dropboxDir(hqRoot: string, laneId: string): string;
 export declare function dropboxInboxPath(hqRoot: string, laneId: string): string;
+/** A recovery drain can claim the inbox, draining files, or dead inflight files. */
+export declare function dropboxInboxHasMessages(hqRoot: string, laneId: string): boolean;
+/**
+ * Return a failed recovery claim to the append-only inbox without replacing
+ * messages appended while resume validation or spawn was in progress.
+ */
+export declare function requeueDropboxMessages(hqRoot: string, laneId: string, messages: readonly DropboxMessage[]): void;
 /**
  * Worker tool-call liveness (watcher.ts reads it). A Claude worker run with
  * `--output-format json` writes nothing to worker.out until it exits, so the

package/dist/lib/lanes/dropbox.js

@@ -65,6 +65,75 @@ export function dropboxDir(hqRoot, laneId) {
 export function dropboxInboxPath(hqRoot, laneId) {
     return path.join(dropboxDir(hqRoot, laneId), INBOX_NAME);
 }
+function directoryHasRecoverableFiles(dir, nestedInboxOnly = false) {
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((name) => !name.startsWith("."));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+    for (const name of names) {
+        const candidate = path.join(dir, name);
+        let stat;
+        try {
+            stat = fs.statSync(candidate);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+        if (nestedInboxOnly) {
+            if (!stat.isDirectory())
+                continue;
+            try {
+                const inbox = fs.statSync(path.join(candidate, INBOX_NAME));
+                if (inbox.isFile() && inbox.size > 0)
+                    return true;
+            }
+            catch (err) {
+                if (err.code !== "ENOENT")
+                    throw err;
+            }
+        }
+        else if (stat.isFile() && stat.size > 0) {
+            return true;
+        }
+    }
+    return false;
+}
+function fileHasBytes(filePath) {
+    try {
+        const stat = fs.statSync(filePath);
+        return stat.isFile() && stat.size > 0;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+/** A recovery drain can claim the inbox, draining files, or dead inflight files. */
+export function dropboxInboxHasMessages(hqRoot, laneId) {
+    const box = dropboxDir(hqRoot, laneId);
+    return fileHasBytes(path.join(box, INBOX_NAME)) ||
+        directoryHasRecoverableFiles(path.join(box, DRAINING_DIR)) ||
+        directoryHasRecoverableFiles(path.join(box, INFLIGHT_DIR), true);
+}
+/**
+ * Return a failed recovery claim to the append-only inbox without replacing
+ * messages appended while resume validation or spawn was in progress.
+ */
+export function requeueDropboxMessages(hqRoot, laneId, messages) {
+    if (messages.length === 0)
+        return;
+    const inbox = dropboxInboxPath(hqRoot, laneId);
+    fs.mkdirSync(path.dirname(inbox), { recursive: true });
+    fs.appendFileSync(inbox, messages.map((message) => `${JSON.stringify(message)}\n`).join(""), "utf8");
+}
 /**
  * Worker tool-call liveness (watcher.ts reads it). A Claude worker run with
  * `--output-format json` writes nothing to worker.out until it exits, so the
@@ -220,7 +289,7 @@ export function drainDropboxAtPath(box, depsInput = {}) {
         return [];
     const inbox = path.join(box, INBOX_NAME);
     const draining = path.join(box, DRAINING_DIR);
-    const delivered = path.join(box, DELIVERED_DIR);
+    const delivered = path.join(box, deps.archiveDirectory ?? DELIVERED_DIR);
     const inflightRoot = path.join(box, INFLIGHT_DIR);
     try {
         deps.mkdirSync(box, { recursive: true });

package/dist/lib/lanes/reconcile.d.ts

@@ -81,6 +81,8 @@ export interface ReconcileDeps {
     readRegistryFlag?: typeof readLanesRegistryFlag;
     /** Active-company fallback for questions raised from an unscoped lane. */
     resolveQuestionActiveCompany?: () => Promise<LaneCompanyRef>;
+    /** Resume queued messages after this pass wins a local dead-worker CAS. */
+    recoverQueuedMessages?: (lane: LaneRecord) => Promise<void>;
     /** Detached mesh seam for dead-watcher recovery. */
     mesh?: LaneMesh | null;
     /** Bound on one terminal mesh emit during dead-host recovery. Default 10 s. */

package/dist/lib/lanes/reconcile.js

@@ -1172,6 +1172,18 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                             }
                         }
                     }
+                    if (!deps.dryRun && deps.recoverQueuedMessages) {
+                        try {
+                            await deps.recoverQueuedMessages(result.record);
+                        }
+                        catch (err) {
+                            markDirty(summary, {
+                                kind: "lane",
+                                id: lane.lane_id,
+                                why: `queued message recovery failed: ${err instanceof Error ? err.message : String(err)}`,
+                            });
+                        }
+                    }
                 }
             }
             catch (err) {

package/dist/lib/lanes/watcher-main.js

@@ -5,6 +5,9 @@
  * Usage: node watcher-main.js <lane-id>
  * Requires HQ_ROOT in the environment.
  */
+import { spawnSync } from "node:child_process";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { runWatcherLoop } from "./watcher.js";
 import { LanesError } from "./errors.js";
 import { openMeshTransport } from "../mesh/client.js";
@@ -27,8 +30,21 @@ function main() {
         process.stderr.write("hq lanes watcher: requires lane id argv and HQ_ROOT in the environment\n");
         process.exit(1);
     }
+    const cliEntry = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../index.js");
     void runWatcherLoop(hqRoot, laneId, {
         resolveQuestionActiveCompany,
+        recoverQueuedMessages: async () => {
+            const result = spawnSync(process.execPath, [cliEntry, "lanes", "_recover-queued-messages", laneId], {
+                env: process.env,
+                encoding: "utf8",
+                timeout: 120_000,
+            });
+            if (result.error)
+                throw result.error;
+            if (result.status !== 0) {
+                throw new Error(`recovery command exited ${result.status ?? result.signal ?? "without status"}: ${(result.stderr ?? "").trim()}`);
+            }
+        },
     }).catch((err) => {
         process.stderr.write(`hq lanes watcher: ${err instanceof Error ? err.message : String(err)}${err instanceof Error && err.stack ? `\n${err.stack}` : ""}\n`);
         process.exit(1);

package/dist/lib/lanes/watcher.d.ts

@@ -48,7 +48,7 @@ export declare const WATCHER_HEARTBEAT_MS: number;
  * once the file would exceed this, the oldest complete lines are dropped.
  */
 export declare const WATCHER_OUT_MAX_BYTES: number;
-export declare const WATCHER_DECISION_EVENTS: readonly ["liveness_transition", "silence_deadline", "envelope_observed", "envelope_invalid", "envelope_repair", "classification", "terminal_write", "mesh_event", "mesh_event_failed"];
+export declare const WATCHER_DECISION_EVENTS: readonly ["liveness_transition", "silence_deadline", "envelope_observed", "envelope_invalid", "envelope_repair", "classification", "terminal_write", "message_recovery", "message_recovery_failed", "message_undeliverable", "mesh_event", "mesh_event_failed"];
 /** Terminal reason when the envelope failed to parse after the repair turn (spec §4). */
 export { ENVELOPE_INVALID_REASON };
 export type WatcherDecisionEvent = (typeof WATCHER_DECISION_EVENTS)[number];
@@ -222,6 +222,8 @@ export interface WatcherLoopDeps {
     retrySpawnDeps?: Omit<SpawnLaneDeps, "admissionHost">;
     /** Active-company fallback when an unscoped lane asks from its envelope. */
     resolveQuestionActiveCompany?: () => Promise<LaneCompanyRef>;
+    /** Resume an atomically queued inbox after this watcher wins terminal CAS. */
+    recoverQueuedMessages?: (lane: LaneRecord) => Promise<void>;
 }
 /**
  * Wrap one mesh call. A failed emit is logged as `mesh_event_failed` with
@@ -231,6 +233,7 @@ export interface WatcherLoopDeps {
 export declare function emitMeshSoft(event: string, logDecision: (record: Record<string, unknown>) => void, at: string, fn: (signal: AbortSignal) => Promise<void>, timeoutMs?: number): Promise<boolean>;
 /** Question ids an ask envelope raised, as `raiseEnvelopeQuestions` mints them. */
 export declare function envelopeQuestionIds(laneId: string, envelopeRef: string, envelope: LaneEnvelope, questionIndexes?: readonly number[]): string[];
+/** Detached and synchronous classifiers share one process-identity claim. */
 export declare function runWatcherLoop(hqRoot: string, laneId: string, deps?: WatcherLoopDeps): Promise<void>;
 export type EnvelopeRepairDecision = {
     action: "spawned";

package/dist/lib/lanes/watcher.js

@@ -37,16 +37,16 @@ import { LanesError } from "./errors.js";
 import { questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
 import { isTerminalLaneState, ENVELOPE_INVALID_REASON, parseLaneEnvelope, STORY_STATUSES, } from "./types.js";
 import { laneStories, storyStatusForEnvelope } from "./stories.js";
-import { readLane, retryUpdateLane } from "./store.js";
+import { readLane, retryUpdateLane, withLaneHireLocks } from "./store.js";
 import { readWorkerRunResult } from "./delivery.js";
 import { applyDefaultQuotaHold, quotaSignalFromFields, readQuotaSignal, recordAccountQuota, } from "./quota.js";
 import { PROVIDER_REJECTED_REASON, QUOTA_STATUS, isProviderLoginFailure, providerRejectionDetails, readProviderRejection, } from "./provider-rejection.js";
-import { readToolActivity, toolActivityPath } from "./dropbox.js";
+import { dropboxInboxHasMessages, readToolActivity, toolActivityPath } from "./dropbox.js";
 import { loadLanesConfig, providerProgressEventMinIntervalMs, providerQuotaDefaultHoldMs } from "./config.js";
 import { resolveAdmissionHost as resolveProcessAdmissionHost } from "./admission-host.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneProgressEvent, emitLaneTerminalStateEvent, laneStoryStatusSuppressionKey, progressEventDue, } from "./mesh-events.js";
 import { envelopeQuestionId } from "./questions.js";
-import { laneRunDir, missingPidProbe, probePidRecord, readPidRecord, readProcStarttime, readSpawnManifest, envelopeRepairMode, spawnEnvelopeRepair, retryLaneOnAlternateAccount, } from "./spawn.js";
+import { laneRunDir, missingPidProbe, probePidRecord, readPidRecord, readProcStarttime, readSpawnManifest, envelopeRepairMode, spawnEnvelopeRepair, writePidRecord, retryLaneOnAlternateAccount, } from "./spawn.js";
 /** Spec §5.7: no signal for 20 minutes while the process is still alive. */
 export const SILENCE_MS = 20 * 60 * 1000;
 export const WATCHER_POLL_MS = 5_000;
@@ -66,6 +66,9 @@ export const WATCHER_DECISION_EVENTS = [
     "envelope_repair",
     "classification",
     "terminal_write",
+    "message_recovery",
+    "message_recovery_failed",
+    "message_undeliverable",
     "mesh_event",
     "mesh_event_failed",
 ];
@@ -670,7 +673,56 @@ function defaultSleep(ms) {
         setTimeout(resolve, ms);
     });
 }
+const WATCHER_LOOP_OWNER_FILE = "watcher-loop.pid";
+function claimWatcherLoop(hqRoot, laneId, deps) {
+    const runDir = laneRunDir(hqRoot, laneId);
+    const ownerPath = path.join(runDir, WATCHER_LOOP_OWNER_FILE);
+    const isAlive = deps.isAlive ?? isPidAlive;
+    const readStarttime = deps.readStarttime ?? readProcStarttime;
+    const owner = withLaneHireLocks(hqRoot, [laneId], () => {
+        fs.mkdirSync(runDir, { recursive: true });
+        const existing = readPidRecord(ownerPath);
+        if (existing !== null && probePidRecord(existing, isAlive, readStarttime).alive) {
+            return null;
+        }
+        if (existing !== null)
+            fs.unlinkSync(ownerPath);
+        writePidRecord(ownerPath, {
+            pid: process.pid,
+            starttime: readStarttime(process.pid) ?? readProcStarttime(process.pid) ?? undefined,
+        });
+        const stat = fs.statSync(ownerPath);
+        return { dev: stat.dev, ino: stat.ino };
+    });
+    if (owner === null)
+        return null;
+    return () => {
+        withLaneHireLocks(hqRoot, [laneId], () => {
+            try {
+                const current = fs.statSync(ownerPath);
+                if (current.dev === owner.dev && current.ino === owner.ino)
+                    fs.unlinkSync(ownerPath);
+            }
+            catch (err) {
+                if (err.code !== "ENOENT")
+                    throw err;
+            }
+        });
+    };
+}
+/** Detached and synchronous classifiers share one process-identity claim. */
 export async function runWatcherLoop(hqRoot, laneId, deps = {}) {
+    const release = claimWatcherLoop(hqRoot, laneId, deps);
+    if (release === null)
+        return;
+    try {
+        await runWatcherLoopOwned(hqRoot, laneId, deps);
+    }
+    finally {
+        release();
+    }
+}
+async function runWatcherLoopOwned(hqRoot, laneId, deps) {
     const sleep = deps.sleep ?? defaultSleep;
     const now = deps.now ?? (() => Date.now());
     const isAlive = deps.isAlive ?? isPidAlive;
@@ -1118,6 +1170,28 @@ export async function runWatcherLoop(hqRoot, laneId, deps = {}) {
                         await emitMeshSoft(`lane_${updated.state}`, logDecision, tick.emit.at, (signal) => emitLaneTerminalStateEvent(mesh, updated, updated.state, updated.terminal_reason ?? classification.reason, signal), meshRequestTimeoutMs);
                     }
                 }
+                if (terminalWrite.changed && deps.recoverQueuedMessages) {
+                    try {
+                        if (dropboxInboxHasMessages(hqRoot, laneId)) {
+                            await deps.recoverQueuedMessages(updated);
+                            logDecision({
+                                event: "message_recovery",
+                                at: tick.emit.at,
+                                state: updated.state,
+                            });
+                        }
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        process.stderr.write(`hq lanes watcher: queued message recovery failed for ${laneId}: ${message}\n`);
+                        logDecision({
+                            event: "message_recovery_failed",
+                            at: tick.emit.at,
+                            state: updated.state,
+                            error: message,
+                        });
+                    }
+                }
             }
         }
         lastSignalMs = tick.nextLastSignalMs;

package/dist/utils/cognito-session.d.ts

@@ -114,6 +114,8 @@ export type EnsureCognitoTokenOptions = {
      * cached. Explicit `"person"` never uses machine creds.
      */
     tokenSource?: CognitoTokenSource;
+    /** Cancels bounded, non-interactive person-session refreshes. */
+    signal?: AbortSignal;
 };
 /**
  * On-disk person Cognito cache path for `env` (`HQ_STATE_DIR` or `~/.hq`).
@@ -196,6 +198,12 @@ export declare function readPersonTokenFile(home?: string, env?: NodeJS.ProcessE
  * the response subject differs, put the bytes back and leave them there.
  */
 export declare function refreshActivePersonTokens(cached: CognitoTokens, env?: NodeJS.ProcessEnv): Promise<CognitoTokens>;
+/**
+ * Client-health's short-lived flag read cannot use hq-cloud's unbounded refresh
+ * helper. Reuse its lockfile protocol, attach the caller signal to the refresh
+ * request, and persist only after the request has completed before the deadline.
+ */
+export declare function refreshActivePersonTokensForClientHealth(cached: CognitoTokens, signal: AbortSignal): Promise<CognitoTokens>;
 /** Derive actor kind from an ID token's custom:entity* claims (no verify). */
 export declare function actorKindFromIdToken(idToken: string | undefined): CognitoActorKind;
 /**