@narumitw/pi-usage 0.49.3 → 0.50.0

package/README.md

@@ -9,6 +9,7 @@
 - Opens one interactive `/usage` menu with current state and next actions.
 - Automatically queries the selected model provider and active runtime account.
 - Supports OpenAI Codex subscription windows, resets, credits, and model-specific buckets.
+- Redeems earned Codex usage-limit resets for the active, matching Pi OAuth account with fresh availability, explicit confirmation, and idempotent retry.
 - Supports GitHub Copilot AI Credits, legacy premium requests, Free chat quota, additional usage, percentage, and reset time.
 - Supports OpenRouter per-key credit limits plus daily, weekly, monthly, and all-time spend.
 - Provides explicit refresh, another-provider, and all-configured-provider actions.
@@ -35,7 +36,7 @@ pi -e npm:@narumitw/pi-usage
 Try this package locally from the repository root:
 
 ```bash
-pi -e ./extensions/pi-usage
+pi -e ./packages/pi-usage
 ```
 
 ## 🚀 Usage
@@ -51,6 +52,7 @@ with these actions:
 
 ```text
 Refresh current usage
+Redeem usage limit reset…   # Current Codex OAuth accounts only
 View another configured provider…
 View all configured providers…
 Close
@@ -62,18 +64,35 @@ and closes the root menu. Print and JSON modes reject `/usage` observably becaus
 interactive flow. The cancellable live-query progress view remains extension-owned because it streams
 provider work and supports in-flight abort rather than presenting a standard menu screen.
 
+For the current OpenAI Codex provider, **Redeem usage limit reset…** checks fresh earned-reset
+details, lets you select a reset when details are available, and shows the exact reset before asking
+for confirmation. **No, go back** is the safe default and cancellation before confirmation sends no
+mutation. After confirmation, the reset operation cannot be cancelled from its progress view; session
+replacement or shutdown still aborts owned work. A transport failure offers **Try again** with the
+same redemption request ID so the backend can treat an uncertain retry idempotently. Successful,
+already-completed, not-needed, and no-credit outcomes are reported separately, then usage and the
+statusline are refreshed for the still-current account.
+
 ## 📋 Provider semantics
 
 ### OpenAI Codex
 
 - Provider ID: `openai-codex`
 - Semantics: ChatGPT consumer subscription limits
-- Source: the Codex usage endpoint using Pi's resolved runtime authorization
+- Source: the Codex usage and earned-reset endpoints using Pi's resolved runtime authorization
 - Displayed data: returned duration-based windows, resets, credits, earned usage-limit resets, and additional model buckets
+- Reset mutation: `POST /wham/rate-limit-reset-credits/consume` with a unique redemption request ID and, when available, the selected opaque credit ID
 - Statusline examples: `codex 59% 5h 61% wk` or `codex spark 100% 5h`
 
 The statusline selects a returned bucket that matches the current Codex model when one is available. Unlike `pi-codex-usage`, this successor intentionally has no Codex CLI fallback because the CLI may be logged into a different account than Pi's active runtime account.
 
+Reset redemption is available only when Codex is the current provider and Pi's freshly resolved access
+token exactly matches its stored OpenAI Codex OAuth credential. `pi-usage` forwards only the bearer
+authorization and matching `chatgpt-account-id` to the official ChatGPT origin. API-key credentials,
+configured-but-not-current Codex accounts, account changes during the flow, and custom/proxy origins
+fail before mutation. Backend-provided titles and descriptions are sanitized for terminal display;
+opaque credit and account IDs are never shown or persisted by the extension.
+
 ### GitHub Copilot
 
 - Provider ID: `github-copilot`
@@ -127,7 +146,8 @@ Behavior changes:
 ## 🚧 Limitations
 
 - Only providers with a meaningful usage source and verifiable Pi runtime auth are supported.
-- GitHub Copilot quota uses an undocumented GitHub endpoint that may change without notice.
+- GitHub Copilot quota and OpenAI Codex reset redemption use undocumented provider endpoints that may change without notice.
+- Codex reset redemption requires a current ChatGPT OAuth login created through Pi; Codex API keys cannot redeem earned subscription resets.
 - Credentials resolved for custom provider base URLs are never forwarded to the providers' official usage endpoints; effective auth origin validation requires Pi 0.81.0 or newer.
 - Provider reports are snapshots and may themselves be delayed by the provider.
 - OpenRouter successful inference responses do not expose proactive request-rate counters; `/usage` reports the documented per-key credit/spend fields instead.
@@ -137,11 +157,12 @@ Behavior changes:
 ## 🗂️ Package layout
 
 ```txt
