@oh-my-pi/pi-coding-agent 15.11.3 → 15.11.6

package/src/session/agent-session.ts

@@ -73,6 +73,9 @@ import type {
 	Model,
 	ProviderResponseMetadata,
 	ProviderSessionState,
+	ResetCreditAccountStatus,
+	ResetCreditRedeemOutcome,
+	ResetCreditTarget,
 	ServiceTier,
 	SimpleStreamOptions,
 	TextContent,
@@ -107,7 +110,7 @@ import {
 	relativePathWithinRoot,
 	Snowflake,
 } from "@oh-my-pi/pi-utils";
-import { snapcompactCompact } from "@oh-my-pi/snapcompact";
+import * as snapcompact from "@oh-my-pi/snapcompact";
 import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager } from "../async";
 import { classifyDifficulty } from "../auto-thinking/classifier";
 import { reset as resetCapabilities } from "../capability";
@@ -237,6 +240,7 @@ 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 BashExecutionMessage,
 	type CustomMessage,
@@ -855,8 +859,13 @@ function extractPermissionLocations(
  *  `tag` is set only by `enqueueCustomMessageDisplay` (used for skill-prompt
  *  custom messages queued during streaming) and is matched by the custom-role
  *  `message_start` dequeue branch; user-message pushes leave it undefined and
- *  rely on the existing text-equality match. */
-type QueuedDisplayEntry = { text: string; tag?: string };
+ *  rely on the existing text-equality match. `images` carries the original
+ *  (pre-normalization) image blocks so queue restoration (Esc / Alt+Up) can
+ *  hand them back to the editor instead of dropping them. */
+type QueuedDisplayEntry = { text: string; tag?: string; images?: ImageContent[] };
+
+/** Entry returned by {@link AgentSession.clearQueue} / {@link AgentSession.popLastQueuedMessage}. */
+export type RestoredQueuedMessage = { text: string; images?: ImageContent[] };
 
 export class AgentSession {
 	readonly agent: Agent;
@@ -5028,7 +5037,7 @@ export class AgentSession {
 	async #queueSteer(text: string, images?: ImageContent[]): Promise<void> {
 		const normalizedImages = await normalizeModelContextImages(images);
 		const displayText = text || (images && images.length > 0 ? "[Image]" : "");
-		this.#steeringMessages.push({ text: displayText });
+		this.#steeringMessages.push({ text: displayText, images });
 		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
 		if (normalizedImages && normalizedImages.length > 0) {
 			content.push(...normalizedImages);
@@ -5040,6 +5049,16 @@ export class AgentSession {
 			attribution: "user",
 			timestamp: Date.now(),
 		});
+		// A steer can land on an idle session: the caller checked isStreaming
+		// before the (potentially slow) image normalization above, so the turn
+		// may have ended in between. Without a drain the message would strand in
+		// the queue until the next manual prompt — schedule an immediate continue,
+		// mirroring #queueFollowUp's idle-path delivery.
+		if (this.#canAutoContinueForFollowUp()) {
+			this.#scheduleAgentContinue({
+				shouldContinue: () => this.#canAutoContinueForFollowUp() && this.agent.hasQueuedMessages(),
+			});
+		}
 	}
 
 	/**
@@ -5048,7 +5067,7 @@ export class AgentSession {
 	async #queueFollowUp(text: string, images?: ImageContent[]): Promise<void> {
 		const normalizedImages = await normalizeModelContextImages(images);
 		const displayText = text || (images && images.length > 0 ? "[Image]" : "");
-		this.#followUpMessages.push({ text: displayText });
+		this.#followUpMessages.push({ text: displayText, images });
 		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
 		if (normalizedImages && normalizedImages.length > 0) {
 			content.push(...normalizedImages);
@@ -5297,12 +5316,14 @@ export class AgentSession {
 	}
 
 	/**
-	 * Clear queued messages and return them.
-	 * Useful for restoring to editor when user aborts.
+	 * Clear queued messages and return them (text plus any attached images).
+	 * Useful for restoring to editor when user aborts. The internal entry
+	 * arrays are handed out as-is — a `tag` (if any) is inert once the record
+	 * leaves the queue.
 	 */
