@indigoai-us/hq-cli 5.345.188 → 5.345.189

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

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

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

package/dist/lib/bot/run.js

@@ -107,6 +107,49 @@ export const API_BACKOFF_CAP_MS = 5 * 60_000;
 /** Honor Retry-After up to this; a bogus 30-day header must not park the bot. */
 export const API_RETRY_AFTER_CAP_MS = 15 * 60_000;
 export const API_RETRY_AFTER_FLOOR_MS = 1_000;
+/**
+ * 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 const STARTUP_VERIFY_RETRY_DELAYS_MS = [5_000, 15_000, 45_000, 120_000];
+/**
+ * True for failures worth retrying: transport errors (no HQ response at all),
+ * request timeouts, rate limits and server errors. Other 4xx answers are real
+ * refusals and are not retried.
+ */
+const TRANSIENT_NETWORK_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ENOTFOUND",
+    "ETIMEDOUT",
+    "EAI_AGAIN",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+function isNetworkShapedError(err, depth = 0) {
+    if (depth > 4 || !err || typeof err !== "object")
+        return false;
+    const e = err;
+    if (typeof e.code === "string" && TRANSIENT_NETWORK_CODES.has(e.code))
+        return true;
+    if (e.name === "AbortError" || e.name === "TimeoutError")
+        return true;
+    if (err instanceof TypeError && e.message === "fetch failed")
+        return true;
+    return isNetworkShapedError(e.cause, depth + 1);
+}
+export function isTransientApiError(err) {
+    if (err instanceof BotApiError)
+        return err.status === 408 || err.status === 429 || err.status >= 500;
+    // Only network-shaped failures (no HQ answer at all). Auth and programming
+    // errors fail at once.
+    return isNetworkShapedError(err);
+}
+/** Plain failed-state reason after the startup retries run out. */
+export function startupUnreachableReason(name) {
+    return `could not reach HQ to start; check the network, then restart the bot (hq bot start ${name})`;
+}
 /**
  * How long to wait after a failed inbox poll or heartbeat.
  * 429/5xx (and transport errors) back off exponentially, honouring Retry-After
@@ -566,8 +609,57 @@ export async function runBot(deps) {
             setStatus({ lastError: `own ${runtime.id} login missing: run hq bot login ${config.name} --runtime ${runtime.id}` });
     }
     deps.cliUpdate?.startup(log);
+    // Stop handling is registered before the startup identity retries, which
+    // can wait about three minutes: a SIGTERM during a wait must still release
+    // the pid lock and record "stopped" with exit 0. Once the loops start,
+    // signals route to the full stop().
+    const startupAbort = new AbortController();
+    let onStopRequest = () => {
+        stopping = true;
+        startupAbort.abort();
+    };
+    const events = deps.processEvents ?? process;
+    events.once("SIGTERM", () => onStopRequest("abort"));
+    events.once("SIGINT", () => onStopRequest("abort"));
+    events.once("SIGUSR2", () => onStopRequest("drain"));
+    const stoppedDuringStartup = async () => {
+        await finish("stopped", 0, "stop requested");
+        return { stop: async () => { }, done, status: () => null, idle: () => true };
+    };
     try {
-        const record = await api.getAgent(config.agentUid);
+        let record;
+        // A network drop at login used to fail the bot with exit 0, which launchd
+        // KeepAlive{SuccessfulExit:false} never restarts, so one blip kept bots
+        // down for a week. Transient failures now retry with a growing delay
+        // before the bot settles into a visible failed state.
+        for (let attempt = 0;; attempt++) {
+            try {
+                record = await api.getAgent(config.agentUid);
+                if (attempt > 0)
+                    setStatus({ lastError: undefined });
+                break;
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                const delayMs = STARTUP_VERIFY_RETRY_DELAYS_MS[attempt];
+                if (stopping)
+                    return await stoppedDuringStartup();
+                if (!isTransientApiError(err))
+                    throw err;
+                if (delayMs === undefined) {
+                    log("error", `could not reach HQ to verify bot identity: ${detail}`);
+                    await finish("failed", 0, startupUnreachableReason(config.name));
+                    return { stop: async () => { }, done, status: () => null, idle: () => true };
+                }
+                log("warn", `could not reach HQ to verify bot identity (try ${attempt + 1} of ${STARTUP_VERIFY_RETRY_DELAYS_MS.length + 1}): ${detail}; retrying in ${Math.round(delayMs / 1000)}s`);
+                setStatus({ lastError: "Could not reach HQ yet; retrying" });
+                await sleep(delayMs, startupAbort.signal);
+                if (stopping)
+                    return await stoppedDuringStartup();
+            }
+        }
+        if (stopping)
+            return await stoppedDuringStartup();
         // Promotion keeps the identity and owner. Ownership alone must not let
         // an old local installation start consuming the cloud bot's inbox.
         if (record.uid !== config.agentUid || record.computeMode !== "local" || record.botKind !== kind) {
@@ -650,6 +742,10 @@ export async function runBot(deps) {
     // Read before the kickoff can write its own marker: whatever is here now was
     // left by a previous run that was cut off mid-turn.
     const leftovers = readInflightTurns(dir);
+    // A signal that arrived anywhere in the startup stretch above ends the bot
+    // here, before any outbound DM.
+    if (stopping)
+        return await stoppedDuringStartup();
     // ── Intro DM (once) ────────────────────────────────────────────────────────
     // The kickoff turn is tied to the intro: it runs only in the start that sent
     // the intro, so introSentAt (persisted before the turn) guarantees it never
@@ -666,6 +762,8 @@ export async function runBot(deps) {
         let offered = false;
         if (offerTool) {
             try {
+                if (stopping)
+                    return await stoppedDuringStartup();
                 await api.sendDm({ toPersonUid: config.ownerUid, body: setupToolOfferText(offerTool, setupWelcomeOpening(config.intro)) });
                 patchBotConfig(dir, { introSentAt: now().toISOString() });
                 log("info", "intro DM sent to owner, leading into the app offer");
@@ -676,6 +774,8 @@ export async function runBot(deps) {
                 log("warn", `coding tool offer could not be sent as the welcome (${err instanceof Error ? err.message : String(err)}); sending the usual welcome`);
             }
         }
+        if (stopping)
+            return await stoppedDuringStartup();
         if (!offered)
             try {
                 const sent = await api.sendDm({ toPersonUid: config.ownerUid, body: introDmText(config.name, config.runtime, config.intro, { kind: effectiveBotKind(config), companies: effectiveBotCompanies(config) }) });
@@ -701,6 +801,8 @@ export async function runBot(deps) {
                 log("warn", `intro DM failed (will retry next start): ${err instanceof Error ? err.message : String(err)}`);
             }
     }
+    if (stopping)
+        return await stoppedDuringStartup();
     // ── Heartbeat loop ─────────────────────────────────────────────────────────
     const failures = new FailureWindow(FAILURE_WINDOW_MS, FAILURE_LIMIT);
     let modelHealth = "ok";
@@ -2639,6 +2741,10 @@ export async function runBot(deps) {
     // app know before any message arrives. A tool that cannot be asked changes
     // nothing; the first turn then reports for itself.
     await runSignInCheck("start");
+    // A signal during the sign-in probe arrives before the full stop() is wired
+    // up below: end here, before the kickoff can send a "needs a sign-in" DM.
+    if (stopping)
+        return await stoppedDuringStartup();
     // The kickoff runs alongside the heartbeat, before the first inbox poll, so
     // an owner message sent meanwhile is answered after it in the same session.
     const kickoff = kickoffAfterIntro
@@ -2837,9 +2943,15 @@ export async function runBot(deps) {
         // bot then exits 0 and stays down instead of being restarted.
         cliUpdatePending = null;
         if (stopping) {
+            // Already stopping (an earlier stop, a startup signal, or an update
+            // restart): still wait for the loops and finish, so this call ends the
+            // bot too. finish() is a no-op once the bot has stopped.
             if (mode === "abort")
                 for (const turn of currentTurns)
                     turn.abort();
+            activeInboxWait?.abort();
+            await Promise.allSettled([heartbeatLoop, inboxLoop]);
+            await finish("stopped", 0, "stop requested");
             return;
         }
         stopping = true;
@@ -2853,13 +2965,7 @@ export async function runBot(deps) {
         await Promise.allSettled([heartbeatLoop, inboxLoop]);
         await finish("stopped", 0, mode === "drain" ? "drain completed (running turns finished)" : "stop requested");
     };
-    const onSignal = () => {
-        void stop();
-    };
-    const events = deps.processEvents ?? process;
-    events.once("SIGTERM", onSignal);
-    events.once("SIGINT", onSignal);
-    events.once("SIGUSR2", () => { void stop("drain"); });
+    onStopRequest = (mode) => { void stop(mode); };
     void inboxLoop.then(() => { if (hasPromotionHold(dir))
         void stop("drain"); });
     setStatus({ canDrainForPromotion: true });

package/dist/lib/bot/runtime-failure.d.ts

@@ -39,6 +39,9 @@ export declare const RUNTIME_REPAIR_ACTIONS: Record<RuntimeRepairClass, RuntimeR
 export declare function isRuntimeRepairClass(cls: RuntimeFailureClass): cls is RuntimeRepairClass;
 /** Sort a runtime's failure text into one class. Order matters: most specific first. */
 export declare function classifyRuntimeFailure(text: string | undefined | null): RuntimeFailureClass;
