@kr78/pi-coding-agent 17.2.10

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

@@ -0,0 +1,673 @@
+/**
+ * Pool-wide planner for spending saved OpenAI Codex rate-limit resets, plus
+ * the process-wide coordinator that serializes attempts.
+ *
+ * A saved reset is a scarce, ~monthly credit — but it is also perishable:
+ * every credit carries an `expiresAt`, and an expired credit is worth exactly
+ * nothing. The planner therefore balances two failure modes instead of only
+ * one: wasting a credit on a window that would have healed anyway, and letting
+ * a credit die unspent. Two rules, evaluated over EVERY stored Codex account
+ * (not just the session's active one):
+ *
+ * - `expiring-credit` (salvage; any trigger): the account's soonest available
+ *   credit expires within `salvageHorizonMs` and the weekly window is at least
+ *   {@link SALVAGE_MIN_USED_FRACTION} used, so redeeming restores real quota.
+ *   The `keepCredits` reserve is deliberately ignored here — reserving a
+ *   credit that is about to expire preserves nothing. If the window resets
+ *   naturally before the credit expires, the next sweep sees a mostly-free
+ *   window and skips: the credit had nothing left to restore. The backend may
+ *   refuse a partial-usage consume with `nothing_to_reset`; that outcome is
+ *   NON-terminal — the episode is deferred (not buried), so the credit is
+ *   retried as usage grows or a window exhausts before expiry.
+ * - `blocked-account` (restore; `blocked` trigger only): a live 429 blocked
+ *   the turn and no sibling credential could take over, so the pool is dry.
+ *   Candidates are accounts with at least one genuinely exhausted chat window
+ *   — 5h primary or weekly secondary. A banked reset clears the account's
+ *   chat rate limits generally, not just the weekly window: OpenAI's own
+ *   client consumes one for a 5h-only block while the weekly window still has
+ *   ~80% headroom (openai/codex#28525). The natural unblock is the LATEST
+ *   reset among the exhausted windows (the account stays blocked until every
+ *   one rolls over) and must be far enough away to justify the spend, with
+ *   credits above the reserve. One candidate is redeemed — active account
+ *   first, then the account whose credit dies soonest — and the redeem clears
+ *   its credential blocks so the retry's re-rank picks it up.
+ *
+ * TRIGGERS: `blocked` runs from the usage-limit branch of the retry pipeline
+ * after sibling switch fails, on force-refreshed reports (the cached snapshot
+ * predates the 429 that got us there). `sweep` piggybacks on every successful
+ * usage-report fetch — the status line polls every 5 minutes while the TUI is
+ * open — so expiring credits are caught even when nothing is blocked.
+ *
+ * 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. This module keys eligibility off exact limit ids
+ * (`openai-codex:primary` / `openai-codex:secondary`) and `usedFraction`,
+ * never off `status`, so the plan names the true blocking window(s) and their
+ * real unblock time. Whether a short wait (e.g. a 5h-only block) is worth a
+ * credit is the `minBlockedMinutes` knob's call, not hardcoded fiat.
+ *
+ * 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 planner itself stays deterministic.
+ */
+import type {
+	OAuthAccountIdentity,
+	ResetCreditAccountStatus,
+	ResetCreditTarget,
+	UsageReport,
+	UsageResetCreditDetail,
+} from "@oh-my-pi/pi-ai";
+import type { CodexAutoRedeemMode } from "../config/settings-schema";
+import { reportMatchesActiveAccount } from "../slash-commands/helpers/active-oauth-account";
+
+/** A chat window counts as exhausted at `usedFraction >= 0.999` (used_percent >= 99.9). */
+export const WINDOW_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_WEEKLY_REMAINING_MS = 7 * 24 * 3_600_000 + 60 * 60_000;
+/** A 5h reset can never be more than one window length (5h) away; +1h slack for skew. */
+export const MAX_PLAUSIBLE_PRIMARY_REMAINING_MS = 5 * 3_600_000 + 60 * 60_000;
+/** Below this usage on BOTH chat windows a salvaged reset restores too little to bother (and risks a `nothing_to_reset` no-op). */
+export const SALVAGE_MIN_USED_FRACTION = 0.25;
+/** Retry spacing after a non-terminal consume outcome (`nothing_to_reset`, transport failure). */
+export const REDEEM_RETRY_DEFER_MS = 30 * 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 attempt-key drift across a minute boundary. */
+export const ATTEMPT_COOLDOWN_MS = 60_000;
+/** Minute bucket for attempt keys, absorbing `reset_after_seconds`/expiry jitter. */
+export const DEBOUNCE_BUCKET_MS = 60_000;
+/** Floor between salvage sweeps; dedupe keys make sweeps idempotent, this just avoids useless re-planning. */
+export const SWEEP_MIN_INTERVAL_MS = 60_000;
+
+export function shouldEvaluateCodexAutoRedeem(mode: CodexAutoRedeemMode): boolean {
+	return mode !== "no";
+}
+
+export function shouldPromptCodexAutoRedeem(mode: CodexAutoRedeemMode): boolean {
+	return mode === "unset";
+}
+
+/** What woke the planner. `sweep` may only salvage; `blocked` may also restore. */
+export type CodexResetTrigger = "blocked" | "sweep";
+
+/** Why one account produced no action (or, with `accountKey: "*"`, a whole rule was off). */
+export type CodexResetSkipReason =
+	| "disabled"
+	| "wrong-provider"
+	| "spark-model"
+	| "no-identity"
+	| "stale-report"
+	| "not-limit-reached"
+	| "no-exhausted-window"
+	| "deferred"
+	| "no-reset-time"
+	| "reset-too-soon"
+	| "reset-implausible"
+	| "credits-unknown"
+	| "no-credits"
+	| "reserve"
+	| "no-expiring-credit"
+	| "window-mostly-free"
+	| "already-attempted"
+	| "cooldown";
+
+export interface CodexResetPlanInput {
+	nowMs: number;
+	trigger: CodexResetTrigger;
+	/** `this.model.provider` — gates the `blocked-account` rule only. */
+	provider: string;
+	/** `this.model.id` — gates the `blocked-account` rule only. */
+	modelId: string;
+	settings: {
+		enabled: boolean;
+		/** `blocked-account`: skip when the natural unblock is closer than this. */
+		minBlockedMinutes: number;
+		/** `blocked-account`: never spend below this many remaining credits. */
+		keepCredits: number;
+		/** `expiring-credit`: salvage window; `<= 0` disables the rule. */
+		salvageHorizonMs: number;
+	};
+	/** Active account (marks the preferred restore candidate); may be undefined. */
+	identity: OAuthAccountIdentity | undefined;
+	/** Usage reports for ALL stored accounts (one per account for Codex). */
+	reports: UsageReport[] | null;
+	attemptedKeys: ReadonlySet<string>;
+	/** Episodes parked by a non-terminal consume outcome, keyed by attempt key (epoch ms). */
+	deferredUntilByKey: ReadonlyMap<string, number>;
+	lastAttemptAtByAccount: ReadonlyMap<string, number>;
+	/**
+	 * Live 429 evidence for the ACTIVE account: absolute epoch ms when the
+	 * provider said the account unblocks, derived from the usage-limit error's
+	 * parsed retry hint AT THE ERROR (absolute, so slow usage IO between the
+	 * error and planning cannot drift it). Authoritative when the usage report
+	 * is stale or missing — the report layer can adopt a pre-block in-flight
+	 * fetch or serve the last-good snapshot when `/wham/usage` fails (it is
+	 * IP-throttled, so failure right after a 429 is common), and such a
+	 * snapshot still shows `limitReached: false` with healthy windows. With no
+	 * usable report at all, a candidate is synthesized from `identity` and the
+	 * redeem re-checks credits live. Only used on `blocked`.
+	 */
+	activeBlockUnblockAtMs?: number;
+}
+
+/** One credit to spend. `redeemResetCredit` picks the account's soonest-expiring credit. */
+export interface CodexResetAction {
+	reason: "blocked-account" | "expiring-credit";
+	target: ResetCreditTarget;
+	accountKey: string;
+	/** Once-per-episode dedupe key; record in `attemptedKeys` BEFORE consuming. */
+	attemptKey: string;
+	/** Human label for notices/prompts (email preferred). */
+	label: string;
+	/** Redeemable credits per the report; undefined for a synthesized live-429 candidate. */
+	availableCount?: number;
+	weeklyUsedFraction?: number;
+	/** `blocked-account`: ms until the natural unblock (latest exhausted-window reset). */
+	remainingMs?: number;
+	/** `blocked-account`: the exhausted chat windows a redeem would clear. */
+	blockedWindows?: ("5h" | "weekly")[];
+	/** `expiring-credit`: the fuller chat window a redeem restores (for messaging). */
+	salvageWindow?: "5h" | "weekly";
+	/** `expiring-credit`: used fraction of {@link CodexResetAction.salvageWindow}. */
+	salvageUsedFraction?: number;
+	/** `expiring-credit`: ms until the credit expires. */
+	expiresInMs?: number;
+	/** True when this is the session's active account. */
+	active: boolean;
+}
+
+export interface CodexResetSkip {
+	/** Normalized account key, or `"*"` for a rule-wide gate. */
+	accountKey: string;
+	rule: "blocked-account" | "expiring-credit" | "account";
+	reason: CodexResetSkipReason;
+}
+
+export interface CodexResetPlan {
+	/** At most one `blocked-account` action (first), then salvages by soonest expiry. */
+	actions: CodexResetAction[];
+	/** Diagnostics for `logger.debug` and tests. */
+	skipped: CodexResetSkip[];
+}
+
+/** Soonest future expiry (epoch ms) among available credits, or undefined. */
+function soonestCreditExpiryMs(
+	credits: readonly UsageResetCreditDetail[] | undefined,
+	nowMs: number,
+): number | undefined {
+	let soonest: number | undefined;
+	for (const credit of credits ?? []) {
+		if ((credit.status ?? "available") !== "available") continue;
+		if (!credit.expiresAt) continue;
+		const expiry = Date.parse(credit.expiresAt);
+		if (Number.isNaN(expiry) || expiry <= nowMs) continue;
+		if (soonest === undefined || expiry < soonest) soonest = expiry;
+	}
+	return soonest;
+}
+
+interface AccountSnapshot {
+	accountKey: string;
+	target: ResetCreditTarget;
+	label: string;
+	active: boolean;
+	/** Undefined when synthesized from live 429 evidence without a report. */
+	availableCount: number | undefined;
+	primaryUsed: number | undefined;
+	primaryResetsAt: number | undefined;
+	weeklyUsed: number | undefined;
+	weeklyResetsAt: number | undefined;
+	limitReached: boolean;
+	creditExpiresAtMs: number | undefined;
+}
+
+/**
+ * Plan which saved Codex resets to spend right now. Pure: a function of the
+ * snapshot inputs only. Callers execute the returned actions in order,
+ * re-checking `attemptedKeys` immediately before each consume.
+ */
+export function planCodexResetRedemptions(input: CodexResetPlanInput): CodexResetPlan {
+	const { nowMs, settings } = input;
+	const skipped: CodexResetSkip[] = [];
+	if (!settings.enabled) return { actions: [], skipped: [{ accountKey: "*", rule: "account", reason: "disabled" }] };
+
+	// Rule-wide gates for `blocked-account`: a redeem can only unblock the turn
+	// when the turn is actually on Codex, and it is unknown whether a credit
+	// resets the separate Spark meter.
+	let blockedRuleActive = input.trigger === "blocked";
+	if (blockedRuleActive && input.provider !== "openai-codex") {
+		blockedRuleActive = false;
+		skipped.push({ accountKey: "*", rule: "blocked-account", reason: "wrong-provider" });
+	}
+	if (blockedRuleActive && input.modelId.includes("-spark")) {
+		blockedRuleActive = false;
+		skipped.push({ accountKey: "*", rule: "blocked-account", reason: "spark-model" });
+	}
+	const salvageRuleActive = settings.salvageHorizonMs > 0;
+
+	const snapshots: AccountSnapshot[] = [];
+	// Whether the ACTIVE account produced a usable snapshot, and whether a
+	// FRESH report proved it has no credits — both gate the last-resort
+	// synthesized candidate below (live 429 with no usable report).
+	let activeHasSnapshot = false;
+	let activeKnownNoCredits = false;
+	for (const report of input.reports ?? []) {
+		if (report.provider !== "openai-codex") continue;
+		const accountIdValue = report.metadata?.accountId;
+		const emailValue = report.metadata?.email;
+		const accountId = typeof accountIdValue === "string" && accountIdValue.trim() ? accountIdValue : undefined;
+		const email = typeof emailValue === "string" && emailValue.trim() ? emailValue : undefined;
+		// Trimmed lowercase, mirroring `normalizeIdentityValue` in active-oauth-account.ts.
+		const accountKey = (accountId ?? email)?.trim().toLowerCase();
+		if (!accountKey) {
+			skipped.push({ accountKey: "*", rule: "account", reason: "no-identity" });
+			continue;
+		}
+		const isActive = reportMatchesActiveAccount(report, input.identity);
+		if (nowMs - report.fetchedAt > REPORT_FRESHNESS_MS) {
+			skipped.push({ accountKey, rule: "account", reason: "stale-report" });
+			continue;
+		}
+		const available = report.resetCredits?.availableCount;
+		// Can't verify availability from the snapshot → don't spend (precision over recall).
+		if (available === undefined) {
+			skipped.push({ accountKey, rule: "account", reason: "credits-unknown" });
+			continue;
+		}
+		if (available < 1) {
+			if (isActive) activeKnownNoCredits = true;
+			skipped.push({ accountKey, rule: "account", reason: "no-credits" });
+			continue;
+		}
+		const primary = report.limits.find(l => l.id === "openai-codex:primary");
+		const weekly = report.limits.find(l => l.id === "openai-codex:secondary");
+		if (isActive) activeHasSnapshot = true;
+		snapshots.push({
+			accountKey,
+			target: { accountId, email },
+			label: email ?? accountId ?? accountKey,
+			active: isActive,
+			availableCount: available,
+			primaryUsed: primary?.amount.usedFraction,
+			primaryResetsAt: primary?.window?.resetsAt,
+			weeklyUsed: weekly?.amount.usedFraction,
+			weeklyResetsAt: weekly?.window?.resetsAt,
+			limitReached: report.metadata?.limitReached === true,
+			creditExpiresAtMs: soonestCreditExpiryMs(report.resetCredits?.credits, nowMs),
+		});
+	}
+
+	const cooledDown = (accountKey: string): boolean => {
+		const lastAt = input.lastAttemptAtByAccount.get(accountKey);
+		return lastAt !== undefined && nowMs - lastAt < ATTEMPT_COOLDOWN_MS;
+	};
+
+	// --- blocked-account: pick ONE restore candidate; one open lane is enough,
+	// the next block re-plans on live data.
+	let restore: CodexResetAction | undefined;
+	if (blockedRuleActive) {
+		interface RestoreCandidate {
+			snapshot: AccountSnapshot;
+			remainingMs: number;
+			unblockAtMs: number;
+			blockedWindows: ("5h" | "weekly")[];
+		}
+		const candidates: RestoreCandidate[] = [];
+		for (const snapshot of snapshots) {
+			const rule = "blocked-account" as const;
+			const skip = (reason: CodexResetSkipReason) => skipped.push({ accountKey: snapshot.accountKey, rule, reason });
+			// Live evidence: the 429 that triggered this pass names the active
+			// account directly, outranking a possibly pre-block report snapshot.
+			const liveUnblockAtMs = snapshot.active ? input.activeBlockUnblockAtMs : undefined;
+			// The wire's own blocked flag must confirm the 429 for THIS account,
+			// unless the live block evidence already does.
+			if (!snapshot.limitReached && liveUnblockAtMs === undefined) {
+				skip("not-limit-reached");
+				continue;
+			}
+			// Identify the exact exhausted window(s) via usedFraction — never
+			// `status` (see the Decision-2 trap in the module docs). Either
+			// window qualifies: a banked reset also clears a 5h-only block
+			// (openai/codex#28525).
+			const exhausted: { window: "5h" | "weekly"; resetsAt: number | undefined; plausibleMs: number }[] = [];
+			if (snapshot.primaryUsed !== undefined && snapshot.primaryUsed >= WINDOW_EXHAUSTED_MIN_FRACTION) {
+				exhausted.push({
+					window: "5h",
+					resetsAt: snapshot.primaryResetsAt,
+					plausibleMs: MAX_PLAUSIBLE_PRIMARY_REMAINING_MS,
+				});
+			}
+			if (snapshot.weeklyUsed !== undefined && snapshot.weeklyUsed >= WINDOW_EXHAUSTED_MIN_FRACTION) {
+				exhausted.push({
+					window: "weekly",
+					resetsAt: snapshot.weeklyResetsAt,
+					plausibleMs: MAX_PLAUSIBLE_WEEKLY_REMAINING_MS,
+				});
+			}
+			let unblockAtMs: number;
+			let blockedWindows: ("5h" | "weekly")[];
+			if (exhausted.length > 0) {
+				// Blocked until EVERY exhausted window rolls over — the unblock is
+				// the latest reset among them. A missing or implausible reset on any
+				// of them means the unblock time is unknown; stay conservative.
+				let latest = Number.NEGATIVE_INFINITY;
+				let invalid: CodexResetSkipReason | undefined;
+				for (const entry of exhausted) {
+					if (entry.resetsAt === undefined) {
+						invalid = "no-reset-time";
+						break;
+					}
+					if (entry.resetsAt - nowMs > entry.plausibleMs) {
+						invalid = "reset-implausible";
+						break;
+					}
+					if (entry.resetsAt > latest) latest = entry.resetsAt;
+				}
+				if (invalid) {
+					skip(invalid);
+					continue;
+				}
+				unblockAtMs = latest;
+				blockedWindows = exhausted.map(e => e.window);
+			} else if (liveUnblockAtMs !== undefined) {
+				// The report's windows look healthy but the live 429 says otherwise:
+				// the snapshot predates the block. Trust the provider's own hint for
+				// the unblock horizon, classifying the window by its scale.
+				if (liveUnblockAtMs - nowMs > MAX_PLAUSIBLE_WEEKLY_REMAINING_MS) {
+					skip("reset-implausible");
+					continue;
+				}
+				unblockAtMs = liveUnblockAtMs;
+				blockedWindows = [liveUnblockAtMs - nowMs > MAX_PLAUSIBLE_PRIMARY_REMAINING_MS ? "weekly" : "5h"];
+			} else {
+				skip("no-exhausted-window");
+				continue;
+			}
+			const remainingMs = unblockAtMs - nowMs;
+			// Anti-waste: too close to the natural unblock — let it roll over.
+			if (remainingMs < settings.minBlockedMinutes * 60_000) {
+				skip("reset-too-soon");
+				continue;
+			}
+			if ((snapshot.availableCount ?? 0) - Math.max(0, Math.trunc(settings.keepCredits)) < 1) {
+				skip("reserve");
+				continue;
+			}
+			if (input.attemptedKeys.has(blockedAttemptKey(snapshot.accountKey, unblockAtMs))) {
+				skip("already-attempted");
+				continue;
+			}
+			const deferredUntil = input.deferredUntilByKey.get(blockedAttemptKey(snapshot.accountKey, unblockAtMs));
+			if (deferredUntil !== undefined && nowMs < deferredUntil) {
+				skip("deferred");
+				continue;
+			}
+			if (cooledDown(snapshot.accountKey)) {
+				skip("cooldown");
+				continue;
+			}
+			candidates.push({ snapshot, remainingMs, unblockAtMs, blockedWindows });
+		}
+		candidates.sort((a, b) => {
+			// Active account first: the sticky session credential stays usable.
+			if (a.snapshot.active !== b.snapshot.active) return a.snapshot.active ? -1 : 1;
+			// Then spend the credit that dies soonest.
+			const aExpiry = a.snapshot.creditExpiresAtMs ?? Number.POSITIVE_INFINITY;
+			const bExpiry = b.snapshot.creditExpiresAtMs ?? Number.POSITIVE_INFINITY;
+			if (aExpiry !== bExpiry) return aExpiry - bExpiry;
+			// Then the deepest bank, then the longest natural wait (most value).
+			const aCount = a.snapshot.availableCount ?? 0;
+			const bCount = b.snapshot.availableCount ?? 0;
+			if (aCount !== bCount) {
+				return bCount - aCount;
+			}
+			return b.remainingMs - a.remainingMs;
+		});
+		let best = candidates[0];
+		// Last resort: the live 429 names the active account but no usable report
+		// survived — stale-dropped, fetch failed entirely, or the credits block
+		// was absent. Synthesize the candidate from the captured identity; the
+		// redeem re-lists credits live, so a blind guess costs nothing
+		// (`no_credit` is terminal, `credit_list_failed` defers). A FRESH report
+		// proving zero credits suppresses this.
+		if (!best && input.activeBlockUnblockAtMs !== undefined && !activeHasSnapshot && !activeKnownNoCredits) {
+			const idValue = input.identity?.accountId;
+			const emailValue = input.identity?.email;
+			const accountId = typeof idValue === "string" && idValue.trim() ? idValue : undefined;
+			const email = typeof emailValue === "string" && emailValue.trim() ? emailValue : undefined;
+			const accountKey = (accountId ?? email)?.trim().toLowerCase();
+			const unblockAtMs = input.activeBlockUnblockAtMs;
+			const remainingMs = unblockAtMs - nowMs;
+			const skip = (reason: CodexResetSkipReason) =>
+				skipped.push({ accountKey: accountKey ?? "*", rule: "blocked-account", reason });
+			if (!accountKey) {
+				skip("no-identity");
+			} else if (Math.max(0, Math.trunc(settings.keepCredits)) > 0) {
+				// A reserve cannot be enforced against an unknown balance.
+				skip("credits-unknown");
+			} else if (remainingMs > MAX_PLAUSIBLE_WEEKLY_REMAINING_MS) {
+				skip("reset-implausible");
+			} else if (remainingMs < settings.minBlockedMinutes * 60_000) {
+				skip("reset-too-soon");
+			} else if (input.attemptedKeys.has(blockedAttemptKey(accountKey, unblockAtMs))) {
+				skip("already-attempted");
+			} else if ((input.deferredUntilByKey.get(blockedAttemptKey(accountKey, unblockAtMs)) ?? 0) > nowMs) {
+				skip("deferred");
+			} else if (cooledDown(accountKey)) {
+				skip("cooldown");
+			} else {
+				best = {
+					snapshot: {
+						accountKey,
+						target: { accountId, email },
+						label: email ?? accountId ?? accountKey,
+						active: true,
+						availableCount: undefined,
+						primaryUsed: undefined,
+						primaryResetsAt: undefined,
+						weeklyUsed: undefined,
+						weeklyResetsAt: undefined,
+						limitReached: true,
+						creditExpiresAtMs: undefined,
+					},
+					remainingMs,
+					unblockAtMs,
+					blockedWindows: [remainingMs > MAX_PLAUSIBLE_PRIMARY_REMAINING_MS ? "weekly" : "5h"],
+				};
+			}
+		}
+		if (best) {
+			restore = {
+				reason: "blocked-account",
+				target: best.snapshot.target,
+				accountKey: best.snapshot.accountKey,
+				attemptKey: blockedAttemptKey(best.snapshot.accountKey, best.unblockAtMs),
+				label: best.snapshot.label,
+				availableCount: best.snapshot.availableCount,
+				weeklyUsedFraction: best.snapshot.weeklyUsed,
+				remainingMs: best.remainingMs,
+				expiresInMs:
+					best.snapshot.creditExpiresAtMs === undefined ? undefined : best.snapshot.creditExpiresAtMs - nowMs,
+				blockedWindows: best.blockedWindows,
+				active: best.snapshot.active,
+			};
+		}
+	}
+
+	// --- expiring-credit: salvage every credit that would otherwise die.
+	const salvages: CodexResetAction[] = [];
+	if (salvageRuleActive) {
+		for (const snapshot of snapshots) {
+			if (snapshot.accountKey === restore?.accountKey) continue; // restore already spends its soonest credit
+			const rule = "expiring-credit" as const;
+			const skip = (reason: CodexResetSkipReason) => skipped.push({ accountKey: snapshot.accountKey, rule, reason });
+			const expiresAtMs = snapshot.creditExpiresAtMs;
+			if (expiresAtMs === undefined || expiresAtMs - nowMs > settings.salvageHorizonMs) {
+				skip("no-expiring-credit");
+				continue;
+			}
+			// Value = the fuller of the two chat windows a redeem restores. A
+			// 5h-only exhausted account with a light week still gains real quota
+			// (openai/codex#28525); a reset on two mostly-free windows restores
+			// ~nothing. If usage grows before the credit expires, a later sweep
+			// reconsiders.
+			const primaryUsed = snapshot.primaryUsed ?? 0;
+			const weeklyUsed = snapshot.weeklyUsed ?? 0;
+			const salvageUsedFraction = Math.max(primaryUsed, weeklyUsed);
+			if (salvageUsedFraction < SALVAGE_MIN_USED_FRACTION) {
+				skip("window-mostly-free");
+				continue;
+			}
+			const salvageWindow: "5h" | "weekly" = primaryUsed >= weeklyUsed ? "5h" : "weekly";
+			const attemptKey = salvageAttemptKey(snapshot.accountKey, expiresAtMs);
+			if (input.attemptedKeys.has(attemptKey)) {
+				skip("already-attempted");
+				continue;
+			}
+			const deferredUntil = input.deferredUntilByKey.get(attemptKey);
+			if (deferredUntil !== undefined && nowMs < deferredUntil) {
+				skip("deferred");
+				continue;
+			}
+			if (cooledDown(snapshot.accountKey)) {
+				skip("cooldown");
+				continue;
+			}
+			salvages.push({
+				reason: "expiring-credit",
+				target: snapshot.target,
+				accountKey: snapshot.accountKey,
+				attemptKey,
+				label: snapshot.label,
+				availableCount: snapshot.availableCount,
+				weeklyUsedFraction: snapshot.weeklyUsed,
+				salvageWindow,
+				salvageUsedFraction,
+				expiresInMs: expiresAtMs - nowMs,
+				active: snapshot.active,
+			});
+		}
+		salvages.sort((a, b) => (a.expiresInMs ?? 0) - (b.expiresInMs ?? 0));
+	}
+
+	const actions = restore ? [restore, ...salvages] : salvages;
+	return { actions, skipped };
+}
+
+/** One attempt per (account, weekly-reset-minute) block episode. */
+export function blockedAttemptKey(accountKey: string, weeklyResetsAtMs: number): string {
+	return `block|${accountKey}|${Math.round(weeklyResetsAtMs / DEBOUNCE_BUCKET_MS)}`;
+}
+
+/** One attempt per (account, credit-expiry-minute) salvage episode. */
+export function salvageAttemptKey(accountKey: string, creditExpiresAtMs: number): string {
+	return `salvage|${accountKey}|${Math.round(creditExpiresAtMs / DEBOUNCE_BUCKET_MS)}`;
+}
+
+/**
+ * Overlay LIVE per-account credit state (from the dedicated
+ * `rate-limit-reset-credits` route) onto usage reports before a blocked pass.
+ *
+ * `/wham/usage` credit counts can be stale or pre-feature, and the usage
+ * provider only consults the live detail endpoint when the usage payload
+ * already reports a POSITIVE count — a stale ZERO is never corrected there.
+ * Live data therefore replaces the report's credit block wholesale; accounts
+ * with no live row (or a failed lookup) get the block stripped, so the planner
+ * treats them as `credits-unknown` instead of trusting a stale count: siblings
+ * stay conservative while the active account can still be synthesized from
+ * live 429 evidence (the redeem re-lists atomically either way).
+ */
+export function overlayLiveResetCredits(
+	reports: UsageReport[] | null,
+	statuses: readonly ResetCreditAccountStatus[],
+): UsageReport[] | null {
+	if (!reports) return reports;
+	return reports.map(report => {
+		if (report.provider !== "openai-codex") return report;
+		const status = statuses.find(
+			s =>
+				(!!s.accountId && s.accountId === report.metadata?.accountId) ||
+				(!!s.email && s.email === report.metadata?.email),
+		);
+		if (!status || status.error) return { ...report, resetCredits: undefined };
+		return {
+			...report,
+			resetCredits: {
+				availableCount: status.availableCount,
+				credits: status.credits
+					.filter(credit => (credit.status ?? "available") === "available")
+					.map(credit => ({ grantedAt: credit.grantedAt, expiresAt: credit.expiresAt, status: credit.status })),
+			},
+		};
+	});
+}
+
+/**
+ * Whether a consume outcome permanently settles its episode. Terminal codes
+ * either spent the credit (`reset`), or prove this credit can never be spent
+ * (`already_redeemed`, `no_credit` — a live listing that really had nothing).
+ * Everything else — `nothing_to_reset` (limits not constrained enough right
+ * now), `credit_list_failed` (flaky listing), thrown transport failures,
+ * unknown codes — leaves the credit banked: the executor releases the attempt
+ * key and
+ * defers the episode by {@link REDEEM_RETRY_DEFER_MS} instead of burying a
+ * live credit for the rest of the process.
+ */
+export function isTerminalRedeemOutcome(code: string): boolean {
+	return code === "reset" || code === "already_redeemed" || code === "no_credit";
+}
+
+/**
+ * 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.
+ *
+ * - `attemptedKeys`: one attempt per episode key — recorded before calling the
+ *   consume so exceptions can't re-enter. Non-terminal outcomes (see
+ *   {@link isTerminalRedeemOutcome}) release the key again and park the
+ *   episode in `deferredUntilByKey` instead.
+ * - `deferredUntilByKey`: earliest retry time for episodes whose consume was
+ *   refused non-terminally (`nothing_to_reset`, transport failure).
+ * - `lastAttemptAtByAccount`: per-account cooldown timestamps (epoch ms),
+ *   catching attempt-key drift across a minute boundary.
+ * - `inFlightByAccount`: serializes blocked passes per account — a second
+ *   session for the same account adopts the in-flight promise instead of
+ *   starting a second consume.
+ * - `sweepInFlight` / `lastSweepAt` / `sweepPromise`: re-entrancy guard, floor,
+ *   and settlement handle for the salvage sweep (a redeem refreshes usage,
+ *   which would recurse into a sweep; the promise lets tests and diagnostics
+ *   await a fire-and-forget sweep instead of polling).
+ * - `notifiedKeys`: headless "run /usage reset" notices already emitted, so a
+ *   5-minute sweep cadence can't spam the transcript.
+ */
+export interface CodexAutoRedeemCoordinator {
+	attemptedKeys: Set<string>;
+	deferredUntilByKey: Map<string, number>;
+	lastAttemptAtByAccount: Map<string, number>;
+	inFlightByAccount: Map<string, Promise<boolean>>;
+	sweepInFlight: boolean;
+	lastSweepAt: number;
+	/** Settlement of the most recently scheduled sweep (never rejects). */
+	sweepPromise: Promise<void> | undefined;
+	notifiedKeys: Set<string>;
+}
+
+/** Fresh, empty coordinator: backs the process-wide default; inject one per test for isolation. */
+export function createCodexAutoRedeemCoordinator(): CodexAutoRedeemCoordinator {
+	return {
+		attemptedKeys: new Set(),
+		deferredUntilByKey: new Map(),
+		lastAttemptAtByAccount: new Map(),
+		inFlightByAccount: new Map(),
+		sweepInFlight: false,
+		lastSweepAt: 0,
+		sweepPromise: undefined,
+		notifiedKeys: new Set(),
+	};
+}
+
+export const defaultCodexAutoRedeemCoordinator: CodexAutoRedeemCoordinator = createCodexAutoRedeemCoordinator();