@vanillagreen/pi-claude-bridge 4.0.0 → 4.0.2

package/src/models.ts

@@ -1,9 +1,9 @@
 // Canonical selection + display order for the model picker.
 // Extracted from index.ts so tests can import without activating the extension.
 
-export const FABLE_MODEL_ID = "claude-fable-5";
+export const FABLE_MODEL_ID = "claude-fable-5-1";
 // 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).
+// primaries whose classifiers can decline a turn (Fable 5.1, 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";
@@ -36,7 +36,7 @@ type BridgeModelMetadata = {
 const FALLBACK_MODELS: Record<string, BridgeModelMetadata> = {
 	[FABLE_MODEL_ID]: {
 		id: FABLE_MODEL_ID,
-		name: "Claude Fable 5",
+		name: "Claude Fable 5.1",
 		reasoning: true,
 		thinkingLevelMap: { xhigh: "xhigh", max: "max" },
 		input: ["text", "image"],
@@ -80,8 +80,8 @@ export function modelDisplayName(modelId: string): string {
 }
 
 // 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.
+// keep MODEL_IDS_IN_ORDER ordering, and fill bridge-owned metadata for supported
+// IDs absent from pi-ai. Unknown missing IDs are still dropped.
 export function buildModels<T extends { id: string; [key: string]: any }>(piAiModels: T[]) {
 	return MODEL_IDS_IN_ORDER
 		.map((id) => piAiModels.find((m) => m.id === id) ?? FALLBACK_MODELS[id])

package/src/native-provider.ts

@@ -60,7 +60,9 @@ export function buildNativeProvider(
 	// passes a probe that also accepts a companion account-router pool.
 	hasCredentials: () => boolean = () => hasClaudeCredentials(env),
 ): unknown {
-	if (!supportsNativeProvider(piAi)) throw new Error(NATIVE_PROVIDER_UNSUPPORTED_MESSAGE);
+	if (!supportsNativeProvider(piAi)) {
+		throw Object.assign(new Error(NATIVE_PROVIDER_UNSUPPORTED_MESSAGE), { code: "CLAUDE_BRIDGE_NATIVE_PROVIDER_UNSUPPORTED" });
+	}
 	// The legacy config path stamped provider/api/baseUrl onto each model during
 	// composition; createProvider passes models through verbatim, so stamp here.
 	// Stamps win over any provider field the source model carries — the models

package/src/query-options.ts

@@ -83,7 +83,7 @@ export function buildClaudeQueryOptions(input: BuildClaudeQueryOptionsInput): Bu
 	const connectorWriteMode = connectorWriteModeFor(bridgeConfig);
 	// Declare the account's connected connectors explicitly so `alwaysLoad` can
 	// hold startup until they attach — otherwise the turn-1 manifest is built
-	// before the CLI has fetched them (kendex#832).
+	// before the CLI has fetched them.
 	const connectorServers = enableCloudMcp ? connectorServersSnapshot(accountScope.claudeConfigDir) : {};
 	const appendSystemPrompt = providerSettings.appendSystemPrompt !== false;
 	const agentsAppend = appendSystemPrompt ? extractAgentsAppend() : undefined;
@@ -98,7 +98,7 @@ export function buildClaudeQueryOptions(input: BuildClaudeQueryOptionsInput): Bu
 	// ignores auto-discovered filesystem MCP servers while Pi owns tool execution.
 	// Connectors mode needs settings resolution ON but restricted to USER scope
 	// only — project/local settings files can smuggle `env`/`apiKeyHelper` from
-	// a hostile checkout (kendex#990). Full rationale on settingSourcesForQuery.
+	// a hostile checkout. Full rationale on settingSourcesForQuery.
 	const settingSources: SettingSource[] | undefined = settingSourcesForQuery(
 		enableCloudMcp, appendSystemPrompt, providerSettings.settingSources);
 	const strictMcpConfigEnabled = !appendSystemPrompt && providerSettings.strictMcpConfig !== false;
@@ -113,7 +113,7 @@ export function buildClaudeQueryOptions(input: BuildClaudeQueryOptionsInput): Bu
 
 	const extraArgs: Record<string, string | null> = {};
 	// Opus 4.7 defaults thinking.display to "omitted" (empty thinking text in stream).
-	// Force summarized so thinking_delta events arrive. See anthropics/claude-agent-sdk-python#830.
+	// Force summarized so thinking_delta events arrive.
 	// Deliberately the raw flag, NOT the typed `thinking` option: every non-disabled
 	// ThinkingConfig also emits `--thinking adaptive` or `--max-thinking-tokens`
 	// (verified in sdk.mjs flag mapping), so the typed form cannot set display
@@ -136,7 +136,7 @@ export function buildClaudeQueryOptions(input: BuildClaudeQueryOptionsInput): Bu
 	// DISABLE_AUTO_COMPACT=1: pi owns context-management and propagates its own
 	// /compact via session_compact (see handler in the extension entry). Letting CC
 	// also autocompact would double-flush the prompt cache and races pi's
-	// threshold with CC's, including CC's anti-thrashing guard (issue #8).
+		// threshold with CC's, including CC's anti-thrashing guard.
 	// Manual /compact in CC still works (we never invoke it).
 	// When connectors are enabled, allow claude.ai cloud MCP servers so the
 	// authenticated account's Gmail/Calendar/Drive tools load. Default stays "0".

package/src/query-state.ts

@@ -2,12 +2,11 @@
 //
 // All per-query and per-turn mutable state lives here. Reentrant queries
 // (subagents) push the parent context onto a stack and get a fresh instance.
-// Adding a new field = one property on the class.
 //
-// Extracted from index.ts so tests can import without activating the extension.
+// Separate from index.ts so tests can import it without activating the extension.
 
 import type { ContentBlockParam } from "@anthropic-ai/sdk/resources";
-import type { AssistantMessage, AssistantMessageEventStream, Model } from "@earendil-works/pi-ai";
+import type { AssistantMessage, AssistantMessageEventStream, Context, Model, SimpleStreamOptions } from "@earendil-works/pi-ai";
 import { isConnectorTool } from "./connectors.js";
 import type { McpResult } from "./extract-tool-results.js";
 import { currentRequestLaneId } from "./request-lane.js";
@@ -15,8 +14,7 @@ import { currentRequestLaneId } from "./request-lane.js";
 /** A mid-query user run captured for replay after the active query ends.
  *  `text` is the joined text form (previews, and the replay prompt when no
  *  image blocks were captured). `blocks` is present when the run carried
- *  images — the replay must send the blocks or the images are silently lost
- *  (kendex#993). */
+ *  images — the replay must send the blocks or the images are silently lost. */
 export interface DeferredUserMessage {
 	text: string;
 	blocks?: ContentBlockParam[];
@@ -25,7 +23,7 @@ export interface DeferredUserMessage {
 /** Diag payload for a deferred-message drop: counts, sites, and lengths only.
  *  The messages are user-authored prompt text and the diag log sits outside
  *  any host app's retention boundary, so no content — not even a preview —
- *  may appear in the entry (VST-15). */
+ *  may appear in the entry. */
 export function summarizeDroppedUserMessages(site: string, dropped: DeferredUserMessage[]): Record<string, unknown> {
 	return {
 		site,
@@ -35,12 +33,22 @@ export function summarizeDroppedUserMessages(site: string, dropped: DeferredUser
 	};
 }
 
+/** A provider call held to replace a query whose Pi history was replaced while
+ *  it ran: the callback's own model, context, options and stream, so the
+ *  replacement runs under the current request instead of the dead query's. */
+export interface QueryRestartRequest {
+	model: Model<any>;
+	context: Context;
+	options: SimpleStreamOptions | undefined;
+	stream: AssistantMessageEventStream;
+}
+
 export interface PendingToolCall {
 	toolName: string;
 	/** The MCP invocation's schema-validated arguments. The SDK hands the handler
 	 *  the COMPLETE input, so this is the authoritative copy — the grace-timer
 	 *  finalize settles a still-partial streamed block from here instead of from
-	 *  its truncated partial JSON (kendex#1469: a `{}` settle made Pi execute
+	 *  its truncated partial JSON (a `{}` settle would make Pi execute
 	 *  empty-argument calls). */
 	args: Record<string, unknown>;
 	/** `QueryContext.callbackGeneration` at registration. A handler from an older
@@ -66,7 +74,7 @@ const DRAIN_CAUSE_TEXT: Record<ToolCallDrainCause, string> = {
 
 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.` }],
+		content: [{ type: "text", text: `tool-call-drain=${cause}\nClaude bridge: ${DRAIN_CAUSE_TEXT[cause]} before this tool call's result was delivered. The call did not complete and produced no output.` }],
 		isError: true,
 	};
 }
@@ -97,7 +105,7 @@ export function drainPendingToolCalls(queryCtx: QueryContext, cause: ToolCallDra
  *  call is guaranteed not to have executed on the Pi side. */
 export function strandedToolCallResult(): McpResult {
 	return {
-		content: [{ type: "text", text: "Claude bridge: this tool call was never forwarded to Pi before its turn ended, so it did not execute and no result can arrive. Re-run the tool." }],
+		content: [{ type: "text", text: "tool-call-stranded=unforwarded\nClaude bridge: this tool call was never forwarded to Pi before its turn ended, so it did not execute and no result can arrive. Re-run the tool." }],
 		isError: true,
 	};
 }
@@ -106,7 +114,7 @@ export function strandedToolCallResult(): McpResult {
  *  forwarded (Pi owes it a result — steer-split deliveries arrive turns later)
  *  or nothing is waiting. Marks the id dead so a lagging stream replay can
  *  never forward it AFTER the model was told it failed — that late forward
- *  would execute the call a second time behind the model's back (kendex#1469).
+ *  would execute the call a second time behind the model's back.
  *  Returns true when a handler was failed. */
 export function failStrandedToolCall(queryCtx: QueryContext, id: string): boolean {
 	if (queryCtx.forwardedToolCallIds.has(id)) return false;
@@ -163,10 +171,16 @@ export function takeQueuedOrParkedResult(queryCtx: QueryContext, id: string): Mc
 /** One connector call's audit state for the life of a query. `recorded` means an
  *  entry for it has already been appended (or attempted), so neither a re-yielded
  *  result nor the teardown flush can record it twice. */
-export interface ConnectorCallAuditState {
+/** Why pi's messages can never carry this call: a claude.ai connector the child
+ *  ran itself, or a foreign MCP tool it loaded from filesystem settings. Only a
+ *  connector backs the connector audit trail. */
+export type ChildSideCallKind = "connector" | "foreign-mcp";
+
+export interface ChildSideCallState {
 	name: string;
+	kind: ChildSideCallKind;
 	/** The child session that issued it, captured when the call was seen — a
-	 *  continuation query gets a new one, and a call is audited against the session
+	 *  continuation query gets its own, and a call is audited against the session
 	 *  that actually made it. */
 	childSessionId?: string;
 	recorded: boolean;
@@ -249,23 +263,38 @@ export class QueryContext {
 	// Query-scoped (fully isolated per query)
 	activeQuery: unknown | null = null;
 	currentPiStream: AssistantMessageEventStream | null = null;
+	/** Pi replaced the history this query's Claude session was built from
+	 *  (compaction, history navigation) while the query was still running.
+	 *  Delivering further tool results into it would keep Claude Code on history
+	 *  Pi no longer holds, so the next provider callback restarts the query from
+	 *  Pi's new context. A query that ENDS while this is set persists its record
+	 *  with needsRebuild, so the next turn rebuilds either way. */
+	piHistoryReplaced = false;
+	/** The handover this replacement asked for was refused, and the refusal is
+	 *  already reported. Every later callback of the query re-reads
+	 *  `piHistoryReplaced`, which stays set, so without this the same refusal
+	 *  would be recorded once per remaining tool result. */
+	reportedHistoryRestartDecline = false;
+	/** The provider callback that observed `piHistoryReplaced`. The dying query's
+	 *  own promise chain runs it, after teardown released the query state, and
+	 *  feeds the replacement query's events into that callback's stream. */
+	restartRequest: QueryRestartRequest | null = null;
 	latestCursor = 0;
 	pendingToolCalls = new Map<string, PendingToolCall>();
 	pendingResults = new Map<string, McpResult>();
 	/** Results a message-boundary reap moved OUT of pendingResults so they stop
-	 *  poisoning mismatch reports, kept CONSUMABLE for a handler that fires later.
-	 *  The 2026-08-17 deadlock session showed the reap's "no consumer will ever
-	 *  come" assumption failing routinely: Pi delivers a turn's results in one
-	 *  callback while the SDK staggers handler invocations past the next message
-	 *  boundary. Query-scoped, bounded by the query's tool-call count. */
+	 *  poisoning mismatch reports, kept CONSUMABLE for a handler that fires later:
+	 *  Pi delivers a turn's results in one callback while the SDK staggers handler
+	 *  invocations past the next message boundary, so a boundary never proves that
+	 *  no consumer will come. Query-scoped, bounded by the query's tool-call count. */
 	reapedResults = new Map<string, McpResult>();
 	/** Every tool-call id this query has handed to Pi inside an ENDED turn — the
 	 *  set endToolUseTurn stamps from the turn's content. A forwarded id is one Pi
 	 *  will execute and answer; it must never be emitted again (a lagging stream
 	 *  replays the same tool_use into the NEXT turn, and per-message turnBlocks
-	 *  dedup cannot see across turns — kendex#1469's duplicate executions), and a
-	 *  handler waiting on it must be left waiting at the stranded-handler drains.
-	 *  Query-scoped, never reset per message. */
+	 *  dedup cannot see across turns), and a handler waiting on it must be left
+	 *  waiting at the stranded-handler drains. Query-scoped, never reset per
+	 *  message. */
 	forwardedToolCallIds = new Set<string>();
 	/** Ids whose waiting handler was resolved with strandedToolCallResult. The
 	 *  model has been told these calls failed; forwarding one later would execute
@@ -287,15 +316,15 @@ export class QueryContext {
 	 * resets at every message boundary, but `pendingResults` is query-scoped, so a
 	 * result stranded there outlives the message that named it. Without this map a
 	 * teardown report can only say "1 queued" with empty toolNames and 0/0
-	 * counters — which is exactly the unactionable record the 2026-07-28 diag log
-	 * showed. Bounded by the number of tool calls in one query.
+	 * counters — an unactionable record. Bounded by the number of tool calls in
+	 * one query.
 	 */
 	queryToolNames = new Map<string, string>();
 	/** id → last-known arguments, query-scoped like queryToolNames and for the
 	 *  same reason: a late handler firing after resetToolTracking wiped the
 	 *  per-message records must still be able to exact-match the parked/queued
 	 *  result of ITS OWN call — without stored args the only fallback is
-	 *  sole-same-name, which can hand it a LIVE sibling's id (kendex#1469). */
+	 *  sole-same-name, which can hand it a LIVE sibling's id. */
 	queryToolArgs = new Map<string, Record<string, unknown>>();
 	claimedToolCallIds = new Set<string>();
 	deliveredToolResultIds = new Set<string>();
@@ -305,13 +334,13 @@ export class QueryContext {
 	deferredUserMessages: DeferredUserMessage[] = [];
 	handledTerminalError = false;
 	// Once visible text/thinking, a complete tool call, or a child-executed
-	// CONNECTOR dispatch reaches Pi, the request must never be replayed on
-	// another account (duplicate side effects). Query-scoped, not per-turn:
+	// connector/foreign-MCP dispatch reaches Pi, the request must never be
+	// replayed on another account (duplicate side effects). Query-scoped, not per-turn:
 	// resetTurnState must not clear it.
 	committedOutput = false;
 	/** True when this query holds NO claim on the module-level shared session
-	 *  record: a reentrant (subagent) query, or a foreign-conversation one-shot
-	 *  (kendex#1001). Every shared-record mutation reachable from this context —
+	 *  record: a reentrant (subagent) query, or a foreign-conversation one-shot.
+	 *  Every shared-record mutation reachable from this context —
 	 *  reportToolResultMismatch's needsRebuild/forceRotate mark, the cursor
 	 *  advances on the tool-result-delivery and orphaned-result paths — must
 	 *  no-op so the PARENT's record stays untouched. Assigned at fresh-query
@@ -335,32 +364,37 @@ export class QueryContext {
 	/** tool_use id → raw SDK tool name. */
 	childExecutedToolCalls = new Map<string, string>();
 	/**
-	 * The same calls, for the connector-call audit trail (see connector-audit.ts).
+	 * Every call the CHILD executed that pi's messages cannot carry — a claude.ai
+	 * connector, or a foreign MCP tool the child loaded itself — keyed by tool_use
+	 * id. Nothing can rebuild these from pi's context, so a history handover is
+	 * refused while the map is non-empty. Connector entries also back the
+	 * connector-call audit trail (see connector-audit.ts).
 	 *
 	 * Query-scoped and deliberately NOT cleared by resetToolTracking: that runs at
 	 * every child message boundary, and a call issued in one child message is only
 	 * reconciled after that message ends. Clearing it there would make an abandoned
 	 * call unrecordable at teardown — which is the one case the trail exists for.
+	 * Fresh-query setup clears it instead, once teardown has flushed it: a reused
+	 * top-level context would otherwise answer for calls an earlier query made.
 	 */
-	connectorCallAudit = new Map<string, ConnectorCallAuditState>();
+	childSideCalls = new Map<string, ChildSideCallState>();
 	/** Claude Code session id for this query, from the SDK's `system` init message.
 	 *  Undefined until it arrives; the audit trail omits the field rather than
 	 *  guessing. */
 	childSessionId: string | undefined;
 	/** Anthropic content-block indexes of the current assistant message that carry
 	 *  a child-executed tool_use. Scoped to one message: cleared at message_start,
-	 *  and an index is released as soon as a new block starts there. */
+	 *  and an index is released as soon as another block starts there. */
 	childExecutedStreamIndexes = new Set<number>();
 
 	// Usage accounting for a Pi turn that spans SEVERAL child assistant messages.
 	//
 	// Every child message is a separate billed API call, and each reports its own
 	// counters — `message_start`/`message_delta` REPLACE rather than accumulate. A
-	// Pi turn used to end at the first tool call, so one Pi message meant one child
-	// message and replacing was right. A turn containing a child-executed connector
-	// call now keeps running across the child's follow-up messages, so replacing
-	// would silently drop everything the earlier ones billed (measured: 55,685
-	// cache-write tokens lost on a single connector turn).
+	// Pi turn that ends at its first tool call spans one child message, where
+	// replacing is right. A turn containing a child-executed connector call keeps
+	// running across the child's follow-up messages, so replacing would silently
+	// drop everything the earlier ones billed.
 	//
 	// So: `turnUsageCarry` holds the totals of the child messages already COMPLETE
 	// in this Pi turn, `currentMessageUsage` holds the one in flight, and the Pi
@@ -404,7 +438,7 @@ export class QueryContext {
 	turnSawToolCall = false;
 
 	get turnBlocks(): Array<any> {
-		if (!this.turnOutput) throw new Error("turnBlocks accessed before resetTurnState");
+		if (!this.turnOutput) throw new Error("turn-state-uninitialized=turnBlocks\nturnBlocks accessed before resetTurnState");
 		return this.turnOutput.content;
 	}
 
@@ -420,8 +454,8 @@ export class QueryContext {
 		this.turnSawStreamEvent = false;
 		this.turnSawToolCall = false;
 		this.handledTerminalError = false;
-		// A new pi message means the previous turn's stream is done with; an armed
-		// end-timer for it must not fire into the new turn's state.
+		// A fresh pi message means the previous turn's stream is done with; an
+		// armed end-timer for it must not fire into this turn's state.
 		if (this.scheduledToolUseEnd) {
 			clearTimeout(this.scheduledToolUseEnd.timer);
 			this.scheduledToolUseEnd = null;
@@ -432,8 +466,8 @@ export class QueryContext {
 		this.currentMessageUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
 		this.currentMessageId = undefined;
 		// Tool-call tracking is NOT reset here — it persists across the
-		// tool-result delivery callback for the same assistant message. New
-		// assistant messages call resetToolTracking() explicitly.
+		// tool-result delivery callback for the same assistant message. Each
+		// assistant message boundary calls resetToolTracking() explicitly.
 	}
 
 	resetToolTracking(): void {
@@ -470,9 +504,10 @@ export class QueryContext {
 			// Both emission paths can see the same call (streamed block, then the
 			// SDK's completed copy), so never overwrite an existing audit state —
 			// that would resurrect one already recorded.
-			if (!this.connectorCallAudit.has(id)) {
-				this.connectorCallAudit.set(id, {
+			if (!this.childSideCalls.has(id)) {
+				this.childSideCalls.set(id, {
 					name: rawName,
+					kind: "connector",
 					...(this.childSessionId ? { childSessionId: this.childSessionId } : {}),
 					recorded: false,
 				});
@@ -481,6 +516,21 @@ export class QueryContext {
 		if (typeof streamIndex === "number") this.childExecutedStreamIndexes.add(streamIndex);
 	}
 
+	/** A foreign MCP tool the child loaded from filesystem settings and ran
+	 *  itself. Pi never sees the call or its result, so it commits the turn the
+	 *  same way a connector does and joins the same map: a rebuild from pi's
+	 *  context would erase an account-visible operation the model could repeat. */
+	noteForeignMcpToolCall(id: string | undefined, rawName: string): void {
+		this.markOutputCommitted();
+		if (!id || this.childSideCalls.has(id)) return;
+		this.childSideCalls.set(id, {
+			name: rawName,
+			kind: "foreign-mcp",
+			...(this.childSessionId ? { childSessionId: this.childSessionId } : {}),
+			recorded: false,
+		});
+	}
+
 	recordToolCall(id: string | undefined, toolName: string, args: Record<string, unknown> = {}): void {
 		if (!id) return;
 		this.queryToolNames.set(id, toolName);
@@ -517,7 +567,7 @@ export class QueryContext {
 		// Ids whose RESULT already sits queued or parked. A handler can fire after
 		// the message boundary wiped the per-message records — by then Pi has
 		// executed its call and only these query-scoped stores still know it
-		// (kendex#1469: the boundary reap used to make such a handler error out
+		// (dropping them at the boundary would make such a handler error out
 		// and the model re-run an already-executed side-effectful call). An
 		// exact-args match here outranks the live sole-same-name fallback below,
 		// so a late handler can never steal a live sibling's id while its own
@@ -556,10 +606,9 @@ export class QueryContext {
 			//   - the handler receives the MCP server's schema-VALIDATED copy of
 			//     the input (zod may strip unknown keys or apply defaults) while
 			//     the record holds the raw streamed input.
-			// Refusing here stranded the call outright: the handler errored into
-			// the child while pi's real result sat queued forever (diag log
-			// 2026-07-28, `edit` with argKeys [edits, path] on both sides). A
-			// same-type sole-candidate claim is strictly safer than that. With
+			// Refusing here strands the call outright: the handler errors into
+			// the child while pi's real result sits queued forever. A same-type
+			// sole-candidate claim is strictly safer than that. With
 			// SEVERAL same-name candidates and no exact match we still refuse —
 			// cross-pairing two live calls is the one outcome worse than failing.
 			chosen = byName[0];
@@ -585,9 +634,8 @@ export class QueryContext {
 	 * assistant fallback). Left in pendingResults, each entry poisons every later
 	 * mismatch report for the whole query (queued>0 with 0/0 counters and no tool
 	 * names) and forces a session rebuild per turn. But the boundary does NOT
-	 * prove the handler gave up — the SDK staggers handler invocations, and the
-	 * 2026-08-17 deadlock session (kendex#1469) had three of five parallel
-	 * handlers fire after this reap destroyed their results. So the reap parks
+	 * prove the handler gave up — the SDK staggers handler invocations, and
+	 * handlers in a parallel batch routinely fire after it. So the reap parks
 	 * instead of dropping: reports stay clean, and a late handler still gets its
 	 * real result through takeQueuedOrParkedResult.
 	 */
@@ -629,9 +677,9 @@ export class QueryContext {
 		const counts = new Map<string, number>();
 		if (affectedIds.size > 0) {
 			// Name the affected ids from the query-scoped map, not just this
-			// message's records: a queued straggler from an earlier child message is
+		// message's records: a queued straggler from a prior child message is
 			// exactly the case a mismatch report exists for, and this message's
-			// turnToolCalls no longer knows it.
+			// turnToolCalls does not know it.
 			for (const id of affectedIds) {
 				const name = this.queryToolNames.get(id)
 					?? this.turnToolCalls.find((call) => call.id === id)?.toolName
@@ -708,14 +756,14 @@ export function stackDepth(): number { return lane().stack.length; }
 
 export function pushContext(): void {
 	const state = lane();
-	if (!state.current.activeQuery) throw new Error("pushContext() called with no active query");
+	if (!state.current.activeQuery) throw new Error("query-stack-push=inactive\npushContext() called with no active query");
 	state.stack.push(state.current);
 	state.current = new QueryContext();
 }
 
 export function popContext(): void {
 	const state = lane();
-	if (state.stack.length === 0) throw new Error("popContext() called with empty stack");
+	if (state.stack.length === 0) throw new Error("query-stack-pop=empty\npopContext() called with empty stack");
 	const parent = state.stack[state.stack.length - 1];
 	parent.deferredUserMessages.push(...state.current.deferredUserMessages);
 	state.current = state.stack.pop()!;

package/src/query-teardown.ts

@@ -2,16 +2,32 @@
 // operates on the ONE context captured at query start — never the live ctx().
 // The two only differ while a reentrant (subagent) context is pushed, which is
 // exactly when a parent query ending abnormally (abort, child process death)
-// used to run this against the subagent's state: the parent's drain, audit
-// flush, and activeQuery clear were skipped, leaking its pending MCP handlers.
+// teardown must run against the parent state. Using the subagent state skips
+// the parent's drain, audit flush, and activeQuery clear, which leaks handlers.
 
 import { reportToolResultMismatch } from "./bridge-state.js";
 import { flushConnectorCallAudit } from "./connector-audit.js";
 import { debug } from "./debug.js";
 import { drainPendingToolCalls, popContextFor, type QueryContext, type ToolCallDrainCause } from "./query-state.js";
 
+/** Close a settled or dying SDK query. Its transport can throw on the way down
+ *  — a child already gone, a socket already closed — and that throw belongs to
+ *  the query being closed, never to whatever its caller does next. */
+export function closeSdkQuery(sdkQuery: unknown): void {
+	try { (sdkQuery as { close(): void }).close(); }
+	catch (error) { debug("provider: closing the sdk query threw; continuing teardown:", error); }
+}
+
+/** Stop an in-flight SDK query. `interrupt()` asks the CLI to stop gracefully,
+ *  `close()` kills it; both are needed, because interrupt alone lets the current
+ *  API call finish. */
+export function abortSdkQuery(sdkQuery: unknown): void {
+	void (sdkQuery as { interrupt(): Promise<void> }).interrupt().catch(() => {});
+	closeSdkQuery(sdkQuery);
+}
+
 /** Tear down `queryCtx` after its SDK query settled. No-ops when the query is
- *  no longer the context's active one (a continuation replaced it, or teardown
+ *  is not the context's active one (a continuation replaced it, or teardown
  *  already ran). Returns true when teardown actually ran. */
 export function teardownQuery(
 	queryCtx: QueryContext,

package/src/rate-limit.ts

@@ -79,7 +79,7 @@ export function normalizeRateLimitUtilization(value: unknown): number | undefine
 	// (100%) because that is the fail-closed direction — under the fraction
 	// convention 1 is the fully-consumed case the warning exists to surface,
 	// while under the percent convention 1% sits below the threshold anyway,
-	// so nothing is lost by warning (VST-16).
+	// so nothing is lost by warning.
 	if (value > 0 && value <= 1) return value * 100;
 	if (value > 1 && value <= 100) return value;
 	return undefined;

package/src/session-persistence.ts

@@ -155,7 +155,7 @@ function canonicalize(p: string | undefined): string | undefined {
 // 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
+// every non-label entry from root→leaf into the fork 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.
@@ -168,12 +168,12 @@ export function shouldRestorePersistedBridgeEntry(
 	currentPiSessionId: string | undefined,
 	currentCwd: string | undefined,
 ): string | undefined {
-	if (!persisted.piSessionId) return "missing piSessionId";
+	if (!persisted.piSessionId) return "restore-session-missing=piSessionId\nMissing piSessionId.";
 	if (currentPiSessionId && persisted.piSessionId !== currentPiSessionId) {
-		return `piSessionId mismatch (persisted=${persisted.piSessionId} current=${currentPiSessionId})`;
+		return `restore-session-mismatch=${persisted.piSessionId} current=${currentPiSessionId}\nThe persisted session differs from the active session.`;
 	}
 	if (currentCwd && canonicalize(persisted.cwd) !== canonicalize(currentCwd)) {
-		return `cwd mismatch (persisted=${persisted.cwd} current=${currentCwd})`;
+		return `restore-cwd-mismatch=${persisted.cwd} current=${currentCwd}\nThe persisted working directory differs from the active directory.`;
 	}
 	return undefined;
 }
@@ -287,7 +287,7 @@ export function schedulePersistSharedSession(ctxLike?: { sessionManager?: unknow
 			// A failed persist means the next startup restores a stale (or no)
 			// bridge marker and silently rebuilds — worth a diagnostic entry.
 			// Like all diagDump output this lands only under CLAUDE_BRIDGE_DEBUG=1
-			// (VST-15); the failure itself stays non-fatal either way.
+			// and the failure itself stays non-fatal either way.
 			diagDump("persist_shared_session_failed", {
 				sessionId: snapshot.sessionId.slice(0, 8),
 				cursor: snapshot.cursor,
@@ -391,7 +391,7 @@ export function planIncrementalPromptBatch(
 
 	// A cursor past the end is PROOF this messages array is not the conversation
 	// the cursor describes (e.g. a reentrant subagent's short context arriving
-	// while the parent's cursor is large). Clamping it used to fabricate a REUSE
+	// while the parent's cursor is large). Clamping it would fabricate a REUSE
 	// plan against foreign history — reject so the caller takes the rebuild path.
 	if (cursor > lastIndex) {
 		debug(`planIncrementalPromptBatch: rejected — cursor=${cursor} beyond last index ${lastIndex}; messages are not the conversation this cursor describes`);
@@ -419,7 +419,7 @@ export function planIncrementalPromptBatch(
 // 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(
+export function verifyWrittenSession(
 	jsonlPath: string,
 	expectedSessionId: string,
 	expectedRecordCount: number,
@@ -436,7 +436,7 @@ function verifyWrittenSession(
 		// reason — an absolute cwd carries the username; the diagDump keeps the
 		// absolute forms.
 		safeNotify(
-			`Session file issue: ${msg}\n` +
+			`${msg}\n` +
 			`cwd=${displayPath(cwd)} realpath=${displayPath(safeRealpath(cwd))}\n` +
 			`Please copy and paste this message into a new issue at https://github.com/vanillagreencom/kendex/issues/new` +
 			(DEBUG ? ` and attach ${DEBUG_LOG_PATH}` : ` (rerun with CLAUDE_BRIDGE_DEBUG=1 to capture a debug log)`),
@@ -479,7 +479,7 @@ function debugSessionPaths(label: string, cwd: string, jsonlPath: string, claude
 //     promptStart can never land on a user message Claude already persisted:
 //     Claude owns [0, cursor), promptStart starts at the cursor and only ever
 //     advances (past the one optional assistant), so everything from
-//     promptStart on is new input. Returns the existing sessionId. Keeps CC's
+//     promptStart on is uncaptured input. 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
@@ -509,12 +509,12 @@ export function syncSharedSession(
 	account?: AccountSessionScope,
 ): SyncResult {
 	const sharedSession = getSharedSession();
-	const priorMessages = messages.slice(0, -1); // everything before the new user prompt
+	const priorMessages = messages.slice(0, -1); // everything before the current user prompt
 	const accountProfileId = account?.accountProfileId;
 	const scopeConfigDir = account?.claudeConfigDir; // resolved dir for managed, undefined for legacy
 	// What cc-session-io reads/writes. Managed requests always carry a resolved
 	// dir (accountSessionScope) so this never falls back to the process env the
-	// child no longer sees; legacy keeps the env rule unchanged.
+	// child does not see; legacy keeps the env rule unchanged.
 	const claudeDir = scopeConfigDir ?? process.env.CLAUDE_CONFIG_DIR;
 	const sameAccount = Boolean(
 		sharedSession &&
@@ -523,7 +523,7 @@ export function syncSharedSession(
 	);
 	const incomingFingerprint = conversationFingerprint(messages);
 
-	// FOREIGN-CONVERSATION guard (Case 6, kendex#1001). A subagent-shaped query
+	// FOREIGN-CONVERSATION guard. A subagent-shaped query
 	// arriving while the parent is IDLE is not reentrant, so it lands here as an
 	// outermost query. Without an identity check its short foreign context takes
 	// the REBUILD path — rewriting the PARENT's session file from foreign
@@ -568,7 +568,7 @@ export function syncSharedSession(
 			// Read the pre-update cursor first: setSharedSession reassigns the live
 			// binding, so comparing against sharedSession.cursor afterwards would
 			// always be equal and the "advanced past trailing assistant" debug
-			// branch could never print (kendex#993).
+			// branch could never print.
 			const cursorBeforeUpdate = sharedSession.cursor;
 			// A REUSE match proves identity, so the anchor may only strengthen here:
 			// a pre-3.1.1 record adopts it outright, and a turn-1 user-only anchor

package/src/session-verify.ts

@@ -57,28 +57,28 @@ export function verifyWrittenSession(jsonlPath: string, expectedSessionId: strin
 	try {
 		st = statSync(jsonlPath);
 	} catch (e) {
-		warnings.push(`file missing after save — path=${jsonlPath} err=${e.message}`);
+		warnings.push(`session-file-missing=${jsonlPath}\nFile missing after save: ${e.message}`);
 		return warnings;
 	}
 	let summary;
 	try {
 		summary = summarizeJsonl(jsonlPath);
 	} catch (e) {
-		warnings.push(`file unreadable — path=${jsonlPath} size=${st.size} err=${e.message}`);
+		warnings.push(`session-file-unreadable=${jsonlPath}\nFile unreadable: size=${st.size} error=${e.message}`);
 		return warnings;
 	}
 	if (summary.count !== expectedRecordCount) {
-		warnings.push(`record count mismatch — expected=${expectedRecordCount} actual=${summary.count} path=${jsonlPath} bytes=${st.size}`);
+		warnings.push(`session-record-count=${summary.count} expected=${expectedRecordCount}\nRecord count differs: path=${jsonlPath} bytes=${st.size}`);
 		return warnings;
 	}
 	try {
 		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}`);
+			warnings.push(`session-id-drift=${expectedSessionId} first=${firstRec.sessionId} last=${lastRec.sessionId}\nSession identity differs from the expected identity.`);
 		}
 	} catch (e) {
-		warnings.push(`malformed JSONL — path=${jsonlPath} err=${e.message}`);
+		warnings.push(`session-json-invalid=${jsonlPath}\nMalformed JSONL: ${e.message}`);
 	}
 	return warnings;
 }