@vanillagreen/pi-claude-bridge 1.3.0 → 1.4.1

package/README.md

@@ -98,6 +98,8 @@ When Claude Code emits rate-limit reset metadata, the bridge shows one red ASCII
 
 Allowed-warning rate-limit events are filtered before user notification. The bridge normalizes unambiguous numeric utilization (`0 < value < 1` as fractional, `1 < value <= 100` as percent), suppresses low or unit-ambiguous values such as exact `1`, and only shows a neutral warning at 80%+ instead of claiming an unverified `% used` value. Check Claude Code `/usage` for exact allowed-warning utilization.
 
+If Claude Code accepts a turn but produces no assistant/tool output, the bridge treats that stream-idle stall as a retryable overload/rate-limit failure: it closes the stalled Claude Code subprocess, emits a normal assistant error with a backoff hint, and lets Flightdeck or `pi-agents-tmux` reuse their existing rate-limit retry ladder. Tune the first-output timeout with `CLAUDE_BRIDGE_STREAM_IDLE_TIMEOUT` (bare numbers are seconds; suffixes `ms`, `s`, and `m` are accepted). Default: `90s`; set `0` to disable.
+
 ## Debugging
 
 Set `CLAUDE_BRIDGE_DEBUG=1` to write bridge logs to `~/.pi/agent/claude-bridge.log` and per-query Claude Code CLI logs under `~/.pi/agent/cc-cli-logs/`.

package/bundle/index.js

