@oh-my-pi/pi-coding-agent 15.11.7 → 15.12.0

package/src/sdk.ts

@@ -89,7 +89,14 @@ import { type FileSlashCommand, loadSlashCommands as loadSlashCommandsInternal }
 import type { HindsightSessionState } from "./hindsight/state";
 import { LocalProtocolHandler, type LocalProtocolOptions } from "./internal-urls";
 import { LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "./lsp/startup-events";
-import { discoverAndLoadMCPTools, MCPManager, type MCPToolsLoadResult } from "./mcp";
+import {
+	discoverAndLoadMCPTools,
+	type MCPLoadResult,
+	MCPManager,
+	MCPToolCache,
+	type MCPToolsLoadResult,
+	parseMCPToolName,
+} from "./mcp";
 import { createSessionMemoryRuntimeContext, resolveMemoryBackend } from "./memory-backend";
 import type { MnemopiSessionState } from "./mnemopi/state";
 import asyncResultTemplate from "./prompts/tools/async-result.md" with { type: "text" };
@@ -147,6 +154,7 @@ import {
 	type DiscoverableTool,
 	filterBySource,
 	formatDiscoverableToolServerSummary,
+	isMCPToolName,
 	selectDiscoverableToolNamesByServer,
 	summarizeDiscoverableTools,
 } from "./tool-discovery/tool-index";
@@ -302,6 +310,76 @@ function buildMcpNotificationBatchMessage(entries: McpNotificationEntry[]): Agen
 	};
 }
 
