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

package/src/prompts/tools/read.md

@@ -1,84 +1,78 @@
 Read files, directories, archives, SQLite databases, images, documents, internal resources, and web URLs through a single `path` string.
 
 <instruction>
-- One tool for filesystem, archives, SQLite, images, documents (PDF/DOCX/PPTX/XLSX/RTF/EPUB/ipynb), internal URIs, and web URLs (reader-mode by default).
 - You SHOULD parallelize independent reads when exploring related files.
-- You SHOULD reach for `read` — not a browser/puppeteer tool — for fetching web content.
+- You SHOULD reach for `read` — not a browser/puppeteer tool — for web content; browser only when `read` cannot deliver it.
 </instruction>
 
 ## Parameters
 
-- `path` — required. Local path, internal URI (`skill://`, `agent://`, `artifact://`, `history://`, `memory://`, `rule://`, `local://`, `vault://`, `mcp://`, `omp://`, `issue://`, `pr://`), or URL. Append `:<sel>` for line ranges, raw mode, or special modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).
+- `path` — required. Local path, internal URI (`skill://`, `agent://`, `artifact://`, `history://`, `memory://`, `rule://`, `local://`, `vault://`, `mcp://`, `omp://`, `issue://`, `pr://`), or URL. Append `:<sel>` for line ranges or special modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).
 
 ## Selectors
 
-Append `:<sel>` to `path`. The bare path falls back to the default mode.
+Append `:<sel>` to `path`; bare path = default mode.
 
-- _(none)_ — parseable code → structural summary (signatures kept, bodies elided); other files → read from the start (up to {{DEFAULT_LIMIT}} lines).
-- `:50` / `:50-` — read from line 50 onward.
+- _(none)_ — parseable code → structural summary; other files → from start (up to {{DEFAULT_LIMIT}} lines).
+- `:50` / `:50-` — from line 50 onward.
 - `:50-200` — lines 50–200 inclusive.
-- `:50+150` — 150 lines starting at line 50.
-- `:20+1` — anchor on line 20 (single-range reads expand by ≤1 leading and ≤3 trailing context lines).
-- `:5-16,960-973` — multiple ranges in one call (sorted, overlaps merged). Multi-range mode returns exact bounds with no context padding.
-- `:raw` — verbatim text; no anchors, no summary, no line prefixes.
-- `:2-4:raw` or `:raw:2-4` — range AND verbatim; the two compose in either order.
-- `:conflicts` — one-line-per-block index of every unresolved git merge conflict.
+- `:50+150` — 150 lines starting at 50.
+- `:20+1` — anchor line 20 (single-range reads pad ≤1 leading / ≤3 trailing context lines).
+- `:5-16,960-973` — multiple ranges in one call (sorted, overlaps merged); exact bounds, no padding.
+- `:raw` — verbatim; no anchors, no summary, no line prefixes.
+- `:2-4:raw` / `:raw:2-4` — range AND verbatim; compose in either order.
+- `:conflicts` — one line per unresolved git merge conflict block.
 
 # Files
 
