osdy-pi 1.11.11 → 1.11.12

package/README.md

@@ -8,6 +8,8 @@ Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive te
 
 **The Control Center consolidates Osdy controls in `/osdyConfig`**: ten categories cover appearance, Git, sounds, accounts, usage, and TODO/Agents provider settings. Account quota previews query a selected stored Codex profile without switching it. The header shows the installed Osdy package version when it fits; constrained layouts show only the centered mascot. See [Control Center in Pi](#control-center-in-pi) for confirmation and persistence boundaries.
 
+**Codex banked resets show counts and per-reset local expiry** in `/usage` and the Control Center. Press **u** in `/usage` or select **Usage → Use or check banked reset** for Cancel-first, active-account use or pending-attempt checks; stored-profile previews stay read-only. See [Use or check a banked reset](#use-or-check-a-banked-reset).
+
 **1.11.0 adds three Spider-Man-inspired dark palettes**, bringing the bundle to **23 themes**. It retains the four-page local usage analytics introduced in 1.10.0, with shared period and profile/provider/model filters, keyboard navigation, and metadata-only history. These version introductions are historical, not a fixed latest-version claim. After npm Trusted Publishing is configured, pushes to main (including direct pushes) run checks and attempt to publish an automatically allocated patch to npm. Failed checks publish nothing; authentication or registry failures can also stop publication. Verify the resolved npm version before installing. Maintainers: [automatic npm publishing setup](https://github.com/OsdyOrtiz/Osdy-Pi/blob/main/docs/npm-publishing.md).
 
 | Area | What ships |
@@ -70,6 +72,10 @@ On macOS, **Option = Alt** in Pi's shortcut names: these bindings register as `c
 
 Ctrl+Option+U opens the existing `/usage` dashboard with the same refresh behavior; it does not open `/osdy-usage`.
 
+When Codex reports an available banked reset count, `/usage`, **Account → View usage**, and the **Usage** category show **Banked resets: N**, including zero. Unknown counts are omitted. Banked resets are separate from paid **Credits** and legacy **Credit resets**; local analytics filters do not change the count. Displaying it never consumes a reset or changes the compact footer.
+
+Positive counts also trigger a best-effort read-only reset-details GET within the same timeout budget. Dashboards label listed resets **Reset 1:**, **Reset 2:**, and so on, with expiry date/time in your machine's **local timezone**; the Usage count row includes these lines in its expanded help (`?`). Missing or invalid expiry shows **Expiry not provided**. Past dates show **expired** with **(cached; local time)** and are excluded from new-reset selection. **Reset expiry details unavailable** or **Partial expiry details: M of N resets listed** identifies missing or incomplete details. The usage summary remains the count authority even when details are empty, capped, inconsistent, or fail. Quotas and the count remain visible on details failure.
+
 - Use **↑/↓**, **Home/End**, or **Page Up/Down** to navigate; **Tab** or **←/→** switches between categories and details. **Enter** selects. Single blank lines separate the heading, summary, compact options, selected-item help, status, and action hints—not individual options. Gaps yield on short viewports so the selected option and controls remain reachable. Press **?** to expand/collapse the selected help and view notes; resize if expanded help is clipped. Confirmation effects remain complete, and **?** never toggles help during confirmation, path editing, loading, querying, or saving.
 - TODO shows configured selection, current eligibility, and actually loaded SDK registration separately. Opt-in/out requires an idle session and a Cancel-first inline confirmation naming the target, owned Gentle filter effects, and reload. Successful selection closes/disposes the panel and releases its editor hold before automatic command reload or the Ctrl+Option+O manual-reload notice described above; restart Pi if reload fails. Rejections stay in the panel. No installs or task-history changes occur; legacy `/osdy-pi todo on|off|status` remains available.
 - Agents shows concise **Joker / Gentle** choices without activating anything. With detail focus, visible lowercase-only **j Joker / g Gentle** letters open the existing confirmation directly; only available, unambiguous rows get shortcuts. **↑/↓ + Enter** remains the fallback. Profile and Agent selections survive category navigation; unavailable choices fall back to the current row. Letters never bypass category focus, confirmation, path input, loading, querying, or saving. Selection is idle-only and Cancel-first confirmed, naming the real target, possible Joker installation, owned agent filters, and preserved unrelated resources. Normal personal Pi only: `pi:dev` and isolated/override sessions are blocked, never redirected to personal settings. Success closes/disposes the panel and releases its editor hold before automatic command reload or the Ctrl+Option+O manual-reload notice described above; restart Pi if reload fails. Legacy `/osdy-pi agents setup|on|off|status` is unchanged.
@@ -81,7 +87,7 @@ Ctrl+Option+U opens the existing `/usage` dashboard with the same refresh behavi
 - **Sounds** shows each event's saved and effective path/source. Configure opens a single-line path editor **inside this overlay**: enter a readable `.mp3`/`.wav` path, then **Enter** to validate and save immediately, or **Esc** to cancel editing. Relative paths resolve against the project directory and save as absolute paths. Clear removes only that event's saved path from the existing v1 audio store (`<agent-dir>/extensions/osdy-pi/audio-notifications.json`). Notifications read this store afresh; refresh failures are reported separately from save failures.
 - Sounds' master enablement is **unavailable**: the existing schema has paths, not an enable switch or presets. Startup `--osdy-pi-sound-<event>` flags override saved paths, so **clearing a saved path does not disable flag-configured playback**. Only **Test effective** explicitly plays a sound; opening categories and configuring paths never play. Tests report unavailable files/platforms or playback failures; playback remains macOS/Windows only. The legacy `/osdy-pi sound setup` wizard is preserved.
 - **Account** shows one row per validated profile, marked **Active** and **Default** where applicable. Select a profile, then use its visible context bar: **v View usage**, **s Switch** (inactive profiles), **d Set default**, and **c Clear default** (when a default exists). **v** or **Enter** explicitly queries that profile's stored Codex credentials without activating it; no second action list appears. Opening, navigating or highlighting never queries; stored profiles are never polled. A dedicated quota view reuses `/usage` dashboard content: Session/Weekly cards, additional bucket groups, remaining-capacity bars, resets, and the quotas/account summary with plan and credits when available. Identity belongs to the selected stored profile; unknown provider/model metadata is labeled honestly. Checked and updated times use local time; absent data is unknown, not zero. Refresh/Back controls and query feedback stay pinned while long dashboard content scrolls. **r Refresh** repeats the selected profile query; **s Switch**, when available, confirms activation of the currently viewed inactive profile. Cancelling that confirmation preserves the quota view and scroll position. **b Back** or **Esc** returns to the overview with the profile selected, without closing the overlay. In quota details, **↑/↓** selects Refresh/Back and **Enter** activates it; **Page Up/Down** and **Home/End** scroll long quota data. Switch, set default, and clear default require an **in-screen confirmation** with Cancel selected initially; **Esc** cancels confirmation without closing the overlay. Single blank separators group the confirmation title, complete effects, choices, and instructions; gaps yield on short viewports. Resize if the full confirmation cannot fit—acceptance stays hidden and blocked. Switching through `/osdyConfig` waits for Pi to become idle; Ctrl+Option+O refuses busy account changes. Successful switching activates through the existing backend and refreshes subscription usage. Login remains Pi-owned (`/login`); create/rename/remove remain available in `/osdy-account`. Category navigation never changes profiles or credentials.
-- **Usage** shows the runtime's cached active Codex subscription quota (remaining-capacity bars and percentages, window, reset/fetch times) and the existing local history owner's recorded token/cache totals, cost gaps, and model detail. Select **Range: day/week/month** for the current local calendar period; toggle **Accounts: all/current** for local analytics (unmanaged when no valid current profile exists). Quota always belongs to the active account, not the analytics filter; local token/cost totals never become quota percentages. Select **Refresh quota and local history** explicitly; rendering and filters never fetch. Empty, loading, unavailable, and limited/incomplete coverage are reported honestly. Estimates are not billing or subscription quota. `/usage` and `/osdy-usage` remain unchanged.
+- **Usage** shows the runtime's cached active Codex subscription quota (remaining-capacity bars and percentages, window, reset/fetch times) and the existing local history owner's recorded token/cache totals, cost gaps, and model detail. Select **Range: day/week/month** for the current local calendar period; toggle **Accounts: all/current** for local analytics (unmanaged when no valid current profile exists). Quota always belongs to the active account, not the analytics filter; local token/cost totals never become quota percentages. Select **Refresh quota and local history** explicitly; rendering and filters never fetch. Empty, loading, unavailable, and limited/incomplete coverage are reported honestly. Estimates are not billing or subscription quota. `/usage` remains the subscription dashboard; `/osdy-usage` remains local analytics.
 - **Esc** closes without undoing live or saved changes, except when cancelling a confirmation/input or returning from Account quota details. Account read-only queries are cancelled on Back/Esc, category exit or close; late results are ignored even if cancellation is not honored. Other in-flight operations still finish and are not claimed cancelled. Late results cannot replace a closed overlay or another category. On narrow terminals, categories and details share the viewport; use Tab to switch.
 
 This modal requires Pi's terminal UI, not RPC, JSON, or print mode. `/osdy-pi` remains the legacy extension command; the external shell command `osdy` (`bin/osdy.mjs`) remains the isolated launcher described below.
@@ -229,7 +235,7 @@ For a project-local installation, run `pi remove -l npm:@juicesharp/rpiv-todo` i
 
 **Quick path:** `/osdyConfig` → **Account** → select a profile → **v** (or **Enter**) for quota bars. Use **r Refresh** to query again or **b Back** / **Esc** to return with the profile selected. From the overview or quota dashboard, **s Switch** opens the same Cancel-first confirmation for the eligible inactive profile; cancelling from quota preserves the view and scroll position. From the overview, **d** sets the default and **c** clears an existing default, also with Cancel-first confirmation. The active profile also supports explicit stored-credential queries.
 
-Preview is **Codex only**, a live query using the selected profile's **stored credentials snapshot**, with no automatic refresh or stored-profile polling. Only **View usage** and the quota view's **Refresh** query; profile navigation does not. It never activates, borrows active credentials, refreshes tokens, writes auth, changes models/session state or overwrites active quota. Missing, malformed, expired or remotely rejected snapshots are unavailable—not zero quota. Even the current profile's stored snapshot may be stale: log in and save through the normal account workflow outside preview. Profile labels and decoded JWT claims do not verify human identity or server validity. Local history remains token/cost estimates, not subscription quota. Legacy `/osdy-account`, `/usage` and `/osdy-usage` remain unchanged; Agents configuration remains normal personal Pi only.
+Preview is **Codex only**, a live query using the selected profile's **stored credentials snapshot**, with no automatic refresh or stored-profile polling. Only **View usage** and the quota view's **Refresh** query; profile navigation does not. It never activates, borrows active credentials, refreshes tokens, writes auth, changes models/session state or overwrites active quota. Missing, malformed, expired or remotely rejected snapshots are unavailable—not zero quota. Even the current profile's stored snapshot may be stale: log in and save through the normal account workflow outside preview. Profile labels and decoded JWT claims do not verify human identity or server validity. Local history remains token/cost estimates, not subscription quota. Legacy `/osdy-account`, `/usage` and `/osdy-usage` remain available; Agents configuration remains normal personal Pi only.
 
 Osdy Pi can keep multiple ChatGPT Plus/Pro accounts authenticated and let you choose which one starts Pi. `personal` and `work` are only examples—you can create as many named profiles as you need.
 
@@ -294,7 +300,7 @@ To resume a specific session directly from the terminal:
 osdy-pi account use work -- --session /absolute/path/to/session.jsonl
 ```
 
-> **Privacy:** each profile keeps a private `auth.json`; Pi runs against its canonical shared `auth.json`. Account activation/preservation atomically copies opaque auth files. The separate explicit Account **View usage / Refresh** query reads a bounded stored auth snapshot, parses its Codex OAuth fields and unverified JWT claims, and sends the access token/account ID only to the fixed HTTPS Codex usage endpoint. It never refreshes tokens, logs in, switches accounts, writes auth, or queries automatically; it does not print or log credentials. Session history, settings, installed packages, and extension resources are shared, so every profile can access that local state. It keeps Pi's canonical `openai-codex` provider and delegates authentication to Pi's built-in `/login` flow.
+> **Privacy:** each profile keeps a private `auth.json`; Pi runs against its canonical shared `auth.json`. Account activation/preservation atomically copies opaque auth files. The separate explicit Account **View usage / Refresh** query reads a bounded stored auth snapshot, parses its Codex OAuth fields and unverified JWT claims, and sends the access token/account ID only to the fixed HTTPS Codex usage and optional reset-details endpoints. It never refreshes tokens, logs in, switches accounts, writes auth, or queries automatically; it does not print or log credentials. Session history, settings, installed packages, and extension resources are shared, so every profile can access that local state. It keeps Pi's canonical `openai-codex` provider and delegates authentication to Pi's built-in `/login` flow.
 
 Account switching is serialized in-process and protected by a private cross-process lock. Osdy Pi accepts only bounded regular auth files, refuses symlink-based auth sources, writes replacements with private permissions, and restores the previous canonical auth and account metadata when activation fails. A separate namespace lock protects concurrent profile creation, rename, and removal. Launchers activate the selected auth before starting Pi while continuing to use the shared agent directory; existing managed-directory links from earlier profile layouts are resolved for compatibility.
 
@@ -446,7 +452,17 @@ Active quota loads when an enabled session starts and refreshes when **Ctrl+Opti
 
 Automatic refresh retains the last snapshot during loading and on error, so an older reading can remain visible until a successful query replaces it. Manual refresh clears the previous snapshot before authentication resolves and supersedes any in-flight automatic request. Account switching refreshes active quota through that same clearing path. Session replacement and shutdown stop the timer, cancel pending requests and clear quota state; late results are ignored.
 
-> **Privacy:** this active-account `/usage` path resolves OAuth through Pi's `modelRegistry`, rather than directly reading auth files. The separate Control Center Account **View usage / Refresh** path reads the selected profile's bounded stored credentials snapshot; it never borrows active credentials or refreshes tokens, logs in, switches accounts, writes auth, or queries automatically. Both paths transmit the access token/account ID only to the fixed HTTPS Codex usage endpoint, reject redirects, and bound timeout and response size. Quota previews do not persist or log credentials or display account IDs, tokens, raw response bodies, or endpoint internals.
+> **Privacy:** this active-account `/usage` path resolves OAuth through Pi's `modelRegistry`, rather than directly reading auth files. The separate Control Center Account **View usage / Refresh** path reads the selected profile's bounded stored credentials snapshot; it never borrows active credentials or refreshes tokens, logs in, switches accounts, writes auth, or queries automatically. Both paths transmit the access token/account ID only to the fixed HTTPS Codex usage and optional reset-details endpoints, reject redirects, and bound timeout and response size. Quota previews do not persist or log credentials or display account IDs, tokens, raw response bodies, or endpoint internals. Only an explicitly selected and confirmed active-account reset additionally POSTs to the fixed Codex reset-consume endpoint.
+
+#### Use or check a banked reset
+
+1. In `/usage`, press **u**; or select **Usage → Use or check banked reset** in `/osdyConfig`. Account → View usage remains read-only, including previews of the current profile.
+2. The overlay closes first. Choose an indexed reset with its **local expiry date/time** (or **Expiry not provided**), then explicitly select **Use reset**. **Cancel is first**; Cancel/Esc sends nothing. The confirmation affects only the **active Codex account** and explains that a successful reset consumes one banked reset. Auth/account/session are checked again before POST.
+3. `/usage` reopens with the result snapshot if the same context remains active; Control Center exits, so reopen Usage to inspect it. A failed quota refresh or local bookkeeping failure is reported separately from a confirmed server outcome. `no_credit` and `nothing_to_reset` do not consume a reset; `already_redeemed` confirms prior success.
+
+**Unknown outcome:** do not start another reset or infer success from a changed count. Use **u** or the Usage row again and explicitly choose **Check pending attempt** to recheck the **same stored request UUID and reset ID**, which may finish an earlier unconfirmed reset—not start a new attempt. A private, durable local pending journal stores attempt identifiers, never credentials; reload does not automatically retry or replay it. Checking remains available with active Codex authentication even when the displayed count is zero or quota is unavailable.
+
+**Blocked storage/lock:** stop for manual verification of the previous attempt and any other running Pi process. Lock acquisition or pre-dispatch journal-save failure prevents a reset POST. Locks are not automatically reclaimed, even when apparently stale; orphaned locks can require manual recovery. There is no automatic lock cleanup or guarantee of perfect crash recovery. This flow has mocked transport tests, not live API, real-reset, or manual TUI verification.
 
 ### Local usage analytics (starting in 1.10.0)
 
@@ -461,7 +477,7 @@ Run `/osdy-usage` in interactive terminal Pi. **Summary** opens by default; use
 
 Narrow terminals stack metrics and wrap names; every group remains reachable by scrolling. Shares use the selected total tokens; bars scale to each ranking's maximum. Loading, stale, scan-limit/warning and unpriced/partial-cost states remain on every page and in help. Sticky status lines wrap instead of concealing cost status behind scan warnings, including at End. When height is scarce, statuses take priority over optional headings, charts and footer controls; the active page remains visible when space permits. Press `?` for methodology and full controls, then `?` again to return. Choosing a page also leaves help without discarding filters.
 
-This is separate from the unchanged `/usage` subscription quota panel. RPC, JSON and print modes receive a short notification instead of charts. The four-page UI passed independent scripted synthetic PTY checks for navigation, shared selection and responsive statuses at 12/32/100 columns, including a five-row terminal. Human visual confirmation and provider-backed capture remain unverified.
+This is separate from the `/usage` subscription quota panel. RPC, JSON and print modes receive a short notification instead of charts. The four-page UI passed independent scripted synthetic PTY checks for navigation, shared selection and responsive statuses at 12/32/100 columns, including a five-row terminal. Human visual confirmation and provider-backed capture remain unverified.
 
 | Control | Action |
 | --- | --- |

package/extensions/osdy-pi/codex-reset-store.test.ts

@@ -0,0 +1,236 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { chmod, mkdtemp, open, readFile, readdir, rm, stat, symlink, writeFile } from "node:fs/promises";
+import type { FileHandle } from "node:fs/promises";
+import { registerHooks } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+registerHooks({
+	resolve(specifier, context, nextResolve) {
+		if (specifier.startsWith(".") && specifier.endsWith(".js") && context.parentURL?.endsWith(".ts")) {
+			const url = new URL(`${specifier.slice(0, -3)}.ts`, context.parentURL);
+			if (existsSync(fileURLToPath(url))) return { shortCircuit: true, url: url.href };
+		}
+		return nextResolve(specifier, context);
+	},
+});
+
+const { createCodexResetStore } = await import("./codex-reset-store.js");
+const accountId = "synthetic-account/../not-a-path";
+const pending = {
+	version: 1 as const, accountId, creditId: "synthetic-credit",
+	requestId: "11111111-1111-4111-8111-111111111111", expiresAt: 2_000, status: "pending" as const,
+};
+const basename = createHash("sha256").update(accountId).digest("hex");
+
+async function fixture(t: test.TestContext) {
+	const directory = await mkdtemp(join(tmpdir(), "osdy-reset-test-"));
+	t.after(() => rm(directory, { recursive: true, force: true })); // Only this synthetic fixture.
+	const root = join(directory, "journal");
+	return { root, store: createCodexResetStore(root) };
+}
+
+void test("private hashed journals round-trip and resolved attempts permit a new request", async (t) => {
+	const { root, store } = await fixture(t);
+	const lease = await store.acquire(accountId);
+	assert.equal(await lease.read(), undefined);
+	await lease.write(pending);
+	assert.deepEqual(await lease.read(), pending);
+	assert.equal((await stat(root)).mode & 0o777, 0o700);
+	for (const name of await readdir(root)) {
+		assert.match(name, /^[a-f0-9]{64}\.(json|lock)$/);
+		assert.equal((await stat(join(root, name))).mode & 0o777, 0o600);
+	}
+	assert.equal((await readFile(join(root, `${basename}.json`), "utf8")).includes("accessToken"), false);
+	await lease.write({ ...pending, status: "resolved", confirmedCode: "reset" });
+	await lease.write({ ...pending, requestId: "22222222-2222-4222-8222-222222222222" });
+	await lease.release();
+	const restored = await store.acquire(accountId);
+	assert.equal((await restored.read())?.requestId, "22222222-2222-4222-8222-222222222222");
+	await restored.release();
+	assert.deepEqual(await readdir(root), [`${basename}.json`]);
+});
+
+void test("account leases are exclusive, isolate accounts, and never reclaim existing stale locks", async (t) => {
+	const { root, store } = await fixture(t);
+	const lease = await store.acquire(accountId);
+	await assert.rejects(store.acquire(accountId), /^Error: Codex reset journal is unavailable$/);
+	const other = await store.acquire("synthetic-other");
+	assert.equal(await other.read(), undefined);
+	await lease.write(pending);
+	assert.equal(await other.read(), undefined);
+	await other.release();
+	await lease.release();
+	await writeFile(join(root, `${basename}.lock`), "", { mode: 0o600 });
+	await assert.rejects(store.acquire(accountId), /^Error: Codex reset journal is unavailable$/);
+	assert.equal(await readFile(join(root, `${basename}.lock`), "utf8"), "");
+});
+
+for (const content of [
+	"{broken", "x".repeat(8_193), JSON.stringify({ ...pending, version: 2 }),
+	JSON.stringify({ ...pending, accountId: "wrong-account" }), JSON.stringify({ ...pending, requestId: "bad" }),
+	JSON.stringify({ ...pending, expiresAt: -1 }), JSON.stringify({ ...pending, accessToken: "forbidden" }),
+	JSON.stringify({ ...pending, status: "resolved", confirmedCode: "invented" }),
+	JSON.stringify({ ...pending, status: "pending", confirmedCode: "reset" }),
+]) {
+	void test(`rejects corrupt or unbounded journal fixture ${content.length}:${content.slice(0, 12)}`, async (t) => {
+		const { root, store } = await fixture(t);
+		const lease = await store.acquire(accountId);
+		await writeFile(join(root, `${basename}.json`), content, { mode: 0o600 });
+		await assert.rejects(lease.read(), /^Error: Codex reset journal is unavailable$/);
+		await lease.release();
+	});
+}
+
+void test("refuses final-file symlinks on both read and atomic write, preserving the target", async (t) => {
+	const { root, store } = await fixture(t);
+	const lease = await store.acquire(accountId);
+	const target = join(root, "synthetic-target");
+	await writeFile(target, "untouched", { mode: 0o600 });
+	await symlink(target, join(root, `${basename}.json`));
+	await assert.rejects(lease.read());
+	await assert.rejects(lease.write(pending));
+	assert.equal(await readFile(target, "utf8"), "untouched");
+	await lease.release();
+	assert.equal((await readdir(root)).some((name) => name.endsWith(".tmp")), false);
+});
+
+void test("refuses symlink roots and non-private journal files or directories", async (t) => {
+	const { root, store } = await fixture(t);
+	const lease = await store.acquire(accountId);
+	await lease.write(pending);
+	await chmod(join(root, `${basename}.json`), 0o644);
+	await assert.rejects(lease.read());
+	await lease.release();
+	await chmod(root, 0o755);
+	await assert.rejects(store.acquire(accountId));
+	const link = `${root}-link`;
+	await symlink(root, link);
+	await assert.rejects(createCodexResetStore(link).acquire(accountId));
+});
+
+void test("validation/write failure cannot replace pending; terminal outcomes must match the logical attempt", async (t) => {
+	const { root, store } = await fixture(t);
+	const lease = await store.acquire(accountId);
+	await lease.write(pending);
+	await assert.rejects(lease.write({ ...pending, creditId: "different" }));
+	await assert.rejects(lease.write({ ...pending, status: "resolved", requestId: "22222222-2222-4222-8222-222222222222" }));
+	await assert.rejects(lease.write({ ...pending, creditId: "x".repeat(8_193) }));
+	assert.deepEqual(await lease.read(), pending);
+	assert.equal((await readdir(root)).some((name) => name.endsWith(".tmp")), false);
+	await lease.write({ ...pending, status: "resolved" }); // Definitely not sent.
+	await lease.release();
+});
+
+void test("invalid UTF-8 must not silently change an opaque stored credit ID", async (t) => {
+	const { root, store } = await fixture(t);
+	const lease = await store.acquire(accountId);
+	const content = Buffer.from(JSON.stringify(pending));
+	content[content.indexOf("synthetic-credit")] = 0xff;
+	await writeFile(join(root, `${basename}.json`), content, { mode: 0o600 });
+	await assert.rejects(lease.read());
+	await lease.release();
+});
+
+void test("resolved request IDs cannot be reused for a new logical attempt", async (t) => {
+	const { store } = await fixture(t);
+	const lease = await store.acquire(accountId);
+	await lease.write(pending);
+	await lease.write({ ...pending, status: "resolved", confirmedCode: "reset" });
+	await assert.rejects(lease.write(pending));
+	await lease.release();
+});
+
+async function fileHandlePrototype(root: string): Promise<FileHandle> {
+	const probe = await open(join(root, "synthetic-probe"), "wx", 0o600);
+	const prototype = Object.getPrototypeOf(probe) as FileHandle;
+	await probe.close();
+	return prototype;
+}
+
+void test("failed temporary write leaves pending intact and cleans only its own temporary file", async (t) => {
+	const { root, store } = await fixture(t);
+	const lease = await store.acquire(accountId);
+	await lease.write(pending);
+	const prototype = await fileHandlePrototype(root);
+	const fault = t.mock.method(prototype, "writeFile", () => Promise.reject(new Error("synthetic write fault")));
+	await assert.rejects(lease.write({ ...pending, status: "resolved", confirmedCode: "reset" }));
+	fault.mock.restore();
+	assert.deepEqual(await lease.read(), pending);
+	assert.equal((await readdir(root)).some((name) => name.endsWith(".tmp")), false);
+	await lease.release();
+});
+
+for (const restoreFails of [false, true]) {
+	void test(`post-rename terminal fsync failure restores pending or retains lock (${restoreFails})`, async (t) => {
+		const { root, store } = await fixture(t);
+		const lease = await store.acquire(accountId);
+		await lease.write(pending);
+		const prototype = await fileHandlePrototype(root);
+		const original = Reflect.get(prototype, "sync");
+		let directorySyncs = 0;
+		const fault = t.mock.method(prototype, "sync", async function (this: FileHandle) {
+			if ((await this.stat()).isDirectory() && (++directorySyncs === 1 || restoreFails)) throw new Error("synthetic fsync fault");
+			await original.call(this);
+		});
+		await assert.rejects(lease.write({ ...pending, status: "resolved", confirmedCode: "reset" }));
+		fault.mock.restore();
+		assert.deepEqual(JSON.parse(await readFile(join(root, `${basename}.json`), "utf8")) as unknown, pending);
+		if (restoreFails) {
+			await assert.rejects(lease.release());
+			await assert.rejects(store.acquire(accountId));
+		} else {
+			await lease.release();
+			const next = await store.acquire(accountId);
+			assert.deepEqual(await next.read(), pending);
+			await next.release();
+		}
+		assert.equal((await readdir(root)).some((name) => name.endsWith(".tmp")), false);
+	});
+}
+
+void test("accepts the byte limit but never reads beyond it", async (t) => {
+	const { root, store } = await fixture(t);
+	const lease = await store.acquire(accountId);
+	const serialized = JSON.stringify(pending);
+	await writeFile(join(root, `${basename}.json`), serialized.padEnd(8_192, " "), { mode: 0o600 });
+	assert.deepEqual(await lease.read(), pending);
+	await writeFile(join(root, `${basename}.json`), serialized.padEnd(8_193, " "), { mode: 0o600 });
+	await assert.rejects(lease.read());
+	await lease.release();
+});
+
+void test("no terminal record without pending, no operations after lease release", async (t) => {
+	const { store } = await fixture(t);
+	const lease = await store.acquire(accountId);
+	await assert.rejects(lease.write({ ...pending, status: "resolved", confirmedCode: "reset" }));
+	assert.equal(await lease.read(), undefined);
+	await lease.release();
+	await assert.rejects(lease.read());
+	await assert.rejects(lease.write(pending));
+});
+
+void test("write snapshots validated fields before asynchronous IO and cannot serialize inherited credentials", async (t) => {
+	const { root, store } = await fixture(t);
+	const lease = await store.acquire(accountId);
+	const input = { ...pending };
+	Object.setPrototypeOf(input, { toJSON: () => ({ ...pending, accessToken: "synthetic-forbidden" }) });
+	const saving = lease.write(input);
+	Object.assign(input, { creditId: "x".repeat(8_193), accessToken: "synthetic-forbidden" });
+	await saving;
+	assert.deepEqual(await lease.read(), pending);
+	assert.equal((await readFile(join(root, `${basename}.json`), "utf8")).includes("synthetic-forbidden"), false);
+	await lease.release();
+});
+
+void test("lock release failure is generic and refuses a subsequent lease", async (t) => {
+	const { root, store } = await fixture(t);
+	const lease = await store.acquire(accountId);
+	await chmod(join(root, `${basename}.lock`), 0o644);
+	await assert.rejects(lease.release(), /^Error: Codex reset journal is unavailable$/);
+	await assert.rejects(store.acquire(accountId));
+});

package/extensions/osdy-pi/codex-reset-store.ts

@@ -0,0 +1,174 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rename, unlink } from "node:fs/promises";
+import type { FileHandle } from "node:fs/promises";
+import { join } from "node:path";
+import type { ConsumeCodexResetCode } from "./codex-usage.js";
+
+/** Resolved without confirmedCode means definitely not sent, never inferred from GET. */
+export type CodexResetRecord = {
+	version: 1;
+	accountId: string;
+	creditId: string;
+	requestId: string;
+	expiresAt?: number;
+} & ({ status: "pending" } | { status: "resolved"; confirmedCode?: ConsumeCodexResetCode });
+
+export type CodexResetLease = {
+	read(): Promise<CodexResetRecord | undefined>;
+	write(record: CodexResetRecord): Promise<void>;
+	release(): Promise<void>;
+};
+
+export type CodexResetStore = { acquire(accountId: string): Promise<CodexResetLease> };
+
+const MAX_BYTES = 8_192;
+const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+const CODES = new Set(["reset", "nothing_to_reset", "no_credit", "already_redeemed"]);
+const unavailable = () => new Error("Codex reset journal is unavailable");
+const isMissing = (error: unknown) => !!error && typeof error === "object" && "code" in error && error.code === "ENOENT";
+const validId = (value: unknown): value is string => typeof value === "string" && value.length <= 512 && !!value.trim() &&
+	!Array.from(value).some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127);
+
+function validateRecord(value: unknown, accountId: string): CodexResetRecord {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw unavailable();
+	// Capture own values once; never serialize caller prototypes, toJSON hooks, or later mutations.
+	const record = { ...value } as Record<string, unknown>;
+	const keys = ["version", "accountId", "creditId", "requestId", "expiresAt", "status", "confirmedCode"];
+	if (Object.getOwnPropertyNames(value).some((key) => !keys.includes(key)) || record.version !== 1 || record.accountId !== accountId ||
+		!validId(record.creditId) || typeof record.requestId !== "string" || !UUID.test(record.requestId) ||
+		(record.expiresAt !== undefined && (typeof record.expiresAt !== "number" || !Number.isSafeInteger(record.expiresAt) || record.expiresAt < 0)) ||
+		(record.status !== "pending" && record.status !== "resolved") ||
+		(record.confirmedCode !== undefined && (record.status !== "resolved" || typeof record.confirmedCode !== "string" || !CODES.has(record.confirmedCode))))
+		throw unavailable();
+	return record as CodexResetRecord;
+}
+
+function sameAttempt(left: CodexResetRecord, right: CodexResetRecord): boolean {
+	return left.accountId === right.accountId && left.creditId === right.creditId &&
+		left.requestId === right.requestId && left.expiresAt === right.expiresAt;
+}
+
+/** The injected root must have trusted parents. No auth material enters this edge. */
+export function createCodexResetStore(rootDirectory: string): CodexResetStore {
+	return {
+		async acquire(accountId) {
+			let lock: FileHandle | undefined;
+			try {
+				if (!validId(accountId)) throw unavailable();
+				await mkdir(rootDirectory, { recursive: true, mode: 0o700 });
+				const root = await lstat(rootDirectory);
+				if (!root.isDirectory() || root.isSymbolicLink() || (root.mode & 0o777) !== 0o700) throw unavailable();
+				const hash = createHash("sha256").update(accountId).digest("hex");
+				const journalPath = join(rootDirectory, `${hash}.json`);
+				const lockPath = join(rootDirectory, `${hash}.lock`);
+				// Existing locks (including empty, stale, or symlink locks) are never reclaimed.
+				lock = await open(lockPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+				const heldLock = lock;
+				const lockStat = await heldLock.stat();
+				let released = false;
+				let poisoned = false;
+
+				async function checkRoot() {
+					if (released || poisoned) throw unavailable();
+					const current = await lstat(rootDirectory);
+					if (!current.isDirectory() || current.isSymbolicLink() || current.dev !== root.dev || current.ino !== root.ino ||
+						(current.mode & 0o777) !== 0o700) throw unavailable();
+				}
+
+				async function read(): Promise<CodexResetRecord | undefined> {
+					let file: FileHandle | undefined;
+					try {
+						await checkRoot();
+						try { file = await open(journalPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+						catch (error) { if (isMissing(error)) return undefined; throw error; }
+						const info = await file.stat();
+						if (!info.isFile() || (info.mode & 0o777) !== 0o600 || info.size > MAX_BYTES) throw unavailable();
+						// A fixed buffer bounds reads even if another writer grows the file after stat.
+						const buffer = Buffer.alloc(MAX_BYTES + 1);
+						let size = 0;
+						while (size < buffer.length) {
+							const { bytesRead } = await file.read(buffer, size, buffer.length - size, size);
+							if (bytesRead === 0) break;
+							size += bytesRead;
+						}
+						if (size > MAX_BYTES) throw unavailable();
+						const text = new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, size));
+						return validateRecord(JSON.parse(text) as unknown, accountId);
+					} catch { throw unavailable(); }
+					finally { await file?.close().catch(() => { throw unavailable(); }); }
+				}
+
+				async function syncDirectory() {
+					const directory = await open(rootDirectory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+					try { await directory.sync(); }
+					finally { await directory.close(); }
+				}
+
+				async function write(record: CodexResetRecord): Promise<void> {
+					let previous: CodexResetRecord | undefined;
+					let published = false;
+					async function atomicSave(next: CodexResetRecord) {
+						const tempPath = join(rootDirectory, `${hash}.${randomUUID()}.tmp`);
+						let temp: FileHandle | undefined;
+						let created = false;
+						try {
+							await checkRoot();
+							temp = await open(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+							created = true;
+							await temp.writeFile(JSON.stringify(next), "utf8");
+							await temp.sync();
+							await temp.close();
+							temp = undefined;
+							await checkRoot();
+							try {
+								const final = await lstat(journalPath);
+								if (!final.isFile() || final.isSymbolicLink() || (final.mode & 0o777) !== 0o600) throw unavailable();
+							} catch (error) { if (!isMissing(error)) throw error; }
+							await rename(tempPath, journalPath);
+							created = false;
+							published = true;
+							await syncDirectory();
+						} finally {
+							try { await temp?.close(); }
+							finally { if (created) await unlink(tempPath); }
+						}
+					}
+					try {
+						record = validateRecord(record, accountId);
+						if (Buffer.byteLength(JSON.stringify(record)) > MAX_BYTES) throw unavailable();
+						previous = await read();
+						if ((previous?.status === "pending" && !sameAttempt(previous, record)) ||
+							(previous?.status === "resolved" && record.status === "pending" && previous.requestId === record.requestId) ||
+							(record.status === "resolved" && (previous?.status !== "pending" || !sameAttempt(previous, record)))) throw unavailable();
+						await atomicSave(record);
+					} catch {
+						// A post-rename fsync failure must not expose a resolved gate. Restore pending;
+						// if even that fails, retain the lock rather than permit another attempt.
+						if (published && record.status === "resolved" && previous?.status === "pending") {
+							try { await atomicSave(previous); }
+							catch { poisoned = true; }
+						}
+						throw unavailable();
+					}
+				}
+
+				async function release(): Promise<void> {
+					try {
+						await checkRoot();
+						const current = await lstat(lockPath);
+						if (!current.isFile() || (current.mode & 0o777) !== 0o600 || current.dev !== lockStat.dev || current.ino !== lockStat.ino)
+							throw unavailable();
+						await heldLock.close();
+						await unlink(lockPath);
+					} catch { throw unavailable(); }
+					finally { released = true; await heldLock.close().catch(() => {}); }
+				}
+				return { read, write, release };
+			} catch {
+				await lock?.close().catch(() => {}); // Never remove an uncertain or pre-existing lock.
+				throw unavailable();
+			}
+		},
+	};
+}

package/extensions/osdy-pi/codex-reset-ui.test.ts

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { registerHooks } from "node:module";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import type { CodexResetResult } from "./codex-reset.js";
+registerHooks({ resolve(specifier, context, next) {
+	if (specifier.startsWith(".") && specifier.endsWith(".js") && context.parentURL?.endsWith(".ts")) {
+		const url = new URL(`${specifier.slice(0, -3)}.ts`, context.parentURL);
+		if (existsSync(fileURLToPath(url))) return { shortCircuit: true, url: url.href };
+	}
+	return next(specifier, context);
+} });
+
+void test("choice labels map indexed local expiry to exact IDs, never render opaque identities", async () => {
+	const { createCodexResetInteraction } = await import("./codex-reset-ui.js");
+	const expiry = Date.parse("2030-07-17T12:30:00Z");
+	const choices = [{ creditId: "opaque-first", expiresAt: expiry }, { creditId: "opaque-second", expiresAt: undefined }];
+	let answer: number | string | undefined = 1;
+	const interaction = createCodexResetInteraction({ select: (_title, options) => {
+		assert.deepEqual(options, [`Reset 1 — expires ${new Date(expiry).toLocaleString()} (local time)`, "Reset 2 — Expiry not provided"]);
+		assert.doesNotMatch(options.join(""), /opaque-/);
+		return Promise.resolve(typeof answer === "number" ? options[answer] : answer);
+	} });
+	assert.equal(await interaction.choose(choices), "opaque-second");
+	for (answer of [undefined, "invented", "opaque-first"]) assert.equal(await interaction.choose(choices), undefined);
+});
+
+void test("new and recovery confirmation use Cancel-first select with honest scope/effects/date", async () => {
+	const { createCodexResetInteraction } = await import("./codex-reset-ui.js");
+	for (const kind of ["new", "recovery"] as const) {
+		for (const accept of [false, true, undefined]) {
+			const interaction = createCodexResetInteraction({ select: (title, options) => {
+				assert.match(title, /active Codex account/);
+				assert.match(title, /Expiry not provided/);
+				assert.doesNotMatch(title, /opaque-/);
+				assert.deepEqual(options, ["Cancel", kind === "new" ? "Use reset" : "Check pending attempt"]);
+				if (kind === "new") assert.match(title, /one banked reset/);
+				else assert.match(title, /same previous request.*may finish.*not a new attempt/i);
+				return Promise.resolve(accept === undefined ? undefined : options[accept ? 1 : 0]);
+			} });
+			const base = { scope: "active-account", cancelFirst: true, creditId: "opaque-credit", expiresAt: undefined } as const;
+			const prompt = kind === "recovery" ? { ...base, kind, requestId: "opaque-request" } : { ...base, kind };
+			assert.equal(await interaction.confirm(prompt), accept === true);
+		}
+	}
+});
+
+void test("confirmed codes remain definite and distinguish refresh/journal failures", async () => {
+	const { notifyCodexResetResult } = await import("./codex-reset-ui.js");
+	for (const code of ["reset", "already_redeemed", "no_credit", "nothing_to_reset"] as const) {
+		const notices: string[] = [];
+		notifyCodexResetResult({ notify: text => { notices.push(text); } }, { kind: "confirmed", code, windowsReset: 2, refreshFailed: true, journalFailed: true });
+		assert.match(notices[0] ?? "", code === "reset" ? /consumed.*2.*windows/i : code === "already_redeemed" ? /previous.*succeeded/i : /not consumed/i);
+		assert.match(notices[0] ?? "", /Quota refresh failed/);
+		assert.match(notices[0] ?? "", /Local attempt bookkeeping failed/);
+		assert.doesNotMatch(notices[0] ?? "", /reset failed|Outcome unknown/i);
+	}
+});
+
+void test("unknown and blocked feedback never suggests another reset or automatic lock cleanup", async () => {
+	const { notifyCodexResetResult } = await import("./codex-reset-ui.js");
+	const results: CodexResetResult[] = [{ kind: "unknown", refreshFailed: false, journalFailed: false },
+		{ kind: "blocked", journalFailed: true }, { kind: "busy" }, { kind: "unavailable" }, { kind: "cancelled" }];
+	const notices: string[] = [];
+	for (const result of results) notifyCodexResetResult({ notify: text => { notices.push(text); } }, result);
+	assert.equal(notices[0], "Outcome unknown; do not start another reset. Use check to confirm the same pending attempt.");
+	assert.match(notices[1] ?? "", /blocked.*manual verification/i);
+	assert.doesNotMatch(notices.join(""), /opaque|token|\.json|auto.*reclaim/i);
+});

package/extensions/osdy-pi/codex-reset-ui.ts

@@ -0,0 +1,52 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { CodexResetInteraction, CodexResetResult } from "./codex-reset.js";
+
+export type CodexResetAction = () => Promise<boolean>;
+const expiryLabel = (expiresAt: number | undefined): string => expiresAt === undefined
+	? "Expiry not provided" : `expires ${new Date(expiresAt).toLocaleString()} (local time)`;
+
+/** Presentation only. Opaque IDs stay in the indexed mapping, not dialog text. */
+export function createCodexResetInteraction(ui: Pick<ExtensionContext["ui"], "select">): CodexResetInteraction {
+	return {
+		async choose(choices) {
+			const labels = choices.map((choice, index) => `Reset ${index + 1} — ${expiryLabel(choice.expiresAt)}`);
+			const selected = await ui.select("Choose a banked reset for the active Codex account", labels);
+			const index = selected === undefined ? -1 : labels.indexOf(selected);
+			return choices[index]?.creditId;
+		},
+		async confirm(prompt) {
+			const recovery = prompt.kind === "recovery";
+			const effect = recovery
+				? "Check the same previous request; this may finish the previous unconfirmed reset, not a new attempt."
+				: "Use one banked reset; one banked reset will be consumed if rate limits are reset.";
+			const accept = recovery ? "Check pending attempt" : "Use reset";
+			return await ui.select(`For the active Codex account: ${effect}\nReset ${expiryLabel(prompt.expiresAt)}.`, ["Cancel", accept]) === accept;
+		},
+	};
+}
+
+/** Definite server outcomes are never relabelled as failures by later local work. */
+export function notifyCodexResetResult(ui: Pick<ExtensionContext["ui"], "notify">, result: CodexResetResult): void {
+	let message: string;
+	switch (result.kind) {
+		case "busy": message = "A banked reset action is already in progress."; break;
+		case "cancelled": message = "Banked reset action cancelled; no new reset was sent."; break;
+		case "unavailable": message = "No currently available banked reset could be selected. Refresh usage to check availability."; break;
+		case "blocked": message = "Banked reset action blocked. Local attempt storage or its lock is unavailable; manual verification is required. No automatic cleanup or retry."; break;
+		case "unknown": message = "Outcome unknown; do not start another reset. Use check to confirm the same pending attempt."; break;
+		case "confirmed":
+			switch (result.code) {
+				case "reset": message = `Banked reset consumed; ${result.windowsReset} rate-limit windows reset.`; break;
+				case "already_redeemed": message = "The previous reset already succeeded; this check did not consume another reset."; break;
+				case "no_credit": message = "No banked reset was available; a reset was not consumed."; break;
+				case "nothing_to_reset": message = "No rate limits needed resetting; a banked reset was not consumed."; break;
+			}
+	}
+	if (result.kind === "unknown" || result.kind === "confirmed") {
+		if (result.refreshFailed) message += " Quota refresh failed; the consumption outcome above is unchanged.";
+		if (result.journalFailed) message += " Local attempt bookkeeping failed; do not start another reset before manual verification.";
+	}
+	const warning = result.kind === "unknown" || result.kind === "blocked" || result.kind === "busy" || result.kind === "unavailable" ||
+		(result.kind === "confirmed" && (result.refreshFailed || result.journalFailed));
+	ui.notify(message, warning ? "warning" : "info");
+}