-extensions/pi-usage/
+packages/pi-usage/
 ├── src/
 │   ├── index.ts       # Pi package entrypoint and helper export barrel
 │   ├── usage.ts       # Menu, cache, and lifecycle orchestration
-│   ├── query.ts       # Runtime auth resolution and provider queries
+│   ├── query.ts       # Runtime auth resolution and bounded provider queries
+│   ├── codex-resets.ts # Codex reset auth, API contracts, and normalization
 │   ├── format.ts      # Provider-aware notifications and statusline text
 │   ├── core.ts        # Cache, concurrency, fingerprint, and redaction helpers
 │   ├── providers/     # Codex, GitHub Copilot, and OpenRouter normalization adapters

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-usage",
-	"version": "0.49.3",
+	"version": "0.50.0",
 	"description": "Pi extension that shows current-account usage for Codex, GitHub Copilot, and OpenRouter.",
 	"type": "module",
 	"license": "MIT",
@@ -25,6 +25,9 @@
 			"./src/index.ts"
 		]
 	},
+	"piExtension": {
+		"lifecycle": "stable"
+	},
 	"scripts": {
 		"check": "biome check --vcs-use-ignore-file=false src test package.json tsconfig.json README.md && npm run typecheck",
 		"format": "biome check --write --vcs-use-ignore-file=false src test package.json tsconfig.json README.md",
@@ -35,14 +38,14 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.7",
-		"@earendil-works/pi-coding-agent": "0.83.0",
+		"@earendil-works/pi-coding-agent": "0.84.1",
 		"@types/node": "26.1.2",
 		"typescript": "7.0.2"
 	},
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/narumiruna/pi-extensions",
-		"directory": "extensions/pi-usage"
+		"directory": "packages/pi-usage"
 	},
 	"dependencies": {
 		"@narumitw/pi-tui-kit": "^0.49.1"

package/src/codex-resets.ts

@@ -0,0 +1,308 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { readStoredCredential } from "@earendil-works/pi-coding-agent";
+import { fingerprintResolvedAuth, sanitizeDisplayText } from "./core.js";
+import {
+	AUTH_FINGERPRINT_SALT,
+	adapterForProvider,
+	fetchProviderJson,
+	resolveUsageAuth,
+} from "./query.js";
+import type { ResolvedUsageAuth, UsageReport } from "./types.js";
+
+const CODEX_RESET_CREDITS_URL = "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits";
+const CODEX_RESET_CONSUME_URL = `${CODEX_RESET_CREDITS_URL}/consume`;
+const MAX_RESET_OPTIONS = 32;
+const MAX_CREDIT_ID_CHARS = 1_024;
+
+type StoredCredentialReader = (providerId: string) => unknown;
+
+export type CodexResetOutcomeCode = "reset" | "nothing_to_reset" | "no_credit" | "already_redeemed";
+
+export interface CodexResetOption {
+	creditId?: string;
+	title: string;
+	description: string;
+	expiresAt?: number;
+}
+
+export interface CodexResetAvailability {
+	availableCount: number;
+	options: CodexResetOption[];
+}
+
+export interface CodexResetOutcome {
+	code: CodexResetOutcomeCode;
+	windowsReset: number;
+}
+
+export function codexResetCount(report: UsageReport): number | undefined {
+	const value = report.metrics.find((metric) => metric.id === "reset-credits")?.value;
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+export function codexResetActionDescription(report: UsageReport): string {
+	const count = codexResetCount(report);
+	if (count === undefined) return "Check reset availability.";
+	if (count === 0) return "No usage limit resets available.";
+	return `You have ${count} ${resetLabel(count)} available.`;
+}
+
+export function genericCodexResetOption(): CodexResetOption {
+	return {
+		title: "Full reset",
+		description: "Reset your current usage limits.",
+	};
+}
+
+export function resetOptionExpiration(option: CodexResetOption): string {
+	if (option.expiresAt === undefined) return "Does not expire.";
+	const expiration = new Date(option.expiresAt * 1_000);
+	if (Number.isNaN(expiration.getTime())) return "Expiration unavailable.";
+	return `Expires ${expiration.toLocaleString()}.`;
+}
+
+export function resetConfirmationLines(option: CodexResetOption | undefined): string[] {
+	if (!option) return ["The selected reset is unavailable."];
+	return [
+		option.title,
+		resetOptionExpiration(option),
+		option.description,
+		"This consumes one earned reset for the current OpenAI Codex account.",
+	];
+}
+
+export function formatCodexResetOutcome(
+	outcome: CodexResetOutcome | undefined,
+	remainingCount: number | undefined,
+): string {
+	const remaining =
+		remainingCount === undefined
+			? ""
+			: ` You have ${remainingCount} ${resetLabel(remainingCount)} left.`;
+	if (!outcome) return "You don't have any usage limit resets available.";
+	if (outcome.code === "reset") return `Usage reset.${remaining}`.trim();
+	if (outcome.code === "already_redeemed") {
+		return `Usage reset was already completed.${remaining}`.trim();
+	}
+	if (outcome.code === "nothing_to_reset") {
+		return "Your usage does not need a reset right now.";
+	}
+	return "No usage limit resets are available.";
+}
+
+export function resetLabel(count: number): string {
+	return count === 1 ? "usage limit reset" : "usage limit resets";
+}
+
+export async function resolveCodexResetAuth(
+	ctx: ExtensionContext,
+	salt: Uint8Array = AUTH_FINGERPRINT_SALT,
+	credentialReader: StoredCredentialReader = readStoredCredential,
+): Promise<ResolvedUsageAuth> {
+	const model = ctx.model;
+	if (model?.provider !== "openai-codex") {
+		throw new Error("Usage limit resets require the current model to use OpenAI Codex.");
+	}
+	const expectedModel = `${model.provider}/${model.id}`;
+	const adapter = adapterForProvider("openai-codex");
+	if (!adapter) throw new Error("OpenAI Codex usage support is unavailable.");
+	const auth = await resolveUsageAuth(ctx, adapter, salt, credentialReader);
+	if (`${ctx.model?.provider}/${ctx.model?.id}` !== expectedModel) {
+		throw new Error("The current model changed while resolving Codex reset authentication.");
+	}
+	if (!auth) throw new Error("No runtime credential is configured for OpenAI Codex.");
+
+	const credential = asObject(credentialReader("openai-codex"));
+	if (credential?.type !== "oauth") {
+		throw new Error(
+			"Usage limit resets require the OpenAI Codex OAuth account configured through Pi /login.",
+		);
+	}
+	const storedAccess = asNonemptyString(credential.access);
+	const resolvedAccess = bearerToken(headerValue(auth.headers, "Authorization")) ?? auth.apiKey;
+	if (!storedAccess || !resolvedAccess) {
+		throw new Error("OpenAI Codex OAuth credentials were incomplete.");
+	}
+	if (storedAccess !== resolvedAccess) {
+		throw new Error(
+			"The active OpenAI Codex runtime account does not match Pi's stored OAuth account.",
+		);
+	}
+	const accountId = validHeaderValue(credential.accountId);
+	if (!accountId)
+		throw new Error("The OpenAI Codex OAuth credential did not include a valid account ID.");
+
+	const authorization = `Bearer ${resolvedAccess}`;
+	const headers = {
+		Authorization: authorization,
+		"chatgpt-account-id": accountId,
+	};
+	return {
+		apiKey: resolvedAccess,
+		headers,
+		fingerprint: fingerprintResolvedAuth({ headers }, salt),
+		secrets: [
+			...new Set([...auth.secrets, storedAccess, resolvedAccess, authorization, accountId]),
+		],
+		model: auth.model,
+	};
+}
+
+export async function listCodexResetCredits(
+	auth: ResolvedUsageAuth,
+	signal: AbortSignal,
+	timeoutMs: number,
+): Promise<CodexResetAvailability> {
+	const payload = await fetchProviderJson(
+		CODEX_RESET_CREDITS_URL,
+		auth,
+		signal,
+		timeoutMs,
+		"Codex usage-limit reset endpoint",
+	);
+	return normalizeCodexResetCreditsPayload(payload);
+}
+
+export async function consumeCodexResetCredit(
+	auth: ResolvedUsageAuth,
+	option: CodexResetOption,
+	redeemRequestId: string,
+	signal: AbortSignal,
+	timeoutMs: number,
+): Promise<CodexResetOutcome> {
+	if (!redeemRequestId) throw new Error("Codex reset redemption request ID must not be empty.");
+	const payload = await fetchProviderJson(
+		CODEX_RESET_CONSUME_URL,
+		auth,
+		signal,
+		timeoutMs,
+		"Codex usage-limit reset consume endpoint",
+		{
+			method: "POST",
+			body: {
+				redeem_request_id: redeemRequestId,
+				...(option.creditId ? { credit_id: option.creditId } : {}),
+			},
+		},
+	);
+	const code = payload.code;
+	if (!isCodexResetOutcomeCode(code)) {
+		throw new Error("Codex reset consume endpoint returned an unknown outcome code.");
+	}
+	const windowsReset =
+		payload.windows_reset === undefined ? 0 : nonnegativeInteger(payload.windows_reset);
+	if (windowsReset === undefined) {
+		throw new Error("Codex reset consume endpoint returned an invalid windows_reset value.");
+	}
+	return { code, windowsReset };
+}
+
+export function normalizeCodexResetCreditsPayload(
+	payload: Record<string, unknown>,
+): CodexResetAvailability {
+	const availableCount = nonnegativeInteger(payload.available_count);
+	if (availableCount === undefined) {
+		throw new Error("Codex reset credits response returned an invalid available_count.");
+	}
+	const rawCredits = payload.credits;
+	if (rawCredits !== undefined && !Array.isArray(rawCredits)) {
+		throw new Error("Codex reset credits response returned invalid credits.");
+	}
+
+	const options = (rawCredits ?? [])
+		.map(asObject)
+		.filter((credit): credit is Record<string, unknown> => Boolean(credit))
+		.filter((credit) => credit.status === "available" && credit.reset_type === "codex_rate_limits")
+		.map(normalizeResetOption)
+		.sort(
+			(left, right) =>
+				(left.expiresAt ?? Number.MAX_SAFE_INTEGER) - (right.expiresAt ?? Number.MAX_SAFE_INTEGER),
+		)
+		.slice(0, Math.min(availableCount, MAX_RESET_OPTIONS));
+
+	if (availableCount > 0 && options.length === 0) {
+		options.push(genericCodexResetOption());
+	}
+	return { availableCount, options };
+}
+
+function normalizeResetOption(credit: Record<string, unknown>): CodexResetOption {
+	const creditId = asOpaqueId(credit.id);
+	if (!creditId) throw new Error("Codex reset credits response returned an invalid credit ID.");
+	let expiresAt: number | undefined;
+	if (credit.expires_at !== undefined && credit.expires_at !== null) {
+		if (typeof credit.expires_at !== "string") {
+			throw new Error("Codex reset credits response returned an invalid expiration time.");
+		}
+		const parsed = Date.parse(credit.expires_at);
+		if (!Number.isFinite(parsed)) {
+			throw new Error("Codex reset credits response returned an invalid expiration time.");
+		}
+		expiresAt = Math.floor(parsed / 1_000);
+	}
+	const title = displayString(credit.title) ?? "Full reset";
+	const description = displayString(credit.description) ?? "Reset your current usage limits.";
+	return {
+		creditId,
+		title,
+		description,
+		...(expiresAt === undefined ? {} : { expiresAt }),
+	};
+}
+
+function isCodexResetOutcomeCode(value: unknown): value is CodexResetOutcomeCode {
+	return (
+		value === "reset" ||
+		value === "nothing_to_reset" ||
+		value === "no_credit" ||
+		value === "already_redeemed"
+	);
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	return value as Record<string, unknown>;
+}
+
+function asNonemptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function asOpaqueId(value: unknown): string | undefined {
+	if (typeof value !== "string" || value.length === 0 || value.length > MAX_CREDIT_ID_CHARS) {
+		return undefined;
+	}
+	return value;
+}
+
+function displayString(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	return sanitizeDisplayText(value, 160) || undefined;
+}
+
+function validHeaderValue(value: unknown): string | undefined {
+	if (typeof value !== "string" || !value || value.length > 512) return undefined;
+	if (/[^\x20-\x7e]/u.test(value)) return undefined;
+	return value;
+}
+
+function nonnegativeInteger(value: unknown): number | undefined {
+	const parsed =
+		typeof value === "number"
+			? value
+			: typeof value === "string" && value.trim()
+				? Number(value)
+				: Number.NaN;
+	if (!Number.isSafeInteger(parsed) || parsed < 0) return undefined;
+	return parsed;
+}
+
+function bearerToken(authorization: string | undefined): string | undefined {
+	return /^Bearer\s+(.+)$/iu.exec(authorization ?? "")?.[1];
+}
+
+function headerValue(headers: Record<string, string>, name: string): string | undefined {
+	return Object.entries(headers).find(
+		([candidate]) => candidate.toLowerCase() === name.toLowerCase(),
+	)?.[1];
+}

package/src/index.ts

@@ -1,3 +1,15 @@
+export type {
+	CodexResetAvailability,
+	CodexResetOption,
+	CodexResetOutcome,
+	CodexResetOutcomeCode,
+} from "./codex-resets.js";
+export {
+	consumeCodexResetCredit,
+	listCodexResetCredits,
+	normalizeCodexResetCreditsPayload,
+	resolveCodexResetAuth,
+} from "./codex-resets.js";
 export {
 	abortError,
 	awaitWithDeadline,

package/src/query.ts

@@ -182,12 +182,16 @@ function candidateModels(ctx: ExtensionContext, providerId: string): PiModel[] {
 	return candidates;
 }
 
-async function fetchProviderJson(
+export async function fetchProviderJson(
 	url: string,
 	auth: ResolvedUsageAuth,
 	signal: AbortSignal,
 	timeoutMs: number,
 	description: string,
+	request: {
+		method?: "GET" | "POST";
+		body?: Record<string, unknown>;
+	} = {},
 ): Promise<Record<string, unknown>> {
 	const controller = new AbortController();
 	let timedOut = false;
@@ -201,7 +205,15 @@ async function fetchProviderJson(
 	try {
 		const headers = { ...auth.headers };
 		if (!hasHeader(headers, "User-Agent")) headers["User-Agent"] = "pi-usage";
-		const response = await fetch(url, { headers, signal: controller.signal });
+		if (request.body && !hasHeader(headers, "Content-Type")) {
+			headers["Content-Type"] = "application/json";
+		}
+		const response = await fetch(url, {
+			method: request.method ?? "GET",
+			headers,
+			...(request.body ? { body: JSON.stringify(request.body) } : {}),
+			signal: controller.signal,
+		});
 		if (controller.signal.aborted)
 			throw Object.assign(new Error("Usage query aborted."), { name: "AbortError" });
 		const text = await readBoundedResponse(

package/src/usage.ts

@@ -1,8 +1,24 @@
+import { randomUUID } from "node:crypto";
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import {
+	type CodexResetAvailability,
+	type CodexResetOption,
+	type CodexResetOutcome,
+	codexResetActionDescription,
+	codexResetCount,
+	consumeCodexResetCredit,
+	formatCodexResetOutcome,
+	genericCodexResetOption,
+	listCodexResetCredits,
+	resetConfirmationLines,
+	resetLabel,
+	resetOptionExpiration,
+	resolveCodexResetAuth,
+} from "./codex-resets.js";
 import {
 	awaitWithDeadline,
 	errorMessage,
@@ -38,6 +54,12 @@ const REFRESH_CURRENT = "Refresh current usage";
 const VIEW_ANOTHER = "View another configured provider…";
 const VIEW_ALL = "View all configured providers…";
 const CLOSE = "Close";
+const REDEEM_CODEX_RESET = "Redeem usage limit reset…";
+
+type UsageExtensionDependencies = {
+	credentialReader?: (providerId: string) => unknown;
+	createRedemptionId?: () => string;
+};
 
 type QueryOutcome = {
 	state: ProviderUsageState;
@@ -50,7 +72,12 @@ type StableCurrent = {
 	model: PiModel | undefined;
 };
 
-export default function usageExtension(pi: ExtensionAPI) {
+export default function usageExtension(
+	pi: ExtensionAPI,
+	dependencies: UsageExtensionDependencies = {},
+) {
+	const credentialReader = dependencies.credentialReader;
+	const createRedemptionId = dependencies.createRedemptionId ?? randomUUID;
 	const cache = new UsageCache(CACHE_TTL_MS);
 	const failureBackoff = new Map<string, { until: number; message: string }>();
 	const latestQueries = new Map<string, number>();
@@ -123,6 +150,16 @@ export default function usageExtension(pi: ExtensionAPI) {
 		if (shouldSchedule && sessionActive) scheduleStatusRefresh(ctx, model);
 	};
 
+	const invalidateProviderState = (providerId: string) => {
+		cache.clearProvider(providerId);
+		for (const key of failureBackoff.keys()) {
+			if (key.startsWith(`${providerId}:`)) failureBackoff.delete(key);
+		}
+		for (const key of latestQueries.keys()) {
+			if (key.startsWith(`${providerId}:`)) latestQueries.delete(key);
+		}
+	};
+
 	const transitionCurrentIdentity = (nextIdentity: string, providerId: string) => {
 		if (!activeCurrentIdentity || activeCurrentIdentity === nextIdentity) {
 			activeCurrentIdentity = nextIdentity;
@@ -130,14 +167,7 @@ export default function usageExtension(pi: ExtensionAPI) {
 		}
 		const previousProviderId = activeCurrentIdentity.split(":", 1)[0] ?? "";
 		for (const id of new Set([previousProviderId, providerId])) {
-			if (!id) continue;
-			cache.clearProvider(id);
-			for (const key of failureBackoff.keys()) {
-				if (key.startsWith(`${id}:`)) failureBackoff.delete(key);
-			}
-			for (const key of latestQueries.keys()) {
-				if (key.startsWith(`${id}:`)) latestQueries.delete(key);
-			}
+			if (id) invalidateProviderState(id);
 		}
 		activeCurrentIdentity = nextIdentity;
 	};
@@ -346,12 +376,14 @@ export default function usageExtension(pi: ExtensionAPI) {
 		label: string,
 		parentSignal: AbortSignal,
 		operation: (signal: AbortSignal) => Promise<T>,
+		cancellable = true,
 	): Promise<T | undefined> => {
 		const { runTask } = await import("@narumitw/pi-tui-kit");
 		if (parentSignal.aborted) return undefined;
 		const result = await runTask(ctx, {
 			label,
 			signal: parentSignal,
+			cancellable,
 			onError: () => undefined,
 			task: ({ signal }) => operation(signal),
 		});
@@ -465,10 +497,33 @@ export default function usageExtension(pi: ExtensionAPI) {
 			publishStableCurrent(ctx, stableCurrent);
 			let current = stableCurrent.outcome;
 			let visibleStates: ProviderUsageState[] = [current.state];
+			let resetAvailability: CodexResetAvailability | undefined;
+			let selectedReset: CodexResetOption | undefined;
+			let resetAuthFingerprint: string | undefined;
+			let resetModelIdentity: string | undefined;
+			let redemptionId: string | undefined;
+			let resetOutcome: CodexResetOutcome | undefined;
+			let resetFailure: string | undefined;
 			const { defineMenu, runMenu } = await import("@narumitw/pi-tui-kit");
 			if (controller.signal.aborted || statusGeneration !== menuGeneration) return;
-			type Screen = "main" | "providers";
-			type Action = "refresh" | "another" | "all" | "provider";
+			type Screen =
+				| "main"
+				| "providers"
+				| "reset-picker"
+				| "reset-confirm"
+				| "reset-result"
+				| "reset-error";
+			type Action =
+				| "refresh"
+				| "another"
+				| "all"
+				| "provider"
+				| "open-resets"
+				| "select-reset"
+				| "cancel-reset"
+				| "consume-reset"
+				| "back-to-usage"
+				| "back-to-resets";
 			const menu = defineMenu<undefined, Screen, Action, ExtensionCommandContext>({
 				start: "main",
 				screens: {
@@ -478,6 +533,17 @@ export default function usageExtension(pi: ExtensionAPI) {
 						lines: formatProviderStates(visibleStates).split("\n"),
 						items: [
 							{ id: "refresh", label: REFRESH_CURRENT, action: "refresh" },
+							...(current.state.status === "ready" && current.state.providerId === "openai-codex"
+								? [
+										{
+											id: "open-resets",
+											label: REDEEM_CODEX_RESET,
+											description: codexResetActionDescription(current.state.report),
+											disabled: codexResetCount(current.state.report) === 0,
+											action: "open-resets" as const,
+										},
+									]
+								: []),
 							{ id: "another", label: VIEW_ANOTHER, action: "another" },
 							{ id: "all", label: VIEW_ALL, action: "all" },
 							{ id: "close", label: CLOSE, close: true },
@@ -496,8 +562,219 @@ export default function usageExtension(pi: ExtensionAPI) {
 							})),
 						hint: "back",
 					}),
+					"reset-picker": () => ({
+						kind: "choice",
+						title: "Usage limit resets",
+						lines: [
+							`${resetAvailability?.availableCount ?? 0} ${resetLabel(resetAvailability?.availableCount ?? 0)} available.`,
+						],
+						items: (resetAvailability?.options ?? []).map((option, index) => ({
+							id: `reset-${index}`,
+							label: option.title,
+							description: resetOptionExpiration(option),
+							details: [option.description],
+						})),
+						action: "select-reset",
+						initialItemId: "reset-0",
+						hint: "back",
+					}),
+					"reset-confirm": () => ({
+						kind: "actions",
+						title: "Use this reset?",
+						lines: resetConfirmationLines(selectedReset),
+						items: [
+							{ id: "cancel-reset", label: "No, go back", action: "cancel-reset" },
+							{ id: "consume-reset", label: "Yes, use reset", action: "consume-reset" },
+						],
+						hint: "back",
+					}),
+					"reset-result": () => ({
+						kind: "actions",
+						title: "Usage limit resets",
+						lines: [
+							formatCodexResetOutcome(
+								resetOutcome,
+								current.state.status === "ready"
+									? codexResetCount(current.state.report)
+									: undefined,
+							),
+						],
+						items: [
+							{
+								id: "back-to-usage",
+								label: "Back to usage",
+								action: "back-to-usage",
+							},
+							{ id: "close", label: CLOSE, close: true },
+						],
+						hint: "back",
+					}),
+					"reset-error": () => ({
+						kind: "actions",
+						title: "Usage limit resets",
+						lines: [resetFailure ?? "Couldn't reset usage. Please try again."],
+						items: [
+							{ id: "consume-reset", label: "Try again", action: "consume-reset" },
+							{ id: "back-to-resets", label: "Back", action: "back-to-resets" },
+						],
+						hint: "back",
+					}),
 				},
 				actions: {
+					"open-resets": async () => {
+						const summaryCount =
+							current.state.status === "ready" && current.state.providerId === "openai-codex"
+								? codexResetCount(current.state.report)
+								: undefined;
+						try {
+							const loaded = await runMenuOperation(
+								ctx,
+								"Checking usage limit resets…",
+								controller.signal,
+								async (signal) => {
+									const expectedModel = modelIdentity(ctx.model);
+									const auth = await awaitWithDeadline(
+										resolveCodexResetAuth(ctx, undefined, credentialReader),
+										signal,
+										DEFAULT_TIMEOUT_MS,
+										"resolving current Codex reset authentication",
+									);
+									let availability: CodexResetAvailability;
+									try {
+										availability = await listCodexResetCredits(auth, signal, DEFAULT_TIMEOUT_MS);
+									} catch (error) {
+										if (isAbortError(error) || summaryCount === undefined || summaryCount <= 0) {
+											throw error;
+										}
+										availability = {
+											availableCount: summaryCount,
+											options: [genericCodexResetOption()],
+										};
+									}
+									const revalidated = await awaitWithDeadline(
+										resolveCodexResetAuth(ctx, undefined, credentialReader),
+										signal,
+										DEFAULT_TIMEOUT_MS,
+										"revalidating current Codex reset authentication",
+									);
+									if (
+										modelIdentity(ctx.model) !== expectedModel ||
+										revalidated.fingerprint !== auth.fingerprint
+									) {
+										throw new Error(
+											"The active Codex model or account changed while loading usage limit resets.",
+										);
+									}
+									return { availability, auth, expectedModel };
+								},
+							);
+							if (!loaded) return { kind: "stay" };
+							resetAvailability = loaded.availability;
+							resetAuthFingerprint = loaded.auth.fingerprint;
+							resetModelIdentity = loaded.expectedModel;
+							selectedReset = undefined;
+							redemptionId = undefined;
+							resetOutcome = undefined;
+							resetFailure = undefined;
+							return {
+								kind: "to",
+								screen: loaded.availability.availableCount > 0 ? "reset-picker" : "reset-result",
+							};
+						} catch (error) {
+							if (isAbortError(error) || isStaleExtensionContextError(error)) {
+								return { kind: "stay" };
+							}
+							ctx.ui.notify(`Couldn't load usage limit resets: ${errorMessage(error)}`, "error");
+							return { kind: "stay" };
+						}
+					},
+					"select-reset": ({ itemId }) => {
+						const index = Number(itemId.replace(/^reset-/u, ""));
+						const option = Number.isSafeInteger(index)
+							? resetAvailability?.options[index]
+							: undefined;
+						if (!option) return { kind: "rejected" };
+						selectedReset = option;
+						redemptionId = undefined;
+						resetFailure = undefined;
+						return { kind: "to", screen: "reset-confirm" };
+					},
+					"cancel-reset": () => ({ kind: "back" }),
+					"consume-reset": async () => {
+						if (!selectedReset || !resetAuthFingerprint || !resetModelIdentity) {
+							return { kind: "rejected" };
+						}
+						try {
+							redemptionId ??= createRedemptionId();
+							const attemptId = redemptionId;
+							const option = selectedReset;
+							const expectedFingerprint = resetAuthFingerprint;
+							const expectedModel = resetModelIdentity;
+							const result = await runMenuOperation(
+								ctx,
+								"Resetting your usage…",
+								controller.signal,
+								async (signal) => {
+									const auth = await awaitWithDeadline(
+										resolveCodexResetAuth(ctx, undefined, credentialReader),
+										signal,
+										DEFAULT_TIMEOUT_MS,
+										"revalidating current Codex reset authentication",
+									);
+									if (
+										modelIdentity(ctx.model) !== expectedModel ||
+										auth.fingerprint !== expectedFingerprint
+									) {
+										throw new Error(
+											"The active Codex model or account changed; the reset was not used.",
+										);
+									}
+									const outcome = await consumeCodexResetCredit(
+										auth,
+										option,
+										attemptId,
+										signal,
+										DEFAULT_TIMEOUT_MS,
+									);
+									invalidateProviderState("openai-codex");
+									const model = ctx.model;
+									if (modelIdentity(model) !== expectedModel) return { outcome };
+									const refreshed = await queryCurrentState(ctx, model, true, signal);
+									const stable = await outcomeStillCurrent(
+										ctx,
+										model,
+										menuGeneration,
+										refreshed,
+										signal,
+									);
+									return stable ? { outcome, refreshed, model } : { outcome };
+								},
+								false,
+							);
+							if (!result) return { kind: "close" };
+							resetOutcome = result.outcome;
+							resetFailure = undefined;
+							if (result.refreshed && result.model) {
+								stableCurrent = { outcome: result.refreshed, model: result.model };
+								current = result.refreshed;
+								visibleStates = [current.state];
+								publishStableCurrent(ctx, stableCurrent);
+							}
+							return { kind: "to", screen: "reset-result" };
+						} catch (error) {
+							if (isAbortError(error) || isStaleExtensionContextError(error)) {
+								return { kind: "close" };
+							}
+							resetFailure = `Couldn't reset usage: ${errorMessage(error)}. Try again with the same request.`;
+							return { kind: "to", screen: "reset-error" };
+						}
+					},
+					"back-to-usage": () => ({ kind: "to", screen: "main" }),
+					"back-to-resets": () => {
+						redemptionId = undefined;
+						resetFailure = undefined;
+						return { kind: "to", screen: "reset-picker" };
+					},
 					refresh: async () => {
 						const refreshed = await queryStableCurrent(
 							ctx,
@@ -633,6 +910,11 @@ export default function usageExtension(pi: ExtensionAPI) {
 	});
 
 	pi.on("session_start", (_event, ctx) => {
+		statusGeneration += 1;
+		clearStatusTimer();
+		for (const controller of activeControllers) controller.abort();
+		activeControllers.clear();
+		statusController = undefined;
 		sessionActive = true;
 		startStatusRefresh(ctx, ctx.model, false);
 	});