bare-agent 0.33.0 → 0.34.0

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.33.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.0` optional peer for governance) | Apache 2.0
+> v0.34.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.0` optional peer for governance) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/02-features/usage-guide.md)
 
@@ -817,11 +817,11 @@ new CLIPipe({ command: 'claude', args: ['-p', '--model', 'sonnet'], toolProtocol
 **CLIPipe NATIVE tool mode (BA-16, `toolProtocol:'claude-mcp'`).** The claude CLI has a real tool channel; native mode uses it instead of emulating one. The CLI runs its OWN multi-turn session per `generate()` call and executes your `tools` natively over an MCP bridge that calls back into your in-process `execute` closures. Because the CLI owns the inner cycle, the Loop's per-round machinery cannot run — so the governance you'd wire on `Loop` moves to the **provider**, at the one seam every tool call crosses:
 - `policy` — the SAME `(tool, args, ctx) => true|string` chokepoint as `Loop({policy})`, so a wired `wireGate(gate).policy` writes **audit rows of identical shape, zero gate changes**. A deny is a tool result (advisory); the handler never runs. **Required here** — a `Loop({policy})` in native mode would be a fence that is silently not there, so the Loop throws.
 - `maxConsecutiveDenials` (3) / `maxIdenticalToolErrors` (3) — BA-11/BA-12 guards at the bridge, same narrowest triggers; end the session `denied:<tool>` / `stuck:<tool>`.
-- `maxTurns` — maps to the CLI's `--max-turns`; the bound stop is `error:'max_turns'`, never a silent success.
-- `onTurn` — streams each completed turn's usage (four cache tiers, `costUsd:null` — the CLI prices the session) as it arrives, then one closing `kind:'session'` event with the authoritative total. Shape mirrors `onLlmResult`, so `wireGate(gate).onLlmResult` drops in; when wired the Loop skips its own forward (billed once, never starved).
+- `maxTurns` — a bound on **assistant/LLM turns**, the SAME unit as the Loop path, so one number means one thing on both surfaces (BA-17). NOT a tool-call count: one turn can fire a dozen parallel tool calls and still be one turn (measured: 12 calls across 2 turns, inside `--max-turns 3`). Enforced twice — the CLI's own `--max-turns` stops cleanly at N (and emits the result event that carries the session's real cost), plus a parent-side counter that kills the session if a turn beyond N is ever seen, since that flag is undocumented in `claude --help`. The stop is `error:'max_turns'` + `stopReason:'max_turns'` and **carries the last turn's text forward** — the CLI reports `result:null` on a bounded session, so an unfixed build returned `text:''`.
+- `onTurn` — fires once per **assistant turn** (BA-17: the CLI emits a separate stream event per content *block*, all repeating that message's usage — firing per event inflated a caller's turn axis ~5–7× and its token axis 5.04×), carrying four cache tiers and `costUsd:null` since the CLI prices the session, not the turn. Then one closing `kind:'session'` event carrying the authoritative cost **and the token residual** — a turn's `message.usage` is a snapshot taken at its first block and never revised (a turn that emitted ~816 output tokens reported 2), so the closing event makes the streamed tiers add up to exactly the CLI's own session total. Shape mirrors `onLlmResult`, so `wireGate(gate).onLlmResult` drops in; when wired the Loop skips its own forward (billed once, never starved).
 - `sessionTimeout` (600s) / `bridgeTimeoutMs` (120s) — whole-session and per-handler ceilings.
 
-`GenerateResult.session` (`{turns, toolCalls, error, usageReported}`) carries what really happened; `metrics.sessionTurns` reports the real turn count so a 14-turn session never reads as one round. A terminal the CLI detects inside the session (bound, guard, or a **broken tool bridge** — a dead bridge still ends `subtype:'success'`, so it is caught parent-side by attempted-vs-served tool calls) surfaces as the run's `error`, never a laundered clean finish. `assemble`/`trim`/`cacheMessages` and a Loop-level `policy` all THROW at construction in native mode (no silently-dead knobs — the CLI owns the transcript). The bridge is a unix socket (0600 in a 0700 dir), never a listening port. Claude-only for now; the CLI-specific parts live in `src/provider-clipipe-mcp.js` + `src/mcp-bridge-stub.js` behind the same seam as emulation.
+`GenerateResult.session` (`{turns, toolCalls, error, usageReported}`) carries what really happened; `metrics.sessionTurns` reports the real turn count — assistant *messages*, not stream events — so a 14-turn session never reads as one round, and a 2-turn session never reads as 14. A terminal the CLI detects inside the session (bound, guard, or a **broken tool bridge** — a dead bridge still ends `subtype:'success'`, so it is caught parent-side by attempted-vs-served tool calls) surfaces as the run's `error`, never a laundered clean finish. `assemble`/`trim`/`cacheMessages` and a Loop-level `policy` all THROW at construction in native mode (no silently-dead knobs — the CLI owns the transcript). The bridge is a unix socket (0600 in a 0700 dir), never a listening port. Claude-only for now; the CLI-specific parts live in `src/provider-clipipe-mcp.js` + `src/mcp-bridge-stub.js` behind the same seam as emulation.
 
 All return `{ text, toolCalls, usage: { inputTokens, outputTokens }, model?, costUsd? }`. The optional `model` (v0.16.1+) is the id the response was produced by — Loop prefers it over `provider.model` for cost accounting. By default CLIPipe returns `toolCalls: []` and zero usage (CLI tools don't report tokens) and omits `model`. **Structured output (v0.26.0+):** set `parse: 'claude-json'` (a preset for `claude -p --output-format json`) — or a `(stdout) => Partial<GenerateResult>` function for any other CLI — and CLIPipe maps the CLI's JSON envelope onto real `usage`, `model`, and `costUsd`, throwing `ProviderError` on a malformed/error envelope (never a silent raw-text fall-back). `costUsd` (optional `GenerateResult` field) is an **authoritative** per-call price the provider reports itself; when finite the Loop prefers it over the internal rate-table `estimateCost`, so a CLI-piped run enforces a bareguard USD cap with no local pricing table (a `0` counts as priced, distinct from null/unpriced). `toolCalls` stays `[]` regardless (CLIPipe is tool-free).
 
@@ -829,6 +829,8 @@ All return `{ text, toolCalls, usage: { inputTokens, outputTokens }, model?, cos
 
 **Error body (v0.11.0):** on an HTTP error the OpenAI/Anthropic/Ollama providers throw a `ProviderError` whose `message` carries the upstream error string. The full parsed response is **not** attached to `err.body` by default (so an unexpected field can't leak through logs that dump the error object). Pass `{ exposeErrorBody: true }` to attach it for debugging.
 
+**Request/idle timeout (BA-18, v0.34.0):** the four http(s) providers (Anthropic, OpenAI, Gemini, Ollama) accept a `timeoutMs` option — constructor default **600000 (10 min)**, overridable per call via `generate(..., { timeoutMs })`, and `0`/`Infinity` disables it. Before this they wired only `req.on('error')`, so a socket the server silently dropped — or a response that never starts — hung `generate()` until the OS TCP timeout (~2h): a hang, not an error, so retry/casualty policy above it never fired. `timeoutMs` bounds on socket **inactivity** (`req.setTimeout`), so a slow-but-streaming response is not killed — only a silent/never-answering socket trips it; the 10-min default clears any single non-streaming completion (TTFB ≈ generation time). On trip, `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`, `retryable: true`). **Retry is caller-side and already wired:** `new Loop({ provider, retry: new Retry() })` wraps `provider.generate`, and `DEFAULT_RETRY_ON` classifies `ETIMEDOUT` (and `ECONNRESET`/`ENOTFOUND`/429/5xx) as transient — so a wired `Retry` retries a timed-out request and rethrows under `retryOn: () => false`, with no extra wiring (`run-plan`'s `stepRetry` is a second consumer of the same seam). CLIPipe already bounded its child process (`timeout`, default 30000 for one-shot) and is unchanged.
+
 **Plaintext-key warning (Unreleased):** the OpenAI provider's `baseUrl` accepts `http://` (for local/OpenAI-compatible endpoints), but a `Bearer` key sent over plaintext http to a **non-loopback** host is exposed on the wire. The provider now warns once when that happens. Loopback hosts (`localhost`/`127.0.0.0/8`/`::1` — local proxies, Ollama-style endpoints) stay silent, since that's the legitimate keyless-local case. The header is **not** stripped (some local proxies want a key), so use `https` for any remote endpoint, or drop `apiKey` when the local endpoint needs none.
 
 **Cost estimation:** Loop automatically estimates USD cost per run based on model and token usage. The `cost` field appears in every `loop.run()` result and in `loop:done` stream events. Pricing covers OpenAI and Anthropic models; unknown models use a default average. To adjust rates, edit `COST_PER_1K` at the top of `src/loop.js`. The model is resolved as `result.model || provider.model` (v0.16.1+) — providers now echo the model in their `generate()` result, so cost accounting holds even when `provider.model` is absent or varies per response, e.g. behind `FallbackProvider` or `CircuitBreaker.wrapProvider` (the wrapper also preserves `model`/`name` passthrough props). Wire `onLlmResult` (via `wireGate`) and a `budget.maxCostUsd` cap then halts on token-heavy workloads too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "files": [
     "index.js",
     "index.d.ts",

package/src/provider-anthropic.d.ts

@@ -32,6 +32,10 @@ export type AnthropicOptions = {
      * - Attach the full upstream response to `err.body` on HTTP errors (off by default to avoid leaking unexpected fields through error logs; `err.message` still carries the API error).
      */
     exposeErrorBody?: boolean | undefined;
+    /**
+     * - BA-18: request/idle timeout in ms. A silent or never-answering socket (dropped by the server, or a response that never starts) was otherwise bounded only by the OS TCP timeout (~2h) — a hang, not an error, so every retry policy above it was inert. Bounds on socket INACTIVITY (the timer resets on activity, so a slow-but-streaming response is not killed); on trip, `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) that a wired `Retry` (`Loop({ retry })`) retries. Default 10 min sits above any single non-streaming completion; `0` or `Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
+     */
+    timeoutMs?: number | undefined;
 };
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -47,6 +51,7 @@ export type AnthropicOptions = {
  *
  *   **MEASURED CAVEAT — this option does not "turn thinking on".** On `claude-sonnet-5` adaptive thinking is ALREADY the default: sending this changed the observed thinking rate not at all (2/10 rounds with it vs 3/10 without — `poc/ba7-adaptive-default.mjs`). Its real use is pinning the mode and reaching `display`/`effort`. The change that mattered is that thinking blocks are now PRESERVED and replayed (see `Message.providerBlocks`), which happens whether or not you ever set this.
  * @property {boolean} [exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default to avoid leaking unexpected fields through error logs; `err.message` still carries the API error).
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. A silent or never-answering socket (dropped by the server, or a response that never starts) was otherwise bounded only by the OS TCP timeout (~2h) — a hang, not an error, so every retry policy above it was inert. Bounds on socket INACTIVITY (the timer resets on activity, so a slow-but-streaming response is not killed); on trip, `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) that a wired `Retry` (`Loop({ retry })`) retries. Default 10 min sits above any single non-streaming completion; `0` or `Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
  */
 export class AnthropicProvider {
     /**
@@ -61,11 +66,12 @@ export class AnthropicProvider {
     cacheMessages: boolean;
     thinking: any;
     exposeErrorBody: boolean;
+    timeoutMs: number | undefined;
     /**
      * Generate a response from the Anthropic API.
      * @param {Message[]} messages - Conversation messages (OpenAI format, auto-converted).
      * @param {ToolDef[]} [tools=[]] - Tool definitions.
-     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, system).
+     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, system, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[AnthropicProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
      */
@@ -94,8 +100,9 @@ export class AnthropicProvider {
     _toAnthropicMessage(msg: Message): any;
     /**
      * @param {Record<string, any>} body
+     * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
      * @returns {Promise<any>}
      */
-    _request(body: Record<string, any>): Promise<any>;
+    _request(body: Record<string, any>, timeoutMs?: number): Promise<any>;
     _warnedInsecure: boolean | undefined;
 }

package/src/provider-anthropic.js

@@ -5,6 +5,7 @@ const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
+const { resolveTimeoutMs, applyRequestTimeout } = require('./provider-http');
 
 /** @param {string} hostname @returns {boolean} */
 function isLoopbackHost(hostname) {
@@ -27,6 +28,7 @@ function isLoopbackHost(hostname) {
  *
  *   **MEASURED CAVEAT — this option does not "turn thinking on".** On `claude-sonnet-5` adaptive thinking is ALREADY the default: sending this changed the observed thinking rate not at all (2/10 rounds with it vs 3/10 without — `poc/ba7-adaptive-default.mjs`). Its real use is pinning the mode and reaching `display`/`effort`. The change that mattered is that thinking blocks are now PRESERVED and replayed (see `Message.providerBlocks`), which happens whether or not you ever set this.
  * @property {boolean} [exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default to avoid leaking unexpected fields through error logs; `err.message` still carries the API error).
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. A silent or never-answering socket (dropped by the server, or a response that never starts) was otherwise bounded only by the OS TCP timeout (~2h) — a hang, not an error, so every retry policy above it was inert. Bounds on socket INACTIVITY (the timer resets on activity, so a slow-but-streaming response is not killed); on trip, `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) that a wired `Retry` (`Loop({ retry })`) retries. Default 10 min sits above any single non-streaming completion; `0` or `Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
  */
 
 class AnthropicProvider {
@@ -52,13 +54,15 @@ class AnthropicProvider {
     this.thinking = options.thinking != null ? options.thinking : null;
     // See OpenAIProvider: attach full upstream body to err.body only on opt-in.
     this.exposeErrorBody = options.exposeErrorBody === true;
+    // BA-18: request/idle timeout (ms). Resolved at call time (default 600000; 0/Infinity disable).
+    this.timeoutMs = options.timeoutMs;
   }
 
   /**
    * Generate a response from the Anthropic API.
    * @param {Message[]} messages - Conversation messages (OpenAI format, auto-converted).
    * @param {ToolDef[]} [tools=[]] - Tool definitions.
-   * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, system).
+   * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, system, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[AnthropicProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
    */
@@ -142,8 +146,9 @@ class AnthropicProvider {
     // BA-10: some models (e.g. claude-sonnet-5) reject a non-default `temperature` with a 400 — drop it
     // and retry once rather than let the whole call fail. `temperatureDropped` flows back so an upstream
     // receipt (recurse's refineLeaf) can report the effective temperature, not the one the model ignored.
+    const timeoutMs = resolveTimeoutMs(this.timeoutMs, options.timeoutMs);
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request(body),
+      request: () => this._request(body, timeoutMs),
       hadTemperature: () => body.temperature != null,
       stripTemperature: () => { delete body.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -275,9 +280,10 @@ class AnthropicProvider {
 
   /**
    * @param {Record<string, any>} body
+   * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(body) {
+  _request(body, timeoutMs = 0) {
     return new Promise((resolve, reject) => {
       const payload = JSON.stringify(body);
       const url = new URL(this.baseUrl + '/messages');
@@ -314,6 +320,7 @@ class AnthropicProvider {
           }
         });
       });
+      applyRequestTimeout(req, timeoutMs, 'AnthropicProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();

package/src/provider-clipipe-mcp.d.ts

@@ -89,6 +89,21 @@ export function resolveSessionError(facts: {
 /**
  * Line-oriented processor for the CLI's `stream-json` stdout.
  *
+ * ONE TURN IS ONE ASSISTANT MESSAGE, NOT ONE EVENT (BA-17). Measured on the real wire: the CLI
+ * emits a SEPARATE `assistant` event per content BLOCK of the same message, and every one of them
+ * repeats that message's `usage` verbatim — one 13-block message arrived as 13 events carrying the
+ * same numbers. Treating each event as a turn is wrong on both axes a caller meters:
+ *   - the TURN axis  — a caller whose attempt bound is an LLM-turn count sees 14 "turns" for 2 real
+ *                      ones (measured 7×; 4.4× on the adopter's failing run), so its net guillotines
+ *                      the session at a fraction of the allowance it advertised;
+ *   - the TOKEN axis — the same message's usage is added once per block (measured 5.04× inflated
+ *                      against the CLI's own session total), so a budget cap fires early on tokens
+ *                      that were never spent.
+ * So a RUN of consecutive events sharing `message.id` is ONE turn: usage is recorded once and one
+ * `onTurn` fires. Adjacent-run dedup, not a Set — an id that somehow recurred later must still count
+ * as a new turn (dropping a real turn is the failure that matters). An event with NO id degrades to
+ * one-turn-per-event: the pre-BA-17 behaviour, never a collapse of the whole session into one turn.
+ *
  * FRAMING IS SYNCHRONOUS. The obvious shape — an `async` stdout handler that `await`s `onTurn`
  * inside its parse loop — has a data-corruption bug: while the `await` is suspended, the next
  * `'data'` event re-enters the handler and mutates the SHARED line buffer, so the suspended parse
@@ -104,18 +119,32 @@ export function resolveSessionError(facts: {
  * @param {any} o.ctx
  * @param {number} o.startedAt
  * @param {(err: Error) => void} o.onHalt - called if a forwarded `onTurn` throws a HaltError.
+ * @param {number|null} [o.turnCap] - BA-17 backstop: fires `onLimit` the moment a turn BEYOND this
+ *   many is observed. Deliberately not `>=`: `--max-turns` is passed to the CLI too, and when it
+ *   works (measured: it does, and it counts assistant turns) the CLI ends the session ITSELF at the
+ *   cap and emits its `result` event — which is the only place the authoritative session cost
+ *   arrives. Killing the session at exactly N would throw that figure away on every bounded run. So
+ *   this fires ONLY on an overrun, i.e. only if the flag ever stops working — it is undocumented in
+ *   `claude --help`, so the guarantee cannot rest on it alone.
+ * @param {(() => void)} [o.onLimit] - called once when `turnCap` is exceeded.
  */
-export function createSessionStream({ onTurn, ctx, startedAt, onHalt }: {
+export function createSessionStream({ onTurn, ctx, startedAt, onHalt, turnCap, onLimit }: {
     onTurn: Function | null;
     ctx: any;
     startedAt: number;
     onHalt: (err: Error) => void;
+    turnCap?: number | null | undefined;
+    onLimit?: (() => void) | undefined;
 }): {
     /** Feed a stdout chunk. Pure synchronous framing — never awaits. */
     feed(chunk: Buffer | string): void;
     /** Await every queued per-turn forward — call before resolving the session. */
     flush(): Promise<void>;
     readonly turns: import("../types").Usage[];
+    /** Assistant TURNS observed — including any that carried no usage. */
+    readonly turnCount: number;
+    /** The last turn's text. The work a bounded/guard-stopped session still did (BA-5). */
+    readonly lastText: string;
     readonly attempted: number;
     readonly final: any;
 };

package/src/provider-clipipe-mcp.js

@@ -257,6 +257,13 @@ const SUBTYPE_MAP = {
   error_during_execution: { stopReason: null, error: 'session_error' },
 };
 
+/**
+ * Terminals WE impose that ARE stop reasons in the neutral vocabulary. A guard terminal
+ * (`denied:`/`stuck:`) is deliberately absent — those are faults, not stop reasons.
+ * @type {Record<string, string>}
+ */
+const TERMINAL_STOP = { max_turns: 'max_turns' };
+
 /**
  * @param {string|null|undefined} subtype
  * @returns {{stopReason: string|null, error: string|null}}
@@ -291,7 +298,15 @@ function classifySubtype(subtype) {
  */
 function resolveSessionError(facts) {
   const fromSubtype = classifySubtype(facts.subtype);
-  if (facts.terminal) return { stopReason: fromSubtype.stopReason, error: facts.terminal };
+  if (facts.terminal) {
+    // A terminal WE imposed kills the session before its `result` event, so there is no subtype to
+    // read a stop reason from. Where the terminal IS a stop reason in the neutral vocabulary, say so
+    // — a consumer branching on `stopReason` must not see `null` for a bound it asked for.
+    // Own-property only: same proto-key footgun as SUBTYPE_MAP.
+    const named = Object.prototype.hasOwnProperty.call(TERMINAL_STOP, facts.terminal)
+      ? TERMINAL_STOP[facts.terminal] : null;
+    return { stopReason: named || fromSubtype.stopReason, error: facts.terminal };
+  }
   const bridgeBroken = facts.bridgeDown
     || (Number.isFinite(facts.attempted) && Number.isFinite(facts.served) && facts.attempted > facts.served);
   if (bridgeBroken) return { stopReason: fromSubtype.stopReason, error: 'bridge-failed' };
@@ -302,6 +317,21 @@ function resolveSessionError(facts) {
 /**
  * Line-oriented processor for the CLI's `stream-json` stdout.
  *
+ * ONE TURN IS ONE ASSISTANT MESSAGE, NOT ONE EVENT (BA-17). Measured on the real wire: the CLI
+ * emits a SEPARATE `assistant` event per content BLOCK of the same message, and every one of them
+ * repeats that message's `usage` verbatim — one 13-block message arrived as 13 events carrying the
+ * same numbers. Treating each event as a turn is wrong on both axes a caller meters:
+ *   - the TURN axis  — a caller whose attempt bound is an LLM-turn count sees 14 "turns" for 2 real
+ *                      ones (measured 7×; 4.4× on the adopter's failing run), so its net guillotines
+ *                      the session at a fraction of the allowance it advertised;
+ *   - the TOKEN axis — the same message's usage is added once per block (measured 5.04× inflated
+ *                      against the CLI's own session total), so a budget cap fires early on tokens
+ *                      that were never spent.
+ * So a RUN of consecutive events sharing `message.id` is ONE turn: usage is recorded once and one
+ * `onTurn` fires. Adjacent-run dedup, not a Set — an id that somehow recurred later must still count
+ * as a new turn (dropping a real turn is the failure that matters). An event with NO id degrades to
+ * one-turn-per-event: the pre-BA-17 behaviour, never a collapse of the whole session into one turn.
+ *
  * FRAMING IS SYNCHRONOUS. The obvious shape — an `async` stdout handler that `await`s `onTurn`
  * inside its parse loop — has a data-corruption bug: while the `await` is suspended, the next
  * `'data'` event re-enters the handler and mutates the SHARED line buffer, so the suspended parse
@@ -317,11 +347,28 @@ function resolveSessionError(facts) {
  * @param {any} o.ctx
  * @param {number} o.startedAt
  * @param {(err: Error) => void} o.onHalt - called if a forwarded `onTurn` throws a HaltError.
+ * @param {number|null} [o.turnCap] - BA-17 backstop: fires `onLimit` the moment a turn BEYOND this
+ *   many is observed. Deliberately not `>=`: `--max-turns` is passed to the CLI too, and when it
+ *   works (measured: it does, and it counts assistant turns) the CLI ends the session ITSELF at the
+ *   cap and emits its `result` event — which is the only place the authoritative session cost
+ *   arrives. Killing the session at exactly N would throw that figure away on every bounded run. So
+ *   this fires ONLY on an overrun, i.e. only if the flag ever stops working — it is undocumented in
+ *   `claude --help`, so the guarantee cannot rest on it alone.
+ * @param {(() => void)} [o.onLimit] - called once when `turnCap` is exceeded.
  */
-function createSessionStream({ onTurn, ctx, startedAt, onHalt }) {
+function createSessionStream({ onTurn, ctx, startedAt, onHalt, turnCap = null, onLimit = () => {} }) {
   let buf = '';
   let attempted = 0;
   let final = null;
+  /** Adjacent-run dedup key: the `message.id` of the turn currently being emitted. */
+  let turnId = /** @type {string|null} */ (null);
+  /** Has the CURRENT turn already contributed its usage? Blocks of one message repeat it. */
+  let turnMetered = false;
+  let turnCount = 0;
+  let limitFired = false;
+  /** Text of the current turn, and the last turn that produced any — BA-5 work preservation. */
+  let curText = '';
+  let lastText = '';
   /** @type {import('../types').Usage[]} */ const turns = [];
   /** @type {any[]} */ const queue = [];
   /** @type {Promise<void>|null} */ let draining = null;
@@ -367,29 +414,59 @@ function createSessionStream({ onTurn, ctx, startedAt, onHalt }) {
           }
         }
 
-        if (ev.type === 'assistant' && ev.message && ev.message.usage) {
-          const u = ev.message.usage;
-          /** @type {import('../types').Usage} */
-          const usage = {
-            inputTokens: Number(u.input_tokens) || 0,
-            outputTokens: Number(u.output_tokens) || 0,
-          };
-          // Omit an absent tier rather than emit a synthetic 0 (per the Usage contract).
-          if (Number.isFinite(u.cache_read_input_tokens)) usage.cacheReadTokens = u.cache_read_input_tokens;
-          if (Number.isFinite(u.cache_creation_input_tokens)) usage.cacheCreationTokens = u.cache_creation_input_tokens;
-          turns.push(usage);
-          // Stream it: a session that dies mid-run must already have surfaced every completed turn's
-          // spend, or the gate loses it. Queued (not awaited here) so framing cannot race the buffer.
-          if (onTurn) queue.push({
-            model: (ev.message && ev.message.model) || null,
-            provider: 'clipipe',
-            usage,
-            costUsd: null, // the CLI prices the SESSION, not the turn — explicitly unpriced, never a synthetic 0.
-            pricing: 'unpriced',
-            durationMs: Date.now() - startedAt,
-            ctx, // what a wired gate records spend against — same as the Loop's onLlmResult.
-            kind: 'turn',
-          });
+        if (ev.type === 'assistant' && ev.message) {
+          // Is this event the start of a NEW assistant turn, or another block of the current one?
+          // No id at all ⇒ its own turn (degrade to the pre-BA-17 shape, never collapse into one).
+          const id = (typeof ev.message.id === 'string' && ev.message.id) ? ev.message.id : null;
+          if (id === null || id !== turnId) {
+            turnId = id;
+            turnMetered = false;
+            curText = '';
+            turnCount++;
+            // The overrun backstop. `>` not `>=`, so a CLI that honours --max-turns keeps its clean
+            // exit (and with it the only report of the session's real cost).
+            if (!limitFired && Number.isFinite(turnCap) && Number(turnCap) > 0 && turnCount > Number(turnCap)) {
+              limitFired = true;
+              onLimit();
+            }
+          }
+
+          // BA-5: keep the turn's own words, so a bound/guard stop still returns the work done. The
+          // CLI reports `result: null` on a bounded session — measured — so this is the ONLY source.
+          for (const block of (ev.message.content || [])) {
+            if (block && block.type === 'text' && typeof block.text === 'string' && block.text) {
+              curText += block.text;
+              lastText = curText;
+            }
+          }
+
+          // Usage rides on EVERY block-event of the message; count it once per turn. Read on any
+          // event of the turn (not just the first) — the first block need not be the one carrying it.
+          if (ev.message.usage && !turnMetered) {
+            turnMetered = true;
+            const u = ev.message.usage;
+            /** @type {import('../types').Usage} */
+            const usage = {
+              inputTokens: Number(u.input_tokens) || 0,
+              outputTokens: Number(u.output_tokens) || 0,
+            };
+            // Omit an absent tier rather than emit a synthetic 0 (per the Usage contract).
+            if (Number.isFinite(u.cache_read_input_tokens)) usage.cacheReadTokens = u.cache_read_input_tokens;
+            if (Number.isFinite(u.cache_creation_input_tokens)) usage.cacheCreationTokens = u.cache_creation_input_tokens;
+            turns.push(usage);
+            // Stream it: a session that dies mid-run must already have surfaced every completed turn's
+            // spend, or the gate loses it. Queued (not awaited here) so framing cannot race the buffer.
+            if (onTurn) queue.push({
+              model: ev.message.model || null,
+              provider: 'clipipe',
+              usage,
+              costUsd: null, // the CLI prices the SESSION, not the turn — explicitly unpriced, never a synthetic 0.
+              pricing: 'unpriced',
+              durationMs: Date.now() - startedAt,
+              ctx, // what a wired gate records spend against — same as the Loop's onLlmResult.
+              kind: 'turn',
+            });
+          }
         }
 
         if (ev.type === 'result') final = ev;
@@ -399,6 +476,10 @@ function createSessionStream({ onTurn, ctx, startedAt, onHalt }) {
     /** Await every queued per-turn forward — call before resolving the session. */
     async flush() { if (draining) await draining; await drain(); },
     get turns() { return turns; },
+    /** Assistant TURNS observed — including any that carried no usage. */
+    get turnCount() { return turnCount; },
+    /** The last turn's text. The work a bounded/guard-stopped session still did (BA-5). */
+    get lastText() { return lastText; },
     get attempted() { return attempted; },
     get final() { return final; },
   };
@@ -452,11 +533,18 @@ function runSession(opts) {
     const child = spawn(command, args, { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
     let stderr = '', settled = false;
     /** @type {Error|null} */ let turnHalt = null;
+    /** @type {string|null} A terminal WE imposed from the stream (today: the BA-17 turn backstop). */
+    let terminal = null;
     const started = Date.now();
 
     /** Kill the session now — a guard tripped or governance halted mid-flight. */
     const abort = () => { try { child.kill('SIGTERM'); } catch (_) { /* already gone */ } };
-    const stream = createSessionStream({ onTurn, ctx, startedAt: started, onHalt: (err) => { turnHalt = err; abort(); } });
+    const stream = createSessionStream({
+      onTurn, ctx, startedAt: started,
+      onHalt: (err) => { turnHalt = err; abort(); },
+      turnCap: Number.isFinite(maxTurns) ? maxTurns : null,
+      onLimit: () => { terminal = 'max_turns'; abort(); },
+    });
 
     const done = async (extra = {}) => {
       if (settled) return;
@@ -465,7 +553,11 @@ function runSession(opts) {
       // Flush queued per-turn forwards before resolving — a session that ends while a forward is
       // pending must still surface that turn's spend to the gate (F12/F18).
       try { await stream.flush(); } catch (_) { /* onTurn failures are surfaced in-drain, never fatal */ }
-      resolve({ turns: stream.turns, final: stream.final, stderr, ms: Date.now() - started, turnHalt, attempted: stream.attempted, ...extra });
+      resolve({
+        turns: stream.turns, turnCount: stream.turnCount, lastText: stream.lastText,
+        final: stream.final, stderr, ms: Date.now() - started, turnHalt, terminal,
+        attempted: stream.attempted, ...extra,
+      });
     };
 
     const timer = setTimeout(() => {

package/src/provider-clipipe.d.ts

@@ -68,8 +68,16 @@ export type CLIPipeOptions = {
      */
     onTurn?: Function | undefined;
     /**
-     * - (native mode) Maps to the CLI's `--max-turns`. The bound stop is NAMED
-     * (`error_max_turns` → `session.error:'max_turns'`), never a silent clean success.
+     * - (native mode) Bound on ASSISTANT/LLM TURNS — the same unit as the
+     * Loop path's turn bound, so a caller's `maxTurns` means one thing on both surfaces (BA-17). NOT a
+     * tool-call count: a single turn may issue a dozen parallel tool calls and still be one turn
+     * (measured: 12 calls across 2 turns, well inside `--max-turns 3`). Enforced twice on purpose —
+     * the CLI's own `--max-turns` stops the session cleanly at N and emits its result event (the only
+     * report of the session's real cost), and a parent-side counter kills it if a turn beyond N is
+     * ever observed, since that flag is undocumented in `claude --help` and a rename would otherwise
+     * silently unbound the session. Either way the stop is NAMED (`session.error:'max_turns'`,
+     * `stopReason:'max_turns'`) and carries the last turn's text forward, never a silent clean success
+     * and never an empty result.
      */
     maxTurns?: number | undefined;
     /**
@@ -107,65 +115,6 @@ export type CLIPipeOptions = {
      */
     probeCapability?: boolean | undefined;
 };
-/** @typedef {import('../types').Message} Message */
-/** @typedef {import('../types').ToolDef} ToolDef */
-/** @typedef {import('../types').GenerateResult} GenerateResult */
-/**
- * @typedef {object} CLIPipeOptions
- * @property {string} [command] - CLI command to spawn (required).
- * @property {string[]} [args=[]] - Arguments to pass to the command.
- * @property {string} [cwd] - Working directory for the child process.
- * @property {Record<string, string>} [env] - Environment variables for the child process.
- * @property {number} [timeout=30000] - Timeout in milliseconds.
- * @property {string} [systemPromptFlag] - CLI flag for system prompt (e.g. '--system'). When set, system messages are extracted and passed via this flag instead of stdin.
- * @property {(chunk: string) => void} [onChunk] - Called with each stdout chunk as it streams.
- * @property {'claude-json'|((stdout: string) => Partial<GenerateResult>)} [parse] - Opt-in structured-output parser for stdout. Default (unset) returns stdout verbatim as `text` with zero usage (no behavior change). `'claude-json'` is a shipped preset for `claude -p --output-format json`: it maps the CLI's result envelope onto `GenerateResult` (text←`result`, usage←`usage.*`, model←first `modelUsage` key, costUsd←`total_cost_usd`) and throws `ProviderError` on malformed JSON or an error envelope (`is_error`/non-success subtype). A function is the CLI-agnostic escape hatch: it receives trimmed stdout and returns a partial `GenerateResult` (merged over defaults); throw to signal a parse failure.
- * @property {'claude'|'claude-mcp'} [toolProtocol] - Opt into TOOL MODE. Two modes, and the choice is
- *   about COST, not capability. `'claude-mcp'` (BA-16, NATIVE — prefer this on the claude CLI): one CLI
- *   session per call, the caller's `tools` exposed to it as a real MCP server whose handlers call back
- *   into your own in-process closures. The CLI owns the inner cycle and caches its transcript
- *   session-side. `'claude'` (v0.32.0, EMULATION): one CLI spawn per round with the whole transcript
- *   re-rendered and re-sent, parsed back through a JSON envelope. Emulation re-buys the full prefix
- *   every turn, which the adopter measured at **$0.25–0.55/round** against **~$0.006/turn** native — so
- *   it is the right instrument only for a CLI with NO MCP support, not a default. NOT claimed for
- *   native: better output quality (n=2 suggestive evidence exists and is deliberately unminted).
- *   Native mode sets {@link CLIPipeProvider#ownsCycle}, which makes the Loop REFUSE options it could
- *   never honor (`assemble`/`trim`/`cacheMessages`, and a Loop-level `policy`) instead of leaving them
- *   silently dead. See the native-only properties below.
- * @property {(tool: string, args: any, ctx?: any) => any} [policy] - (native mode) The gate, same contract as `Loop({policy})`: only `true`
- *   allows, a string is the deny reason fed back verbatim, a thrown `HaltError` is a clean governance
- *   exit. REQUIRED here rather than on the Loop, because in native mode no tool call ever reaches the
- *   Loop — a `Loop({policy})` would be a fence that is silently not there (the Loop throws instead).
- *   Wiring the same `wireGate(gate).policy` keeps audit rows byte-shape-identical, with zero gate changes.
- * @property {Function} [onTurn] - (native mode) Called with `{model, provider, usage, costUsd, pricing,
- *   durationMs, ctx, kind}` for EACH completed CLI turn as it arrives (`kind:'turn'`, four cache tiers,
- *   `costUsd:null` — the CLI prices the session, not the turn), then once at session end
- *   (`kind:'session'`) carrying the authoritative total cost with zero usage. Streaming, never
- *   sum-at-end: a session that dies mid-run must already have surfaced every completed turn's spend or
- *   the gate loses all of it. The event shape mirrors `Loop({onLlmResult})`, so `wireGate(gate).onLlmResult`
- *   drops straight in — and when it is wired the Loop skips its own forward, so nothing is billed twice.
- * @property {number} [maxTurns] - (native mode) Maps to the CLI's `--max-turns`. The bound stop is NAMED
- *   (`error_max_turns` → `session.error:'max_turns'`), never a silent clean success.
- * @property {number} [maxConsecutiveDenials=3] - (native mode) BA-11 at the bridge: a single deny stays
- *   advisory so the model can pivot to an allowed tool; N in a row with no allowed call between ends the
- *   session with `denied:<tool>`. `0`/`Infinity` disables.
- * @property {number} [maxIdenticalToolErrors=3] - (native mode) BA-12 at the bridge: only a BYTE-IDENTICAL
- *   repeat (name + JSON args) counts, so a model varying its args while recovering is never punished. N in
- *   a row ends the session with `stuck:<tool>`. `0`/`Infinity` disables.
- * @property {number} [sessionTimeout=600000] - (native mode) Wall-clock ceiling for one whole session. The
- *   30s `timeout` default is for one-shot text and would kill an agentic session mid-run.
- * @property {number} [bridgeTimeoutMs] - (native mode) Ceiling for ONE tool-handler round-trip across the
- *   bridge. A hung handler becomes an error tool result rather than a hung session (default 120s).
- *
- *   Either mode: a non-empty `tools` array on `generate()` routes to tool mode; an empty one stays
- *   plain text. With NO `toolProtocol`, `tools` are IGNORED (plain-text, the long-standing behavior —
- *   a non-tool-calling CLI legitimately sits in a Loop with tools mounted) plus a one-time `console.warn`.
- *   Emulation additionally requires a capable model (weak ones answer in prose; see `probeCapability`);
- *   native mode needs no such probe, because the CLI's own tool channel does not depend on the model
- *   agreeing to fill in a JSON questionnaire. The claude-specific parts of each live in
- *   `provider-clipipe-tools.js` / `provider-clipipe-mcp.js`, so a second CLI slots in behind the same seams.
- * @property {boolean} [probeCapability=true] - (EMULATION tool mode only) On the first tool-mode `generate`, run ONE cheap upfront probe that asks the model to obtain unknowable info via a tool. If it answers in prose instead of emitting a tool_call, throw a loud `ProviderError` naming the model — FAIL FAST rather than silently degrade mid-run (the weak-model failure mode). Behaviour-based, never a model name-list (a roster goes stale, BA-10). The verdict is cached per instance (one probe per provider, not per turn). Set `false` to skip when the caller already knows the model is capable.
- */
 export class CLIPipeProvider {
     /**
      * Provider that pipes prompts to a CLI command via stdin and reads stdout.

package/src/provider-clipipe.js

@@ -43,8 +43,16 @@ const { createBridge, resolveSessionError, runSession } = require('./provider-cl
  *   sum-at-end: a session that dies mid-run must already have surfaced every completed turn's spend or
  *   the gate loses all of it. The event shape mirrors `Loop({onLlmResult})`, so `wireGate(gate).onLlmResult`
  *   drops straight in — and when it is wired the Loop skips its own forward, so nothing is billed twice.
- * @property {number} [maxTurns] - (native mode) Maps to the CLI's `--max-turns`. The bound stop is NAMED
- *   (`error_max_turns` → `session.error:'max_turns'`), never a silent clean success.
+ * @property {number} [maxTurns] - (native mode) Bound on ASSISTANT/LLM TURNS — the same unit as the
+ *   Loop path's turn bound, so a caller's `maxTurns` means one thing on both surfaces (BA-17). NOT a
+ *   tool-call count: a single turn may issue a dozen parallel tool calls and still be one turn
+ *   (measured: 12 calls across 2 turns, well inside `--max-turns 3`). Enforced twice on purpose —
+ *   the CLI's own `--max-turns` stops the session cleanly at N and emits its result event (the only
+ *   report of the session's real cost), and a parent-side counter kills it if a turn beyond N is
+ *   ever observed, since that flag is undocumented in `claude --help` and a rename would otherwise
+ *   silently unbound the session. Either way the stop is NAMED (`session.error:'max_turns'`,
+ *   `stopReason:'max_turns'`) and carries the last turn's text forward, never a silent clean success
+ *   and never an empty result.
  * @property {number} [maxConsecutiveDenials=3] - (native mode) BA-11 at the bridge: a single deny stays
  *   advisory so the model can pivot to an allowed tool; N in a row with no allowed call between ends the
  *   session with `denied:<tool>`. `0`/`Infinity` disables.
@@ -66,6 +74,31 @@ const { createBridge, resolveSessionError, runSession } = require('./provider-cl
  * @property {boolean} [probeCapability=true] - (EMULATION tool mode only) On the first tool-mode `generate`, run ONE cheap upfront probe that asks the model to obtain unknowable info via a tool. If it answers in prose instead of emitting a tool_call, throw a loud `ProviderError` naming the model — FAIL FAST rather than silently degrade mid-run (the weak-model failure mode). Behaviour-based, never a model name-list (a roster goes stale, BA-10). The verdict is cached per instance (one probe per provider, not per turn). Set `false` to skip when the caller already knows the model is capable.
  */
 
+/**
+ * Session total minus what the per-turn events already reported, per tier, floored at 0.
+ *
+ * Floored because a negative would be a CREDIT to a gate's running total — an under-count that
+ * silently widens a budget cap. If the streamed turns ever overshoot the session total, the honest
+ * report is "nothing further", never "give some back".
+ *
+ * @param {import('../types').Usage} total
+ * @param {import('../types').Usage[]} streamed
+ * @returns {import('../types').Usage}
+ */
+function subtractUsage(total, streamed) {
+  const sum = (/** @type {keyof import('../types').Usage} */ k) =>
+    streamed.reduce((a, t) => a + (Number(t[k]) || 0), 0);
+  const at = (/** @type {keyof import('../types').Usage} */ k) =>
+    Math.max(0, (Number(total[k]) || 0) - sum(k));
+  /** @type {import('../types').Usage} */
+  const out = { inputTokens: at('inputTokens'), outputTokens: at('outputTokens') };
+  // Only report a cache tier the session actually had — an absent tier stays absent, never a
+  // synthetic 0 (the Usage contract).
+  if (total.cacheReadTokens !== undefined) out.cacheReadTokens = at('cacheReadTokens');
+  if (total.cacheCreationTokens !== undefined) out.cacheCreationTokens = at('cacheCreationTokens');
+  return out;
+}
+
 class CLIPipeProvider {
   /**
    * Provider that pipes prompts to a CLI command via stdin and reads stdout.
@@ -289,17 +322,25 @@ class CLIPipeProvider {
       throw new ProviderError(`[CLIPipeProvider] failed to spawn "${this.command}": ${r.spawnError.message}`, /** @type {any} */ ({ status: 0 }));
     }
 
-    /** @type {import('../types').Usage} */
-    const usage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
-    for (const t of r.turns) {
-      usage.inputTokens += t.inputTokens || 0;
-      usage.outputTokens += t.outputTokens || 0;
-      usage.cacheReadTokens += t.cacheReadTokens || 0;
-      usage.cacheCreationTokens += t.cacheCreationTokens || 0;
-    }
+    // The result event carries the session's authoritative totals. It has no `model` key — the model
+    // id lives under `modelUsage` — which is exactly what `mapClaudeMeta` already unpacks for the
+    // emulation path, so the native path reuses it rather than re-deriving three fields by hand.
+    const meta = r.final ? mapClaudeMeta(r.final) : null;
+
+    // `result.usage` is the authoritative session total and is preferred when present: it also
+    // captures a turn the CLI billed but never emitted as an event (measured — a bounded session's
+    // cut-off turn). Summing the per-turn records is the fallback for a session we killed before its
+    // result event. Either way the arithmetic is per-TURN, never per block-event (BA-17).
+    const usage = (meta && r.final.usage) ? meta.usage : r.turns.reduce((/** @type {any} */ a, t) => ({
+      inputTokens: a.inputTokens + (t.inputTokens || 0),
+      outputTokens: a.outputTokens + (t.outputTokens || 0),
+      cacheReadTokens: a.cacheReadTokens + (t.cacheReadTokens || 0),
+      cacheCreationTokens: a.cacheCreationTokens + (t.cacheCreationTokens || 0),
+    }), { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 });
 
     const { stopReason, error } = resolveSessionError({
-      terminal: st.terminal,
+      // A bridge/guard terminal is more specific than the turn backstop, so it wins the tag.
+      terminal: st.terminal || r.terminal,
       bridgeDown: st.bridgeDown,
       attempted: r.attempted,
       served: st.toolCalls,
@@ -307,17 +348,25 @@ class CLIPipeProvider {
       subtype: r.final && r.final.subtype,
     });
 
-    const costUsd = (r.final && Number.isFinite(r.final.total_cost_usd)) ? r.final.total_cost_usd : null;
-
-    // The authoritative price arrives only at session end (the CLI prices the SESSION, not the turn),
-    // so when per-turn streaming is wired it gets one closing event carrying the cost with zero
-    // usage — the tokens were already streamed, and double-counting either axis would be a lie.
+    const costUsd = (meta && Number.isFinite(meta.costUsd)) ? /** @type {number} */ (meta.costUsd) : null;
+
+    // The authoritative figures arrive only at session end — the CLI prices the SESSION, not the
+    // turn — so when per-turn streaming is wired, one closing event RECONCILES both axes.
+    //
+    // Money: the whole cost, which no turn reported.
+    // Tokens: the RESIDUAL, not zero and not the total. A turn's `message.usage` is a snapshot taken
+    // when its first block was emitted and never revised (measured: a turn that emitted ~816 output
+    // tokens reported 2, identically on all 13 of its block-events), so the streamed per-turn sum is
+    // real but SHORT of the session total. Sending the difference makes a gate's token axis add up
+    // to exactly what the CLI itself reports — where sending the total would double-count everything
+    // already streamed, and sending zero would leave the axis quietly under-fed.
+    const residual = subtractUsage(usage, r.turns);
     if (this.onTurn) {
       try {
         await this.onTurn({
-          model: (r.final && r.final.model) || null,
+          model: (meta && meta.model) || null,
           provider: 'clipipe',
-          usage: { inputTokens: 0, outputTokens: 0 },
+          usage: residual,
           costUsd,
           pricing: costUsd === null ? 'unpriced' : 'priced',
           durationMs: r.ms,
@@ -329,15 +378,23 @@ class CLIPipeProvider {
       }
     }
 
+    // BA-5 on the native path: a bound or a tripped guard is normal termination for a bounded
+    // attempt, and the text is the ONLY channel from this attempt to the next. The CLI reports
+    // `result: null` when it stops on its own bound (measured), and a session we killed never emits
+    // a result at all — so fall back to the last assistant turn's own words rather than ''.
+    const finalText = (r.final && typeof r.final.result === 'string' && r.final.result)
+      ? r.final.result
+      : (r.lastText || '');
+
     /** @type {GenerateResult} */
     const result = {
-      text: (r.final && typeof r.final.result === 'string') ? r.final.result : '',
+      text: finalText,
       toolCalls: [],
       usage,
-      model: (r.final && r.final.model) || null,
+      model: (meta && meta.model) || null,
       stopReason,
       session: {
-        turns: r.turns.length,
+        turns: r.turnCount,
         toolCalls: st.toolCalls,
         error,
         // Only true when we ACTUALLY streamed — unwired, the Loop must still forward the total or

package/src/provider-gemini.d.ts

@@ -19,6 +19,10 @@ export type GeminiOptions = {
      * - Attach the full upstream response to `err.body` on HTTP errors (off by default; `err.message` still carries the API error).
      */
     exposeErrorBody?: boolean | undefined;
+    /**
+     * - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
+     */
+    timeoutMs?: number | undefined;
 };
 /**
  * @typedef {object} GeminiOptions
@@ -26,6 +30,7 @@ export type GeminiOptions = {
  * @property {string} [model='gemini-2.5-flash'] - Model ID.
  * @property {string} [baseUrl='https://generativelanguage.googleapis.com/v1beta'] - API base (override for proxies; posts to `${baseUrl}/models/${model}:generateContent`).
  * @property {boolean} [exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default; `err.message` still carries the API error).
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
  */
 /**
  * Google Gemini provider (native `generateContent` API, NOT the OpenAI-compat endpoint — that endpoint
@@ -41,11 +46,12 @@ export class GeminiProvider {
     model: string;
     baseUrl: string;
     exposeErrorBody: boolean;
+    timeoutMs: number | undefined;
     /**
      * Generate a response from the Gemini API.
      * @param {Message[]} messages - Conversation messages (OpenAI format, auto-converted).
      * @param {ToolDef[]} [tools=[]] - Tool definitions.
-     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens).
+     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[GeminiProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
      */
@@ -66,8 +72,9 @@ export class GeminiProvider {
     /**
      * @param {string} path
      * @param {Record<string, any>} body
+     * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
      * @returns {Promise<any>}
      */
-    _request(path: string, body: Record<string, any>): Promise<any>;
+    _request(path: string, body: Record<string, any>, timeoutMs?: number): Promise<any>;
     _warnedInsecure: boolean | undefined;
 }

package/src/provider-gemini.js

@@ -5,6 +5,7 @@ const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
+const { resolveTimeoutMs, applyRequestTimeout } = require('./provider-http');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -23,6 +24,7 @@ function isLoopbackHost(hostname) {
  * @property {string} [model='gemini-2.5-flash'] - Model ID.
  * @property {string} [baseUrl='https://generativelanguage.googleapis.com/v1beta'] - API base (override for proxies; posts to `${baseUrl}/models/${model}:generateContent`).
  * @property {boolean} [exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default; `err.message` still carries the API error).
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
  */
 
 /**
@@ -39,13 +41,15 @@ class GeminiProvider {
     this.model = options.model || 'gemini-2.5-flash';
     this.baseUrl = options.baseUrl || 'https://generativelanguage.googleapis.com/v1beta';
     this.exposeErrorBody = options.exposeErrorBody === true;
+    // BA-18: request/idle timeout (ms). Resolved at call time (default 600000; 0/Infinity disable).
+    this.timeoutMs = options.timeoutMs;
   }
 
   /**
    * Generate a response from the Gemini API.
    * @param {Message[]} messages - Conversation messages (OpenAI format, auto-converted).
    * @param {ToolDef[]} [tools=[]] - Tool definitions.
-   * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens).
+   * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[GeminiProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
    */
@@ -107,8 +111,9 @@ class GeminiProvider {
 
     // BA-10: graceful degrade if a model rejects a non-default `temperature` (Gemini nests it under
     // generationConfig). Keyed off the API error text, so dormant on models that accept temperature.
+    const timeoutMs = resolveTimeoutMs(this.timeoutMs, options.timeoutMs);
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request(`/models/${this.model}:generateContent`, body),
+      request: () => this._request(`/models/${this.model}:generateContent`, body, timeoutMs),
       hadTemperature: () => body.generationConfig?.temperature != null,
       stripTemperature: () => { if (body.generationConfig) delete body.generationConfig.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -174,9 +179,10 @@ class GeminiProvider {
   /**
    * @param {string} path
    * @param {Record<string, any>} body
+   * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(path, body) {
+  _request(path, body, timeoutMs = 0) {
     return new Promise((resolve, reject) => {
       const url = new URL(this.baseUrl + path);
       const transport = url.protocol === 'https:' ? https : http;
@@ -213,6 +219,7 @@ class GeminiProvider {
           }
         });
       });
+      applyRequestTimeout(req, timeoutMs, 'GeminiProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();

package/src/provider-http.d.ts

@@ -0,0 +1,34 @@
+/**
+ * BA-18 — shared request-timeout helper for the http(s)-based providers (Anthropic, OpenAI,
+ * Gemini, Ollama). They all build a `http.ClientRequest` with only `req.on('error')` wired, so a
+ * socket the server silently dropped — or a response that never starts — was bounded only by the
+ * OS TCP timeout (~2h on Linux). That presents to the caller as a hang, not a failure, so every
+ * retry/casualty policy above it is inert. This adds a finite, configurable idle bound in one
+ * place so the four providers cannot drift.
+ */
+export const DEFAULT_TIMEOUT_MS: 600000;
+/**
+ * Resolve the effective timeout in ms. A per-call value overrides the instance default, but `null`
+ * and `undefined` BOTH mean "inherit" — so a per-call `null` never shadows an instance-level
+ * disable (finding-2). The explicit opt-out idiom is `0` or `Infinity` → returns 0 (no bound, the
+ * pre-BA-18 behaviour). A NaN / negative / otherwise non-finite value is treated as a caller
+ * MISTAKE and falls back to {@link DEFAULT_TIMEOUT_MS}: it must never silently disable the safety
+ * bound, which would round optimistically back toward the ~2h hang BA-18 exists to prevent
+ * (finding-3; the disable-edge bug class).
+ * @param {number|undefined|null} instanceTimeout
+ * @param {number|undefined|null} [callTimeout]
+ * @returns {number} a finite positive ms bound, or 0 to disable
+ */
+export function resolveTimeoutMs(instanceTimeout: number | undefined | null, callTimeout?: number | undefined | null): number;
+/**
+ * Bound an in-flight ClientRequest on socket INACTIVITY. On timeout, destroy the request with a
+ * retryable {@link TimeoutError} (`code: 'ETIMEDOUT'`) — `DEFAULT_RETRY_ON` classifies that as
+ * transient, and the provider's own `req.on('error', reject)` turns it into a rejected promise, so
+ * the caller regains control instead of hanging. Idle semantics (via `req.setTimeout`): the timer
+ * resets on any socket activity, so a slow-but-streaming response is NOT killed — only a silent or
+ * never-answering socket trips it. A `timeoutMs` of 0 is a no-op (bound disabled).
+ * @param {import('http').ClientRequest} req
+ * @param {number} timeoutMs - resolved bound; 0 disables
+ * @param {string} providerName - for the error message (e.g. 'AnthropicProvider')
+ */
+export function applyRequestTimeout(req: import("http").ClientRequest, timeoutMs: number, providerName: string): void;

package/src/provider-http.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const { TimeoutError } = require('./errors');
+
+/**
+ * BA-18 — shared request-timeout helper for the http(s)-based providers (Anthropic, OpenAI,
+ * Gemini, Ollama). They all build a `http.ClientRequest` with only `req.on('error')` wired, so a
+ * socket the server silently dropped — or a response that never starts — was bounded only by the
+ * OS TCP timeout (~2h on Linux). That presents to the caller as a hang, not a failure, so every
+ * retry/casualty policy above it is inert. This adds a finite, configurable idle bound in one
+ * place so the four providers cannot drift.
+ */
+
+// 10 minutes: safely above any single non-streaming completion (a big reasoning response is a few
+// minutes at most), well below the ~2h OS TCP default. These requests are non-streaming, so a legit
+// slow completion can have no socket activity until the whole body arrives (TTFB ≈ generation time)
+// — the default must clear that, not a typical round-trip.
+const DEFAULT_TIMEOUT_MS = 600000;
+
+/**
+ * Resolve the effective timeout in ms. A per-call value overrides the instance default, but `null`
+ * and `undefined` BOTH mean "inherit" — so a per-call `null` never shadows an instance-level
+ * disable (finding-2). The explicit opt-out idiom is `0` or `Infinity` → returns 0 (no bound, the
+ * pre-BA-18 behaviour). A NaN / negative / otherwise non-finite value is treated as a caller
+ * MISTAKE and falls back to {@link DEFAULT_TIMEOUT_MS}: it must never silently disable the safety
+ * bound, which would round optimistically back toward the ~2h hang BA-18 exists to prevent
+ * (finding-3; the disable-edge bug class).
+ * @param {number|undefined|null} instanceTimeout
+ * @param {number|undefined|null} [callTimeout]
+ * @returns {number} a finite positive ms bound, or 0 to disable
+ */
+function resolveTimeoutMs(instanceTimeout, callTimeout) {
+  const raw = callTimeout != null ? callTimeout : instanceTimeout; // null/undefined per-call → inherit
+  if (raw == null) return DEFAULT_TIMEOUT_MS;    // absent on both → finite default
+  const n = Number(raw);
+  if (n === 0 || n === Infinity) return 0;       // the explicit opt-out idiom → no bound
+  if (!Number.isFinite(n) || n < 0) return DEFAULT_TIMEOUT_MS; // NaN / negative / garbage → SAFE default, never a silent disable
+  return n;                                      // finite positive bound
+}
+
+/**
+ * Bound an in-flight ClientRequest on socket INACTIVITY. On timeout, destroy the request with a
+ * retryable {@link TimeoutError} (`code: 'ETIMEDOUT'`) — `DEFAULT_RETRY_ON` classifies that as
+ * transient, and the provider's own `req.on('error', reject)` turns it into a rejected promise, so
+ * the caller regains control instead of hanging. Idle semantics (via `req.setTimeout`): the timer
+ * resets on any socket activity, so a slow-but-streaming response is NOT killed — only a silent or
+ * never-answering socket trips it. A `timeoutMs` of 0 is a no-op (bound disabled).
+ * @param {import('http').ClientRequest} req
+ * @param {number} timeoutMs - resolved bound; 0 disables
+ * @param {string} providerName - for the error message (e.g. 'AnthropicProvider')
+ */
+function applyRequestTimeout(req, timeoutMs, providerName) {
+  if (!(timeoutMs > 0)) return;
+  req.setTimeout(timeoutMs, () => {
+    req.destroy(new TimeoutError(`[${providerName}] request timed out after ${timeoutMs}ms of socket inactivity`));
+  });
+}
+
+module.exports = { DEFAULT_TIMEOUT_MS, resolveTimeoutMs, applyRequestTimeout };

package/src/provider-ollama.d.ts

@@ -5,6 +5,10 @@ export type OllamaOptions = {
     model?: string | undefined;
     url?: string | undefined;
     exposeErrorBody?: boolean | undefined;
+    /**
+     * - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout. `0`/`Infinity` disables it. Overridable per call via `generate(..., { timeoutMs })`. (A local Ollama that is loading a large model cold can be slow to first byte — raise this or disable it for very large local models.)
+     */
+    timeoutMs?: number | undefined;
 };
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -14,6 +18,7 @@ export type OllamaOptions = {
  * @property {string} [model='llama3.2']
  * @property {string} [url='http://localhost:11434']
  * @property {boolean} [exposeErrorBody=false]
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout. `0`/`Infinity` disables it. Overridable per call via `generate(..., { timeoutMs })`. (A local Ollama that is loading a large model cold can be slow to first byte — raise this or disable it for very large local models.)
  */
 export class OllamaProvider {
     /**
@@ -23,11 +28,12 @@ export class OllamaProvider {
     model: string;
     url: string;
     exposeErrorBody: boolean;
+    timeoutMs: number | undefined;
     /**
      * Generate a response from a local Ollama instance.
      * @param {Message[]} messages - Conversation messages.
      * @param {ToolDef[]} [tools=[]] - Tool definitions.
-     * @param {Record<string, any>} [options={}] - Options (`temperature`, `maxTokens`).
+     * @param {Record<string, any>} [options={}] - Options (`temperature`, `maxTokens`, `timeoutMs` — a per-call override of the constructor's `timeoutMs`; see BA-18).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[OllamaProvider] ...` — on HTTP errors or invalid JSON response.
      */
@@ -38,7 +44,8 @@ export class OllamaProvider {
     /**
      * @param {string} path
      * @param {Record<string, any>} body
+     * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
      * @returns {Promise<any>}
      */
-    _request(path: string, body: Record<string, any>): Promise<any>;
+    _request(path: string, body: Record<string, any>, timeoutMs?: number): Promise<any>;
 }

package/src/provider-ollama.js

@@ -4,6 +4,7 @@ const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
+const { resolveTimeoutMs, applyRequestTimeout } = require('./provider-http');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -14,6 +15,7 @@ const { normalizeStopReason } = require('./provider-stop-reason');
  * @property {string} [model='llama3.2']
  * @property {string} [url='http://localhost:11434']
  * @property {boolean} [exposeErrorBody=false]
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout. `0`/`Infinity` disables it. Overridable per call via `generate(..., { timeoutMs })`. (A local Ollama that is loading a large model cold can be slow to first byte — raise this or disable it for very large local models.)
  */
 
 class OllamaProvider {
@@ -25,13 +27,15 @@ class OllamaProvider {
     this.url = options.url || 'http://localhost:11434';
     // See OpenAIProvider: attach full upstream body to err.body only on opt-in.
     this.exposeErrorBody = options.exposeErrorBody === true;
+    // BA-18: request/idle timeout (ms). Resolved at call time (default 600000; 0/Infinity disable).
+    this.timeoutMs = options.timeoutMs;
   }
 
   /**
    * Generate a response from a local Ollama instance.
    * @param {Message[]} messages - Conversation messages.
    * @param {ToolDef[]} [tools=[]] - Tool definitions.
-   * @param {Record<string, any>} [options={}] - Options (`temperature`, `maxTokens`).
+   * @param {Record<string, any>} [options={}] - Options (`temperature`, `maxTokens`, `timeoutMs` — a per-call override of the constructor's `timeoutMs`; see BA-18).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[OllamaProvider] ...` — on HTTP errors or invalid JSON response.
    */
@@ -64,8 +68,9 @@ class OllamaProvider {
 
     // BA-10: graceful degrade if a model rejects a non-default `temperature` (Ollama nests it under
     // `options`). Keyed off the API error text, so dormant on models that accept temperature.
+    const timeoutMs = resolveTimeoutMs(this.timeoutMs, options.timeoutMs);
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request('/api/chat', body),
+      request: () => this._request('/api/chat', body, timeoutMs),
       hadTemperature: () => body.options?.temperature != null,
       stripTemperature: () => { if (body.options) delete body.options.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -110,9 +115,10 @@ class OllamaProvider {
   /**
    * @param {string} path
    * @param {Record<string, any>} body
+   * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(path, body) {
+  _request(path, body, timeoutMs = 0) {
     return new Promise((resolve, reject) => {
       const url = new URL(this.url + path);
       const payload = JSON.stringify(body);
@@ -141,6 +147,7 @@ class OllamaProvider {
           }
         });
       });
+      applyRequestTimeout(req, timeoutMs, 'OllamaProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();

package/src/provider-openai.d.ts

@@ -14,6 +14,13 @@ export type OpenAIOptions = {
      * debugging only.
      */
     exposeErrorBody?: boolean | undefined;
+    /**
+     * - BA-18: request/idle timeout in ms. Bounds a silent or
+     * never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError`
+     * (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity`
+     * disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
+     */
+    timeoutMs?: number | undefined;
 };
 /**
  * @typedef {object} OpenAIOptions
@@ -25,6 +32,10 @@ export type OpenAIOptions = {
  *   field in an error payload can't leak through logs that dump the error
  *   object; `err.message` still carries the API's error message. Turn on for
  *   debugging only.
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or
+ *   never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError`
+ *   (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity`
+ *   disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
  */
 export class OpenAIProvider {
     /**
@@ -35,11 +46,12 @@ export class OpenAIProvider {
     model: string;
     baseUrl: string;
     exposeErrorBody: boolean;
+    timeoutMs: number | undefined;
     /**
      * Generate a response from the OpenAI API.
      * @param {Message[]} messages - Conversation messages.
      * @param {ToolDef[]} [tools=[]] - Tool definitions.
-     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens).
+     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[OpenAIProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
      */
@@ -60,8 +72,9 @@ export class OpenAIProvider {
     /**
      * @param {string} path
      * @param {Record<string, any>} body
+     * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
      * @returns {Promise<any>}
      */
-    _request(path: string, body: Record<string, any>): Promise<any>;
+    _request(path: string, body: Record<string, any>, timeoutMs?: number): Promise<any>;
     _warnedInsecure: boolean | undefined;
 }

package/src/provider-openai.js

@@ -5,6 +5,7 @@ const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
+const { resolveTimeoutMs, applyRequestTimeout } = require('./provider-http');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -27,6 +28,10 @@ function isLoopbackHost(hostname) {
  *   field in an error payload can't leak through logs that dump the error
  *   object; `err.message` still carries the API's error message. Turn on for
  *   debugging only.
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or
+ *   never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError`
+ *   (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity`
+ *   disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
  */
 
 class OpenAIProvider {
@@ -38,13 +43,15 @@ class OpenAIProvider {
     this.model = options.model || 'gpt-4o-mini';
     this.baseUrl = options.baseUrl || 'https://api.openai.com/v1';
     this.exposeErrorBody = options.exposeErrorBody === true;
+    // BA-18: request/idle timeout (ms). Resolved at call time (default 600000; 0/Infinity disable).
+    this.timeoutMs = options.timeoutMs;
   }
 
   /**
    * Generate a response from the OpenAI API.
    * @param {Message[]} messages - Conversation messages.
    * @param {ToolDef[]} [tools=[]] - Tool definitions.
-   * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens).
+   * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[OpenAIProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
    */
@@ -65,8 +72,9 @@ class OpenAIProvider {
 
     // BA-10: newer models (o1/gpt-5-class) reject a non-default `temperature` with a 400 — drop it and
     // retry once. `temperatureDropped` flows back so an upstream receipt can report the effective value.
+    const timeoutMs = resolveTimeoutMs(this.timeoutMs, options.timeoutMs);
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request('/chat/completions', body),
+      request: () => this._request('/chat/completions', body, timeoutMs),
       hadTemperature: () => body.temperature != null,
       stripTemperature: () => { delete body.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -124,9 +132,10 @@ class OpenAIProvider {
   /**
    * @param {string} path
    * @param {Record<string, any>} body
+   * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(path, body) {
+  _request(path, body, timeoutMs = 0) {
     return new Promise((resolve, reject) => {
       const url = new URL(this.baseUrl + path);
       const transport = url.protocol === 'https:' ? https : http;
@@ -168,6 +177,7 @@ class OpenAIProvider {
           }
         });
       });
+      applyRequestTimeout(req, timeoutMs, 'OpenAIProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();