oma-coding-agent 1.1.4

package/src/session/auth-broker-config.ts

@@ -0,0 +1,92 @@
+/**
+ * Resolve auth-broker connection configuration for the local omp client.
+ *
+ * This is a thin coding-agent wrapper around the shared resolver in
+ * `@oh-my-pi/pi-ai/auth-broker/discover` that preserves the process-lifetime
+ * memoization expected by the CLI and injects the full `resolveConfigValue`
+ * (including `!command` config indirection) from coding-agent's config layer.
+ *
+ * Precedence (highest first):
+ *   1. `OMP_AUTH_BROKER_URL` / `OMP_AUTH_BROKER_TOKEN` env vars.
+ *   2. `auth.broker.url` / `auth.broker.token` in `~/.omp/agent/config.yml`
+ *      (hidden from the settings UI; `!command` resolution supported).
+ *   3. Token file `~/.omp/auth-broker.token` (paired with URL from env or config).
+ *
+ * Returns null when no broker URL is configured — caller falls back to the
+ * local SQLite store.
+ *
+ * Reads config.yml directly (instead of going through `Settings.init`) because
+ * `discoverAuthStorage` runs before the settings singleton is initialized in
+ * `runRootCommand`, and we want hand-edited config entries to be honoured at
+ * boot without forcing a startup reorder.
+ */
+
+import {
+	type AuthBrokerClientConfig,
+	type DiscoverAuthStorageOptions,
+	discoverAuthStorage as discoverAuthStorageShared,
+	getAuthBrokerTokenFilePath,
+	resolveAuthBrokerConfig as resolveAuthBrokerConfigShared,
+} from "@oh-my-pi/pi-ai/auth-broker/discover";
+import { getAgentDir } from "@oh-my-pi/pi-utils";
+import { resolveConfigValue } from "../config/resolve-config-value";
+import type { AuthStorage } from "./auth-storage";
+
+export { type AuthBrokerClientConfig, getAuthBrokerTokenFilePath };
+
+/**
+ * Process-lifetime memo for {@link resolveAuthBrokerConfig}. Keyed on the env
+ * inputs (plus agent dir, which decides which config.yml is read) so tests
+ * that flip `OMP_AUTH_BROKER_*` between cases still observe the change, while
+ * repeated resolution within one CLI invocation (startup, subagent sessions)
+ * skips the config.yml read and any `!command` token resolution.
+ */
+let cachedConfigKey: string | null = null;
+let cachedConfigPromise: Promise<AuthBrokerClientConfig | null> | null = null;
+
+/**
+ * Read broker configuration. Returns null when the URL is missing
+ * (broker disabled — local store is used). Throws when URL is set but no
+ * token is available — the caller cannot fall back silently because the
+ * user explicitly asked to use the broker.
+ *
+ * Successful resolutions (including "no broker configured") are memoized for
+ * the process lifetime; failures are not, so a missing token can be fixed and
+ * retried. Concurrent callers share one in-flight resolution.
+ */
+export function resolveAuthBrokerConfig(): Promise<AuthBrokerClientConfig | null> {
+	const key = `${process.env.OMP_AUTH_BROKER_URL ?? ""}\u0000${process.env.OMP_AUTH_BROKER_TOKEN ?? ""}\u0000${getAgentDir()}`;
+	if (cachedConfigPromise && cachedConfigKey === key) return cachedConfigPromise;
+	const promise = resolveAuthBrokerConfigShared({
+		agentDir: getAgentDir(),
+		configValueResolver: resolveConfigValue,
+	});
+	cachedConfigKey = key;
+	cachedConfigPromise = promise;
+	promise.catch(() => {
+		if (cachedConfigPromise === promise) {
+			cachedConfigPromise = null;
+			cachedConfigKey = null;
+		}
+	});
+	return promise;
+}
+
+/**
+ * Create an AuthStorage instance, using the broker when configured and falling
+ * back to the local SQLite store otherwise. Delegates to the shared resolver in
+ * pi-ai so the CLI, subagents, and the catalog generator all see the same
+ * credentials.
+ *
+ * Default `agentDir` is the current configured agent directory.
+ */
+export function discoverAuthStorage(
+	agentDir: string = getAgentDir(),
+	options?: Omit<DiscoverAuthStorageOptions, "agentDir" | "configValueResolver">,
+): Promise<AuthStorage> {
+	return discoverAuthStorageShared({
+		...options,
+		agentDir,
+		configValueResolver: resolveConfigValue,
+	});
+}

package/src/session/auth-storage.ts

