@indigoai-us/hq-cli 5.345.159 → 5.345.161

package/dist/lib/billing/usage-cost.js

@@ -13,6 +13,8 @@
  *   - optionally, the live cloud file-history listing `hq storage status`
  *     uses, to split storage into current files and old versions and to see a
  *     prune right away (Storage Lens, behind usage-limits, updates daily).
+ *     With the usage statement, the listing is a separate current-storage
+ *     breakdown only; the statement's month-average storage meter is billed.
  * usage-limits also answers `vaults` when the server counts them; without it
  * the vault meter is `not-available`.
  * The call-count meters (syncs, gateway calls, HQ MCP calls, agent runs) have
@@ -145,6 +147,83 @@ export function dailyRollupSource(fetchRows) {
         },
     };
 }
+/** Statement line key (hq-pro `UsageStatementLine.key`) -> rate-card key. */
+const STATEMENT_KEYS = new Set(BUNDLED_USAGE_METER_RATES.map(({ key }) => key));
+/**
+ * Meter readings from a `GET /v1/billing/usage` statement body (hq-pro
+ * src/billing/usage-statement.ts, US-006). `usage` is the natural amount:
+ * counters are the month's total, gauges the mean daily level. Storage comes
+ * in bytes and is converted with the statement's own `storageBytesPerGb`.
+ * A line that is unavailable, not billed yet, or missing is `not-available`,
+ * never zero. Null when the body is not a statement.
+ */
+function centsField(v) {
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
+}
+export function meterReadingsFromStatement(body) {
+    const rec = body !== null && typeof body === "object" && !Array.isArray(body)
+        ? body
+        : null;
+    if (!rec || !Array.isArray(rec.lines))
+        return null;
+    const bytesPerGb = typeof rec.storageBytesPerGb === "number" && rec.storageBytesPerGb > 0
+        ? rec.storageBytesPerGb
+        : BYTES_PER_GB;
+    const byKey = new Map();
+    for (const raw of rec.lines) {
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const line = raw;
+        if (typeof line.key !== "string" || !STATEMENT_KEYS.has(line.key))
+            continue;
+        const key = line.key;
+        const measured = line.status === "measured" || line.status === "partial";
+        const usage = line.usage;
+        if (!measured || typeof usage !== "number" || !Number.isFinite(usage) || usage < 0) {
+            byKey.set(key, { key, value: null, state: "not-available" });
+            continue;
+        }
+        const reading = { key, value: key === "storage" ? usage / bytesPerGb : usage, state: "measured" };
+        const cost = centsField(line.costCents);
+        const projected = centsField(line.projectedCostCents);
+        if (cost !== null && projected !== null) {
+            reading.accrued = {
+                monthToDateUsd: cost / 100,
+                projectedUsd: projected / 100,
+                ...(line.waived === true ? { waived: true } : {}),
+            };
+        }
+        byKey.set(key, reading);
+    }
+    return BUNDLED_USAGE_METER_RATES.map(({ key }) => byKey.get(key) ?? { key, value: null, state: "not-available" });
+}
+/**
+ * The usage statement as a source (`GET /v1/billing/usage`, US-015). The
+ * company statement is owner-gated on the server; a person statement is the
+ * caller's own. `fetchStatement` resolves the decoded body, or null when the
+ * server did not answer.
+ */
+export function usageStatementSource(fetchStatement) {
+    return {
+        name: "usage-statement",
+        async read(scope, now) {
+            const { start, end } = monthWindow(now);
+            const body = await fetchStatement(scope);
+            const meters = meterReadingsFromStatement(body);
+            if (meters === null) {
+                throw new Error("Could not read usage from HQ right now. Try again, or run `hq login` if you are signed out.");
+            }
+            const allowanceCents = centsField(body.allowanceCents);
+            return {
+                scope,
+                source: "usage-statement",
+                period: { start: start.toISOString(), end: end.toISOString(), asOf: now.toISOString() },
+                meters,
+                ...(allowanceCents !== null ? { allowanceUsd: allowanceCents / 100 } : {}),
+            };
+        },
+    };
+}
 /**
  * The one function every caller uses to read a month of usage. Switch the
  * default source here when the US-005 rollup has a read route.
@@ -159,8 +238,15 @@ export async function readMonthUsage(scope, deps, source = usageLimitsSource(dep
     const split = await deps.readStorageSplit(scope).catch(() => null);
     if (!split)
         return base;
-    // The live listing is fresher than the daily Storage Lens figure, so a prune
-    // shows up in the very next read.
+    // An accrued source (the usage statement, the daily rollup) bills storage as
+    // the month's average. That meter is authoritative: the live listing is a
+    // point-in-time figure, kept only as the separate `storage` breakdown that
+    // explains what is taking space. It never replaces or re-prices the meter.
+    if (base.source !== "usage-limits")
+        return { ...base, storage: split };
+    // usage-limits storage is itself a point-in-time reading (Storage Lens,
+    // updated daily). The live listing measures the same thing more freshly, so
+    // a prune shows up in the very next read.
     const liveGb = (split.currentBytes + split.oldVersionBytes) / BYTES_PER_GB;
     return {
         ...base,
@@ -169,7 +255,8 @@ export async function readMonthUsage(scope, deps, source = usageLimitsSource(dep
     };
 }
 const round2 = (n) => Math.round(n * 100) / 100;
-export function computeBill(usage, rates = BUNDLED_USAGE_METER_RATES, allowanceUsd = USAGE_MONTHLY_ALLOWANCE_USD) {
+export function computeBill(usage, rates = BUNDLED_USAGE_METER_RATES, cardAllowanceUsd = USAGE_MONTHLY_ALLOWANCE_USD) {
+    const allowanceUsd = usage.allowanceUsd ?? cardAllowanceUsd;
     const asOf = new Date(usage.period.asOf);
     const { start, end } = monthWindow(asOf);
     const dayMs = 86_400_000;
@@ -187,6 +274,19 @@ export function computeBill(usage, rates = BUNDLED_USAGE_METER_RATES, allowanceU
             incomplete = true;
             return { ...pick(rate), value: null, state: reading.state, monthToDateUsd: null, projectedUsd: null };
         }
+        if (reading.accrued) {
+            const { monthToDateUsd: m, projectedUsd: p, waived } = reading.accrued;
+            mtd += m;
+            projected += p;
+            return {
+                ...pick(rate),
+                value: reading.value,
+                state: "measured",
+                monthToDateUsd: round2(m),
+                projectedUsd: round2(p),
+                ...(waived ? { waivedInTrial: true } : {}),
+            };
+        }
         if (rate.waivedInTrial && usage.trialActive === true) {
             return { ...pick(rate), value: reading.value, state: "measured", monthToDateUsd: 0, projectedUsd: 0, waivedInTrial: true };
         }

package/dist/lib/billing/usage-only.d.ts

@@ -24,8 +24,44 @@
  */
 import { type UsageCard } from "./usage-card.js";
 export type PricingPlan = "usage-only" | "current";
