@indigoai-us/hq-cli 5.345.187 → 5.345.189

package/dist/hq-cloud-sync-runner/package.json

@@ -1 +1 @@
-{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.106","bundleSha256":"ae4c7a7b3040977faff6e9ea7f302bc9e46cf77675347788642e362c3337e3fe","formatVersion":1}
+{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.107","bundleSha256":"4ffaf3a579e9222aa2e9a1850e355d4a152d6d3323cf0583154cf28e1d45459a","formatVersion":1}

package/dist/lib/agent-kit/inbox-fetch.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Bounded, once-retried read of the agent's server inbox.
+ *
+ * `hq agent inbox` and the `hq_inbox_read` MCP tool used to do one token mint
+ * and one GET with no deadline and no retry, so three transient conditions
+ * each showed up as a local-mirror fallback that cleared minutes later
+ * (feedback 3e376c49, DEV-4065):
+ *
+ *   - the machine-token cache is shared with the kit poller and heartbeat,
+ *     which re-mint in the same minute each hour; hq-cloud serialises mints
+ *     behind a 20 s lock and throws "... held by another process ..." when it
+ *     gives up waiting;
+ *   - the server bounds its inbox pull at 18 s and answers 503 with
+ *     `Retry-After: 2` when the listing stalls;
+ *   - a half-open socket can hang the GET until the OS drops it.
+ *
+ * Each attempt (mint plus GET) runs under one deadline. A first attempt that
+ * fails for one of those reasons is retried exactly once after a short delay
+ * (the server's `Retry-After`, capped, when it sent one). The second attempt
+ * mints a fresh token, because the first failure may have been the mint. Auth
+ * and not-found answers, and a 200 whose body is invalid, are never retried.
+ * Pure apart from the injected `sleep`/`random`, so tests drive it with fake
+ * timers.
+ */
+import type { MergedInbox } from "./inbox-state.js";
+/** Env override for the per-attempt deadline; values under the floor are raised to it. */
+export declare const AGENT_INBOX_TIMEOUT_ENV = "HQ_AGENT_INBOX_TIMEOUT_MS";
+/** Delay before the one retry when the server sent no usable `Retry-After`. */
+export declare const AGENT_INBOX_RETRY_BASE_MS = 1500;
+/** Jitter added to the base delay, so clients that fail together do not retry together. */
+export declare const AGENT_INBOX_RETRY_JITTER_MS = 500;
+/** Longest wait honoured from a `Retry-After` header. */
+export declare const AGENT_INBOX_RETRY_AFTER_CAP_MS = 5000;
+/** Total attempts: the first read plus one retry. */
+export declare const AGENT_INBOX_MAX_ATTEMPTS = 2;
+export interface InboxFetchResponse {
+    status: number;
+    /** Decoded JSON body, or `undefined` when it did not decode. Never a raw string of response bytes. */
+    body: unknown;
+    /** Parsed numeric `Retry-After` header in seconds, when the server sent one. */
+    retryAfterSeconds?: number;
+}
+export interface FetchServerInboxDeps {
+    /** Mint (or fetch from cache) the machine token. Called again for the retry. */
+    mint: (signal: AbortSignal) => Promise<string>;
+    /** GET the inbox with `token`. Must not throw on a non-2xx status. */
+    fetch: (token: string, signal: AbortSignal) => Promise<InboxFetchResponse>;
+    sleep?: (ms: number) => Promise<void>;
+    /** Uniform [0, 1) source for the jitter. */
+    random?: () => number;
+    /** Per-attempt deadline covering mint plus GET. */
+    timeoutMs?: number;
+}
+export type FetchServerInboxOutcome = {
+    ok: true;
+    response: {
+        status: number;
+        body: unknown;
+    };
+    attempts: number;
+} | {
+    ok: false;
+    error: unknown;
+    attempts: number;
+};
+/** Per-attempt deadline from the env, defaulting to the kit's request timeout. */
+export declare function resolveAgentInboxTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/** Whether a thrown first attempt is worth one more try. */
+export declare function isRetryableInboxError(err: unknown): boolean;
+export declare function isRetryableInboxStatus(status: number): boolean;
+/** `Retry-After` as seconds, or undefined for a missing, non-numeric or negative value. */
+export declare function parseRetryAfterSeconds(header: string | null | undefined): number | undefined;
+/**
+ * Read the server inbox with at most AGENT_INBOX_MAX_ATTEMPTS attempts, each
+ * bounded by `timeoutMs`. Never throws: the outcome carries either the last
+ * response or the last error, plus how many attempts were made.
+ */
+export declare function fetchServerInboxWithRetry(deps: FetchServerInboxDeps): Promise<FetchServerInboxOutcome>;
+/** Suffix added to the degradation note when the retry also failed. */
+export declare const AGENT_INBOX_AFTER_ATTEMPTS_SUFFIX = " (after 2 attempts)";
+export interface AnnotatedInbox extends MergedInbox {
+    /** True whenever the answer is not a complete server read. */
+    stale: boolean;
+    /** Present when more than one attempt was made, so a hard failure is distinct from a single blip. */
+    attempts?: number;
+}
+/**
+ * Add `stale` and, when a retry happened, `attempts` to a merged inbox. A
+ * degraded note after a retry also says so in words.
+ */
+export declare function annotateInboxAttempts(merged: MergedInbox, attempts: number): AnnotatedInbox;
+//# sourceMappingURL=inbox-fetch.d.ts.map

package/dist/lib/agent-kit/inbox-fetch.js

@@ -0,0 +1,135 @@
+/**
+ * Bounded, once-retried read of the agent's server inbox.
+ *
+ * `hq agent inbox` and the `hq_inbox_read` MCP tool used to do one token mint
+ * and one GET with no deadline and no retry, so three transient conditions
+ * each showed up as a local-mirror fallback that cleared minutes later
+ * (feedback 3e376c49, DEV-4065):
+ *
+ *   - the machine-token cache is shared with the kit poller and heartbeat,
+ *     which re-mint in the same minute each hour; hq-cloud serialises mints
+ *     behind a 20 s lock and throws "... held by another process ..." when it
+ *     gives up waiting;
+ *   - the server bounds its inbox pull at 18 s and answers 503 with
+ *     `Retry-After: 2` when the listing stalls;
+ *   - a half-open socket can hang the GET until the OS drops it.
+ *
+ * Each attempt (mint plus GET) runs under one deadline. A first attempt that
+ * fails for one of those reasons is retried exactly once after a short delay
+ * (the server's `Retry-After`, capped, when it sent one). The second attempt
+ * mints a fresh token, because the first failure may have been the mint. Auth
+ * and not-found answers, and a 200 whose body is invalid, are never retried.
+ * Pure apart from the injected `sleep`/`random`, so tests drive it with fake
+ * timers.
+ */
+import { networkTransportErrorCode } from "../../utils/network-transport-error.js";
+import { KIT_REQUEST_TIMEOUT_MIN_MS, KIT_REQUEST_TIMEOUT_MS, KitRequestTimeoutError, withRequestTimeout } from "./run/request-timeout.js";
+/** Env override for the per-attempt deadline; values under the floor are raised to it. */
+export const AGENT_INBOX_TIMEOUT_ENV = "HQ_AGENT_INBOX_TIMEOUT_MS";
+/** Delay before the one retry when the server sent no usable `Retry-After`. */
+export const AGENT_INBOX_RETRY_BASE_MS = 1_500;
+/** Jitter added to the base delay, so clients that fail together do not retry together. */
+export const AGENT_INBOX_RETRY_JITTER_MS = 500;
+/** Longest wait honoured from a `Retry-After` header. */
+export const AGENT_INBOX_RETRY_AFTER_CAP_MS = 5_000;
+/** Total attempts: the first read plus one retry. */
+export const AGENT_INBOX_MAX_ATTEMPTS = 2;
+// 504 is absent on purpose: vaultApiFetch already retries a 504 once
+// (Lambda invoke errors), and a second outer retry would make three GETs.
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503]);
+const LOCK_HELD_RE = /held by another process/i;
+const TRANSPORT_MESSAGE_RE = /\b(fetch failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN)\b/;
+/** Per-attempt deadline from the env, defaulting to the kit's request timeout. */
+export function resolveAgentInboxTimeoutMs(env = process.env) {
+    const raw = env[AGENT_INBOX_TIMEOUT_ENV]?.trim();
+    if (!raw)
+        return KIT_REQUEST_TIMEOUT_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        return KIT_REQUEST_TIMEOUT_MS;
+    return Math.max(KIT_REQUEST_TIMEOUT_MIN_MS, Math.floor(n));
+}
+/** Whether a thrown first attempt is worth one more try. */
+export function isRetryableInboxError(err) {
+    if (err instanceof KitRequestTimeoutError)
+        return true;
+    if (!(err instanceof Error))
+        return false;
+    if (LOCK_HELD_RE.test(err.message))
+        return true;
+    if (networkTransportErrorCode(err) !== null)
+        return true;
+    if (err instanceof TypeError && err.message === "fetch failed")
+        return true;
+    return TRANSPORT_MESSAGE_RE.test(err.message);
+}
+export function isRetryableInboxStatus(status) {
+    return RETRYABLE_STATUSES.has(status);
+}
+/** `Retry-After` as seconds, or undefined for a missing, non-numeric or negative value. */
+export function parseRetryAfterSeconds(header) {
+    if (header === null || header === undefined)
+        return undefined;
+    const trimmed = header.trim();
+    if (!/^\d+(\.\d+)?$/.test(trimmed))
+        return undefined;
+    const n = Number(trimmed);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+function retryDelayMs(retryAfterSeconds, random) {
+    if (retryAfterSeconds !== undefined) {
+        return Math.min(AGENT_INBOX_RETRY_AFTER_CAP_MS, Math.round(retryAfterSeconds * 1000));
+    }
+    return AGENT_INBOX_RETRY_BASE_MS + Math.floor(random() * AGENT_INBOX_RETRY_JITTER_MS);
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Read the server inbox with at most AGENT_INBOX_MAX_ATTEMPTS attempts, each
+ * bounded by `timeoutMs`. Never throws: the outcome carries either the last
+ * response or the last error, plus how many attempts were made.
+ */
+export async function fetchServerInboxWithRetry(deps) {
+    const sleep = deps.sleep ?? defaultSleep;
+    const random = deps.random ?? Math.random;
+    const timeoutMs = deps.timeoutMs ?? KIT_REQUEST_TIMEOUT_MS;
+    let attempts = 0;
+    for (;;) {
+        attempts += 1;
+        const last = attempts >= AGENT_INBOX_MAX_ATTEMPTS;
+        let retryAfterSeconds;
+        try {
+            const res = await withRequestTimeout(timeoutMs, undefined, async (signal) => {
+                const token = await deps.mint(signal);
+                return deps.fetch(token, signal);
+            });
+            if (last || !isRetryableInboxStatus(res.status)) {
+                return { ok: true, response: { status: res.status, body: res.body }, attempts };
+            }
+            retryAfterSeconds = res.retryAfterSeconds;
+        }
+        catch (err) {
+            if (last || !isRetryableInboxError(err))
+                return { ok: false, error: err, attempts };
+        }
+        await sleep(retryDelayMs(retryAfterSeconds, random));
+    }
+}
+/** Suffix added to the degradation note when the retry also failed. */
+export const AGENT_INBOX_AFTER_ATTEMPTS_SUFFIX = ` (after ${AGENT_INBOX_MAX_ATTEMPTS} attempts)`;
+/**
+ * Add `stale` and, when a retry happened, `attempts` to a merged inbox. A
+ * degraded note after a retry also says so in words.
+ */
+export function annotateInboxAttempts(merged, attempts) {
+    const stale = merged.source !== "server";
+    const retried = attempts > 1;
+    const note = merged.note && retried && stale ? `${merged.note}${AGENT_INBOX_AFTER_ATTEMPTS_SUFFIX}` : merged.note;
+    return {
+        entries: merged.entries,
+        source: merged.source,
+        stale,
+        ...(note ? { note } : {}),
+        ...(retried ? { attempts } : {}),
+    };
+}
+//# sourceMappingURL=inbox-fetch.js.map

package/dist/lib/agent-kit/mcp/tools.d.ts

@@ -16,6 +16,7 @@
  * tool result.
  */
 import type { ExternalMachineCreds } from "../creds.js";
+import { type FetchServerInboxDeps } from "../inbox-fetch.js";
 import type { AgentKitPaths } from "../paths.js";
 import { type McpTool } from "./jsonrpc.js";
 export interface HqRunResult {
@@ -32,7 +33,8 @@ export interface McpToolClients {
     paths: Pick<AgentKitPaths, "inboxDir" | "attachmentsDir">;
     /** Run `hq <args…>` as the machine identity; never throws. */
     runHq: (args: string[]) => Promise<HqRunResult>;
-    getToken: () => Promise<string>;
+    /** Machine token; `signal` cancels this caller's wait on a shared mint. */
+    getToken: (signal?: AbortSignal) => Promise<string>;
     /**
      * Whether this kit mirrors the vault to disk. Off by default, and it decides
      * what `hq_search` can honestly do: the local qmd index only exists when
@@ -47,15 +49,22 @@ export interface McpToolClients {
      * key through the presign API, as the machine identity.
      */
     downloadVaultObject: (scopeUid: string, key: string) => Promise<Buffer>;
-    /** Authenticated JSON call against the control plane. */
+    /**
+     * Authenticated JSON call against the control plane. `retryAfterSeconds` is
+     * the server's numeric `Retry-After`, when it sent one.
+     */
     apiJson: (token: string, path: string, init?: {
         method?: string;
         body?: Record<string, unknown>;
         query?: Record<string, string>;
+        signal?: AbortSignal;
     }) => Promise<{
         status: number;
         body: unknown;
+        retryAfterSeconds?: number;
     }>;
+    /** Test seam for hq_inbox_read's bounded retry (sleep, jitter source, per-attempt deadline). */
+    inboxRetry?: Pick<FetchServerInboxDeps, "sleep" | "random" | "timeoutMs">;
 }
 export declare function clampOutput(text: string, max?: number): string;
 /** Vault paths are company-anchored and must not escape. */

package/dist/lib/agent-kit/mcp/tools.js

@@ -19,6 +19,7 @@ import { CLI_VERSION } from "../../../cli-version.js";
 import { peekIdToken } from "../../../utils/id-token.js";
 import { PERSON_AGENT_AUDIENCE_MESSAGE, callerMayUseAudience, defaultAudienceFor, isAgentUid, isRecipientUid } from "../../../lib/notify-recipient.js";
 import { tokenIsMachinePrincipal } from "../../../lib/caller-principal.js";
+import { annotateInboxAttempts, fetchServerInboxWithRetry, resolveAgentInboxTimeoutMs } from "../inbox-fetch.js";
 import { redactAgentInboxItem } from "../inbox-redact.js";
 import { markInboxDone, mergeAgentInbox, readDoneIds, summarizeInboxEntry } from "../inbox-state.js";
 import { AttachmentCompanyUnresolvedError, fetchChatAttachment } from "./attachments.js";
@@ -286,10 +287,21 @@ export function buildAgentMcpTools(clients) {
                 const limit = int(args, "limit", { min: 1, max: 100, fallback: 20 });
                 const includeDone = args.include_done === true;
                 const done = readDoneIds(clients.paths);
-                const { entries, note: serverNote, source } = await mergeAgentInbox(clients.paths, async () => {
-                    const token = await clients.getToken();
-                    return clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`);
+                // Same bounded, once-retried server read as `hq agent inbox`.
+                let attempts = 1;
+                const merged = await mergeAgentInbox(clients.paths, async () => {
+                    const outcome = await fetchServerInboxWithRetry({
+                        timeoutMs: resolveAgentInboxTimeoutMs(process.env),
+                        ...clients.inboxRetry,
+                        mint: (signal) => clients.getToken(signal),
+                        fetch: (token, signal) => clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`, { signal }),
+                    });
+                    attempts = outcome.attempts;
+                    if (!outcome.ok)
+                        throw outcome.error;
+                    return outcome.response;
                 });
+                const { entries, note: serverNote, source, stale, attempts: attemptsMade } = annotateInboxAttempts(merged, attempts);
                 const byId = new Map(entries.map((e) => [e.id, e]));
                 const rows = [...byId.values()]
                     .filter((e) => includeDone || !done.has(e.id))
@@ -299,6 +311,8 @@ export function buildAgentMcpTools(clients) {
                 return textResult(clampOutput(JSON.stringify({
                     count: rows.length,
                     source,
+                    stale,
+                    ...(attemptsMade !== undefined ? { attempts: attemptsMade } : {}),
                     messages: rows,
                     ...(serverNote ? { note: serverNote } : {}),
                     ...(hasFiles ? { attachmentsHint: ATTACHMENTS_HINT } : {}),

package/dist/lib/bot/fleet-local.d.ts

@@ -139,7 +139,9 @@ export declare const HQ_FLEET_LOCAL_RELEASE: FleetLocalReleasePin;
 export declare const HQ_FLEET_LOCAL_PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEASJoapvo0WMTg+Wu3Jvt0nzlXLOBEr+G1aJRi0JkEb4A=\n-----END PUBLIC KEY-----\n";
 export declare function fleetHome(home?: string, env?: NodeJS.ProcessEnv): string;
 export declare function verifyFleetLocalRelease(files: FleetLocalReleaseFiles, release?: FleetLocalReleasePin, publicKey?: string): void;
-export declare function resolveFleetReleaseToken(env?: NodeJS.ProcessEnv): string;
+/** `gh auth token` fallback for the release download token. */
+export declare const FLEET_RELEASE_TOKEN_TIMEOUT_MS = 15000;
+export declare function resolveFleetReleaseToken(env?: NodeJS.ProcessEnv, run?: FleetLocalExec): string;
 export declare function fetchHqFleetReleaseLinks(release: FleetLocalReleasePin): Promise<Map<string, string> | null>;
 export declare const FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS = 30000;
 export declare const FLEET_LOCAL_ARCHIVE_DOWNLOAD_TIMEOUT_MS: number;

package/dist/lib/bot/fleet-local.js

@@ -105,18 +105,24 @@ export function verifyFleetLocalRelease(files, release = HQ_FLEET_LOCAL_RELEASE,
         throw expectedError(`HQ Fleet Local ${release.version} manifest signature is invalid.`);
     }
 }
-export function resolveFleetReleaseToken(env = process.env) {
+/** `gh auth token` fallback for the release download token. */
+export const FLEET_RELEASE_TOKEN_TIMEOUT_MS = 15_000;
+export function resolveFleetReleaseToken(env = process.env, run = execFileSync) {
     for (const name of ["HQ_FLEET_RELEASE_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"]) {
         const value = env[name]?.trim();
         if (value)
             return value;
     }
     try {
-        const value = execFileSync("gh", ["auth", "token"], {
+        // gh can block on a keychain prompt; a create must fail, not hang.
+        const output = run("gh", ["auth", "token"], {
             encoding: "utf8",
             stdio: ["ignore", "pipe", "ignore"],
             windowsHide: true,
-        }).trim();
+            timeout: FLEET_RELEASE_TOKEN_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+        });
+        const value = (Buffer.isBuffer(output) ? output.toString("utf8") : output).trim();
         if (value)
             return value;
     }

package/dist/lib/bot/fleet-python.d.ts

@@ -26,6 +26,12 @@ export interface FleetPython {
 export declare const HQ_FLEET_PYTHON_VERSION = "3.13.17";
 export declare const HQ_FLEET_PYTHON_TOOL: FleetPythonToolPin;
 export declare const FLEET_PYTHON_TOOL_DOWNLOAD_TIMEOUT_MS: number;
+/** Unpacking the pinned installer archive. */
+export declare const FLEET_PYTHON_EXTRACT_TIMEOUT_MS: number;
+/** `uv python install`: downloads and unpacks the private Python. */
+export declare const FLEET_PYTHON_INSTALL_TIMEOUT_MS: number;
+/** `uv python find`: local lookup only. */
+export declare const FLEET_PYTHON_FIND_TIMEOUT_MS = 60000;
 /** One lock for the whole machine: the installer and the private Python are shared by every bot. */
 export declare const FLEET_PYTHON_LOCK_NAME = "hq-fleet-python";
 /**

package/dist/lib/bot/fleet-python.js

@@ -18,6 +18,12 @@ export const HQ_FLEET_PYTHON_TOOL = {
     },
 };
 export const FLEET_PYTHON_TOOL_DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
+/** Unpacking the pinned installer archive. */
+export const FLEET_PYTHON_EXTRACT_TIMEOUT_MS = 2 * 60_000;
+/** `uv python install`: downloads and unpacks the private Python. */
+export const FLEET_PYTHON_INSTALL_TIMEOUT_MS = 15 * 60_000;
+/** `uv python find`: local lookup only. */
+export const FLEET_PYTHON_FIND_TIMEOUT_MS = 60_000;
 /** One lock for the whole machine: the installer and the private Python are shared by every bot. */
 export const FLEET_PYTHON_LOCK_NAME = "hq-fleet-python";
 function expectedError(message) {
@@ -27,9 +33,13 @@ function toolBinaryName(platform) {
     return platform === "win32" ? "uv.exe" : "uv";
 }
 /** The last lines a failed child process wrote, or its exit code, so the user sees why. */
-function causeOf(error) {
+function causeOf(error, timeoutMs) {
     if (error && typeof error === "object") {
         const failure = error;
+        // A child killed by execFileSync's timeout: say so instead of a bare signal.
+        if (failure.code === "ETIMEDOUT") {
+            return timeoutMs !== undefined ? `timed out after ${Math.round(timeoutMs / 1000)}s` : "timed out";
+        }
         const stderr = failure.stderr === undefined ? "" : (Buffer.isBuffer(failure.stderr) ? failure.stderr.toString("utf8") : String(failure.stderr));
         const tail = stderr.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).slice(-3).join(" ");
         if (tail)
@@ -132,10 +142,15 @@ async function installTool(deps) {
         const extracted = path.join(staging, "extracted");
         fs.mkdirSync(extracted, { mode: 0o700 });
         try {
-            run(tarExecutable(platform, deps.env ?? process.env), ["-xf", archive, "-C", extracted], { stdio: ["ignore", "ignore", "pipe"], windowsHide: true });
+            run(tarExecutable(platform, deps.env ?? process.env), ["-xf", archive, "-C", extracted], {
+                stdio: ["ignore", "ignore", "pipe"],
+                windowsHide: true,
+                timeout: FLEET_PYTHON_EXTRACT_TIMEOUT_MS,
+                killSignal: "SIGKILL",
+            });
         }
         catch (error) {
-            throw expectedError(`HQ Fleet Local could not unpack its runtime installer (${causeOf(error)}).`);
+            throw expectedError(`HQ Fleet Local could not unpack its runtime installer (${causeOf(error, FLEET_PYTHON_EXTRACT_TIMEOUT_MS)}).`);
         }
         const unpacked = findFile(extracted, toolBinaryName(platform));
         if (!unpacked)
@@ -179,10 +194,12 @@ async function ensureFleetPythonLocked(root, deps) {
             stdio: ["ignore", "ignore", "pipe"],
             env,
             windowsHide: true,
+            timeout: FLEET_PYTHON_INSTALL_TIMEOUT_MS,
+            killSignal: "SIGKILL",
         });
     }
     catch (error) {
-        throw expectedError(`HQ Fleet Local could not install its private Python ${version} (${causeOf(error)}). If this mentions a download, check your internet connection and retry.`);
+        throw expectedError(`HQ Fleet Local could not install its private Python ${version} (${causeOf(error, FLEET_PYTHON_INSTALL_TIMEOUT_MS)}). If this mentions a download, check your internet connection and retry.`);
     }
     let found;
     try {
@@ -191,11 +208,13 @@ async function ensureFleetPythonLocked(root, deps) {
             env,
             encoding: "utf8",
             windowsHide: true,
+            timeout: FLEET_PYTHON_FIND_TIMEOUT_MS,
+            killSignal: "SIGKILL",
         });
         found = (Buffer.isBuffer(output) ? output.toString("utf8") : output).trim();
     }
     catch (error) {
-        throw expectedError(`HQ Fleet Local installed its private Python but could not locate it (${causeOf(error)}).`);
+        throw expectedError(`HQ Fleet Local installed its private Python but could not locate it (${causeOf(error, FLEET_PYTHON_FIND_TIMEOUT_MS)}).`);
     }
     const python = path.resolve(found);
     if (!found || !fs.existsSync(python) || !isInside(pythonDir, python, platform)) {

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

@@ -20,7 +20,9 @@ export declare const PROBE_SYSTEM_PROMPT = "You are an HQ bot being checked befo
 /** A probe that has not answered by then is reported as `transient`. */
 export declare const PROBE_DEFAULT_TIMEOUT_MS = 120000;
 /** The plain sentence for a failed probe: what is wrong and the one fix. */
-export declare function probeFailureText(cls: RuntimeFailureClass, runtime: BotRuntimeId | string): string;
+export declare function probeFailureText(cls: RuntimeFailureClass, runtime: BotRuntimeId | string, usageLimit?: {
+    resetsAt?: string;
+}): string;
 export interface RuntimeProbeResult {
     ok: boolean;
     /** null when ok; otherwise the same classes a bot's failure DM uses. */
@@ -30,6 +32,10 @@ export interface RuntimeProbeResult {
     runtime: BotRuntimeId;
     /** The model asked for; null = the runtime's own default. */
     model: string | null;
+    /** The tool's plan ran out of usage (class `transient`). */
+    usageLimit?: boolean;
+    /** When that limit resets, as the tool wrote it ("9pm (Asia/Dhaka)"). */
+    resetsAt?: string;
     /** The CLI was too old for `from`, and the probe answered on `to`. */
     modelFallback?: {
         from: string;

package/dist/lib/bot/probe.js

@@ -15,7 +15,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { classifyRuntimeError } from "./runtime-failure.js";
+import { classifyRuntimeError, isRuntimeUsageLimit, usageLimitResetsAt } from "./runtime-failure.js";
 import { runtimeDisplayName } from "./runtime-sign-in.js";
 import { RuntimeError, runRuntimeTurn, runtimeFor } from "./runtime/index.js";
 import { turnEnv } from "./run.js";
@@ -24,8 +24,12 @@ export const PROBE_SYSTEM_PROMPT = "You are an HQ bot being checked before it is
 /** A probe that has not answered by then is reported as `transient`. */
 export const PROBE_DEFAULT_TIMEOUT_MS = 120_000;
 /** The plain sentence for a failed probe: what is wrong and the one fix. */
-export function probeFailureText(cls, runtime) {
+export function probeFailureText(cls, runtime, usageLimit) {
     const tool = runtimeDisplayName(runtime);
+    if (cls === "transient" && usageLimit) {
+        const when = usageLimit.resetsAt ? ` It resets ${usageLimit.resetsAt}.` : "";
+        return `${tool} has hit its plan's usage limit.${when} Check again after it resets, or pick another tool.`;
+    }
     switch (cls) {
         case "signed-out":
             return `${tool} is not signed in on this computer. Sign in to ${tool} in HQ, then check again.`;
@@ -84,11 +88,15 @@ export async function probeBotRuntime(opts) {
         const raw = err instanceof RuntimeError ? `${err.message}\n${err.stderrExcerpt}` : err instanceof Error ? err.message : String(err);
         // Same rule as a bot turn: the runtime's reported error decides, never a tail of its output.
         const cls = classifyRuntimeError(err);
+        const limited = cls === "transient" && isRuntimeUsageLimit(raw);
+        const resetsAt = limited ? usageLimitResetsAt(raw) : undefined;
         return {
             ok: false,
             class: cls,
-            detail: probeFailureText(cls, opts.runtime),
+            detail: probeFailureText(cls, opts.runtime, limited ? { resetsAt } : undefined),
             ...base,
+            ...(limited ? { usageLimit: true } : {}),
+            ...(resetsAt ? { resetsAt } : {}),
             diagnostic: raw.slice(0, 400),
             durationMs: now() - started,
         };

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

@@ -71,6 +71,15 @@ export declare const API_BACKOFF_CAP_MS: number;
 /** Honor Retry-After up to this; a bogus 30-day header must not park the bot. */
 export declare const API_RETRY_AFTER_CAP_MS: number;
 export declare const API_RETRY_AFTER_FLOOR_MS = 1000;
+/**
+ * Delays between startup identity-check tries when HQ cannot be reached
+ * (five tries over about three minutes). After the last one the bot stops in
+ * a visible failed state the person can retry.
+ */
+export declare const STARTUP_VERIFY_RETRY_DELAYS_MS: readonly number[];
+export declare function isTransientApiError(err: unknown): boolean;
+/** Plain failed-state reason after the startup retries run out. */
+export declare function startupUnreachableReason(name: string): string;
 /**
  * How long to wait after a failed inbox poll or heartbeat.
  * 429/5xx (and transport errors) back off exponentially, honouring Retry-After