@@ -0,0 +1,24 @@
+/**
+ * Re-exports from @oh-my-pi/pi-ai.
+ * All credential storage types and the AuthStorage class now live in the ai package.
+ */
+
+export type {
+	ApiKeyCredential,
+	AuthCredential,
+	AuthCredentialEntry,
+	AuthCredentialStore,
+	AuthStorageData,
+	AuthStorageOptions,
+	CredentialOrigin,
+	CredentialOriginKind,
+	OAuthAccountIdentity,
+	OAuthCredential,
+	ResetCreditAccountStatus,
+	ResetCreditRedeemOutcome,
+	ResetCreditTarget,
+	SerializedAuthStorage,
+	StoredAuthCredential,
+} from "@oh-my-pi/pi-ai";
+export { AuthStorage, REMOTE_REFRESH_SENTINEL, SqliteAuthCredentialStore } from "@oh-my-pi/pi-ai";
+export type { SnapshotResponse } from "@oh-my-pi/pi-ai/auth-broker/types";

package/src/session/blob-store.ts

@@ -0,0 +1,255 @@
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { isEnoent, logger } from "@oh-my-pi/pi-utils";
+
+const BLOB_PREFIX = "blob:sha256:";
+
+export interface BlobPutOptions {
+	/** Optional file extension for a sidecar hardlink/copy that OS openers can type-detect. */
+	extension?: string;
+}
+
+export interface BlobPutResult {
+	hash: string;
+	/** Canonical content-addressed path, always `<dir>/<sha256-hex>`. */
+	path: string;
+	/** Path with the requested extension when supplied, otherwise the canonical path. */
+	displayPath: string;
+	get ref(): string;
+}
+
+/**
+ * Content-addressed blob store for externalizing large binary data (images) from session JSONL files.
+ *
+ * Files are stored canonically at `<dir>/<sha256-hex>`. Callers may also request
+ * a typed sidecar path (`<dir>/<sha256-hex>.<ext>`) for `file://` links and OS
+ * image viewers; blob refs and reads still address the extensionless hash path.
+ * The SHA-256 hash is computed over the raw binary data (not base64).
+ * Content-addressing makes writes idempotent and provides automatic deduplication
+ * across sessions.
+ */
+
+const IMAGE_EXTENSION_BY_MIME: Record<string, string> = {
+	"image/png": "png",
+	"image/jpeg": "jpg",
+	"image/jpg": "jpg",
+	"image/gif": "gif",
+	"image/webp": "webp",
+	"image/svg+xml": "svg",
+};
+
+function normalizeBlobExtension(extension: string | undefined): string | undefined {
+	if (!extension) return undefined;
+	const normalized = extension.startsWith(".") ? extension.slice(1) : extension;
+	if (normalized.length === 0 || normalized.length > 32) return undefined;
+	if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(normalized)) return undefined;
+	return normalized.toLowerCase();
+}
+
+async function ensureDisplayPath(blobPath: string, displayPath: string, data: Buffer): Promise<void> {
+	if (displayPath === blobPath) return;
+	try {
+		await fsp.link(blobPath, displayPath);
+		return;
+	} catch (err) {
+		if (typeof err === "object" && err !== null && "code" in err && err.code === "EEXIST") return;
+		logger.debug("Blob display hardlink failed; falling back to copy", {
+			blobPath,
+			displayPath,
+			error: err instanceof Error ? err.message : String(err),
+		});
+	}
+	await Bun.write(displayPath, data);
+}
+
+function ensureDisplayPathSync(blobPath: string, displayPath: string, data: Buffer): void {
+	if (displayPath === blobPath) return;
+	try {
+		fs.linkSync(blobPath, displayPath);
+		return;
+	} catch (err) {
+		if (typeof err === "object" && err !== null && "code" in err && err.code === "EEXIST") return;
+		logger.debug("Blob display hardlink failed; falling back to copy", {
+			blobPath,
+			displayPath,
+			error: err instanceof Error ? err.message : String(err),
+		});
+	}
+	fs.writeFileSync(displayPath, data);
+}
+
+export function blobExtensionForImageMimeType(mimeType: string | undefined): string | undefined {
+	if (!mimeType) return undefined;
+	const lower = mimeType.toLowerCase();
+	const known = IMAGE_EXTENSION_BY_MIME[lower];
+	if (known) return known;
+	if (!lower.startsWith("image/")) return undefined;
+	const subtype = lower.slice("image/".length).split(";")[0]?.split("+")[0];
+	return normalizeBlobExtension(subtype);
+}
+
+export class BlobStore {
+	constructor(readonly dir: string) {}
+
+	/**
+	 * Write binary data to the blob store.
+	 * @returns SHA-256 hex hash of the data
+	 */
+	async put(data: Buffer, options?: BlobPutOptions): Promise<BlobPutResult> {
+		const hash = new Bun.SHA256().update(data).digest("hex");
+		const blobPath = path.join(this.dir, hash);
+		const extension = normalizeBlobExtension(options?.extension);
+		const displayPath = extension ? `${blobPath}.${extension}` : blobPath;
+		const result = {
+			hash,
+			path: blobPath,
+			displayPath,
+			get ref() {
+				return `${BLOB_PREFIX}${hash}`;
+			},
+		};
+
+		await Bun.write(blobPath, data);
+		await ensureDisplayPath(blobPath, displayPath, data);
+		return result;
+	}
+
+	/**
+	 * Synchronous variant of {@link put}. Use on persistence hot paths where the caller
+	 * cannot afford the microtask hops of the async version (e.g. OOM-safe session writes).
+	 * Returns once the bytes are in the kernel page cache.
+	 */
+	putSync(data: Buffer, options?: BlobPutOptions): BlobPutResult {
+		const hash = new Bun.SHA256().update(data).digest("hex");
+		const blobPath = path.join(this.dir, hash);
+		const extension = normalizeBlobExtension(options?.extension);
+		const displayPath = extension ? `${blobPath}.${extension}` : blobPath;
+		const result = {
+			hash,
+			path: blobPath,
+			displayPath,
+			get ref() {
+				return `${BLOB_PREFIX}${hash}`;
+			},
+		};
+		fs.mkdirSync(this.dir, { recursive: true });
+		fs.writeFileSync(blobPath, data);
+		ensureDisplayPathSync(blobPath, displayPath, data);
+		return result;
+	}
+
+	/** Read blob by hash, returns Buffer or null if not found. */
+	async get(hash: string): Promise<Buffer | null> {
+		const blobPath = path.join(this.dir, hash);
+		try {
+			const file = Bun.file(blobPath);
+			const ab = await file.arrayBuffer();
+			return Buffer.from(ab);
+		} catch (err) {
+			if (isEnoent(err)) return null;
+			throw err;
+		}
+	}
+
+	/** Check if a blob exists. */
+	async has(hash: string): Promise<boolean> {
+		try {
+			await fsp.access(path.join(this.dir, hash));
+			return true;
+		} catch {
+			return false;
+		}
+	}
+}
+
+/** Check if a data string is a blob reference. */
+export function isBlobRef(data: string): boolean {
+	return data.startsWith(BLOB_PREFIX);
+}
+
+/** Extract the SHA-256 hash from a blob reference string. */
+export function parseBlobRef(data: string): string | null {
+	if (!data.startsWith(BLOB_PREFIX)) return null;
+	return data.slice(BLOB_PREFIX.length);
+}
+
+/** Identify provider transport image data URLs so persistence can externalize and restore them losslessly. */
+export function isImageDataUrl(data: string): boolean {
+	return data.startsWith("data:image/") && data.includes(";base64,");
+}
+
+/**
+ * Externalize a provider image data URL to the blob store, returning a blob reference.
+ * The full data URL string is preserved so transport-native history can be reconstructed on resume.
+ */
+export async function externalizeImageDataUrl(blobStore: BlobStore, dataUrl: string): Promise<string> {
+	if (isBlobRef(dataUrl)) return dataUrl;
+	const { ref } = await blobStore.put(Buffer.from(dataUrl, "utf8"));
+	return ref;
+}
+
+/** Synchronous variant of {@link externalizeImageDataUrl}. */
+export function externalizeImageDataUrlSync(blobStore: BlobStore, dataUrl: string): string {
+	if (isBlobRef(dataUrl)) return dataUrl;
+	return blobStore.putSync(Buffer.from(dataUrl, "utf8")).ref;
+}
+
+/**
+ * Externalize an image's base64 data to the blob store, returning a blob reference.
+ * If the data is already a blob reference, returns it unchanged.
+ */
+export async function externalizeImageData(
+	blobStore: BlobStore,
+	base64Data: string,
+	mimeType?: string,
+): Promise<string> {
+	if (isBlobRef(base64Data)) return base64Data;
+	const buffer = Buffer.from(base64Data, "base64");
+	const { ref } = await blobStore.put(buffer, {
+		extension: blobExtensionForImageMimeType(mimeType),
+	});
+	return ref;
+}
+
+/** Synchronous variant of {@link externalizeImageData}. */
+export function externalizeImageDataSync(blobStore: BlobStore, base64Data: string, mimeType?: string): string {
+	if (isBlobRef(base64Data)) return base64Data;
+	return blobStore.putSync(Buffer.from(base64Data, "base64"), {
+		extension: blobExtensionForImageMimeType(mimeType),
+	}).ref;
+}
+
+/**
+ * Resolve an externalized provider image data URL back to its original string.
+ * If the data is not a blob reference, returns it unchanged.
+ * If the blob is missing, logs a warning and returns the reference as-is.
+ */
+export async function resolveImageDataUrl(blobStore: BlobStore, data: string): Promise<string> {
+	const hash = parseBlobRef(data);
+	if (!hash) return data;
+
+	const buffer = await blobStore.get(hash);
+	if (!buffer) {
+		logger.warn("Blob not found for persisted image data URL", { hash });
+		return data;
+	}
+	return buffer.toString("utf8");
+}
+
+/**
+ * Resolve a blob reference back to base64 data.
+ * If the data is not a blob reference, returns it unchanged.
+ * If the blob is missing, logs a warning and returns a placeholder.
+ */
+export async function resolveImageData(blobStore: BlobStore, data: string): Promise<string> {
+	const hash = parseBlobRef(data);
+	if (!hash) return data;
+
+	const buffer = await blobStore.get(hash);
+	if (!buffer) {
+		logger.warn("Blob not found for image reference", { hash });
+		return data; // Return the ref as-is; downstream will see invalid base64 but won't crash
+	}
+	return buffer.toString("base64");
+}