+/** Whether a server supplied shared status (including an unreadable/null value). */
+export declare function hasBillingStateField(body: unknown): boolean;
+export type BillingStateKind = "usage" | "usage-trial" | "legacy-payer" | "legacy-free" | "enterprise" | "comped";
 /**
- * Read the pricing plan out of a decoded hq-pro body. `pricingPlan` wins;
+ * hq-pro's shared plan status (`billingState`, hq-pro #5088
+ * src/billing/billing-state.ts), the fields the CLI reads. Version 1 only.
+ */
+export interface SharedBillingState {
+    kind: BillingStateKind;
+    scope: "company" | "person";
+    view: "full" | "member";
+    trial: {
+        daysLeft: number;
+        endsAt: string;
+    } | null;
+    /** A pause the server is applying now, or null. */
+    paused: {
+        reason: string;
+        resumesOn: string | null;
+    } | null;
+    /** What this caller may do. All false in the member view. */
+    actions: {
+        addCard: boolean;
+        raiseLimit: boolean;
+        switchToUsage: boolean;
+        manageBilling: boolean;
+    };
+}
+/**
+ * Read a known v1 `billingState` off a decoded body. An unknown version,
+ * scope, view or kind (or a malformed trial) is null: it is never read as a
+ * legacy plan. A person state is always the full view.
+ */
+export declare function readBillingState(body: unknown): SharedBillingState | null;
+export { usagePauseFromBody, type UsagePause } from "./usage-pause.js";
+/**
+ * Read the pricing plan out of a decoded hq-pro body. Known `billingState` wins;
+ * only a server without that field uses the legacy `pricingPlan` signal;
  * a `personalUsage` object (person summary) means usage-only. Anything else
  * is UNKNOWN.
  */