+type DeferredMCPActivation = {
+	mcpDiscoveryEnabled: boolean;
+	explicitlyRequestedMCPToolNames: string[];
+	activateAllMCPTools: boolean;
+};
+
+function formatMCPConnectingMessage(serverNames: string[]): string {
+	return `Connecting to MCP servers: ${serverNames.join(", ")}…`;
+}
+
+function createPendingMCPTool(name: string): Tool {
+	const parsed = parseMCPToolName(name);
+	const serverName = parsed?.serverName;
+	const mcpToolName = parsed?.toolName ?? name;
+	const label = serverName ? `${serverName}/${mcpToolName}` : name;
+	const message = serverName
+		? `MCP server "${serverName}" is still connecting; tool "${name}" is not yet available. Retry after the MCP connection completes.`
+		: `MCP discovery is still in progress; tool "${name}" is not yet available. Retry after MCP connection completes.`;
+	const tool: Tool & { mcpServerName?: string; mcpToolName?: string } = {
+		name,
+		label,
+		description: `Pending MCP tool. ${message}`,
+		parameters: {
+			type: "object",
+			properties: {},
+			additionalProperties: true,
+		},
+		approval: "write",
+		intent: "omit",
+		mcpServerName: serverName,
+		mcpToolName,
+		async execute() {
+			return {
+				content: [{ type: "text", text: message }],
+				details: { serverName, mcpToolName, isError: true },
+				isError: true,
+			};
+		},
+	};
+	return tool;
+}
+
+function collectPendingMCPToolNames(
+	explicitToolNames: readonly string[] | undefined,
+	restoredSelectedToolNames: readonly string[],
+): string[] {
+	const names = new Set<string>();
+	for (const name of explicitToolNames ?? []) {
+		const normalized = name.toLowerCase();
+		if (isMCPToolName(normalized)) names.add(normalized);
+	}
+	for (const name of restoredSelectedToolNames) {
+		const normalized = name.toLowerCase();
+		if (isMCPToolName(normalized)) names.add(normalized);
+	}
+	return [...names];
+}
+
+function logMCPLoadErrors(errors: MCPLoadResult["errors"]): void {
+	for (const [serverName, error] of errors) {
+		logger.error("MCP tool load failed", { path: `mcp:${serverName}`, error });
+	}
+}
+
+function applyMCPEnvironment(result: { exaApiKeys: string[] }): void {
+	if (result.exaApiKeys.length > 0 && !$env.EXA_API_KEY) {
+		Bun.env.EXA_API_KEY = result.exaApiKeys[0];
+	}
+}
+
 // Types
 export interface CreateAgentSessionOptions {
 	/** Working directory for project-local discovery. Default: getProjectDir() */
@@ -1518,46 +1596,131 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		let mcpManager: MCPManager | undefined = options.mcpManager;
 		toolSession.mcpManager = mcpManager;
 		const enableMCP = options.enableMCP ?? true;
+		const deferMCPDiscoveryForUI = enableMCP && !mcpManager && options.hasUI === true;
 		const customTools: CustomTool[] = [];
+		let startDeferredMCPDiscovery:
+			| ((liveSession: AgentSession, activation: DeferredMCPActivation) => void)
+			| undefined;
+		const onMCPConnecting = (serverNames: string[]) => {
+			if (!options.hasUI || serverNames.length === 0) return;
+			process.stderr.write(`${chalk.gray(formatMCPConnectingMessage(serverNames))}\n`);
+		};
+		const mcpDiscoverOptions = {
+			onConnecting: onMCPConnecting,
+			enableProjectConfig: settings.get("mcp.enableProjectConfig") ?? true,
+			// Always filter Exa - we have native integration
+			filterExa: true,
+			// Filter browser MCP servers when builtin browser tool is active
+			filterBrowser: settings.get("browser.enabled") ?? false,
+		};
 		if (enableMCP && !mcpManager) {
-			const mcpResult = await logger.time("discoverAndLoadMCPTools", discoverAndLoadMCPTools, cwd, {
-				onConnecting: serverNames => {
-					if (options.hasUI && serverNames.length > 0) {
-						process.stderr.write(`${chalk.gray(`Connecting to MCP servers: ${serverNames.join(", ")}…`)}\n`);
-					}
-				},
-				enableProjectConfig: settings.get("mcp.enableProjectConfig") ?? true,
-				// Always filter Exa - we have native integration
-				filterExa: true,
-				// Filter browser MCP servers when builtin browser tool is active
-				filterBrowser: settings.get("browser.enabled") ?? false,
-				cacheStorage: settings.getStorage(),
-				authStorage,
-			});
-			mcpManager = mcpResult.manager;
-			toolSession.mcpManager = mcpManager;
+			if (deferMCPDiscoveryForUI) {
+				const cacheStorage = settings.getStorage();
+				mcpManager = new MCPManager(cwd, cacheStorage ? new MCPToolCache(cacheStorage) : null);
+				mcpManager.setAuthStorage(authStorage);
+				toolSession.mcpManager = mcpManager;
+
+				if (settings.get("mcp.notifications")) {
+					mcpManager.setNotificationsEnabled(true);
+				}
 
-			if (settings.get("mcp.notifications")) {
-				mcpManager.setNotificationsEnabled(true);
-			}
-			// If we extracted Exa API keys from MCP configs and EXA_API_KEY isn't set, use the first one
-			if (mcpResult.exaApiKeys.length > 0 && !$env.EXA_API_KEY) {
-				Bun.env.EXA_API_KEY = mcpResult.exaApiKeys[0];
-			}
+				const deferredMCPManager = mcpManager;
+				startDeferredMCPDiscovery = (liveSession, activation) => {
+					void (async () => {
+						try {
+							const mcpResult = await logger.time("discoverAndLoadMCPTools", () =>
+								deferredMCPManager.discoverAndConnect(mcpDiscoverOptions),
+							);
+							// The session can be torn down while servers are still connecting.
+							// Don't resurrect tools on a disposed session, and don't leak the
+							// transports/subprocesses the connect just spawned.
+							if (liveSession.isDisposed) {
+								await deferredMCPManager.disconnectAll();
+								return;
+							}
+							applyMCPEnvironment(mcpResult);
+							logMCPLoadErrors(mcpResult.errors);
+							// `tools.discoveryMode: "auto"` was resolved against a registry that
+							// held only built-ins plus persisted placeholder names. Recompute with
+							// the real MCP tool count: a large toolset must flip discovery on
+							// BEFORE the refresh, or activateAll would dump every MCP tool into
+							// the active set with no search_tool_bm25 registered.
+							let discoveryEnabled = activation.mcpDiscoveryEnabled;
+							let activateAll = activation.activateAllMCPTools;
+							if (!discoveryEnabled) {
+								const nonMCPToolNames = [...toolRegistry.keys()].filter(name => !isMCPToolName(name));
+								const projectedMode = resolveEffectiveToolDiscoveryMode(
+									settings,
+									countToolsForAutoDiscovery([...nonMCPToolNames, ...mcpResult.tools.map(tool => tool.name)]),
+								);
+								if (projectedMode !== "off") {
+									effectiveDiscoveryMode = projectedMode;
+									mcpDiscoveryEnabled = true;
+									discoveryEnabled = true;
+									activateAll = false;
+									liveSession.enableMCPDiscovery();
+									if (!toolRegistry.has("search_tool_bm25")) {
+										const searchTool: Tool = new SearchToolBm25Tool(toolSession);
+										toolRegistry.set(
+											searchTool.name,
+											new ExtensionToolWrapper(wrapToolWithMetaNotice(searchTool), extensionRunner) as Tool,
+										);
+									}
+									await liveSession.setActiveToolsByName([
+										...liveSession.getActiveToolNames(),
+										"search_tool_bm25",
+									]);
+								}
+							}
+							await liveSession.refreshMCPTools(mcpResult.tools, { activateAll });
+							if (activation.explicitlyRequestedMCPToolNames.length > 0) {
+								if (discoveryEnabled && !activation.mcpDiscoveryEnabled) {
+									// Discovery flipped on mid-flight: route the explicit request
+									// through discovery-aware activation so selection persists.
+									await liveSession.activateDiscoveredMCPTools(activation.explicitlyRequestedMCPToolNames);
+								} else if (!discoveryEnabled) {
+									await liveSession.setActiveToolsByName([
+										...liveSession.getActiveToolNames(),
+										...activation.explicitlyRequestedMCPToolNames,
+									]);
+								}
+							}
+						} catch (error) {
+							logger.error("MCP tool load failed", {
+								path: ".mcp.json",
+								error: error instanceof Error ? error.message : String(error),
+							});
+						}
+					})();
+				};
+			} else {
+				const mcpResult = await logger.time("discoverAndLoadMCPTools", discoverAndLoadMCPTools, cwd, {
+					...mcpDiscoverOptions,
+					cacheStorage: settings.getStorage(),
+					authStorage,
+				});
+				mcpManager = mcpResult.manager;
+				toolSession.mcpManager = mcpManager;
 
-			// Log MCP errors
-			for (const { path, error } of mcpResult.errors) {
-				logger.error("MCP tool load failed", { path, error });
-			}
+				if (settings.get("mcp.notifications")) {
+					mcpManager.setNotificationsEnabled(true);
+				}
+				applyMCPEnvironment(mcpResult);
 
-			if (mcpResult.tools.length > 0) {
-				// MCP tools are LoadedCustomTool, extract the tool property
-				customTools.push(...mcpResult.tools.map(loaded => loaded.tool));
+				// Log MCP errors
+				for (const { path, error } of mcpResult.errors) {
+					logger.error("MCP tool load failed", { path, error });
+				}
+
+				if (mcpResult.tools.length > 0) {
+					// MCP tools are LoadedCustomTool, extract the tool property
+					customTools.push(...mcpResult.tools.map(loaded => loaded.tool));
+				}
 			}
 		}
 		// Only top-level sessions own the global MCPManager. Subagents already
 		// receive the parent's manager via `options.mcpManager`, and reassigning
-		// the singleton to the same value is a no-op \u2014 keep the gate explicit
+		// the singleton to the same value is a no-op — keep the gate explicit
 		// to mirror the AsyncJobManager ownership rule.
 		if (mcpManager && !options.parentTaskPrefix) MCPManager.setInstance(mcpManager);
 
@@ -1852,6 +2015,14 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		for (const tool of wrappedExtensionTools) {
 			toolRegistry.set(tool.name, tool);
 		}
+		if (deferMCPDiscoveryForUI && mcpManager) {
+			for (const name of collectPendingMCPToolNames(options.toolNames, existingSession.selectedMCPToolNames)) {
+				if (!toolRegistry.has(name)) {
+					toolRegistry.set(name, createPendingMCPTool(name));
+				}
+			}
+		}
+
 		// Wrap every tool with `ExtensionToolWrapper` so the per-tool approval gate runs on every
 		// call site, regardless of whether any user extensions are loaded. See the runner-construction
 		// comment above for the safety invariant this enforces.
@@ -1879,7 +2050,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			}
 		}
 