package/src/session/client-bridge.ts

@@ -0,0 +1,85 @@
+/**
+ * ClientBridge — abstraction over capabilities provided by an external client
+ * (e.g. ACP editor host) that the agent can route through instead of operating
+ * directly on the local filesystem / spawning local subprocesses.
+ *
+ * When `undefined`, tools fall back to local IO. When populated (currently
+ * only by `AcpAgent`), tools route requests through the client so it can
+ * surface unsaved buffer state, render terminals in the IDE, or gate
+ * destructive operations behind user permission prompts.
+ */
+
+export interface ClientBridgeCapabilities {
+	/** Client implements `fs/read_text_file`. */
+	readTextFile?: boolean;
+	/** Client implements `fs/write_text_file`. */
+	writeTextFile?: boolean;
+	/** Client implements the `terminal/*` family. */
+	terminal?: boolean;
+	/** Client implements `session/request_permission`. */
+	requestPermission?: boolean;
+}
+
+export interface ClientBridgePermissionToolCall {
+	toolCallId: string;
+	toolName: string;
+	title: string;
+	kind?: string;
+	status?: "pending" | "in_progress" | "completed" | "failed";
+	rawInput?: unknown;
+	content?: unknown[];
+	locations?: { path: string; line?: number }[];
+}
+
+export type ClientBridgePermissionOptionKind = "allow_once" | "allow_always" | "reject_once" | "reject_always";
+
+export interface ClientBridgePermissionOption {
+	optionId: string;
+	name: string;
+	kind: ClientBridgePermissionOptionKind;
+}
+
+export type ClientBridgePermissionOutcome =
+	| { outcome: "cancelled" }
+	| { outcome: "selected"; optionId: string; kind?: ClientBridgePermissionOptionKind };
+
+export interface ClientBridgeTerminalExitStatus {
+	exitCode?: number | null;
+	signal?: string | null;
+}
+
+export interface ClientBridgeTerminalOutput {
+	output: string;
+	truncated: boolean;
+	exitStatus?: ClientBridgeTerminalExitStatus | null;
+}
+
+export interface ClientBridgeTerminalHandle {
+	terminalId: string;
+	waitForExit(): Promise<ClientBridgeTerminalExitStatus>;
+	currentOutput(): Promise<ClientBridgeTerminalOutput>;
+	kill(): Promise<void>;
+	release(): Promise<void>;
+}
+
+export interface ClientBridgeCreateTerminalParams {
+	command: string;
+	args?: string[];
+	env?: Array<{ name: string; value: string }>;
+	cwd?: string;
+	outputByteLimit?: number;
+}
+
+export interface ClientBridge {
+	readonly capabilities: ClientBridgeCapabilities;
+	/** ACP v1 clients cannot show server-initiated turns as busy after prompt response. */
+	readonly deferAgentInitiatedTurns?: boolean;
+	readTextFile?(params: { path: string; line?: number; limit?: number }): Promise<string>;
+	writeTextFile?(params: { path: string; content: string }): Promise<void>;
+	createTerminal?(params: ClientBridgeCreateTerminalParams): Promise<ClientBridgeTerminalHandle>;
+	requestPermission?(
+		toolCall: ClientBridgePermissionToolCall,
+		options: ClientBridgePermissionOption[],
+		signal?: AbortSignal,
+	): Promise<ClientBridgePermissionOutcome>;
+}

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

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