@vanillagreen/pi-claude-bridge 1.6.2 → 1.9.0

package/src/models.ts

@@ -3,15 +3,19 @@
 // Extracted from index.ts so tests can import without activating the extension.
 
 export const FABLE_MODEL_ID = "claude-fable-5";
+// Opus 4.8 is both a selectable model and the safety-fallback target for the two
+// primaries whose classifiers can decline a turn (Fable 5, Opus 5).
 export const FABLE_FALLBACK_MODEL_ID = "claude-opus-4-8";
+export const OPUS_5_MODEL_ID = "claude-opus-5";
 export const SONNET_5_MODEL_ID = "claude-sonnet-5";
 
 export function fallbackModelForPrimaryModel(modelId: string): string | undefined {
-	return modelId === FABLE_MODEL_ID ? FABLE_FALLBACK_MODEL_ID : undefined;
+	return modelId === FABLE_MODEL_ID || modelId === OPUS_5_MODEL_ID ? FABLE_FALLBACK_MODEL_ID : undefined;
 }
 
 export const MODEL_IDS_IN_ORDER = [
 	FABLE_MODEL_ID,
+	OPUS_5_MODEL_ID,
 	FABLE_FALLBACK_MODEL_ID,
 	"claude-opus-4-7",
 	"claude-opus-4-6",
@@ -40,6 +44,15 @@ const FALLBACK_MODELS: Record<string, BridgeModelMetadata> = {
 		contextWindow: 1000000,
 		maxTokens: 128000,
 	},
+	[OPUS_5_MODEL_ID]: {
+		id: OPUS_5_MODEL_ID,
+		name: "Claude Opus 5",
+		reasoning: true,
+		thinkingLevelMap: { xhigh: "xhigh", max: "max" },
+		input: ["text", "image"],
+		contextWindow: 1000000,
+		maxTokens: 128000,
+	},
 	[FABLE_FALLBACK_MODEL_ID]: {
 		id: FABLE_FALLBACK_MODEL_ID,
 		name: "Claude Opus 4.8",
@@ -53,12 +66,20 @@ const FALLBACK_MODELS: Record<string, BridgeModelMetadata> = {
 		id: SONNET_5_MODEL_ID,
 		name: "Claude Sonnet 5",
 		reasoning: true,
+		thinkingLevelMap: { xhigh: "xhigh", max: "max" },
 		input: ["text", "image"],
 		contextWindow: 1000000,
 		maxTokens: 128000,
 	},
 };
 
+// Human label for the safety-fallback notice. Every id that participates in a
+// fallbackModelForPrimaryModel pairing has an entry above; the raw id is the
+// last-resort label so an unmapped pairing still reads sensibly.
+export function modelDisplayName(modelId: string): string {
+	return FALLBACK_MODELS[modelId]?.name ?? modelId;
+}
+
 // Project pi-ai's model entries down to the fields pi's registerProvider expects,
 // keep MODEL_IDS_IN_ORDER ordering, and fill bridge-owned future IDs when pi-ai
 // has not shipped metadata for them yet. Unknown missing IDs are still dropped.

package/src/prompt-context.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "fs";
-import { homedir } from "os";
 import { dirname, join, resolve } from "path";
+import { isolatedFromEnv, piUserDir } from "./config.js";
 
 export interface PromptContextSettings {
 	includeAppendSystemPromptMd?: boolean;
@@ -14,12 +14,6 @@ export interface PromptContextAppend {
 	labels: string[];
 }
 
-function piUserDir(): string {
-	const configured = process.env.PI_CODING_AGENT_DIR?.trim();
-	if (configured) return resolve(configured.replace(/^~(?=\/|$)/, homedir()));
-	return join(homedir(), ".pi", "agent");
-}
-
 function readTrimmed(path: string): string | undefined {
 	try {
 		if (!existsSync(path)) return undefined;
@@ -46,7 +40,8 @@ export function readAppendSystemPromptFiles(cwd: string): Array<{ label: string;
 	const files: Array<{ label: string; path: string }> = [
 		{ label: "global APPEND_SYSTEM.md", path: join(piUserDir(), "APPEND_SYSTEM.md") },
 	];
-	const projectPath = findProjectAppendSystem(cwd);
+	// Isolated mode: no cwd-ancestor discovery — the host app owns the prompt surface.
+	const projectPath = isolatedFromEnv() ? undefined : findProjectAppendSystem(cwd);
 	if (projectPath) files.push({ label: "project .pi/APPEND_SYSTEM.md", path: projectPath });
 
 	const seen = new Set<string>();

package/src/query-state.ts

@@ -14,6 +14,48 @@ export interface PendingToolCall {
 	resolve: (result: McpResult) => void;
 }
 
+// Why pending MCP handlers were drained without a real tool result. A drained
+// handler is waiting on a result pi will now never deliver, so the drain must
+// resolve as an error — never as a successful result whose text merely says the
+// turn died, which a consumer cannot tell apart from a tool that genuinely
+// returned that string. The cause is carried because an abort, an idle timeout,
+// and a plain end-with-stragglers are different things to act on.
+export type ToolCallDrainCause = "abort" | "stream-idle-timeout" | "query-end";
+
+const DRAIN_CAUSE_TEXT: Record<ToolCallDrainCause, string> = {
+	"abort": "the turn was aborted",
+	"stream-idle-timeout": "the Claude Code stream went idle and the turn timed out",
+	"query-end": "the query ended",
+};
+
+export function interruptedToolCallResult(cause: ToolCallDrainCause): McpResult {
+	return {
+		content: [{ type: "text", text: `Claude bridge: ${DRAIN_CAUSE_TEXT[cause]} before this tool call's result was delivered. The call did not complete and produced no output.` }],
+		isError: true,
+	};
+}
+
+// Precedence matches the forceRotate expression at the query-teardown site: an
+// explicit abort (pi's signal or our own abort handler) outranks a stream-idle
+// timeout, which outranks a plain end with stragglers.
+export function toolCallDrainCause(flags: { wasAborted?: boolean; signalAborted?: boolean; streamIdleTimedOut?: boolean }): ToolCallDrainCause {
+	if (flags.wasAborted || flags.signalAborted) return "abort";
+	if (flags.streamIdleTimedOut) return "stream-idle-timeout";
+	return "query-end";
+}
+
+/** Resolves every handler still waiting on `queryCtx` with an error result naming
+ *  `cause`, clears the map, and returns how many were drained. Scoped to the one
+ *  context it is given — never touches a sibling or parent query's handlers. */
+export function drainPendingToolCalls(queryCtx: QueryContext, cause: ToolCallDrainCause): number {
+	const drained = queryCtx.pendingToolCalls.size;
+	if (drained === 0) return 0;
+	const result = interruptedToolCallResult(cause);
+	for (const pending of queryCtx.pendingToolCalls.values()) pending.resolve(result);
+	queryCtx.pendingToolCalls.clear();
+	return drained;
+}
+
 export interface TurnToolCallRecord {
 	id: string;
 	toolName: string;

package/src/rate-limit.ts

@@ -0,0 +1,63 @@
+export const RATE_LIMIT_AUTO_RESUME_EVENT = "vstack:rate-limit";
+export const RATE_LIMIT_TOKEN = "\x1b[31m[rate-limit]\x1b[39m";
+
+export function isExtraUsageRequiredMessage(value: unknown): boolean {
+	let text: string;
+	if (typeof value === "string") text = value;
+	else if (value instanceof Error) text = value.message;
+	else {
+		try { text = JSON.stringify(value ?? ""); }
+		catch { text = String(value); }
+	}
+	return /extra[-\s]?usage|overage|extra usage billing|extra usage credits|1M context/i.test(text);
+}
+
+export function uniqueNonEmptyLines(values: unknown[]): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const value of values) {
+		const text = typeof value === "string" ? value.trim() : value == null ? "" : String(value).trim();
+		if (!text || seen.has(text)) continue;
+		seen.add(text);
+		out.push(text);
+	}
+	return out;
+}
+
+export function formatResetTimestamp(value: unknown): string {
+	const parsed = typeof value === "number" ? value : typeof value === "string" ? Date.parse(value) : Number.NaN;
+	if (!Number.isFinite(parsed)) return "unknown";
+	return new Date(parsed).toLocaleString(undefined, {
+		day: "numeric",
+		hour: "numeric",
+		minute: "2-digit",
+		month: "short",
+		second: "2-digit",
+		timeZoneName: "short",
+		year: "numeric",
+	});
+}
+
+export const ALLOWED_RATE_LIMIT_WARNING_UTILIZATION_THRESHOLD = 80;
+
+export function normalizeRateLimitUtilization(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return undefined;
+	if (value === 0) return 0;
+	// Claude SDK payloads have appeared as both fractions and percentages.
+	// Exact 1 is unit-ambiguous (1% vs 100%), so do not use it for allowed-warning copy.
+	if (value > 0 && value < 1) return value * 100;
+	if (value > 1 && value <= 100) return value;
+	return undefined;
+}
+
+function rateLimitTypeLabel(value: unknown): string {
+	const text = typeof value === "string" ? value.trim() : "";
+	return text || "unknown";
+}
+
+export function formatAllowedRateLimitWarning(info: { status?: unknown; utilization?: unknown; rateLimitType?: unknown } | null | undefined): string | undefined {
+	if (info?.status !== "allowed_warning") return undefined;
+	const utilization = normalizeRateLimitUtilization(info.utilization);
+	if (utilization === undefined || utilization < ALLOWED_RATE_LIMIT_WARNING_UTILIZATION_THRESHOLD) return undefined;
+	return `Claude rate limit warning: nearing ${rateLimitTypeLabel(info.rateLimitType)} limit; check Claude Code /usage for exact utilization.`;
+}

package/src/session-persistence.ts

@@ -0,0 +1,329 @@
+import { type AssistantMessage, type Context } from "@earendil-works/pi-ai";
+import { createSession, deleteSession, openSession, repairToolPairing } from "cc-session-io";
+import { createHash } from "crypto";
+import { realpathSync, statSync } from "fs";
+import { resolve as pathResolve } from "path";
+import { extensionApi, piUI, reportSyntheticToolResultRepair, setSharedSession, sharedSession, type SessionState } from "./bridge-state.js";
+import { convertPiMessages } from "./convert.js";
+import { DEBUG, DEBUG_LOG_PATH, debug, diagDump } from "./debug.js";
+import { verifyWrittenSession as _verifyWrittenSession } from "./session-verify.js";
+import { findUnpairedToolUses } from "./tool-pairing-audit.js";
+
+// --- Session persistence ---
+
+const BRIDGE_SESSION_CUSTOM_TYPE = "claude-bridge-session";
+
+interface PersistedBridgeSessionState extends SessionState {
+	fingerprint: string;
+	piSessionId?: string;
+	updatedAt: string;
+}
+
+function fingerprintMessages(messages: Context["messages"]): string {
+	const normalized = messages.map((message) => {
+		if (message.role === "assistant") {
+			return {
+				role: message.role,
+				provider: (message as AssistantMessage).provider,
+				model: (message as AssistantMessage).model,
+				content: (message as AssistantMessage).content,
+			};
+		}
+		return message;
+	});
+	return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
+}
+
+function readBuiltSessionContext(sessionManager: unknown): { messages: Context["messages"] } | undefined {
+	const built = typeof (sessionManager as any)?.buildSessionContext === "function" ? (sessionManager as any).buildSessionContext() : undefined;
+	return Array.isArray(built?.messages) ? built as { messages: Context["messages"] } : undefined;
+}
+
+function latestPersistedBridgeSession(sessionManager: unknown): PersistedBridgeSessionState | undefined {
+	const entries = typeof (sessionManager as any)?.getEntries === "function" ? (sessionManager as any).getEntries() : [];
+	if (!Array.isArray(entries)) return undefined;
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry?.type !== "custom" || entry.customType !== BRIDGE_SESSION_CUSTOM_TYPE) continue;
+		const data = entry.data as Partial<PersistedBridgeSessionState> | undefined;
+		if (!data || typeof data.sessionId !== "string" || typeof data.cursor !== "number" || typeof data.cwd !== "string" || typeof data.fingerprint !== "string") continue;
+		return data as PersistedBridgeSessionState;
+	}
+	return undefined;
+}
+
+function claudeSessionExists(sessionId: string, cwd: string): boolean {
+	try {
+		const session = openSession({ sessionId, projectPath: cwd, claudeDir: process.env.CLAUDE_CONFIG_DIR });
+		statSync(session.jsonlPath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function canonicalize(p: string | undefined): string | undefined {
+	if (!p) return undefined;
+	try { return realpathSync.native(p); } catch { return pathResolve(p); }
+}
+
+// Decides whether a persisted bridge-session marker is safe to restore.
+//
+// The fork case is the load-bearing one: pi/core's createBranchedSession copies
+// every non-label entry from root→leaf into the new session file. That includes
+// our claude-bridge-session markers from the parent. Restoring from them would
+// --resume parent's Claude jsonl on the fork's first turn, leaking conversation
+// past the fork point.
+//
+// Returns undefined when the entry is safe to use, or a short rejection reason
+// for diagnostic logging. Old entries without piSessionId always reject, which
+// degrades safely to the rebuild path.
+export function shouldRestorePersistedBridgeEntry(
+	persisted: { piSessionId?: string; cwd: string },
+	currentPiSessionId: string | undefined,
+	currentCwd: string | undefined,
+): string | undefined {
+	if (!persisted.piSessionId) return "missing piSessionId";
+	if (currentPiSessionId && persisted.piSessionId !== currentPiSessionId) {
+		return `piSessionId mismatch (persisted=${persisted.piSessionId} current=${currentPiSessionId})`;
+	}
+	if (currentCwd && canonicalize(persisted.cwd) !== canonicalize(currentCwd)) {
+		return `cwd mismatch (persisted=${persisted.cwd} current=${currentCwd})`;
+	}
+	return undefined;
+}
+
+export function restoreSharedSessionFromPi(ctx: { sessionManager?: unknown; cwd?: string }): void {
+	const persisted = latestPersistedBridgeSession(ctx.sessionManager);
+	if (!persisted) return;
+	const currentPiSessionId = typeof (ctx.sessionManager as any)?.getSessionId === "function" ? (ctx.sessionManager as any).getSessionId() : undefined;
+	const currentCwd = typeof (ctx.sessionManager as any)?.getCwd === "function" ? (ctx.sessionManager as any).getCwd() : ctx.cwd;
+	const rejection = shouldRestorePersistedBridgeEntry(persisted, currentPiSessionId, currentCwd);
+	if (rejection) {
+		debug(`restoreSharedSession: ${rejection} — forcing rebuild`);
+		return;
+	}
+	const built = readBuiltSessionContext(ctx.sessionManager);
+	if (!built) return;
+	const cursor = Math.max(0, Math.min(persisted.cursor, built.messages.length));
+	const fingerprint = fingerprintMessages(built.messages.slice(0, cursor));
+	if (fingerprint !== persisted.fingerprint) {
+		debug(`restoreSharedSession: fingerprint mismatch for ${persisted.sessionId.slice(0, 8)}`);
+		return;
+	}
+	if (!claudeSessionExists(persisted.sessionId, persisted.cwd)) {
+		debug(`restoreSharedSession: Claude session missing for ${persisted.sessionId.slice(0, 8)}`);
+		return;
+	}
+	setSharedSession({ sessionId: persisted.sessionId, cursor, cwd: persisted.cwd });
+	debug(`restoreSharedSession: restored ${persisted.sessionId.slice(0, 8)}, cursor=${cursor}`);
+}
+
+export function schedulePersistSharedSession(ctxLike?: { sessionManager?: unknown }): void {
+	if (!extensionApi || !sharedSession || !ctxLike?.sessionManager) return;
+	const snapshot = { ...sharedSession };
+	const timer = setTimeout(() => {
+		try {
+			const built = readBuiltSessionContext(ctxLike.sessionManager);
+			if (!built) return;
+			const cursor = Math.max(0, Math.min(snapshot.cursor, built.messages.length));
+			const data: PersistedBridgeSessionState = {
+				...snapshot,
+				cursor,
+				fingerprint: fingerprintMessages(built.messages.slice(0, cursor)),
+				piSessionId: typeof (ctxLike.sessionManager as any)?.getSessionId === "function" ? (ctxLike.sessionManager as any).getSessionId() : undefined,
+				updatedAt: new Date().toISOString(),
+			};
+			extensionApi?.appendEntry(BRIDGE_SESSION_CUSTOM_TYPE, data);
+			debug(`persistSharedSession: saved ${data.sessionId.slice(0, 8)}, cursor=${data.cursor}`);
+		} catch (error) {
+			debug("persistSharedSession failed:", error);
+		}
+	}, 0);
+	timer.unref?.();
+}
+
+// Convert pi messages to Anthropic API format for session import.
+// Lossy: non-Anthropic thinking blocks are dropped (no valid signature). User and
+// tool-result image blocks are preserved when possible. If assistant blocks are
+// otherwise incompatible, convertPiMessages emits a text placeholder so the record
+// sequence stays valid before repairToolPairing runs.
+function convertAndImportMessages(
+	session: ReturnType<typeof createSession>,
+	messages: Context["messages"],
+	customToolNameToSdk?: Map<string, string>,
+	cwd?: string,
+): void {
+	const { anthropicMessages, sanitizedIds } = convertPiMessages(messages, customToolNameToSdk);
+
+	debug(`convertAndImportMessages: ${messages.length} pi msgs → ${anthropicMessages.length} anthropic msgs`);
+	debug(`convertAndImportMessages: imported roles:`, anthropicMessages.map((m, i) => {
+		const c = m.content;
+		if (typeof c === "string") return `[${i}]${m.role}:text`;
+		if (Array.isArray(c)) return `[${i}]${m.role}:${(c).map((b) => b.type).join("+")}`;
+		return `[${i}]${m.role}:?`;
+	}).join(" "));
+	if (sanitizedIds.size > 0) {
+		debug(`convertAndImportMessages: sanitized ${sanitizedIds.size} tool IDs:`,
+			[...sanitizedIds.entries()].map(([orig, clean]) => orig === clean ? orig : `${orig}→${clean}`).join(", "));
+	}
+	// Pre-repair for debug logging; importMessages also repairs internally (idempotent).
+	const missingToolResults = findUnpairedToolUses(anthropicMessages);
+	const repaired = repairToolPairing(anthropicMessages);
+	if (missingToolResults.length > 0) {
+		reportSyntheticToolResultRepair(missingToolResults, {
+			cwd,
+			messageCount: messages.length,
+			anthropicMessageCount: anthropicMessages.length,
+			sessionId: session.sessionId,
+			jsonlPath: session.jsonlPath,
+		});
+	}
+	if (repaired.length !== anthropicMessages.length) {
+		debug(`convertAndImportMessages: repairToolPairing ${anthropicMessages.length} → ${repaired.length} msgs`);
+	}
+	if (repaired.length) session.importMessages(repaired);
+}
+
+interface SyncResult {
+	sessionId: string | null;
+}
+
+/**
+ * Ensure the shared session has all messages up to (but not including) the last user message.
+ * Returns session ID to resume from, or null if no resume needed.
+ */
+// Read the session file we just wrote and sanity-check it. Warns instead of
+// throwing — CC may be more tolerant than our checks, so a false positive
+// shouldn't block the user. Pure logic is in session-verify.js; this wrapper
+// fans each warning out to debug log + piUI notify + diagDump.
+function verifyWrittenSession(
+	jsonlPath: string,
+	expectedSessionId: string,
+	expectedRecordCount: number,
+	cwd: string,
+): void {
+	const warnings = _verifyWrittenSession(jsonlPath, expectedSessionId, expectedRecordCount);
+	for (const msg of warnings) {
+		debug(`WARNING session verify: ${msg}`);
+		piUI?.notify(
+			`Session file issue: ${msg}\n` +
+			`cwd=${cwd} realpath=${safeRealpath(cwd)} CLAUDE_CONFIG_DIR=${process.env.CLAUDE_CONFIG_DIR ?? "(unset)"}\n` +
+			`Please copy and paste this message into a new issue at https://github.com/elidickinson/pi-claude-bridge/issues/new` +
+			(DEBUG ? ` and attach ${DEBUG_LOG_PATH}` : ` (rerun with CLAUDE_BRIDGE_DEBUG=1 to capture a debug log)`),
+			"warning",
+		);
+		diagDump("session_verify_fail", { msg, jsonlPath, cwd, realpath: safeRealpath(cwd), claudeConfigDir: process.env.CLAUDE_CONFIG_DIR ?? null });
+	}
+}
+
+function safeRealpath(p: string): string {
+	try { return realpathSync(p); } catch (e) { return `<failed: ${(e as Error).message}>`; }
+}
+
+// Diagnostic snapshot of where a session file was just written. Catches the
+// class of bugs where pi writes to ~/.claude/projects/<X> but CC SDK reads
+// from ~/.claude/projects/<Y> (symlinks, CLAUDE_CONFIG_DIR, hash mismatch).
+function debugSessionPaths(label: string, cwd: string, jsonlPath: string): void {
+	const realCwd = safeRealpath(cwd);
+	let fileSize: number | null = null;
+	let fileExists = false;
+	try {
+		const st = statSync(jsonlPath);
+		fileExists = true;
+		fileSize = st.size;
+	} catch { /* file may not exist yet */ }
+	debug(`${label}: cwd=${cwd}`);
+	if (realCwd !== cwd) debug(`${label}: realpath(cwd)=${realCwd} (DIFFERS — symlink-resolved path is what CC SDK uses)`);
+	debug(`${label}: jsonlPath=${jsonlPath}`);
+	debug(`${label}: fileExists=${fileExists}${fileSize != null ? ` size=${fileSize}` : ""}`);
+	debug(`${label}: env.CLAUDE_CONFIG_DIR=${process.env.CLAUDE_CONFIG_DIR ?? "(unset)"} HOME=${process.env.HOME ?? "(unset)"}`);
+}
+
+// Two semantic paths:
+//   REUSE — pi's history is in sync with the existing sharedSession (or drifted
+//     only by the trailing final-assistant message that pi appends after
+//     streamSimple returns, which CC's own persisted session already has).
+//     Returns the existing sessionId. Keeps CC's prompt cache warm.
+//   REBUILD — no session yet, or pi's history has diverged (non-trailing
+//     missed messages, e.g. another provider took a turn). Wipes the existing
+//     session file (if any) and writes a fresh one containing all prior
+//     messages, reusing the same sessionId across rebuilds so UUIDs stay
+//     stable for the lifetime of pi's session.
+//
+// Why a full rebuild rather than patching:
+//   Injecting deltas into an existing session creates a branch that CC's
+//   --resume doesn't follow (documented attempt prior to this). A complete
+//   overwrite at the same path is simpler and correct.
+//
+// Why reuse the sessionId across rebuilds:
+//   CC re-reads the JSONL on every --resume call — no in-process UUID
+//   caching. Validated in tests/exp-session-clear.mjs, including the case
+//   where CC had appended its own tool_use/tool_result records between
+//   rebuilds. Preserving the UUID means stable log correlation across
+//   provider switches and no orphaned session files.
+//
+// Log strings still say "Case 1/2/3/4" so existing diagnostics (int-cache.sh,
+// int-session-resume.mjs) keep grepping the same anchors.
+export function syncSharedSession(
+	messages: Context["messages"],
+	cwd: string,
+	customToolNameToSdk?: Map<string, string>,
+	modelId?: string,
+): SyncResult {
+	const priorMessages = messages.slice(0, -1); // everything before the new user prompt
+
+	// REUSE path
+	if (sharedSession && !sharedSession.needsRebuild) {
+		const missed = priorMessages.slice(sharedSession.cursor);
+		const trailingAssistantOnly =
+			missed.length === 1 && (missed[0] as { role?: string }).role === "assistant";
+		if (missed.length === 0 || trailingAssistantOnly) {
+			if (trailingAssistantOnly) {
+				setSharedSession({ ...sharedSession, cursor: priorMessages.length, cwd });
+			}
+			debug(`Case 3: ${trailingAssistantOnly ? "advanced cursor past trailing assistant, " : ""}resuming session ${sharedSession.sessionId.slice(0, 8)}, cursor=${sharedSession.cursor}`);
+			debug(`syncResult: path=reuse sessionId=${sharedSession.sessionId} cursor=${sharedSession.cursor}`);
+			return { sessionId: sharedSession.sessionId };
+		}
+	}
+
+	// REBUILD path
+	if (priorMessages.length === 0) {
+		debug(`Case 1: clean start, ${messages.length} total messages`);
+		debug(`syncResult: path=clean-start`);
+		return { sessionId: null };
+	}
+	const previousSessionId = sharedSession?.sessionId;
+	const previousCursor = sharedSession?.cursor ?? 0;
+	// preserveId: rebuild in place (deleteSession + createSession with the
+	// existing UUID), so prompt-cache UUIDs stay stable for log correlation
+	// and for any tools that key off them. Skipped only when there's a
+	// concurrent writer we shouldn't race — see forceRotate docs above.
+	const preserveId = previousSessionId !== undefined && !sharedSession?.forceRotate;
+	if (preserveId) {
+		// Wipe prior jsonl + companion dir (no-op if nothing to wipe).
+		deleteSession(previousSessionId!, cwd, process.env.CLAUDE_CONFIG_DIR);
+	}
+	const session = createSession({
+		projectPath: cwd,
+		claudeDir: process.env.CLAUDE_CONFIG_DIR,
+		...(preserveId ? { sessionId: previousSessionId } : {}),
+		...(modelId ? { model: modelId } : {}),
+	});
+	convertAndImportMessages(session, priorMessages, customToolNameToSdk, cwd);
+	session.save();
+	verifyWrittenSession(session.jsonlPath, session.sessionId, session.messages.length, cwd);
+	setSharedSession({ sessionId: session.sessionId, cursor: priorMessages.length, cwd });
+	if (previousSessionId === undefined) {
+		debug(`Case 2: first turn with ${priorMessages.length} prior messages → session ${session.sessionId.slice(0, 8)}, ${session.messages.length} records`);
+	} else if (preserveId) {
+		const missedCount = priorMessages.length - previousCursor;
+		debug(`Case 4: ${missedCount} missed messages, ${priorMessages.length} total → rewrote session ${session.sessionId.slice(0, 8)} (same id), ${session.messages.length} records`);
+	} else {
+		debug(`Case 4 post-abort: ${priorMessages.length} total → new session ${session.sessionId.slice(0, 8)} (was ${previousSessionId.slice(0, 8)}, rotated to avoid race with orphan writer), ${session.messages.length} records`);
+	}
+	debugSessionPaths(`${session.sessionId.slice(0, 8)}`, cwd, session.jsonlPath);
+	debug(`syncResult: path=rebuild sessionId=${session.sessionId} priors=${priorMessages.length} ${previousSessionId === undefined ? "first" : preserveId ? "preserved" : "rotated-post-abort"}`);
+	return { sessionId: session.sessionId };
+}

package/src/stream-idle-watchdog.ts

@@ -0,0 +1,134 @@
+import { type AssistantMessage, type AssistantMessageEventStream } from "@earendil-works/pi-ai";
+import { type QueryContext } from "./query-state.js";
+
+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;
+}
+
+export 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;
+}
+
+export 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,
+	};
+}