+export declare function isRuntimeUsageLimit(text: string | undefined | null): boolean;
+/** When a usage limit resets, as the tool wrote it ("9pm (Asia/Dhaka)"), or undefined. */
+export declare function usageLimitResetsAt(text: string | undefined | null): string | undefined;
 export declare function isBunProcessError(text: string | undefined | null): boolean;
 /** A process that exits non-zero this soon, with no stream event, never started its turn. */
 export declare const RUNTIME_CRASH_MAX_MS = 5000;

package/dist/lib/bot/runtime-failure.js

@@ -44,7 +44,15 @@ const VERSION_TOO_OLD_MODEL = /\bthe ['"`]([^'"`\s]{1,128})['"`] model requires
  * Codex with a ChatGPT account".
  */
 const MODEL_UNSUPPORTED = /there'?s an issue with the selected model|\bnot_found_error\b[^\n]{0,200}\bmodel:\s|\bmodel_not_found\b|\b(?:unknown|invalid|unsupported) model\b|\bthe (?:requested )?model ['"`]?[^'"`\s]{1,128}['"`]? (?:does not exist|is not supported|is not available|was not found|has been deprecated)\b|\bmodel ['"`][^'"`\s]{1,128}['"`] (?:does not exist|is not supported|is not available|not found)\b|\bdo(?:es)? not have access to (?:the )?model\b|\bmodel is not supported when using codex with a chatgpt account\b/i;
-const TRANSIENT = /\brate[_ ]limit|\busage[_ ]limit|\byou've hit your usage limit\b|\btoo many requests\b|\b429\b|\boverloaded\b|\b(?:502|503|504|529)\b|\bservice unavailable\b|\bbad gateway\b|\bgateway time-?out\b|\binternal server error\b|\bECONNRESET\b|\bECONNREFUSED\b|\bETIMEDOUT\b|\bENOTFOUND\b|\bEAI_AGAIN\b|\bENETUNREACH\b|\bsocket hang up\b|\bnetwork (?:error|is unreachable)\b|\bstream (?:disconnected|error)\b|\bconnection (?:reset|refused|closed|error)\b|\btimed out\b|\bexceeded \d+ms \(HQ_BOT_TURN_TIMEOUT_MS\)/i;
+/**
+ * The account's plan ran out of usage. Claude Code: "You've hit your weekly
+ * limit · resets 9pm (Asia/Dhaka)", "You've hit your session limit". Codex:
+ * "You've hit your usage limit".
+ */
+const USAGE_LIMIT = /\byou'?ve (?:hit|reached) your (?:[\w-]+ ){0,3}limit\b|\b(?:usage|session|weekly|daily|monthly|5-hour) limit (?:reached|exceeded)\b/i;
+/** "9pm (Asia/Dhaka)" from "... · resets 9pm (Asia/Dhaka)". */
+const USAGE_LIMIT_RESET = /\bresets?(?: at| on)? ([^\n|·]{1,60}?)\s*(?:$|[\n|·])/im;
+const TRANSIENT = /\brate[_ ]limit|\busage[_ ]limit|\btoo many requests\b|\b429\b|\boverloaded\b|\b(?:502|503|504|529)\b|\bservice unavailable\b|\bbad gateway\b|\bgateway time-?out\b|\binternal server error\b|\bECONNRESET\b|\bECONNREFUSED\b|\bETIMEDOUT\b|\bENOTFOUND\b|\bEAI_AGAIN\b|\bENETUNREACH\b|\bsocket hang up\b|\bnetwork (?:error|is unreachable)\b|\bstream (?:disconnected|error)\b|\bconnection (?:reset|refused|closed|error)\b|\btimed out\b|\bexceeded \d+ms \(HQ_BOT_TURN_TIMEOUT_MS\)/i;
 /** Sort a runtime's failure text into one class. Order matters: most specific first. */
 export function classifyRuntimeFailure(text) {
     const t = (text ?? "").trim();
@@ -58,10 +66,20 @@ export function classifyRuntimeFailure(text) {
         return "signed-out";
     if (MODEL_UNSUPPORTED.test(t))
         return "model-unsupported";
-    if (TRANSIENT.test(t))
+    if (TRANSIENT.test(t) || USAGE_LIMIT.test(t))
         return "transient";
     return "unknown";
 }
+export function isRuntimeUsageLimit(text) {
+    return USAGE_LIMIT.test((text ?? "").trim());
+}
+/** When a usage limit resets, as the tool wrote it ("9pm (Asia/Dhaka)"), or undefined. */
+export function usageLimitResetsAt(text) {
+    const t = text ?? "";
+    if (!USAGE_LIMIT.test(t))
+        return undefined;
+    return USAGE_LIMIT_RESET.exec(t)?.[1]?.trim() || undefined;
+}
 /**
  * Bun's process-level error line (Claude Code is a Bun-compiled binary):
  * "error: An unknown error occurred (Unexpected)". The excerpt joins stderr