package/dist/lib/billing/usage-only.js

@@ -40,8 +40,84 @@ function asRecord(value) {
         ? value
         : null;
 }
+/** Whether a server supplied shared status (including an unreadable/null value). */
+export function hasBillingStateField(body) {
+    const rec = asRecord(body);
+    return rec !== null && Object.prototype.hasOwnProperty.call(rec, "billingState");
+}
+const BILLING_STATE_KINDS = [
+    "usage",
+    "usage-trial",
+    "legacy-payer",
+    "legacy-free",
+    "enterprise",
+    "comped",
+];
+function readTrial(value) {
+    if (value === null || value === undefined)
+        return null;
+    const trial = asRecord(value);
+    if (!trial ||
+        typeof trial.daysLeft !== "number" ||
+        !Number.isFinite(trial.daysLeft) ||
+        trial.daysLeft < 0 ||
+        typeof trial.endsAt !== "string" ||
+        !Number.isFinite(Date.parse(trial.endsAt))) {
+        return undefined;
+    }
+    return { daysLeft: trial.daysLeft, endsAt: trial.endsAt };
+}
+function readPaused(value) {
+    const paused = asRecord(value);
+    if (!paused || typeof paused.reason !== "string" || !paused.reason)
+        return null;
+    return {
+        reason: paused.reason,
+        resumesOn: typeof paused.resumesOn === "string" ? paused.resumesOn : null,
+    };
+}
 /**
- * Read the pricing plan out of a decoded hq-pro body. `pricingPlan` wins;
+ * Read a known v1 `billingState` off a decoded body. An unknown version,
+ * scope, view or kind (or a malformed trial) is null: it is never read as a
+ * legacy plan. A person state is always the full view.
+ */
+export function readBillingState(body) {
+    const state = asRecord(asRecord(body)?.billingState);
+    if (!state || state.version !== 1)
+        return null;
+    if (state.scope !== "company" && state.scope !== "person")
+        return null;
+    if (state.view !== "full" && state.view !== "member")
+        return null;
+    if (state.scope === "person" && state.view !== "full")
+        return null;
+    if (typeof state.kind !== "string" || !BILLING_STATE_KINDS.includes(state.kind))
+        return null;
+    const trial = readTrial(state.trial);
+    if (trial === undefined)
+        return null;
+    const actions = asRecord(state.actions);
+    return {
+        kind: state.kind,
+        scope: state.scope,
+        view: state.view,
+        trial,
+        paused: readPaused(state.paused),
+        actions: {
+            addCard: actions?.addCard === true,
+            raiseLimit: actions?.raiseLimit === true,
+            switchToUsage: actions?.switchToUsage === true,
+            manageBilling: actions?.manageBilling === true,
+        },
+    };
+}
+function sharedBillingState(body) {
+    return readBillingState(body);
+}
+export { usagePauseFromBody } from "./usage-pause.js";
+/**
+ * Read the pricing plan out of a decoded hq-pro body. Known `billingState` wins;
+ * only a server without that field uses the legacy `pricingPlan` signal;
  * a `personalUsage` object (person summary) means usage-only. Anything else
  * is UNKNOWN.
  */