-		const effectiveDiscoveryMode = resolveEffectiveToolDiscoveryMode(
+		// `let`: the deferred MCP discovery closure upgrades these when the real
+		// MCP tool count pushes `auto` past its threshold; `rebuildSystemPrompt`
+		// below reads the live bindings.
+		let effectiveDiscoveryMode = resolveEffectiveToolDiscoveryMode(
 			settings,
 			countToolsForAutoDiscovery(toolRegistry.keys()),
 		);
@@ -1890,7 +2064,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				new ExtensionToolWrapper(wrapToolWithMetaNotice(searchTool), extensionRunner) as Tool,
 			);
 		}
-		const mcpDiscoveryEnabled = effectiveDiscoveryMode !== "off"; // back-compat: true when any discovery active
+		let mcpDiscoveryEnabled = effectiveDiscoveryMode !== "off"; // back-compat: true when any discovery active
 
 		const reloadSshTool = async (): Promise<AgentTool | null> => {
 			if (!requestedToolNameSet.has("ssh")) return null;
@@ -1942,7 +2116,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			const memoryBackend = await resolveMemoryBackend(settings);
 			const memoryInstructions = await memoryBackend.buildDeveloperInstructions(agentDir, settings, session);
 
-			// Build combined append prompt: memory instructions + MCP server instructions
+			// Build combined append prompt: memory instructions + MCP server instructions.
+			// For UI sessions MCP discovery is deferred, so `getServerInstructions()` is
+			// empty until the background connect completes; the rebuild that
+			// `refreshMCPTools` triggers post-discovery then picks up the now-connected
+			// servers' instructions, so they join the prompt for the rest of the session.
 			const serverInstructions = mcpManager?.getServerInstructions();
 			let appendPrompt: string | undefined = memoryInstructions ?? undefined;
 			if (serverInstructions && serverInstructions.size > 0) {
@@ -2494,7 +2672,26 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// Skip when reusing a parent's manager — the parent owns the callbacks.
 		if (mcpManager && !options.mcpManager) {
 			mcpManager.setOnToolsChanged(tools => {
-				void session.refreshMCPTools(tools);
+				void (async () => {
+					try {
+						await session.refreshMCPTools(
+							tools,
+							deferMCPDiscoveryForUI && !mcpDiscoveryEnabled && options.toolNames === undefined
+								? { activateAll: true }
+								: undefined,
+						);
+						if (deferMCPDiscoveryForUI && !mcpDiscoveryEnabled && explicitlyRequestedMCPToolNames.length > 0) {
+							await session.setActiveToolsByName([
+								...session.getActiveToolNames(),
+								...explicitlyRequestedMCPToolNames,
+							]);
+						}
+					} catch (error) {
+						logger.warn("MCP tool refresh failed", {
+							error: error instanceof Error ? error.message : String(error),
+						});
+					}
+				})();
 			});
 			// Wire prompt refresh → rebuild MCP prompt slash commands
 			mcpManager.setOnPromptsChanged(serverName => {
@@ -2527,6 +2724,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			});
 		}
 
+		startDeferredMCPDiscovery?.(session, {
+			mcpDiscoveryEnabled,
+			explicitlyRequestedMCPToolNames,
+			activateAllMCPTools: !mcpDiscoveryEnabled && options.toolNames === undefined,
+		});
+
 		return {
 			session,
 			extensionsResult,

package/src/session/agent-session.ts

@@ -100,6 +100,7 @@ import { modelsAreEqual } from "@oh-my-pi/pi-catalog/models";
 import { countTokens, MacOSPowerAssertion } from "@oh-my-pi/pi-natives";
 import {
 	extractRetryHint,
+	formatDuration,
 	getAgentDbPath,
 	getInstallId,
 	isBunTestRuntime,
@@ -240,7 +241,13 @@ import { normalizeModelContextImages } from "../utils/image-loading";
 import { buildNamedToolChoice } from "../utils/tool-choice";
 import type { AuthStorage } from "./auth-storage";
 import type { ClientBridge, ClientBridgePermissionOption, ClientBridgePermissionOutcome } from "./client-bridge";
-import { defaultCodexAutoRedeemCoordinator, evaluateCodexAutoRedeem } from "./codex-auto-reset";
+import {
+	type CodexAutoRedeemRedeemDecision,
+	defaultCodexAutoRedeemCoordinator,
+	evaluateCodexAutoRedeem,
+	shouldEvaluateCodexAutoRedeem,
+	shouldPromptCodexAutoRedeem,
+} from "./codex-auto-reset";
 import {
 	type BashExecutionMessage,
 	type CustomMessage,
@@ -1418,6 +1425,11 @@ export class AgentSession {
 		return this.#ttsrManager;
 	}
 
+	/** Secret obfuscator, when secrets are configured; /share redaction reuses it. */
+	get obfuscator(): SecretObfuscator | undefined {
+		return this.#obfuscator;
+	}
+
 	/** Whether a TTSR abort is pending (stream was aborted to inject rules) */
 	get isTtsrAbortPending(): boolean {
 		return this.#ttsrAbortPending;
@@ -3140,6 +3152,12 @@ export class AgentSession {
 		state.resetConversationTracking();
 	}
 
+	/** True once dispose() has begun; deferred background work (e.g. the deferred
+	 *  MCP discovery task in sdk.ts) must not touch the session past this point. */
+	get isDisposed(): boolean {
+		return this.#isDisposed;
+	}
+
 	/**
 	 * Synchronously mark the session as disposing so new work is rejected
 	 * immediately: Python/eval starts throw, queued asides are dropped, and the
@@ -3473,6 +3491,17 @@ export class AgentSession {
 		return this.#mcpDiscoveryEnabled;
 	}
 
+	/**
+	 * Flip MCP discovery on after deferred discovery learns the real tool count.
+	 * UI sessions resolve `tools.discoveryMode: "auto"` before MCP servers
+	 * connect, so a large MCP toolset discovered later must be able to upgrade
+	 * the session from the force-activate path to the discovery path. One-way:
+	 * discovery is never downgraded mid-session.
+	 */
+	enableMCPDiscovery(): void {
+		this.#mcpDiscoveryEnabled = true;
+	}
+
 	getSelectedMCPToolNames(): string[] {
 		if (!this.#mcpDiscoveryEnabled) {
 			return this.getActiveToolNames().filter(name => isMCPToolName(name) && this.#toolRegistry.has(name));
@@ -10176,20 +10205,63 @@ export class AgentSession {
 			signal,
 		});
 	}
+	async #confirmCodexAutoRedeem(decision: CodexAutoRedeemRedeemDecision): Promise<boolean> {
+		const runner = this.#extensionRunner;
+		if (!runner?.hasUI()) {
+			this.emitNotice(
+				"warning",
+				"Codex saved reset is eligible, but auto-redeem is unset and no prompt UI is available. Run `/usage reset` or set codexResets.autoRedeem.",
+				"codex-auto-reset",
+			);
+			return false;
+		}
+
+		const who = decision.target.email ?? decision.target.accountId ?? "the active account";
+		const resetLabel = decision.availableCount === 1 ? "reset" : "resets";
+		try {
+			const choice = await runner
+				.getUIContext()
+				.select(
+					`Do you wanna redeem your reset?\n${who} is blocked by the weekly Codex limit for about ${formatDuration(decision.remainingMs)}. Spend 1 of ${decision.availableCount} saved ${resetLabel}?`,
+					[
+						{
+							label: "Yes",
+							description: "Redeem now and remember yes for future eligible Codex weekly blocks.",
+						},
+						{
+							label: "No",
+							description: "Do not auto-redeem saved Codex resets.",
+						},
+					],
+				);
+			if (choice === "Yes") {
+				this.settings.set("codexResets.autoRedeem", "yes");
+				return true;
+			}
+			if (choice === "No") {
+				this.settings.set("codexResets.autoRedeem", "no");
+			}
+		} catch (error) {
+			logger.warn("codex-auto-reset prompt failed", { error: String(error) });
+		}
+		return false;
+	}
 
 	/**
 	 * Auto-redeem hook for {@link AgentSession.#handleRetryableError}'s
 	 * usage-limit branch. Returns `true` only when a saved Codex reset was
-	 * actually spent (so the caller retries immediately). Opt-in, reactive, and
-	 * heavily gated — see `./codex-auto-reset` and the design in
-	 * `local://autoreset-spec.md`. Per-account in-flight dedup lets concurrent
-	 * sessions adopt one redeem instead of double-spending.
+	 * actually spent (so the caller retries immediately). The "unset" mode is
+	 * reactive but asks before spending; "yes" skips that prompt, and "no" avoids
+	 * the eligibility IO entirely. The decision remains heavily gated — see
+	 * `./codex-auto-reset` and the design in `local://autoreset-spec.md`.
+	 * Per-account in-flight dedup lets concurrent sessions adopt one redeem
+	 * instead of double-spending.
 	 */
 	async #maybeAutoRedeemCodexReset(coordinator = defaultCodexAutoRedeemCoordinator): Promise<boolean> {
 		const cfg = this.settings.getGroup("codexResets");
 		const model = this.model;
 		// Cheap exits before any IO.
-		if (!cfg.autoRedeem || !model || model.provider !== "openai-codex") return false;
+		if (!shouldEvaluateCodexAutoRedeem(cfg.autoRedeem) || !model || model.provider !== "openai-codex") return false;
 		const authStorage = this.#modelRegistry.authStorage;
 		// Capture identity BEFORE awaits: markUsageLimitReached leaves the
 		// usage-limit session credential sticky, so this names the blocked account.
@@ -10206,7 +10278,7 @@ export class AgentSession {
 				provider: model.provider,
 				modelId: model.id,
 				settings: {
-					autoRedeem: cfg.autoRedeem,
+					autoRedeem: true,
 					minBlockedMinutes: Math.max(0, cfg.minBlockedMinutes),
 					keepCredits: Math.max(0, Math.trunc(cfg.keepCredits)),
 				},
@@ -10219,6 +10291,9 @@ export class AgentSession {
 				logger.debug("codex-auto-reset: skipped", { reason: decision.reason });
 				return false;
 			}
+			if (shouldPromptCodexAutoRedeem(cfg.autoRedeem) && !(await this.#confirmCodexAutoRedeem(decision))) {
+				return false;
+			}
 			// Commit the attempt BEFORE acting so this block can never re-enter.
 			coordinator.attemptedBlockKeys.add(decision.blockKey);
 			coordinator.lastAttemptAtByAccount.set(decision.accountKey, Date.now());

package/src/session/codex-auto-reset.ts

@@ -24,8 +24,8 @@
  * eligibility off exact limit ids (`openai-codex:primary` /
  * `openai-codex:secondary`) and `usedFraction`, never off `status`.
  *
- * ANTI-WASTE GATES (in evaluation order): the policy must be OFF unless opted
- * in; the active model must be Codex (not Spark — a Spark block lives on a
+ * ANTI-WASTE GATES (in evaluation order): the policy must not be set to "no";
+ * the active model must be Codex (not Spark — a Spark block lives on a
  * separate meter and it is unknown whether a credit even resets it); a fresh
  * usage report for the active account must confirm `limitReached`; the WEEKLY
  * (secondary) window must be genuinely exhausted — a 5h-only block self-heals
@@ -38,12 +38,14 @@
  * read-only views are passed in so the predicate itself stays deterministic.
  */
 import type { OAuthAccountIdentity, ResetCreditTarget, UsageReport } from "@oh-my-pi/pi-ai";
+import type { CodexAutoRedeemMode } from "../config/settings-schema";
 import { reportMatchesActiveAccount } from "../slash-commands/helpers/active-oauth-account";
 
 /** Weekly window counts as exhausted at `usedFraction >= 0.999` (used_percent >= 99.9). */
 export const WEEKLY_EXHAUSTED_MIN_FRACTION = 0.999;
 /** A weekly reset can never be more than one window length (7d) away; +1h slack for skew. */
 export const MAX_PLAUSIBLE_REMAINING_MS = 7 * 24 * 3_600_000 + 60 * 60_000;
+
 /** Report must be no older than the 5-min usage cache TTL plus slack. */
 export const REPORT_FRESHNESS_MS = 10 * 60_000;
 /** Per-account cooldown that catches blockKey drift across a minute boundary. */
@@ -51,6 +53,14 @@ export const ATTEMPT_COOLDOWN_MS = 60_000;
 /** Minute bucket for blockKey, absorbing `reset_after_seconds`-derived jitter. */
 export const DEBOUNCE_BUCKET_MS = 60_000;
 
+export function shouldEvaluateCodexAutoRedeem(mode: CodexAutoRedeemMode): boolean {
+	return mode !== "no";
+}
+
+export function shouldPromptCodexAutoRedeem(mode: CodexAutoRedeemMode): boolean {
+	return mode === "unset";
+}
+
 export type CodexAutoRedeemSkipReason =
 	| "disabled"
 	| "wrong-provider"
@@ -83,16 +93,18 @@ export interface CodexAutoRedeemInput {
 	lastAttemptAtByAccount: ReadonlyMap<string, number>;
 }
 
+export interface CodexAutoRedeemRedeemDecision {
+	redeem: true;
+	target: ResetCreditTarget;
+	accountKey: string;
+	blockKey: string;
+	weeklyResetAtMs: number;
+	remainingMs: number;
+	availableCount: number;
+}
+
 export type CodexAutoRedeemDecision =
-	| {
-			redeem: true;
-			target: ResetCreditTarget;
-			accountKey: string;
-			blockKey: string;
-			weeklyResetAtMs: number;
-			remainingMs: number;
-			availableCount: number;
-	  }
+	| CodexAutoRedeemRedeemDecision
 	| { redeem: false; reason: CodexAutoRedeemSkipReason };
 
 /** Trimmed lowercase, or undefined when blank. Mirrors `normalizeIdentityValue` in active-oauth-account.ts. */

package/src/session/session-manager.ts

@@ -1994,6 +1994,12 @@ export class SessionManager {
 	#byId: Map<string, SessionEntry> = new Map();
 	#labelsById: Map<string, string> = new Map();
 	#leafId: string | null = null;
+	/**
+	 * Collab replication tap: invoked for every appended entry with the
+	 * in-memory (pre-blob-externalization) entry, so inline images survive.
+	 * Failures are swallowed — a broadcast error must never break persistence.
+	 */
+	onEntryAppended?: (entry: SessionEntry) => void;
 	#usageStatistics = {
 		input: 0,
 		output: 0,
@@ -2927,6 +2933,44 @@ export class SessionManager {
 				this.#usageStatistics.cost += usage.cost.total;
 			}
 		}
+		if (this.onEntryAppended) {
+			try {
+				this.onEntryAppended(entry);
+			} catch (err) {
+				logger.warn("collab entry hook failed", { error: String(err) });
+			}
+		}
+	}
+
+	/**
+	 * Append a foreign (host-authored) entry verbatim, preserving its
+	 * `id`/`parentId` — no id minting. Used by collab guests to mirror the
+	 * host session into the local replica file.
+	 */
+	ingestReplicatedEntry(entry: SessionEntry): void {
+		this.#appendEntry(entry);
+	}
+
+	/**
+	 * Snapshot the session for collab replication: the live header plus a deep
+	 * copy of every entry (the host mutates entries in place on
+	 * truncation/rewrite paths, so guests must not share references).
+	 */
+	snapshotForReplication(): { header: SessionHeader; entries: SessionEntry[] } {
+		const live = this.getHeader();
+		const header: SessionHeader = live
+			? structuredClone(live)
+			: {
+					type: "session",
+					version: CURRENT_SESSION_VERSION,
+					id: this.#sessionId,
+					title: this.#sessionName,
+					titleSource: this.#titleSource,
+					timestamp: new Date().toISOString(),
+					cwd: this.cwd,
+				};
+		const entries = structuredClone(this.#fileEntries.filter(e => e.type !== "session")) as SessionEntry[];
+		return { header, entries };
 	}
 
 	/** Append a message as child of current leaf, then advance leaf. Returns entry id.

package/src/session/snapcompact-inline.ts

@@ -123,14 +123,16 @@ function selectSystemPromptImageTarget(
 
 /** Tool-result swap candidate, in context order. */
 export interface InlineToolResultCandidate {
-	/** toolCallId — stable identity for render caching and application. */
+	/** Stable identifier for rendering cache key and applying the swap. */
 	id: string;
-	/** Token count of the joined text blocks (0 when empty or image-carrying). */
+	/** Token count of the joined text blocks (0 for empty or image-carrying). */
 	textTokens: number;
-	/** Frames needed to render the text (0 = empty or below the token floor). */
+	/** Frames needed to render the text (0 = empty, below floor, image-carrying, or error). */
 	frames: number;
 	/** Already carries an image (screenshot etc.) — never re-imaged. */
 	hasImage: boolean;
+	/** Error tool results must stay text-only for provider API validation. */
+	isError?: boolean;
 }
 
 export interface InlineSystemPromptCandidate {
@@ -173,6 +175,7 @@ export function planInlineSwaps(input: InlinePlanInput): InlineSwapPlan {
 		for (let k = 0; k < input.toolResults.length - 1 && budget > 0; k++) {
 			const candidate = input.toolResults[k];
 			if (candidate.hasImage) continue;
+			if (candidate.isError) continue;
 			if (candidate.textTokens < MIN_TOOL_RESULT_TOKENS) continue;
 			if (candidate.frames === 0 || candidate.frames > budget) continue;
 			if (!passesSavingsGate(candidate.frames, input.shape, candidate.textTokens)) continue;
@@ -211,6 +214,7 @@ export interface InlineMessageView {
 	role: string;
 	toolCallId?: string;
 	content?: unknown;
+	isError?: boolean;
 }
 
 export interface SnapcompactSavingsEstimate {
@@ -280,6 +284,7 @@ export function estimateInlineSavings(input: {
 	if (options.renderToolResults) {
 		for (const message of input.messages) {
 			if (message.role !== "toolResult" || typeof message.toolCallId !== "string") continue;
+			if (message.isError) continue;
 			const blocks: BlockViews = Array.isArray(message.content) ? (message.content as BlockViews) : [];
 			const hasImage = blocks.some(block => block.type === "image");
 			const text = hasImage
@@ -418,6 +423,7 @@ export class SnapcompactInlineTransformer {
 				liveToolCallIds.add(message.toolCallId);
 				// Don't re-image results that already carry images (screenshots etc.).
 				const hasImage = message.content.some(block => block.type === "image");
+				if (message.isError) continue;
 				const text = hasImage
 					? ""
 					: message.content