-	clearQueue(): { steering: string[]; followUp: string[] } {
-		const steering = this.#steeringMessages.map(e => e.text);
-		const followUp = this.#followUpMessages.map(e => e.text);
+	clearQueue(): { steering: RestoredQueuedMessage[]; followUp: RestoredQueuedMessage[] } {
+		const steering = this.#steeringMessages;
+		const followUp = this.#followUpMessages;
 		this.#steeringMessages = [];
 		this.#followUpMessages = [];
 		this.agent.clearAllQueues();
@@ -5328,21 +5349,21 @@ export class AgentSession {
 	/**
 	 * Pop the last queued message (steering first, then follow-up).
 	 * Used by dequeue keybinding to restore messages to editor one at a time.
-	 * Returns the popped entry's `.text`; the tag (if any) dies with the
-	 * record — no orphan state can outlive the queue entry.
+	 * Returns the popped entry's text and images; the tag (if any) dies with
+	 * the record — no orphan state can outlive the queue entry.
 	 */
-	popLastQueuedMessage(): string | undefined {
+	popLastQueuedMessage(): RestoredQueuedMessage | undefined {
 		// Pop from steering first (LIFO)
 		if (this.#steeringMessages.length > 0) {
 			const entry = this.#steeringMessages.pop();
 			this.agent.popLastSteer();
-			return entry?.text;
+			return entry;
 		}
 		// Then from follow-up
 		if (this.#followUpMessages.length > 0) {
 			const entry = this.#followUpMessages.pop();
 			this.agent.popLastFollowUp();
-			return entry?.text;
+			return entry;
 		}
 		return undefined;
 	}
@@ -5382,11 +5403,7 @@ export class AgentSession {
 	#cloneTodoPhases(phases: TodoPhase[]): TodoPhase[] {
 		return phases.map(phase => ({
 			name: phase.name,
-			tasks: phase.tasks.map(task => {
-				const out: TodoItem = { content: task.content, status: task.status };
-				if (task.notes && task.notes.length > 0) out.notes = [...task.notes];
-				return out;
-			}),
+			tasks: phase.tasks.map(task => ({ content: task.content, status: task.status })),
 		}));
 	}
 
@@ -6368,7 +6385,10 @@ export class AgentSession {
 				details = compactionPrep.details;
 				preserveData = compactionPrep.preserveData;
 			} else if (snapcompactReady) {
-				const snapcompactResult = await snapcompactCompact(preparation, { convertToLlm, model: this.model });
+				const snapcompactResult = await snapcompact.compact(preparation, {
+					convertToLlm,
+					model: this.model,
+				});
 				summary = snapcompactResult.summary;
 				shortSummary = snapcompactResult.shortSummary;
 				firstKeptEntryId = snapcompactResult.firstKeptEntryId;
@@ -6582,7 +6602,7 @@ export class AgentSession {
 			const rawHandoffText = await generateHandoff(
 				this.agent.state.messages,
 				model,
-				apiKey,
+				this.#modelRegistry.resolver(model, this.sessionId),
 				{
 					systemPrompt: this.#obfuscateForProvider(this.#baseSystemPrompt),
 					tools: obfuscateProviderTools(this.#obfuscator, this.agent.state.tools),
@@ -7252,6 +7272,22 @@ export class AgentSession {
 		this.#closeProviderSessionsForModelSwitch(currentModel, currentModel);
 	}
 
+	#resetCurrentResponsesProviderSession(reason: string): void {
+		const currentModel = this.model;
+		if (currentModel?.api !== "openai-responses" && currentModel?.api !== "openai-codex-responses") {
+			return;
+		}
+
+		this.#closeProviderSessionsForModelSwitch(currentModel, currentModel);
+		this.agent.appendOnlyContext?.invalidateForModelChange();
+		logger.debug("Reset Responses provider session after stale replay error", {
+			provider: currentModel.provider,
+			model: currentModel.id,
+			api: currentModel.api,
+			reason,
+		});
+	}
+
 	/**
 	 * Re-evaluate append-only context mode, creating or destroying the
 	 * manager as needed. Called on model switch AND setting change.
@@ -7577,7 +7613,7 @@ export class AgentSession {
 				return await compact(
 					this.#obfuscatePreparationForProvider(preparation),
 					candidate,
-					apiKey,
+					this.#modelRegistry.resolver(candidate, this.sessionId),
 					this.#obfuscateTextForProvider(customInstructions),
 					signal,
 					{
@@ -7882,7 +7918,10 @@ export class AgentSession {
 			} else if (action === "snapcompact") {
 				// Local, deterministic: render discarded history onto PNG frames.
 				// No model candidates, no API key, no retry loop.
-				const snapcompactResult = await snapcompactCompact(preparation, { convertToLlm, model: this.model });
+				const snapcompactResult = await snapcompact.compact(preparation, {
+					convertToLlm,
+					model: this.model,
+				});
 				summary = snapcompactResult.summary;
 				shortSummary = snapcompactResult.shortSummary;
 				firstKeptEntryId = snapcompactResult.firstKeptEntryId;
@@ -7906,7 +7945,7 @@ export class AgentSession {
 							compactResult = await compact(
 								this.#obfuscatePreparationForProvider(preparation),
 								candidate,
-								apiKey,
+								this.#modelRegistry.resolver(candidate, this.sessionId),
 								undefined,
 								autoCompactionSignal,
 								{
@@ -8293,11 +8332,33 @@ export class AgentSession {
 		if (isContextOverflow(message, contextWindow)) return false;
 
 		if (this.#isClassifierRefusal(message)) return true;
+		if (this.#isStaleOpenAIResponsesReplayError(message)) return true;
 
 		const err = message.errorMessage;
 		return this.#isTransientErrorMessage(err) || isUsageLimitError(err);
 	}
 
+	#isStaleOpenAIResponsesReplayError(message: AssistantMessage): boolean {
+		const currentApi = this.model?.api;
+		if (
+			message.api !== "openai-responses" &&
+			message.api !== "openai-codex-responses" &&
+			currentApi !== "openai-responses" &&
+			currentApi !== "openai-codex-responses"
+		) {
+			return false;
+		}
+
+		const errorMessage = message.errorMessage;
+		if (!errorMessage) return false;
+
+		return (
+			/\bItem with id ['"][^'"]+['"] not found\.?/i.test(errorMessage) ||
+			(/previous[ _]?response/i.test(errorMessage) &&
+				/not[ _]?found|invalid|expired|stale|zero[ _-]?data[ _-]?retention/i.test(errorMessage))
+		);
+	}
+
 	#isClassifierRefusal(message: AssistantMessage): boolean {
 		if (message.stopReason !== "error") return false;
 		const stopType = message.stopDetails?.type;
@@ -8631,15 +8692,22 @@ export class AgentSession {
 		}
 
 		const errorMessage = message.errorMessage || "Unknown error";
+		const staleOpenAIResponsesReplayError = this.#isStaleOpenAIResponsesReplayError(message);
 		const parsedRetryAfterMs = this.#parseRetryAfterMsFromError(errorMessage);
-		let delayMs = calculateRetryBackoffDelayMs(retrySettings.baseDelayMs, this.#retryAttempt);
+		let delayMs = staleOpenAIResponsesReplayError
+			? 0
+			: calculateRetryBackoffDelayMs(retrySettings.baseDelayMs, this.#retryAttempt);
 		let switchedCredential = false;
 		let switchedModel = false;
 		// Set when a usage-limit error pinned the wait to credential
 		// availability — suppresses the generic retry-after bump below.
 		let usageLimitWaitMs: number | undefined;
 
-		if (this.model && isUsageLimitError(errorMessage)) {
+		if (staleOpenAIResponsesReplayError) {
+			this.#resetCurrentResponsesProviderSession("stale replay error");
+		}
+
+		if (this.model && !staleOpenAIResponsesReplayError && isUsageLimitError(errorMessage)) {
 			const retryAfterMs = parsedRetryAfterMs ?? calculateRateLimitBackoffMs(parseRateLimitReason(errorMessage));
 			const outcome = await this.#modelRegistry.authStorage.markUsageLimitReached(
 				this.model.provider,
@@ -8653,6 +8721,13 @@ export class AgentSession {
 			if (outcome.switched) {
 				switchedCredential = true;
 				delayMs = 0;
+			} else if (await this.#maybeAutoRedeemCodexReset()) {
+				// A live usage-limit 429 on the active Codex account, with a banked
+				// reset and the opt-in setting on: spend the reset and retry
+				// immediately instead of waiting out the window. Runs after the
+				// free sibling-switch above and before model fallback below.
+				switchedCredential = true;
+				delayMs = 0;
 			} else {
 				// No sibling credential is usable right now. Wait for whichever
 				// comes first: the provider's retry-after window for the current
@@ -8676,7 +8751,7 @@ export class AgentSession {
 		}
 
 		const currentSelector = this.model ? formatRetryFallbackSelector(this.model, this.thinkingLevel) : undefined;
-		if (!switchedCredential && currentSelector) {
+		if (!staleOpenAIResponsesReplayError && !switchedCredential && currentSelector) {
 			if (retrySettings.modelFallback) {
 				if (!classifierRefusal) {
 					this.#noteRetryFallbackCooldown(currentSelector, parsedRetryAfterMs, errorMessage);
@@ -9813,7 +9888,7 @@ export class AgentSession {
 			const branchSummarySettings = this.settings.getGroup("branchSummary");
 			const result = await generateBranchSummary(entriesToSummarize, {
 				model,
-				apiKey,
+				apiKey: this.#modelRegistry.resolver(model, this.sessionId),
 				signal: this.#branchSummaryAbortController.signal,
 				customInstructions: this.#obfuscateTextForProvider(options.customInstructions),
 				reserveTokens: branchSummarySettings.reserveTokens,
@@ -10070,6 +10145,123 @@ export class AgentSession {
 		});
 	}
 
+	/**
+	 * Redeem one saved Codex rate-limit reset for a specific account, injecting
+	 * the provider base URL like {@link AgentSession.fetchUsageReports}. Powers
+	 * the `/usage reset` command and auto-redeem. Never throws for business
+	 * outcomes — inspect the returned `code`.
+	 */
+	async redeemResetCredit(target: ResetCreditTarget, signal?: AbortSignal): Promise<ResetCreditRedeemOutcome> {
+		return this.#modelRegistry.authStorage.redeemResetCredit({
+			target,
+			baseUrlResolver: provider => this.#modelRegistry.getProviderBaseUrl?.(provider),
+			signal,
+		});
+	}
+
+	/**
+	 * List saved Codex rate-limit resets per stored account, fetched live from
+	 * the dedicated credits endpoint (bypasses the usage cache). Powers the
+	 * `/usage reset` account selector.
+	 */
+	async listResetCredits(signal?: AbortSignal): Promise<ResetCreditAccountStatus[]> {
+		return this.#modelRegistry.authStorage.listResetCredits({
+			sessionId: this.sessionId,
+			baseUrlResolver: provider => this.#modelRegistry.getProviderBaseUrl?.(provider),
+			signal,
+		});
+	}
+
+	/**
+	 * 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.
+	 */
+	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;
+		const authStorage = this.#modelRegistry.authStorage;
+		// Capture identity BEFORE awaits: markUsageLimitReached leaves the
+		// usage-limit session credential sticky, so this names the blocked account.
+		const identity = authStorage.getOAuthAccountIdentity("openai-codex", this.sessionId);
+		const accountKey = (identity?.accountId ?? identity?.email)?.trim().toLowerCase();
+		if (!accountKey) return false;
+		const existing = coordinator.inFlightByAccount.get(accountKey);
+		if (existing) return existing;
+
+		const run = (async (): Promise<boolean> => {
+			const reports = await this.fetchUsageReports();
+			const decision = evaluateCodexAutoRedeem({
+				nowMs: Date.now(),
+				provider: model.provider,
+				modelId: model.id,
+				settings: {
+					autoRedeem: cfg.autoRedeem,
+					minBlockedMinutes: Math.max(0, cfg.minBlockedMinutes),
+					keepCredits: Math.max(0, Math.trunc(cfg.keepCredits)),
+				},
+				identity,
+				reports,
+				attemptedBlockKeys: coordinator.attemptedBlockKeys,
+				lastAttemptAtByAccount: coordinator.lastAttemptAtByAccount,
+			});
+			if (!decision.redeem) {
+				logger.debug("codex-auto-reset: skipped", { reason: decision.reason });
+				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());
+			const who = decision.target.email ?? decision.target.accountId ?? "the active account";
+			const outcome = await authStorage.redeemResetCredit({
+				target: decision.target,
+				baseUrlResolver: provider => this.#modelRegistry.getProviderBaseUrl?.(provider),
+				// Not tied to the retry abort controller: aborting a consume
+				// mid-flight leaves credit state unknown.
+				signal: AbortSignal.timeout(15_000),
+			});
+			switch (outcome.code) {
+				case "reset": {
+					const left = Math.max(0, decision.availableCount - 1);
+					this.emitNotice(
+						"info",
+						`Auto-redeemed a saved Codex rate-limit reset for ${who} (${left} left); retrying now.`,
+						"codex-auto-reset",
+					);
+					void this.fetchUsageReports();
+					return true;
+				}
+				case "already_redeemed":
+					this.emitNotice(
+						"warning",
+						"A saved Codex reset was already redeemed elsewhere; waiting for the window.",
+						"codex-auto-reset",
+					);
+					return false;
+				case "no_credit":
+					logger.debug("codex-auto-reset: no_credit (snapshot/live mismatch)", { account: accountKey });
+					return false;
+				case "nothing_to_reset":
+					this.emitNotice(
+						"warning",
+						"Codex reset reported nothing to reset; auto-redeem suppressed for this window.",
+						"codex-auto-reset",
+					);
+					return false;
+				default:
+					this.emitNotice("warning", `Codex auto-redeem failed (${outcome.code}).`, "codex-auto-reset");
+					return false;
+			}
+		})().finally(() => coordinator.inFlightByAccount.delete(accountKey));
+		coordinator.inFlightByAccount.set(accountKey, run);
+		return run;
+	}
+
 	/**
 	 * Estimate context tokens from messages, using the last assistant usage when available.
 	 */

package/src/session/auth-storage.ts

@@ -12,7 +12,11 @@ export type {
 	AuthStorageOptions,
 	CredentialOrigin,
 	CredentialOriginKind,
+	OAuthAccountIdentity,
 	OAuthCredential,
+	ResetCreditAccountStatus,
+	ResetCreditRedeemOutcome,
+	ResetCreditTarget,
 	SerializedAuthStorage,
 	SnapshotResponse,
 	StoredAuthCredential,

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

@@ -0,0 +1,190 @@
+/**
+ * Pure decision predicate for auto-redeeming a saved OpenAI Codex rate-limit
+ * reset, plus the process-wide coordinator that serializes attempts.
+ *
+ * WHY THIS IS REACTIVE-ONLY (never proactive):
+ * The only trustworthy "blocked right now" signal is a live 429 /
+ * `usage_limit_reached` from a request authenticated as the session's active
+ * Codex credential. The session hook calls this predicate from the usage-limit
+ * branch of the retry pipeline, *after* free remedies (sibling-account switch)
+ * fail and *before* model fallback. A proactive surface (the status-line usage
+ * poll) cannot be used: at `used_percent < 100` the account is not actually
+ * limited, so redeeming would be a credit-wasting no-op; at exactly 100 the
+ * user may be idle, so the freshly-reset weekly window would tick away with
+ * nobody working. Saved resets are a scarce, ~monthly, effectively
+ * irreversible resource — every gate here is biased to precision over recall:
+ * we would rather miss a redeem than waste a credit.
+ *
+ * THE DECISION-2 TRAP (status MUST NOT be used to find the blocker):
+ * `openai-codex.ts` applies the top-level `rate_limit.limit_reached` flag to
+ * BOTH the primary (5h) and secondary (weekly) `buildUsageLimit` calls, so when
+ * an account is blocked, *both* limit entries carry `status: "exhausted"`
+ * regardless of which window is actually at 100%. Only `amount.usedFraction`
+ * disambiguates which window is the real blocker. This module therefore keys
+ * 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
+ * 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
+ * within the hour, so a credit spent there buys nothing; the natural reset must be far
+ * enough away to justify spending a ~30-day credit yet within one plausible
+ * window length; a credit must be verifiably available above the reserve; and
+ * the same block episode must not have been attempted already (debounce +
+ * per-account cooldown). All of this is pure — no fetches, no IO. The only
+ * stateful piece is the {@link CodexAutoRedeemCoordinator} container, whose
+ * read-only views are passed in so the predicate itself stays deterministic.
+ */
+import type { OAuthAccountIdentity, ResetCreditTarget, UsageReport } from "@oh-my-pi/pi-ai";
+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. */
+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 type CodexAutoRedeemSkipReason =
+	| "disabled"
+	| "wrong-provider"
+	| "spark-model"
+	| "no-identity"
+	| "no-report"
+	| "stale-report"
+	| "not-limit-reached"
+	| "weekly-not-exhausted"
+	| "no-reset-time"
+	| "reset-too-soon"
+	| "reset-implausible"
+	| "credits-unknown"
+	| "reserve"
+	| "already-attempted"
+	| "cooldown";
+
+export interface CodexAutoRedeemInput {
+	nowMs: number;
+	/** `this.model.provider`. */
+	provider: string;
+	/** `this.model.id`. */
+	modelId: string;
+	settings: { autoRedeem: boolean; minBlockedMinutes: number; keepCredits: number };
+	/** `getOAuthAccountIdentity("openai-codex", sessionId)`, captured at hook entry before any await. */
+	identity: OAuthAccountIdentity | undefined;
+	/** `session.fetchUsageReports()` (≤5-min cache). */
+	reports: UsageReport[] | null;
+	attemptedBlockKeys: ReadonlySet<string>;
+	lastAttemptAtByAccount: ReadonlyMap<string, number>;
+}
+
+export type CodexAutoRedeemDecision =
+	| {
+			redeem: true;
+			target: ResetCreditTarget;
+			accountKey: string;
+			blockKey: string;
+			weeklyResetAtMs: number;
+			remainingMs: number;
+			availableCount: number;
+	  }
+	| { redeem: false; reason: CodexAutoRedeemSkipReason };
+
+/** Trimmed lowercase, or undefined when blank. Mirrors `normalizeIdentityValue` in active-oauth-account.ts. */
+function normalize(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim().toLowerCase() : undefined;
+}
+
+/**
+ * Decide whether to auto-redeem a saved Codex reset for the active account.
+ *
+ * Pure: every gate below is a function of the snapshot inputs only. Order
+ * matters — cheapest / most-decisive gates first so the common "not eligible"
+ * paths short-circuit before any account/report matching.
+ */
+export function evaluateCodexAutoRedeem(input: CodexAutoRedeemInput): CodexAutoRedeemDecision {
+	const { nowMs, settings } = input;
+	if (!settings.autoRedeem) return { redeem: false, reason: "disabled" };
+	if (input.provider !== "openai-codex") return { redeem: false, reason: "wrong-provider" };
+	// Unknown #1: it is unknown whether a credit resets the separate Spark meter.
+	if (input.modelId.includes("-spark")) return { redeem: false, reason: "spark-model" };
+
+	const accountKey = normalize(input.identity?.accountId) ?? normalize(input.identity?.email);
+	if (!accountKey) return { redeem: false, reason: "no-identity" };
+
+	const report = input.reports?.find(
+		r => r.provider === "openai-codex" && reportMatchesActiveAccount(r, input.identity),
+	);
+	if (!report) return { redeem: false, reason: "no-report" };
+	if (nowMs - report.fetchedAt > REPORT_FRESHNESS_MS) return { redeem: false, reason: "stale-report" };
+	// The wire's own blocked flag must confirm the 429.
+	if (report.metadata?.limitReached !== true) return { redeem: false, reason: "not-limit-reached" };
+
+	// EXACT ids — never `status` (see the Decision-2 trap in the module docs).
+	// The saved reset applies to the WEEKLY window, so that is the blocker we act
+	// on. A 5h-only block (weekly still has headroom) self-heals within the hour,
+	// so spending a scarce ~monthly credit there would be wasted.
+	const weekly = report.limits.find(l => l.id === "openai-codex:secondary");
+	const wUsed = weekly?.amount.usedFraction;
+	if (!weekly || wUsed === undefined || wUsed < WEEKLY_EXHAUSTED_MIN_FRACTION) {
+		return { redeem: false, reason: "weekly-not-exhausted" };
+	}
+
+	const resetsAt = weekly.window?.resetsAt;
+	if (resetsAt === undefined) return { redeem: false, reason: "no-reset-time" };
+	const remainingMs = resetsAt - nowMs;
+	// anti-waste: too close to the natural reset — let it roll over instead of spending a credit.
+	if (remainingMs < settings.minBlockedMinutes * 60_000) return { redeem: false, reason: "reset-too-soon" };
+	if (remainingMs > MAX_PLAUSIBLE_REMAINING_MS) return { redeem: false, reason: "reset-implausible" };
+
+	const available = report.resetCredits?.availableCount;
+	// can't verify availability from the snapshot → don't spend (precision over recall).
+	if (available === undefined) return { redeem: false, reason: "credits-unknown" };
+	if (available - Math.max(0, Math.trunc(settings.keepCredits)) < 1) {
+		return { redeem: false, reason: "reserve" };
+	}
+
+	const blockKey = `${accountKey}|${Math.round(resetsAt / DEBOUNCE_BUCKET_MS)}`;
+	if (input.attemptedBlockKeys.has(blockKey)) return { redeem: false, reason: "already-attempted" };
+	const lastAt = input.lastAttemptAtByAccount.get(accountKey);
+	if (lastAt !== undefined && nowMs - lastAt < ATTEMPT_COOLDOWN_MS) return { redeem: false, reason: "cooldown" };
+
+	return {
+		redeem: true,
+		target: { accountId: input.identity?.accountId, email: input.identity?.email },
+		accountKey,
+		blockKey,
+		weeklyResetAtMs: resetsAt,
+		remainingMs,
+		availableCount: available,
+	};
+}
+
+/**
+ * Process-wide (NOT per-session) coordinator state. Parallel subagent sessions
+ * share the same Codex accounts and must not race a double-spend, so this is a
+ * single shared container, not a per-session field.
+ *
+ * - `attemptedBlockKeys`: one attempt EVER per block episode, regardless of
+ *   outcome — recorded before calling the consume so exceptions can't re-enter.
+ * - `lastAttemptAtByAccount`: per-account cooldown timestamps (epoch ms),
+ *   catching blockKey drift across a minute boundary.
+ * - `inFlightByAccount`: serializes per account — a second session for the same
+ *   account adopts the in-flight promise instead of starting a second consume.
+ */
+export interface CodexAutoRedeemCoordinator {
+	attemptedBlockKeys: Set<string>;
+	lastAttemptAtByAccount: Map<string, number>;
+	inFlightByAccount: Map<string, Promise<boolean>>;
+}
+
+export const defaultCodexAutoRedeemCoordinator: CodexAutoRedeemCoordinator = {
+	attemptedBlockKeys: new Set(),
+	lastAttemptAtByAccount: new Map(),
+	inFlightByAccount: new Map(),
+};

package/src/session/session-dump-format.ts

@@ -4,6 +4,7 @@
 import type { AgentMessage, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import { INTENT_FIELD } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, Model } from "@oh-my-pi/pi-ai";
+import { isZodSchema, zodToWireSchema } from "@oh-my-pi/pi-ai/utils/schema";
 import {
 	type BashExecutionMessage,
 	type BranchSummaryMessage,
@@ -47,6 +48,12 @@ function stripTypeBoxFields(obj: unknown): unknown {
 	return obj;
 }
 
+/** Resolve tool parameters to a plain JSON Schema object for dump output. */
+function toolParametersToJsonSchema(parameters: unknown): unknown {
+	if (isZodSchema(parameters)) return zodToWireSchema(parameters);
+	return stripTypeBoxFields(parameters);
+}
+
 /** Serialize an object as XML parameter elements, one per key. */
 function formatArgsAsXml(args: Record<string, unknown>, indent = "\t"): string {
 	const parts: string[] = [];
@@ -89,7 +96,7 @@ export function formatSessionDumpText(options: FormatSessionDumpTextOptions): st
 		for (const tool of tools) {
 			lines.push(`<tool name="${tool.name}">`);
 			lines.push(tool.description);
-			const parametersClean = stripTypeBoxFields(tool.parameters);
+			const parametersClean = toolParametersToJsonSchema(tool.parameters);
 			lines.push(`\nParameters:\n${formatArgsAsXml(parametersClean as Record<string, unknown>)}`);
 			lines.push("<" + "/tool>\n");
 		}