@@ -49,6 +125,10 @@ export function pricingPlanFromBody(body) {
     const rec = asRecord(body);
     if (!rec)
         return null;
+    if (hasBillingStateField(rec)) {
+        const state = sharedBillingState(rec);
+        return state ? (state.kind === "usage" || state.kind === "usage-trial" ? "usage-only" : "current") : null;
+    }
     if (rec.pricingPlan === "usage-only")
         return "usage-only";
     if (rec.pricingPlan === "current")
@@ -62,6 +142,8 @@ export function isUsageOnly(plan) {
 }
 /** True when a company summary says a usage-only trial is running. Absent is false. */
 export function usageTrialActiveFromBody(body) {
+    if (hasBillingStateField(body))
+        return sharedBillingState(body)?.kind === "usage-trial";
     return asRecord(asRecord(body)?.usageTrial)?.status === "active";
 }
 async function defaultGetJson(token, path, query, timeoutMs) {
@@ -111,9 +193,12 @@ export function pricingPlanFromMembership(body, companyRef) {
         const slug = typeof row.companySlug === "string" ? row.companySlug.toLowerCase() : "";
         if (uid !== ref && slug !== ref)
             continue;
-        if (row.pricingPlan === "usage-only" || row.pricingPlan === "current")
-            return row.pricingPlan;
-        return null;
+        if (hasBillingStateField(row)) {
+            const state = sharedBillingState(row);
+            if (!state || state.scope !== "company")
+                return null;
+        }
+        return pricingPlanFromBody(row);
     }
     return null;
 }

package/dist/lib/billing/usage-pause.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The usage pause block on a 402 body (hq-pro src/billing/usage-pause.ts,
+ * US-024): `{ code: "usage_paused", reason, message, actionUrl }`.
+ *
+ * Every refusal hq-pro makes because of an account's usage state (the trial
+ * cap, a card needed past the monthly allowance, the monthly spend limit)
+ * carries it. A client shows `message` as written and links `actionUrl`; it
+ * adds no plan name and no upgrade offer.
+ *
+ * Leaf module (no imports) so the sync refusal tracker and the 402 decoder
+ * can share it without loading the HTTP layer.
+ */
+export declare const USAGE_PAUSE_CODE = "usage_paused";
+export interface UsagePause {
+    /** `usage_trial_cap` | `usage_card_required` | `usage_spend_limit` (or a newer code). */
+    reason: string;
+    /** One plain-language paragraph from the server. */
+    message: string;
+    /** Where to act: the company or personal Billing page (https). */
+    actionUrl?: string;
+}
+/**
+ * Read `usagePause` off a decoded 402 body, or off any record that carries
+ * it. Null when absent or malformed (wrong code, empty message).
+ */
+export declare function usagePauseFromBody(body: unknown): UsagePause | null;
+//# sourceMappingURL=usage-pause.d.ts.map

package/dist/lib/billing/usage-pause.js