@@ -21976,7 +21976,7 @@ function readSession(jsonlPath, projectPath) {
 // src/index.ts
 import { spawn as spawnProcess } from "child_process";
 import { createHash } from "crypto";
-import { accessSync, appendFileSync as appendFileSync3, chmodSync, constants as fsConstants, mkdirSync as mkdirSync3, readFileSync as readFileSync7, realpathSync as realpathSync3, statSync as statSync3 } from "fs";
+import { accessSync, appendFileSync as appendFileSync3, chmodSync, constants as fsConstants, mkdirSync as mkdirSync3, readFileSync as readFileSync6, realpathSync as realpathSync3, statSync as statSync3 } from "fs";
 import { resolve as pathResolve } from "path";
 import { homedir as homedir5 } from "os";
 import { delimiter, dirname as dirname5, join as join5 } from "path";
@@ -22272,7 +22272,46 @@ function rewriteSkillsBlock(skillsBlock) {
 }
 
 // src/session-verify.ts
-import { statSync as statSync2, readFileSync as readFileSync3 } from "fs";
+import { closeSync as closeSync2, openSync as openSync2, readSync as readSync2, statSync as statSync2 } from "fs";
+import { StringDecoder } from "node:string_decoder";
+function forEachJsonlLine(path, onLine) {
+  const fd = openSync2(path, "r");
+  const buffer = Buffer.allocUnsafe(64 * 1024);
+  const decoder = new StringDecoder("utf8");
+  let pending = "";
+  try {
+    for (; ; ) {
+      const bytesRead = readSync2(fd, buffer, 0, buffer.length, null);
+      if (bytesRead === 0) break;
+      pending += decoder.write(buffer.subarray(0, bytesRead));
+      let start = 0;
+      for (; ; ) {
+        const newline = pending.indexOf("\n", start);
+        if (newline < 0) {
+          pending = pending.slice(start);
+          break;
+        }
+        const line = pending.slice(start, newline);
+        onLine(line.endsWith("\r") ? line.slice(0, -1) : line);
+        start = newline + 1;
+      }
+    }
+    pending += decoder.end();
+    if (pending.length > 0) onLine(pending.endsWith("\r") ? pending.slice(0, -1) : pending);
+  } finally {
+    closeSync2(fd);
+  }
+}
+function summarizeJsonl(path) {
+  const summary = { count: 0 };
+  forEachJsonlLine(path, (line) => {
+    if (!line.trim()) return;
+    summary.count += 1;
+    if (summary.firstLine === void 0) summary.firstLine = line;
+    summary.lastLine = line;
+  });
+  return summary;
+}
 function verifyWrittenSession(jsonlPath, expectedSessionId, expectedRecordCount) {
   const warnings = [];
   let st;
@@ -22282,21 +22321,20 @@ function verifyWrittenSession(jsonlPath, expectedSessionId, expectedRecordCount)
     warnings.push(`file missing after save \u2014 path=${jsonlPath} err=${e2.message}`);
     return warnings;
   }
-  let content;
+  let summary;
   try {
-    content = readFileSync3(jsonlPath, "utf8");
+    summary = summarizeJsonl(jsonlPath);
   } catch (e2) {
     warnings.push(`file unreadable \u2014 path=${jsonlPath} size=${st.size} err=${e2.message}`);
     return warnings;
   }
-  const lines = content.split("\n").filter((l2) => l2.trim().length > 0);
-  if (lines.length !== expectedRecordCount) {
-    warnings.push(`record count mismatch \u2014 expected=${expectedRecordCount} actual=${lines.length} path=${jsonlPath} bytes=${content.length}`);
+  if (summary.count !== expectedRecordCount) {
+    warnings.push(`record count mismatch \u2014 expected=${expectedRecordCount} actual=${summary.count} path=${jsonlPath} bytes=${st.size}`);
     return warnings;
   }
   try {
-    const firstRec = JSON.parse(lines[0]);
-    const lastRec = JSON.parse(lines[lines.length - 1]);
+    const firstRec = JSON.parse(summary.firstLine ?? "");
+    const lastRec = JSON.parse(summary.lastLine ?? "");
     if (firstRec.sessionId !== expectedSessionId || lastRec.sessionId !== expectedSessionId) {
       warnings.push(`sessionId drift \u2014 expected=${expectedSessionId} first=${firstRec.sessionId} last=${lastRec.sessionId}`);
     }
@@ -22564,7 +22602,7 @@ function summarizeMissingToolNames(missing) {
 }
 
 // src/config.ts
-import { existsSync as existsSync3, readFileSync as readFileSync4 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
 import { homedir as homedir2 } from "os";
 import { dirname as dirname2, join as join2, resolve } from "path";
 var PACKAGE_ID = "@vanillagreen/pi-claude-bridge";
@@ -22606,7 +22644,7 @@ function settingsPaths(cwd) {
 function tryParseJson(path) {
   if (!existsSync3(path)) return {};
   try {
-    return JSON.parse(readFileSync4(path, "utf-8"));
+    return JSON.parse(readFileSync3(path, "utf-8"));
   } catch {
     return {};
   }
@@ -22616,7 +22654,7 @@ function readManagerConfig(cwd) {
   for (const path of settingsPaths(cwd)) {
     if (!existsSync3(path)) continue;
     try {
-      const parsed = JSON.parse(readFileSync4(path, "utf8"));
+      const parsed = JSON.parse(readFileSync3(path, "utf8"));
       const configRoot = asRecord(asRecord(asRecord(parsed?.vstack)?.extensionManager)?.config);
       const config2 = asRecord(configRoot?.[PACKAGE_ID]);
       if (config2) mergeDeep(merged, config2);
@@ -22720,7 +22758,7 @@ function loadConfig(cwd) {
 }
 
 // src/agents-md.ts
-import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
 import { homedir as homedir3 } from "os";
 import { dirname as dirname3, join as join3, resolve as resolve2 } from "path";
 var GLOBAL_AGENTS_PATH = join3(homedir3(), ".pi", "agent", "AGENTS.md");
@@ -22745,7 +22783,7 @@ function extractAgentsAppend() {
   const agentsPath = resolveAgentsMdPath();
   if (!agentsPath) return void 0;
   try {
-    const content = readFileSync5(agentsPath, "utf-8").trim();
+    const content = readFileSync4(agentsPath, "utf-8").trim();
     if (!content) return void 0;
     const sanitized = sanitizeAgentsContent(content);
     return sanitized.length > 0 ? `# CLAUDE.md
@@ -22765,7 +22803,7 @@ function sanitizeAgentsContent(content) {
 }
 
 // src/prompt-context.ts
-import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
 import { homedir as homedir4 } from "os";
 import { dirname as dirname4, join as join4, resolve as resolve3 } from "path";
 function piUserDir2() {
@@ -22776,7 +22814,7 @@ function piUserDir2() {
 function readTrimmed(path) {
   try {
     if (!existsSync5(path)) return void 0;
-    const content = readFileSync6(path, "utf8").trim();
+    const content = readFileSync5(path, "utf8").trim();
     return content.length > 0 ? content : void 0;
   } catch {
     return void 0;
@@ -37607,7 +37645,7 @@ function preflightClaudeExecutable(path, cwd) {
   }
   let fileType;
   try {
-    fileType = classifyClaudeExecutableBytes(readFileSync7(realPath).subarray(0, 16));
+    fileType = classifyClaudeExecutableBytes(readFileSync6(realPath).subarray(0, 16));
   } catch (err) {
     throw makeClaudePreflightError("Claude Code executable preflight failed: cannot read executable header before spawning Claude Code.", {
       code: codeValue(err, "EACCES"),
@@ -37873,6 +37911,90 @@ var piUI;
 var extraUsageHelperInFlight = null;
 var RATE_LIMIT_AUTO_RESUME_EVENT = "vstack:rate-limit";
 var RATE_LIMIT_TOKEN = "\x1B[31m[rate-limit]\x1B[39m";
+var DEFAULT_STREAM_IDLE_TIMEOUT_MS = 9e4;
+var STREAM_IDLE_BACKOFF_HINT_MS = 6e4;
+var STREAM_IDLE_TIMEOUT_ENV = "CLAUDE_BRIDGE_STREAM_IDLE_TIMEOUT";
+var activeStreamIdleWatchdogs = /* @__PURE__ */ new WeakMap();
+function parseDurationLiteralMs(value, defaultUnit = "s") {
+  const text = value.trim().toLowerCase();
+  if (!text) return void 0;
+  if (["off", "false", "disabled", "disable"].includes(text)) return 0;
+  const match = text.match(/^(\d+(?:\.\d+)?)\s*(ms|msec|msecs|milliseconds?|s|sec|secs|seconds?|m|min|mins|minutes?)?$/i);
+  if (!match) return void 0;
+  const amount = Number(match[1]);
+  if (!Number.isFinite(amount) || amount < 0) return void 0;
+  const unit = (match[2] ?? defaultUnit).toLowerCase();
+  const multiplier = ["ms", "msec", "msecs", "millisecond", "milliseconds"].includes(unit) ? 1 : ["s", "sec", "secs", "second", "seconds"].includes(unit) ? 1e3 : ["m", "min", "mins", "minute", "minutes"].includes(unit) ? 6e4 : void 0;
+  if (multiplier === void 0) return void 0;
+  const ms = Math.round(amount * multiplier);
+  return Number.isFinite(ms) ? ms : void 0;
+}
+function streamIdleTimeoutMsFromEnv(env = process.env) {
+  const raw = env[STREAM_IDLE_TIMEOUT_ENV]?.trim();
+  if (!raw) return DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+  return parseDurationLiteralMs(raw, "s") ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+}
+function formatDurationShort(ms) {
+  if (ms < 18e4 && ms % 1e3 === 0) return `${ms / 1e3}s`;
+  if (ms % 6e4 === 0) return `${ms / 6e4}m`;
+  if (ms % 1e3 === 0) return `${ms / 1e3}s`;
+  return `${ms}ms`;
+}
+function buildStreamIdleTimeoutErrorMessage(timeoutMs) {
+  return `Claude Code stream idle timeout after ${formatDurationShort(timeoutMs)} with no assistant/tool output; treating stalled stream as retryable 529 overloaded/rate limit condition. Retry after ${formatDurationShort(STREAM_IDLE_BACKOFF_HINT_MS)}.`;
+}
+function createStreamIdleWatchdog({
+  clearTimer = (timer) => clearTimeout(timer),
+  getState,
+  now = () => Date.now(),
+  onTimeout,
+  setTimer = (fn, delayMs) => setTimeout(fn, delayMs),
+  timeoutMs
+}) {
+  let disposed = false;
+  let lastChunkAt = now();
+  let timer = null;
+  let didTimeout = false;
+  const clear = () => {
+    if (!timer) return;
+    try {
+      clearTimer(timer);
+    } catch {
+    }
+    timer = null;
+  };
+  const shouldMonitor = (state) => Boolean(
+    timeoutMs > 0 && state.activeQuery && state.currentPiStream && state.turnOutput && !state.turnStarted && !state.turnSawStreamEvent
+  );
+  const schedule = () => {
+    clear();
+    if (disposed || didTimeout || timeoutMs <= 0) return;
+    const state = getState();
+    if (!shouldMonitor(state)) return;
+    const turnStartedAt = typeof state.turnOutput?.timestamp === "number" ? state.turnOutput.timestamp : 0;
+    const idleStartedAt = Math.max(lastChunkAt, turnStartedAt);
+    const idleMs = Math.max(0, now() - idleStartedAt);
+    if (idleMs >= timeoutMs) {
+      didTimeout = true;
+      onTimeout({ idleMs, timeoutMs });
+      return;
+    }
+    timer = setTimer(schedule, Math.max(1, timeoutMs - idleMs));
+    timer.unref?.();
+  };
+  return {
+    dispose: () => {
+      disposed = true;
+      clear();
+    },
+    noteChunk: () => {
+      lastChunkAt = now();
+      schedule();
+    },
+    refresh: schedule,
+    timedOut: () => didTimeout
+  };
+}
 function isExtraUsageRequiredMessage(value) {
   let text;
   if (typeof value === "string") text = value;
@@ -38639,6 +38761,7 @@ async function consumeQuery(sdkQuery, customToolNameToPi, model, cwd, bridgeConf
   for await (const message of sdkQuery) {
     if (wasAborted()) break;
     const queryCtx = ctx();
+    activeStreamIdleWatchdogs.get(queryCtx)?.noteChunk();
     if (!queryCtx.turnOutput) continue;
     if (!queryCtx.currentPiStream && !(message.type === "assistant" && queryCtx.turnSawToolCall)) continue;
     switch (message.type) {
@@ -38720,6 +38843,7 @@ function streamClaudeAgentSdk(model, context, options) {
     const queryCtx = ctx();
     queryCtx.currentPiStream = stream;
     queryCtx.resetTurnState(model);
+    activeStreamIdleWatchdogs.get(queryCtx)?.refresh();
     const allResults = extractAllToolResults2(context);
     debug(`provider: tool results, ${allResults.length} results, ${queryCtx.pendingToolCalls.size} waiting handlers, ctx.msgs=${context.messages.length}`);
     const unmatchedResultIds = [];
@@ -38859,6 +38983,7 @@ function streamClaudeAgentSdk(model, context, options) {
     `prompt=${promptText.slice(0, 60)}${promptBlocks ? " [+images]" : ""}`
   );
   let wasAborted = false;
+  let streamIdleTimedOut = false;
   const sdkQuery = jA$({ prompt, options: queryOptions });
   ctx().activeQuery = sdkQuery;
   const abortCtx = ctx();
@@ -38870,6 +38995,55 @@ function streamClaudeAgentSdk(model, context, options) {
     } catch {
     }
   };
+  const streamIdleTimeoutMs = streamIdleTimeoutMsFromEnv();
+  const streamIdleWatchdog = streamIdleTimeoutMs > 0 ? createStreamIdleWatchdog({
+    getState: () => ({
+      activeQuery: abortCtx.activeQuery,
+      currentPiStream: abortCtx.currentPiStream,
+      turnOutput: abortCtx.turnOutput,
+      turnSawStreamEvent: abortCtx.turnSawStreamEvent,
+      turnStarted: abortCtx.turnStarted
+    }),
+    onTimeout: ({ idleMs, timeoutMs }) => {
+      if (streamIdleTimedOut || wasAborted || options?.signal?.aborted || abortCtx.activeQuery !== sdkQuery) return;
+      streamIdleTimedOut = true;
+      abortCtx.deferredUserMessages = [];
+      abortCtx.handledTerminalError = true;
+      if (sharedSession) sharedSession = { ...sharedSession, needsRebuild: true, forceRotate: true };
+      const errorMessage = buildStreamIdleTimeoutErrorMessage(timeoutMs);
+      debug("provider: stream idle timeout", `model=${model.id}`, `timeout=${timeoutMs}`, `idle=${idleMs}`);
+      emitRateLimitEvent({
+        idleMs,
+        model: model.id,
+        provider: PROVIDER_ID,
+        rateLimitType: "stream_idle",
+        reason: "Claude Code stream idle timeout",
+        retryAfterMs: STREAM_IDLE_BACKOFF_HINT_MS,
+        source: "claude-bridge",
+        status: "rejected",
+        timeoutMs
+      });
+      piUI?.notify(`${RATE_LIMIT_TOKEN} Claude stream idle timeout after ${formatDurationShort(timeoutMs)} \u2014 retrying via rate-limit backoff`, "warning");
+      if (abortCtx.turnOutput) {
+        abortCtx.turnOutput.stopReason = "error";
+        abortCtx.turnOutput.errorMessage = errorMessage;
+        Object.assign(abortCtx.turnOutput, {
+          rateLimitType: "stream_idle",
+          retryAfterMs: STREAM_IDLE_BACKOFF_HINT_MS,
+          streamIdleTimeoutMs: timeoutMs
+        });
+      }
+      abortCtx.currentPiStream?.push({ type: "error", reason: "error", error: abortCtx.turnOutput });
+      abortCtx.currentPiStream?.end();
+      abortCtx.currentPiStream = null;
+      requestAbort();
+    },
+    timeoutMs: streamIdleTimeoutMs
+  }) : null;
+  if (streamIdleWatchdog) {
+    activeStreamIdleWatchdogs.set(abortCtx, streamIdleWatchdog);
+    streamIdleWatchdog.refresh();
+  }
   const onAbort = () => {
     wasAborted = true;
     abortCtx.deferredUserMessages = [];
@@ -38887,6 +39061,11 @@ function streamClaudeAgentSdk(model, context, options) {
   }
   consumeQuery(sdkQuery, customToolNameToPi, model, cwd, bridgeConfig, () => wasAborted).then(async ({ capturedSessionId }) => {
     debug(`provider: consumeQuery completed, stopReason=${ctx().turnOutput?.stopReason}, error=${ctx().turnOutput?.errorMessage}, aborted=${wasAborted}`);
+    if (streamIdleTimedOut) {
+      abortCtx.deferredUserMessages = [];
+      debug("provider: stream idle timeout already surfaced; skipping normal completion");
+      return;
+    }
     if (wasAborted || options?.signal?.aborted) {
       if (sharedSession) sharedSession = { ...sharedSession, needsRebuild: true, forceRotate: true };
       ctx().deferredUserMessages = [];
@@ -38940,7 +39119,7 @@ function streamClaudeAgentSdk(model, context, options) {
     finalizeCurrentStream(ctx().turnOutput?.stopReason);
   }).catch((error51) => {
     debug(`provider: query error, model=${model.id}, aborted=${Boolean(options?.signal?.aborted)}, error=`, error51);
-    const suppressDuplicateError = ctx().handledTerminalError;
+    const suppressDuplicateError = ctx().handledTerminalError || streamIdleTimedOut;
     const openedExtraUsage = !suppressDuplicateError && isExtraUsageRequiredMessage(error51) && launchExtraUsageHelperIfAllowed(cwd, bridgeConfig, "query error");
     if ((wasAborted || options?.signal?.aborted) && sharedSession) {
       sharedSession = { ...sharedSession, needsRebuild: true, forceRotate: true };
@@ -38960,9 +39139,11 @@ function streamClaudeAgentSdk(model, context, options) {
     ctx().currentPiStream?.end();
     ctx().currentPiStream = null;
   }).finally(() => {
+    streamIdleWatchdog?.dispose();
+    activeStreamIdleWatchdogs.delete(abortCtx);
     if (options?.signal) options.signal.removeEventListener("abort", onAbort);
     if (ctx().activeQuery === sdkQuery) {
-      reportToolResultMismatch(ctx(), "query teardown", cwd, { forceRotate: wasAborted || options?.signal?.aborted });
+      reportToolResultMismatch(ctx(), "query teardown", cwd, { forceRotate: wasAborted || options?.signal?.aborted || streamIdleTimedOut });
       for (const pending of ctx().pendingToolCalls.values()) {
         pending.resolve({ content: [{ type: "text", text: "Query ended" }] });
       }
@@ -39097,10 +39278,15 @@ function index_default(pi) {
 export {
   ALLOWED_RATE_LIMIT_WARNING_UTILIZATION_THRESHOLD,
   CLAUDE_BRIDGE_TOOL_ISOLATION,
+  DEFAULT_STREAM_IDLE_TIMEOUT_MS,
   DISALLOWED_BUILTIN_TOOLS,
+  STREAM_IDLE_BACKOFF_HINT_MS,
+  STREAM_IDLE_TIMEOUT_ENV,
   __testGetBridgeIntegrityState,
   __testSetBridgeIntegrityState,
+  buildStreamIdleTimeoutErrorMessage,
   classifyClaudeExecutableBytes,
+  createStreamIdleWatchdog,
   index_default as default,
   formatAllowedRateLimitWarning,
   formatResetTimestamp,
@@ -39115,6 +39301,7 @@ export {
   restoreSharedSessionFromPi,
   shouldRestorePersistedBridgeEntry,
   spawnClaudeCodeWithDiagnostics,
+  streamIdleTimeoutMsFromEnv,
   uniqueNonEmptyLines,
   wrapClaudeSpawnErrorForSdk
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillagreen/pi-claude-bridge",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Pi provider bridge that runs Claude Code through the Claude Agent SDK, with opt-in forwarding for Pi prompt context.",
   "type": "module",
   "keywords": [

package/src/index.ts

@@ -532,6 +532,137 @@ let extraUsageHelperInFlight: Promise<string> | null = null;
 
 const RATE_LIMIT_AUTO_RESUME_EVENT = "vstack:rate-limit";
 const RATE_LIMIT_TOKEN = "\x1b[31m[rate-limit]\x1b[39m";
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 90_000;
+export const STREAM_IDLE_BACKOFF_HINT_MS = 60_000;
+export const STREAM_IDLE_TIMEOUT_ENV = "CLAUDE_BRIDGE_STREAM_IDLE_TIMEOUT";
+
+type TimerHandle = ReturnType<typeof setTimeout>;
+
+export interface StreamIdleWatchdogState {
+	activeQuery: unknown | null;
+	currentPiStream: AssistantMessageEventStream | null;
+	turnOutput: AssistantMessage | null;
+	turnSawStreamEvent: boolean;
+	turnStarted: boolean;
+}
+
+export interface StreamIdleTimeoutInfo {
+	idleMs: number;
+	timeoutMs: number;
+}
+
+export interface StreamIdleWatchdog {
+	dispose: () => void;
+	noteChunk: () => void;
+	refresh: () => void;
+	timedOut: () => boolean;
+}
+
+const activeStreamIdleWatchdogs = new WeakMap<QueryContext, StreamIdleWatchdog>();
+
+function parseDurationLiteralMs(value: string, defaultUnit: "ms" | "s" = "s"): number | undefined {
+	const text = value.trim().toLowerCase();
+	if (!text) return undefined;
+	if (["off", "false", "disabled", "disable"].includes(text)) return 0;
+	const match = text.match(/^(\d+(?:\.\d+)?)\s*(ms|msec|msecs|milliseconds?|s|sec|secs|seconds?|m|min|mins|minutes?)?$/i);
+	if (!match) return undefined;
+	const amount = Number(match[1]);
+	if (!Number.isFinite(amount) || amount < 0) return undefined;
+	const unit = (match[2] ?? defaultUnit).toLowerCase();
+	const multiplier = ["ms", "msec", "msecs", "millisecond", "milliseconds"].includes(unit)
+		? 1
+		: ["s", "sec", "secs", "second", "seconds"].includes(unit)
+			? 1000
+			: ["m", "min", "mins", "minute", "minutes"].includes(unit)
+				? 60_000
+				: undefined;
+	if (multiplier === undefined) return undefined;
+	const ms = Math.round(amount * multiplier);
+	return Number.isFinite(ms) ? ms : undefined;
+}
+
+export function streamIdleTimeoutMsFromEnv(env: NodeJS.ProcessEnv = process.env): number {
+	const raw = env[STREAM_IDLE_TIMEOUT_ENV]?.trim();
+	if (!raw) return DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+	return parseDurationLiteralMs(raw, "s") ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+}
+
+function formatDurationShort(ms: number): string {
+	if (ms < 180_000 && ms % 1000 === 0) return `${ms / 1000}s`;
+	if (ms % 60_000 === 0) return `${ms / 60_000}m`;
+	if (ms % 1000 === 0) return `${ms / 1000}s`;
+	return `${ms}ms`;
+}
+
+export function buildStreamIdleTimeoutErrorMessage(timeoutMs: number): string {
+	return `Claude Code stream idle timeout after ${formatDurationShort(timeoutMs)} with no assistant/tool output; treating stalled stream as retryable 529 overloaded/rate limit condition. Retry after ${formatDurationShort(STREAM_IDLE_BACKOFF_HINT_MS)}.`;
+}
+
+export function createStreamIdleWatchdog({
+	clearTimer = (timer: TimerHandle) => clearTimeout(timer),
+	getState,
+	now = () => Date.now(),
+	onTimeout,
+	setTimer = (fn: () => void, delayMs: number) => setTimeout(fn, delayMs),
+	timeoutMs,
+}: {
+	clearTimer?: (timer: TimerHandle) => void;
+	getState: () => StreamIdleWatchdogState;
+	now?: () => number;
+	onTimeout: (info: StreamIdleTimeoutInfo) => void;
+	setTimer?: (fn: () => void, delayMs: number) => TimerHandle;
+	timeoutMs: number;
+}): StreamIdleWatchdog {
+	let disposed = false;
+	let lastChunkAt = now();
+	let timer: TimerHandle | null = null;
+	let didTimeout = false;
+
+	const clear = () => {
+		if (!timer) return;
+		try { clearTimer(timer); } catch { /* best effort */ }
+		timer = null;
+	};
+
+	const shouldMonitor = (state: StreamIdleWatchdogState): boolean => Boolean(
+		timeoutMs > 0
+		&& state.activeQuery
+		&& state.currentPiStream
+		&& state.turnOutput
+		&& !state.turnStarted
+		&& !state.turnSawStreamEvent,
+	);
+
+	const schedule = () => {
+		clear();
+		if (disposed || didTimeout || timeoutMs <= 0) return;
+		const state = getState();
+		if (!shouldMonitor(state)) return;
+		const turnStartedAt = typeof state.turnOutput?.timestamp === "number" ? state.turnOutput.timestamp : 0;
+		const idleStartedAt = Math.max(lastChunkAt, turnStartedAt);
+		const idleMs = Math.max(0, now() - idleStartedAt);
+		if (idleMs >= timeoutMs) {
+			didTimeout = true;
+			onTimeout({ idleMs, timeoutMs });
+			return;
+		}
+		timer = setTimer(schedule, Math.max(1, timeoutMs - idleMs));
+		(timer as { unref?: () => void }).unref?.();
+	};
+
+	return {
+		dispose: () => {
+			disposed = true;
+			clear();
+		},
+		noteChunk: () => {
+			lastChunkAt = now();
+			schedule();
+		},
+		refresh: schedule,
+		timedOut: () => didTimeout,
+	};
+}
 
 export function isExtraUsageRequiredMessage(value: unknown): boolean {
 	let text: string;
@@ -1532,6 +1663,7 @@ async function consumeQuery(
 	for await (const message of sdkQuery) {
 		if (wasAborted()) break;
 		const queryCtx = ctx();
+		activeStreamIdleWatchdogs.get(queryCtx)?.noteChunk();
 		if (!queryCtx.turnOutput) continue;
 		if (!queryCtx.currentPiStream && !(message.type === "assistant" && queryCtx.turnSawToolCall)) continue;
 
@@ -1626,6 +1758,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		const queryCtx = ctx();
 		queryCtx.currentPiStream = stream;
 		queryCtx.resetTurnState(model);
+		activeStreamIdleWatchdogs.get(queryCtx)?.refresh();
 		const allResults = extractAllToolResults(context);
 		debug(`provider: tool results, ${allResults.length} results, ${queryCtx.pendingToolCalls.size} waiting handlers, ctx.msgs=${context.messages.length}`);
 		const unmatchedResultIds: string[] = [];
@@ -1822,6 +1955,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 
 	// 3. Start SDK query and claim it for this context
 	let wasAborted = false;
+	let streamIdleTimedOut = false;
 	const sdkQuery = query({ prompt, options: queryOptions });
 	ctx().activeQuery = sdkQuery;
 
@@ -1834,6 +1968,57 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		void sdkQuery.interrupt().catch(() => {});
 		try { sdkQuery.close(); } catch {}
 	};
+	const streamIdleTimeoutMs = streamIdleTimeoutMsFromEnv();
+	const streamIdleWatchdog = streamIdleTimeoutMs > 0
+		? createStreamIdleWatchdog({
+			getState: () => ({
+				activeQuery: abortCtx.activeQuery,
+				currentPiStream: abortCtx.currentPiStream,
+				turnOutput: abortCtx.turnOutput,
+				turnSawStreamEvent: abortCtx.turnSawStreamEvent,
+				turnStarted: abortCtx.turnStarted,
+			}),
+			onTimeout: ({ idleMs, timeoutMs }) => {
+				if (streamIdleTimedOut || wasAborted || options?.signal?.aborted || abortCtx.activeQuery !== sdkQuery) return;
+				streamIdleTimedOut = true;
+				abortCtx.deferredUserMessages = [];
+				abortCtx.handledTerminalError = true;
+				if (sharedSession) sharedSession = { ...sharedSession, needsRebuild: true, forceRotate: true };
+				const errorMessage = buildStreamIdleTimeoutErrorMessage(timeoutMs);
+				debug("provider: stream idle timeout", `model=${model.id}`, `timeout=${timeoutMs}`, `idle=${idleMs}`);
+				emitRateLimitEvent({
+					idleMs,
+					model: model.id,
+					provider: PROVIDER_ID,
+					rateLimitType: "stream_idle",
+					reason: "Claude Code stream idle timeout",
+					retryAfterMs: STREAM_IDLE_BACKOFF_HINT_MS,
+					source: "claude-bridge",
+					status: "rejected",
+					timeoutMs,
+				});
+				piUI?.notify(`${RATE_LIMIT_TOKEN} Claude stream idle timeout after ${formatDurationShort(timeoutMs)} — retrying via rate-limit backoff`, "warning");
+				if (abortCtx.turnOutput) {
+					abortCtx.turnOutput.stopReason = "error";
+					abortCtx.turnOutput.errorMessage = errorMessage;
+					Object.assign(abortCtx.turnOutput as AssistantMessage & Record<string, unknown>, {
+						rateLimitType: "stream_idle",
+						retryAfterMs: STREAM_IDLE_BACKOFF_HINT_MS,
+						streamIdleTimeoutMs: timeoutMs,
+					});
+				}
+				abortCtx.currentPiStream?.push({ type: "error", reason: "error", error: abortCtx.turnOutput! });
+				abortCtx.currentPiStream?.end();
+				abortCtx.currentPiStream = null;
+				requestAbort();
+			},
+			timeoutMs: streamIdleTimeoutMs,
+		})
+		: null;
+	if (streamIdleWatchdog) {
+		activeStreamIdleWatchdogs.set(abortCtx, streamIdleWatchdog);
+		streamIdleWatchdog.refresh();
+	}
 	const onAbort = () => {
 		wasAborted = true;
 		// Prevent stale deferred messages from being replayed by parent on pop
@@ -1853,6 +2038,11 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	consumeQuery(sdkQuery, customToolNameToPi, model, cwd, bridgeConfig, () => wasAborted)
 		.then(async ({ capturedSessionId }) => {
 			debug(`provider: consumeQuery completed, stopReason=${ctx().turnOutput?.stopReason}, error=${ctx().turnOutput?.errorMessage}, aborted=${wasAborted}`);
+			if (streamIdleTimedOut) {
+				abortCtx.deferredUserMessages = [];
+				debug("provider: stream idle timeout already surfaced; skipping normal completion");
+				return;
+			}
 
 			// --- Abort detection in normal completion path ---
 			if (wasAborted || options?.signal?.aborted) {
@@ -1921,7 +2111,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		})
 		.catch((error) => {
 			debug(`provider: query error, model=${model.id}, aborted=${Boolean(options?.signal?.aborted)}, error=`, error);
-			const suppressDuplicateError = ctx().handledTerminalError;
+			const suppressDuplicateError = ctx().handledTerminalError || streamIdleTimedOut;
 			const openedExtraUsage = !suppressDuplicateError && isExtraUsageRequiredMessage(error) && launchExtraUsageHelperIfAllowed(cwd, bridgeConfig, "query error");
 			if ((wasAborted || options?.signal?.aborted) && sharedSession) {
 				sharedSession = { ...sharedSession, needsRebuild: true, forceRotate: true };
@@ -1942,9 +2132,11 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 			ctx().currentPiStream = null;
 		})
 		.finally(() => {
+			streamIdleWatchdog?.dispose();
+			activeStreamIdleWatchdogs.delete(abortCtx);
 			if (options?.signal) options.signal.removeEventListener("abort", onAbort);
 			if (ctx().activeQuery === sdkQuery) {
-				reportToolResultMismatch(ctx(), "query teardown", cwd, { forceRotate: wasAborted || options?.signal?.aborted });
+				reportToolResultMismatch(ctx(), "query teardown", cwd, { forceRotate: wasAborted || options?.signal?.aborted || streamIdleTimedOut });
 				// Drain pending handlers for this query
 				for (const pending of ctx().pendingToolCalls.values()) { pending.resolve({ content: [{ type: "text", text: "Query ended" }] }); }
 				ctx().pendingToolCalls.clear();

package/src/session-verify.ts

@@ -2,7 +2,54 @@
 // callers decide how to surface them (debug log, piUI, diagDump, etc.).
 // Extracted from index.ts so tests can import without activating the extension.
 
-import { statSync, readFileSync } from "fs";
+import { closeSync, openSync, readSync, statSync } from "fs";
+import { StringDecoder } from "node:string_decoder";
+
+interface JsonlSummary {
+	count: number;
+	firstLine?: string;
+	lastLine?: string;
+}
+
+function forEachJsonlLine(path: string, onLine: (line: string) => void): void {
+	const fd = openSync(path, "r");
+	const buffer = Buffer.allocUnsafe(64 * 1024);
+	const decoder = new StringDecoder("utf8");
+	let pending = "";
+	try {
+		for (;;) {
+			const bytesRead = readSync(fd, buffer, 0, buffer.length, null);
+			if (bytesRead === 0) break;
+			pending += decoder.write(buffer.subarray(0, bytesRead));
+			let start = 0;
+			for (;;) {
+				const newline = pending.indexOf("\n", start);
+				if (newline < 0) {
+					pending = pending.slice(start);
+					break;
+				}
+				const line = pending.slice(start, newline);
+				onLine(line.endsWith("\r") ? line.slice(0, -1) : line);
+				start = newline + 1;
+			}
+		}
+		pending += decoder.end();
+		if (pending.length > 0) onLine(pending.endsWith("\r") ? pending.slice(0, -1) : pending);
+	} finally {
+		closeSync(fd);
+	}
+}
+
+function summarizeJsonl(path: string): JsonlSummary {
+	const summary: JsonlSummary = { count: 0 };
+	forEachJsonlLine(path, (line) => {
+		if (!line.trim()) return;
+		summary.count += 1;
+		if (summary.firstLine === undefined) summary.firstLine = line;
+		summary.lastLine = line;
+	});
+	return summary;
+}
 
 export function verifyWrittenSession(jsonlPath: string, expectedSessionId: string, expectedRecordCount: number): string[] {
 	const warnings = [];
@@ -13,21 +60,20 @@ export function verifyWrittenSession(jsonlPath: string, expectedSessionId: strin
 		warnings.push(`file missing after save — path=${jsonlPath} err=${e.message}`);
 		return warnings;
 	}
-	let content;
+	let summary;
 	try {
-		content = readFileSync(jsonlPath, "utf8");
+		summary = summarizeJsonl(jsonlPath);
 	} catch (e) {
 		warnings.push(`file unreadable — path=${jsonlPath} size=${st.size} err=${e.message}`);
 		return warnings;
 	}
-	const lines = content.split("\n").filter((l) => l.trim().length > 0);
-	if (lines.length !== expectedRecordCount) {
-		warnings.push(`record count mismatch — expected=${expectedRecordCount} actual=${lines.length} path=${jsonlPath} bytes=${content.length}`);
+	if (summary.count !== expectedRecordCount) {
+		warnings.push(`record count mismatch — expected=${expectedRecordCount} actual=${summary.count} path=${jsonlPath} bytes=${st.size}`);
 		return warnings;
 	}
 	try {
-		const firstRec = JSON.parse(lines[0]);
-		const lastRec = JSON.parse(lines[lines.length - 1]);
+		const firstRec = JSON.parse(summary.firstLine ?? "");
+		const lastRec = JSON.parse(summary.lastLine ?? "");
 		if (firstRec.sessionId !== expectedSessionId || lastRec.sessionId !== expectedSessionId) {
 			warnings.push(`sessionId drift — expected=${expectedSessionId} first=${firstRec.sessionId} last=${lastRec.sessionId}`);
 		}