-- Reading a directory path returns a depth-limited dirent listing.
+- Directory path → depth-limited dirent listing.
 {{#if IS_HL_MODE}}
-- Reading a file with an explicit selector emits a file snapshot tag header and numbered lines: `[src/foo.ts#1A2B]` then `41:def alpha():`. Copy the `[PATH#TAG]` header for anchored edits; ops use bare line numbers. NEVER fabricate the tag.
+- File with explicit selector → snapshot tag header + numbered lines: `[src/foo.ts#1A2B]` then `41:def alpha():`. Copy the `[PATH#TAG]` header for anchored edits; ops use bare line numbers. NEVER fabricate the tag.
 {{else}}
 {{#if IS_LINE_NUMBER_MODE}}
-- Reading a file with an explicit selector returns lines prefixed with line numbers: `41|def alpha():`.
+- File with explicit selector → lines prefixed with numbers: `41|def alpha():`.
 {{/if}}
 {{/if}}
-- Parseable code without a selector returns a **structural summary**: declarations kept, large bodies collapsed to `..` (merged brace pair) or `…` (standalone). Summarized output ends with a footer demonstrating the multi-range selector you can use to recover the elided bodies, e.g.:
-
-  `[NN lines elided; re-read needed ranges, e.g. <path>:5-16,40-80]`
-
-  Re-issue **only the relevant range(s)** using the multi-range selector (e.g. `<path>:5-16,120-200`). NEVER guess what's inside `..` / `…` — those markers carry no content. NEVER re-read the whole file or use `:raw` when targeted ranges suffice.
+- Parseable code without selector → **structural summary**: declarations kept, bodies collapsed to `..` (merged brace pair) or `…` (standalone). The footer shows the recovery selector: `[NN lines elided; re-read needed ranges, e.g. <path>:5-16,40-80]`. Re-issue ONLY the ranges you need via the multi-range selector. `..`/`…` carry no content — NEVER guess what's inside; NEVER re-read the whole file or `:raw` when ranges suffice.
 
 # Documents & Notebooks
 
-Extracts text from PDF, Word, PowerPoint, Excel, RTF, and EPUB. Notebooks (`.ipynb`) are shown as editable `# %% [type] cell:N` text; edits round-trip back to the underlying JSON preserving notebook metadata. Add `:raw` to a notebook to bypass the converter and read the JSON directly.
+PDF, Word, PowerPoint, Excel, RTF, EPUB → extracted text. Notebooks (`.ipynb`) → editable `# %% [type] cell:N` text; edits round-trip to the underlying JSON preserving metadata. `:raw` bypasses the converter.
 
 # Images
 
 {{#if INSPECT_IMAGE_ENABLED}}
-Reading an image path returns metadata (mime, bytes, dimensions, channels, alpha). For actual visual analysis, call `inspect_image` with the path and a question describing what to inspect.
+Image path → metadata (mime, bytes, dimensions, channels, alpha). For visual analysis, call `inspect_image` with the path and a question.
 {{else}}
-Reading an image path returns the decoded image inline (PNG, JPEG, GIF, WEBP) for direct visual analysis.
+Image path → decoded image inline (PNG, JPEG, GIF, WEBP) for direct visual analysis.
 {{/if}}
 
 # Archives
 
-Supports `.tar`, `.tar.gz`, `.tgz`, `.zip`. Use `archive.ext:path/inside/archive` to read a member, and append a normal selector to the inner path: `archive.zip:dir/file.ts:50-60`.
+`.tar`, `.tar.gz`, `.tgz`, `.zip`. `archive.ext:path/inside/archive` reads a member; inner paths take normal selectors: `archive.zip:dir/file.ts:50-60`.
 
 # SQLite
 
 For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
-- `file.db` — list tables with row counts
+- `file.db` — tables with row counts
 - `file.db:table` — schema + sample rows
-- `file.db:table:key` — single row by primary key
-- `file.db:table?limit=50&offset=100` — paginated rows
-- `file.db:table?where=status='active'&order=created:desc` — filtered rows
-- `file.db?q=SELECT …` — read-only SELECT query
+- `file.db:table:key` — row by primary key
+- `file.db:table?limit=50&offset=100` — pagination
+- `file.db:table?where=status='active'&order=created:desc` — filter/order
+- `file.db?q=SELECT …` — read-only SELECT
 
 # URLs
 
-- Default reader-mode: HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs → clean text/markdown.
-- `:raw` returns untouched HTML; line selectors (`:50`, `:50-100`, `:50+150`) paginate the cached fetched output.
-- Bare `host:port` URLs collide with the selector grammar — add a trailing slash before the selector: `https://example.com/:80`.
+- Reader-mode by default: HTML, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs → clean text/markdown.
+- `:raw` → untouched HTML; line selectors (`:50`, `:50-100`, `:50+150`) paginate the cached fetch.
+- Bare `host:port` collides with the selector grammar — add a trailing slash: `https://example.com/:80`.
 
 # Internal URIs
 
-`skill://<name>`, `agent://<id>`, `artifact://<id>`, `history://<agentId>`, `memory://root`, `rule://<name>`, `local://<name>.md`, `vault://<vault>/<path>`, `mcp://<uri>`, `omp://<doc>.md`, `issue://<N>`, and `pr://<N>` resolve transparently and accept the same line selectors as filesystem paths. Use `artifact://<id>` to recover full output that a previous bash/eval/tool result spilled or truncated. `history://<agentId>` is an agent's transcript as concise markdown; bare `history://` lists agents.
+All `path` URI schemes resolve transparently and take the same line selectors. `artifact://<id>` recovers full output a previous bash/eval/tool result spilled or truncated. `history://<agentId>` is an agent's transcript as concise markdown; bare `history://` lists agents.
 
 <critical>
-- You MUST use `read` for every file, directory, archive, and URL inspection. `cat`, `head`, `tail`, `less`, `more`, `ls`, `tar`, `unzip`, `curl`, `wget` are FORBIDDEN — any such bash call is a bug, regardless of how short or convenient it looks.
-- You MUST prefer `read` over a browser/puppeteer tool for URL content; only reach for a browser when `read` cannot deliver reasonable content.
-- For line ranges, append the selector to `path` (`path="src/foo.ts:50-200"`, `path="src/foo.ts:50+150"`). NEVER substitute `sed -n`, `awk NR`, or `head`/`tail` pipelines.
-- Summary footer names ranges to re-read? Re-issue ONLY the ranges you need via the multi-range selector. NEVER guess what's inside `..` / `…` markers — they carry no content.
+- You MUST use `read` for every file, directory, archive, and URL inspection. `cat`, `head`, `tail`, `less`, `more`, `ls`, `tar`, `unzip`, `curl`, `wget` are FORBIDDEN bash calls, however short or convenient.
+- Line ranges go in the selector (`path="src/foo.ts:50-200"`) — NEVER `sed -n`, `awk NR`, or `head`/`tail` pipelines.
+- Summary footer names elided ranges? Re-issue ONLY those ranges. NEVER guess `..`/`…` content.
 </critical>

package/src/prompts/tools/todo.md

@@ -2,7 +2,7 @@
 
 Manages a phased task list. Pass `ops`: a flat array of operations.
 The next pending task is auto-promoted to `in_progress` after each completion.
-Allowed `op` values are only `init`, `start`, `done`, `drop`, `rm`, `append`, `note`, and `view`. `pending` is a task status, not an `op`; leave not-yet-started tasks implicit in `init`/`append` lists.
+Allowed `op` values are only `init`, `start`, `done`, `drop`, `rm`, `append`, and `view`. `pending` is a task status, not an `op`; leave not-yet-started tasks implicit in `init`/`append` lists.
 
 ## Operations
 
@@ -14,7 +14,6 @@ Allowed `op` values are only `init`, `start`, `done`, `drop`, `rm`, `append`, `n
 |`drop`|`task` or `phase`|Mark abandoned|
 |`rm`|`task` or `phase` (optional)|Remove task or phase's tasks; omit both to clear the entire list|
 |`append`|`phase`, `items: string[]`|Append tasks to `phase`; lazily creates phase|
-|`note`|`task`, `text`|Append a note to a task. Reminders for future-you only.|
 |`view`|—|Read-only: echo the current list without modifying it|
 
 ## Anatomy

package/src/sdk.ts

@@ -2162,10 +2162,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// Per-request provider-context transforms. Obfuscate FIRST so secrets are
 		// redacted from text before snapcompact rasterizes it into PNG frames.
 		// Both operate on the transient outgoing Context only — never persisted.
+		const snapcompactSystemPromptMode = settings.get("snapcompact.systemPrompt");
 		const snapcompactInline =
-			settings.get("snapcompact.systemPrompt") || settings.get("snapcompact.toolResults")
+			snapcompactSystemPromptMode !== "none" || settings.get("snapcompact.toolResults")
 				? new SnapcompactInlineTransformer({
-						renderSystemPrompt: settings.get("snapcompact.systemPrompt"),
+						renderSystemPrompt: snapcompactSystemPromptMode,
 						renderToolResults: settings.get("snapcompact.toolResults"),
 					})
 				: undefined;

package/src/session/agent-session.ts

@@ -73,6 +73,9 @@ import type {
 	Model,
 	ProviderResponseMetadata,
 	ProviderSessionState,
+	ResetCreditAccountStatus,
+	ResetCreditRedeemOutcome,
+	ResetCreditTarget,
 	ServiceTier,
 	SimpleStreamOptions,
 	TextContent,
@@ -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,
@@ -5399,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 })),
 		}));
 	}
 
@@ -8354,7 +8354,8 @@ export class AgentSession {
 
 		return (
 			/\bItem with id ['"][^'"]+['"] not found\.?/i.test(errorMessage) ||
-			(/previous[ _]?response/i.test(errorMessage) && /not[ _]?found|invalid|expired|stale/i.test(errorMessage))
+			(/previous[ _]?response/i.test(errorMessage) &&
+				/not[ _]?found|invalid|expired|stale|zero[ _-]?data[ _-]?retention/i.test(errorMessage))
 		);
 	}
 
@@ -8720,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
@@ -10137,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

@@ -14,6 +14,9 @@ export type {
 	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(),
+};