@@ -0,0 +1,50 @@
+/**
+ * The usage pause block on a 402 body (hq-pro src/billing/usage-pause.ts,
+ * US-024): `{ code: "usage_paused", reason, message, actionUrl }`.
+ *
+ * Every refusal hq-pro makes because of an account's usage state (the trial
+ * cap, a card needed past the monthly allowance, the monthly spend limit)
+ * carries it. A client shows `message` as written and links `actionUrl`; it
+ * adds no plan name and no upgrade offer.
+ *
+ * Leaf module (no imports) so the sync refusal tracker and the 402 decoder
+ * can share it without loading the HTTP layer.
+ */
+export const USAGE_PAUSE_CODE = "usage_paused";
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function httpsUrl(value) {
+    if (typeof value !== "string" || value.trim() !== value)
+        return undefined;
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && url.hostname && !url.username && !url.password
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read `usagePause` off a decoded 402 body, or off any record that carries
+ * it. Null when absent or malformed (wrong code, empty message).
+ */
+export function usagePauseFromBody(body) {
+    const pause = asRecord(asRecord(body)?.usagePause);
+    if (!pause || pause.code !== USAGE_PAUSE_CODE)
+        return null;
+    const message = typeof pause.message === "string" ? pause.message.trim() : "";
+    if (!message)
+        return null;
+    const actionUrl = httpsUrl(pause.actionUrl);
+    return {
+        reason: typeof pause.reason === "string" ? pause.reason : "",
+        message,
+        ...(actionUrl ? { actionUrl } : {}),
+    };
+}
+//# sourceMappingURL=usage-pause.js.map

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

@@ -6,8 +6,9 @@ export declare function ensureBotLog(dir: string): string;
 export declare function rotateBotLogIfNeeded(dir: string, maxBytes?: number): void;
 /** Strip anything that looks like a bearer token, secret, or op:// ref. */
 export declare function redactForLog(message: string): string;
-export declare function botLogLine(level: "info" | "warn" | "error", message: string, now?: () => Date): string;
+export type BotLogLevel = "debug" | "info" | "warn" | "error";
+export declare function botLogLine(level: BotLogLevel, message: string, now?: () => Date): string;
 export declare function appendBotLog(dir: string, line: string): void;
-export type BotLogger = (level: "info" | "warn" | "error", message: string) => void;
+export type BotLogger = (level: BotLogLevel, message: string) => void;
 export declare function createBotLogger(dir: string, now?: () => Date): BotLogger;
 //# sourceMappingURL=log.d.ts.map

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

@@ -54,7 +54,23 @@ export interface ProgressPosterOptions {
      * it, anything else (another message, the end of the turn) keeps it.
      */
     dropPreToolMessages?: boolean;
+    /**
+     * Called with each message dropped because a tool call followed it (see
+     * `dropPreToolMessages` and `isPreToolAside`), so the bot log can record it.
+     */
+    onDropped?: (text: string) => void;
 }
+/** Below this many characters a message right before a tool call is an aside, not a progress note. */
+export declare const PRE_TOOL_ASIDE_MAX_CHARS = 40;
+/**
+ * True for a short assistant text that is an aside to itself when a tool call
+ * follows it ("Bind first, separately." reached a person on 2026-10-13: the
+ * model thinking out loud before a tool_use in the same assistant message).
+ * Real progress notes are full sentences addressed to the person ("Reading
+ * your agency docs now, then I'll look at the client folders.") and run past
+ * the limit; an hq-block is always content the desktop app must draw.
+ */
+export declare function isPreToolAside(text: string): boolean;
 /** Whitespace-insensitive form used to recognise repeated text. */
 export declare function normalizeForCompare(text: string): string;
 /** Matches {"action":"no_reply"} anywhere in a model reply, with or without preamble text. */
@@ -71,7 +87,13 @@ export declare class ProgressPoster {
     private readonly workingNoticeText;
     private readonly buffer;
     private readonly dropPreTool;
-    /** dropPreToolMessages: messages waiting to learn whether a tool call follows. */
+    private readonly onDropped;
+    /**
+     * Messages waiting to learn whether a tool call follows: every message when
+     * dropPreToolMessages is set, short asides (isPreToolAside) otherwise. The
+     * runtime streams one content block per event, so "followed by a tool_use
+     * in the same assistant message" is "the next event is a tool call".
+     */
     private candidates;
     private pending;
     /** In-between questions, held until the turn ends (see the header). */

package/dist/lib/bot/progress.js

@@ -27,6 +27,20 @@ export const PROGRESS_COALESCE_MS = 2_000;
 export const PROGRESS_MIN_GAP_MS = 4_000;
 export const WORKING_NOTICE_MS = 60_000;
 export const WORKING_NOTICE_TEXT = "Working on it — I'll reply here when it's done.";
+/** Below this many characters a message right before a tool call is an aside, not a progress note. */
+export const PRE_TOOL_ASIDE_MAX_CHARS = 40;
+/**
+ * True for a short assistant text that is an aside to itself when a tool call
+ * follows it ("Bind first, separately." reached a person on 2026-10-13: the
+ * model thinking out loud before a tool_use in the same assistant message).
+ * Real progress notes are full sentences addressed to the person ("Reading
+ * your agency docs now, then I'll look at the client folders.") and run past
+ * the limit; an hq-block is always content the desktop app must draw.
+ */
+export function isPreToolAside(text) {
+    const t = text.trim();
+    return t.length < PRE_TOOL_ASIDE_MAX_CHARS && !t.includes("```hq-block");
+}
 /** Whitespace-insensitive form used to recognise repeated text. */
 export function normalizeForCompare(text) {
     return text.replace(/\s+/g, "");
@@ -47,7 +61,13 @@ export class ProgressPoster {
     workingNoticeText;
     buffer;
     dropPreTool;
-    /** dropPreToolMessages: messages waiting to learn whether a tool call follows. */
+    onDropped;
+    /**
+     * Messages waiting to learn whether a tool call follows: every message when
+     * dropPreToolMessages is set, short asides (isPreToolAside) otherwise. The
+     * runtime streams one content block per event, so "followed by a tool_use
+     * in the same assistant message" is "the next event is a tool call".
+     */
     candidates = [];
     pending = [];
     /** In-between questions, held until the turn ends (see the header). */
@@ -82,6 +102,7 @@ export class ProgressPoster {
         this.workingNoticeText = opts.workingNoticeText ?? WORKING_NOTICE_TEXT;
         this.buffer = opts.buffer ?? false;
         this.dropPreTool = opts.dropPreToolMessages ?? false;
+        this.onDropped = opts.onDropped ?? (() => undefined);
     }
     /** Arm the one-time "working on it" note. Call when the turn starts. */
     start() {
@@ -93,6 +114,12 @@ export class ProgressPoster {
             this.noticeTimer = null;
             if (this.finished || this.said.length > 0 || this.noticeSent)
                 return;
+            // A short message is waiting to learn whether a tool call follows: if it
+            // was real, it is the model's own "working on it"; look again later.
+            if (!this.dropPreTool && this.candidates.length > 0) {
+                this.start();
+                return;
+            }
             this.noticeSent = true;
             this.enqueueWith(this.workingNoticeText, this.sendProgress);
         }, this.workingNoticeMs);
@@ -106,9 +133,9 @@ export class ProgressPoster {
         // silence signal, not content, and must never be posted as progress.
         if (containsNoReplySentinel(t))
             return;
-        if (this.dropPreTool) {
-            // The previous message was not followed by a tool call: it was real.
-            this.promoteCandidates();
+        // The previous message was not followed by a tool call: it was real.
+        this.promoteCandidates();
+        if (this.dropPreTool || isPreToolAside(t)) {
             this.candidates.push(t);
             return;
         }
@@ -116,9 +143,18 @@ export class ProgressPoster {
     }
     /** The model called a tool: whatever it wrote just before was a note to itself. */
     tool() {
-        if (this.finished || !this.dropPreTool)
+        if (this.finished)
             return;
+        const dropped = this.candidates;
         this.candidates = [];
+        for (const t of dropped) {
+            try {
+                this.onDropped(t);
+            }
+            catch {
+                /* a log hook must never break the turn */
+            }
+        }
     }
     promoteCandidates() {
         const kept = this.candidates;
@@ -199,6 +235,8 @@ export class ProgressPoster {
     async abandon() {
         if (this.finished)
             return this.chain;
+        // A message the turn ended on (no tool after it) is real.
+        this.promoteCandidates();
         this.finished = true;
         this.cancelNotice();
         this.cancelFlush();

package/dist/lib/bot/run.js

@@ -1118,6 +1118,8 @@ export async function runBot(deps) {
             // reach them, and it posts no "still working" notice either — the
             // desktop app shows that the bot is working.
             ...(isSetupBot ? { dropPreToolMessages: true } : {}),
+            // Short asides before a tool call never reach the person either (isPreToolAside).
+            onDropped: (text) => log("debug", `dropped a pre-tool aside for ${messageId} (${text.length} chars): ${text}`),
             ...deps.progress,
             ...(args.workingNotice === false || silenceable || isSetupBot ? { workingNoticeMs: 0 } : {}),
             ...(silenceable || args.suppressOutput ? { buffer: true } : {}),

package/dist/lib/bot/runtime/claude.d.ts

@@ -27,6 +27,18 @@ export declare const FALLBACK_CLAUDE_PERMISSION_MODE = "auto";
 export declare const CLAUDE_EFFORT_ENV = "HQ_BOT_CLAUDE_EFFORT";
 export declare const DEFAULT_CLAUDE_EFFORT = "medium";
 export declare function claudeEffort(env?: NodeJS.ProcessEnv): string;
+/**
+ * Per-tool-call safety for a bot turn: Claude Code reads these to bound each
+ * Bash tool call (its default and the most a call may ask for). On 2026-10-13
+ * a bot-authored command ended in `cat > /dev/null`, waited on stdin that
+ * never closed, and the turn showed "working" for over 15 minutes. Set only
+ * when the environment does not already set them.
+ */
+export declare const CLAUDE_BASH_DEFAULT_TIMEOUT_ENV = "BASH_DEFAULT_TIMEOUT_MS";
+export declare const CLAUDE_BASH_MAX_TIMEOUT_ENV = "BASH_MAX_TIMEOUT_MS";
+export declare const BOT_BASH_TIMEOUT_MS: number;
+/** Claude's `runtimeEnv` layer: the Bash tool timeouts defaulted (pure). */
+export declare function claudeRuntimeEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function claudePermissionMode(env?: NodeJS.ProcessEnv, autoApprove?: boolean, explicit?: string): string;
 /**
  * True when Claude Code refused to start because bypassPermissions is turned

package/dist/lib/bot/runtime/claude.js

@@ -34,6 +34,25 @@ export const DEFAULT_CLAUDE_EFFORT = "medium";
 export function claudeEffort(env = process.env) {
     return env[CLAUDE_EFFORT_ENV]?.trim() || DEFAULT_CLAUDE_EFFORT;
 }
+/**
+ * Per-tool-call safety for a bot turn: Claude Code reads these to bound each
+ * Bash tool call (its default and the most a call may ask for). On 2026-10-13
+ * a bot-authored command ended in `cat > /dev/null`, waited on stdin that
+ * never closed, and the turn showed "working" for over 15 minutes. Set only
+ * when the environment does not already set them.
+ */
+export const CLAUDE_BASH_DEFAULT_TIMEOUT_ENV = "BASH_DEFAULT_TIMEOUT_MS";
+export const CLAUDE_BASH_MAX_TIMEOUT_ENV = "BASH_MAX_TIMEOUT_MS";
+export const BOT_BASH_TIMEOUT_MS = 10 * 60 * 1000;
+/** Claude's `runtimeEnv` layer: the Bash tool timeouts defaulted (pure). */
+export function claudeRuntimeEnv(env) {
+    const out = { ...env };
+    for (const key of [CLAUDE_BASH_DEFAULT_TIMEOUT_ENV, CLAUDE_BASH_MAX_TIMEOUT_ENV]) {
+        if (!out[key]?.trim())
+            out[key] = String(BOT_BASH_TIMEOUT_MS);
+    }
+    return out;
+}
 export function claudePermissionMode(env = process.env, autoApprove = true, explicit) {
     const raw = env[CLAUDE_PERMISSION_MODE_ENV]?.trim();
     if (raw)
@@ -193,6 +212,7 @@ export function createClaudeRuntime(env = process.env, opts = {}) {
                 args.push("--session-id", scratch.newSessionId);
             return args;
         },
+        runtimeEnv: claudeRuntimeEnv,
         stdinInput(input) {
             return input.platform === "win32"
                 ? JSON.stringify({

package/dist/lib/bot/runtime/index.d.ts

@@ -1,5 +1,5 @@
 import type { BotRuntimeId } from "../config.js";
-import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult, type SpawnLike } from "./types.js";
+import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult, type SpawnLike, type SpawnOptions } from "./types.js";
 export * from "./types.js";
 export { createClaudeRuntime, claudePermissionMode } from "./claude.js";
 export { createCodexRuntime, codexPrompt } from "./codex.js";
@@ -19,6 +19,15 @@ export declare function runtimeFor(id: BotRuntimeId, env?: NodeJS.ProcessEnv): B
 export declare function descendantPids(pid: number, listProcesses?: () => string): number[];
 /** After a stop, wait this long for the output pipes to close before settling anyway. */
 export declare const STOP_SETTLE_GRACE_MS = 2000;
+/**
+ * The child's stdin: a pipe only when this process has something to write to
+ * it (a stdin prompt, which is ended right after it is written, or a
+ * protocol), otherwise closed (`ignore` = /dev/null). The prompt normally
+ * travels on argv, so the model CLI must never inherit or wait on an open
+ * stdin: a bot-authored `cat > /dev/null` on 2026-10-13 blocked a turn for
+ * over 15 minutes.
+ */
+export declare function runtimeStdinMode(options: Pick<SpawnOptions, "stdin" | "protocol">): "pipe" | "ignore";
 export declare const defaultSpawn: SpawnLike;
 /** Time limit for the short helper commands a turn may run (`--version`, the bundled model catalog). */
 export declare const AUX_COMMAND_TIMEOUT_MS = 20000;

package/dist/lib/bot/runtime/index.js

@@ -71,6 +71,17 @@ function defaultListProcesses() {
 }
 /** After a stop, wait this long for the output pipes to close before settling anyway. */
 export const STOP_SETTLE_GRACE_MS = 2_000;
+/**
+ * The child's stdin: a pipe only when this process has something to write to
+ * it (a stdin prompt, which is ended right after it is written, or a
+ * protocol), otherwise closed (`ignore` = /dev/null). The prompt normally
+ * travels on argv, so the model CLI must never inherit or wait on an open
+ * stdin: a bot-authored `cat > /dev/null` on 2026-10-13 blocked a turn for
+ * over 15 minutes.
+ */
+export function runtimeStdinMode(options) {
+    return options.stdin !== undefined || options.protocol ? "pipe" : "ignore";
+}
 export const defaultSpawn = (command, args, options) => new Promise((resolve, reject) => {
     let stdout = "";
     let stderr = "";
@@ -80,7 +91,7 @@ export const defaultSpawn = (command, args, options) => new Promise((resolve, re
     const child = spawn(plan.cmd, plan.args, {
         cwd: options.cwd,
         env: options.env,
-        stdio: [options.stdin !== undefined || options.protocol ? "pipe" : "ignore", "pipe", "pipe"],
+        stdio: [runtimeStdinMode(options), "pipe", "pipe"],
         ...(plan.shell ? { shell: plan.shell } : {}),
         ...(plan.windowsVerbatimArguments !== undefined
             ? { windowsVerbatimArguments: plan.windowsVerbatimArguments }
@@ -347,7 +358,8 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
     const args = runtime.buildArgs(remembered ? { ...turnInput, model: remembered.to } : turnInput, { outputFile, newSessionId });
     // Enforce at the model boundary too: old plists and direct `bot run` callers
     // may lack the guard. A bot prompt must never quit the user's desktop app.
-    const env = { ...(input.env ?? deps.env ?? process.env), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
+    const baseEnv = { ...(input.env ?? deps.env ?? process.env), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
+    const env = { ...(runtime.runtimeEnv?.(baseEnv) ?? baseEnv), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
     const binary = runtime.resolveBinary?.(env, input.cwd, turnInput.platform) ?? runtime.binary;
     const stdin = runtime.stdinInput?.(turnInput);
     const protocol = runtime.spawnProtocol?.(turnInput);