@danypops/jittor 0.1.1 → 0.2.0

package/README.md

@@ -35,11 +35,23 @@ Operations currently include `metrics.record`, `metrics.query`, `metrics.prune`,
 
 Provider adapters currently include official OpenRouter key/usage/model telemetry and an explicitly experimental Codex subscription adapter. The Codex adapter follows the pinned open-source CLI `/wham/usage` payload and `x-codex-*` response-header contracts, accepts additional metered limits, and fails closed on malformed windows or impossible percentages. File credentials must be explicitly configured and private (`0600`); Jittor reads only the access token and account ID, never refreshes credentials, and never logs or persists OAuth secrets.
 
-The native Pi extension preflights input and every provider turn, applies model/thinking decisions, records response headers and finalized usage through the daemon, and blocks requests when required telemetry is unsafe. It follows Pi's current authenticated model/provider and synchronizes Pi's available models before every decision, so unavailable catalog routes are never selected. Its responsive Alef-style footer groups repository and AI identity with cumulative usage, a color-coded context-window bar, and current-provider budget telemetry. Codex shows a bounded quota bar for its longest percentage window; OpenRouter remains honest about its unbounded raw spend and does not fabricate a denominator. Unknown and stale telemetry are marked explicitly. Run `/jittor` for detailed burn pressure, freshness, route state, and confirmed emergency-halt/override controls.
+The native Pi extension preflights input and every provider turn, applies model/thinking decisions, records response headers and finalized usage through the daemon, and blocks requests when required telemetry is unsafe. It follows Pi's current authenticated model/provider and synchronizes Pi's available models before every decision, so unavailable catalog routes are never selected. Its responsive integrated footer groups repository and model identity with cumulative usage, a color-coded context-window bar, and current-provider budget telemetry. Codex shows the active model's bounded quota as a draining remaining-budget bar with reset and freshness information. OpenRouter uses the same drain semantics when its official key telemetry exposes a configured limit and remaining balance; keys without a limit remain honest text-only spend and never receive a fabricated denominator. During Pi compaction, the context bar drains as an animation and reports elapsed time. Unknown and stale telemetry are marked explicitly. Run `/jittor` for detailed burn pressure, freshness, route state, and confirmed emergency-halt/override controls.
 
-Blocking always has a daemon-independent escape hatch. `/jittor off` (or `/jittor-off`) immediately enters persisted monitor-only mode and never blocks provider requests. The informational footer is independently controlled with `/jittor footer on` and `/jittor footer off`, so showing status never enables enforcement. `/jittor on` only enables enforcement after telemetry polling and available-route synchronization succeed. Every fail-closed error includes these recovery commands plus the daemon restart command.
+Blocking always has a daemon-independent escape hatch. `/jittor off` immediately enters persisted monitor-only mode and never blocks provider requests. The informational footer is independently controlled with `/jittor footer on` and `/jittor footer off`, so showing status never enables enforcement. `/jittor on` only enables enforcement after telemetry polling and available-route synchronization succeed. Every fail-closed error includes these recovery commands plus the daemon restart command.
 
-Run `/usage` for a colored Unicode token histogram with X/Y axes, provider/model series, input/output/cache totals, refresh, and `24h`, `7d`, `30d`, or `90d` ranges. Left/Right changes range and `r` refreshes. Usage is persisted by the daemon from finalized Pi assistant messages.
+### Opt-in Codex settled-turn recovery
+
+Transient Codex recovery is securely off by default. Opt in explicitly through `$XDG_CONFIG_HOME/jittor/extension.json` (or `~/.config/jittor/extension.json`):
+
+```json
+{
+  "codexRecoveryEnabled": true
+}
+```
+
+Jittor observes finalized Codex assistant errors through Pi's public message lifecycle, classifies only bounded error metadata, and waits for `agent_settled` before acting. That boundary guarantees Pi's built-in retry, compaction retry, and queued follow-up work has finished. A transient concurrency, rate-limit, overload, or transport failure then schedules one hidden follow-up with Retry-After-aware capped jitter. Recovery is limited to three attempts per ten-minute window, never overlaps pending Pi messages, resets after success, and is canceled by human input or session shutdown. Quota, authentication, invalid-request, unknown, and aborted failures remain terminal. Raw provider payloads are never retained or injected.
+
+Run `/jittor usage` for a colored Unicode token histogram with X/Y axes, provider/model series, input/output/cache totals, refresh, and `24h`, `7d`, `30d`, or `90d` ranges. Left/Right changes range and `r` refreshes. Usage is persisted by the daemon from finalized Pi assistant messages.
 
 See [`docs/CALIBRATION.md`](docs/CALIBRATION.md) for thresholds and rollback, and [`docs/USAGE_PRIOR_ART.md`](docs/USAGE_PRIOR_ART.md) for the chart design research.
 

package/docs/USAGE_PRIOR_ART.md

@@ -1,6 +1,6 @@
 # Token-usage TUI prior art
 
-Research performed before implementing Jittor's `/usage` frontend.
+Research performed before implementing Jittor's `/jittor usage` frontend.
 
 ## Local agent implementations
 
@@ -60,5 +60,5 @@ Jittor combines the best applicable patterns:
 3. Provider/model-preserving series and input/output/cache totals.
 4. Vertically scaled, colored, stacked Unicode bars with fractional top blocks.
 5. Width-safe X/Y axes and provider/model legend.
-6. Native `/usage` panel with Left/Right range switching and refresh.
+6. Native `/jittor usage` panel with Left/Right range switching and refresh.
 7. Data access only through authenticated daemon `metrics.query`; the extension never opens SQLite or reads provider credentials.

package/extension/src/footer.ts

@@ -6,8 +6,13 @@ import {
 	FOOTER_BAR_MIN_WIDTH,
 	FOOTER_CONTEXT_ACCENT_FRACTION,
 	FOOTER_CONTEXT_ERROR_FRACTION,
+	FOOTER_COMPACTION_DRAIN_STEP_MS,
 	FOOTER_CONTEXT_WARNING_FRACTION,
 	FOOTER_WIDE_TERMINAL_WIDTH,
+	MILLISECONDS_PER_DAY,
+	MILLISECONDS_PER_HOUR,
+	MILLISECONDS_PER_MINUTE,
+	MILLISECONDS_PER_SECOND,
 	TELEMETRY_STALE_AFTER_MS,
 } from "../../src/constants.ts";
 
@@ -42,12 +47,24 @@ interface FooterContext {
 	};
 }
 
-/** A provider usage value suitable for the footer. Null fraction means no known denominator. */
-export interface ProviderBudget {
+/** A bounded quota is explicitly remaining; unbounded values never receive a fabricated bar. */
+export type ProviderBudget = {
+	kind: "bounded";
+	label: string;
+	remainingFraction: number;
+	observedAt?: number;
+	resetsAt?: number;
+	resetText?: string;
+} | {
+	kind: "unbounded";
 	label: string;
-	fraction: number | null;
 	valueText: string;
 	observedAt?: number;
+};
+
+export interface CompactionProgress {
+	startedAt: number;
+	initialFraction: number;
 }
 
 interface UsageTotals {
@@ -116,24 +133,72 @@ function fillColor(fraction: number | null): FooterColor {
 	return "dim";
 }
 
-function contextSegment(context: FooterContext, theme: FooterTheme, width: number, compact: boolean): string {
+function compactionFraction(progress: CompactionProgress, width: number, now: number): number {
+	const initialFilled = Math.round(Math.min(1, Math.max(0, progress.initialFraction)) * width);
+	const drained = Math.floor(Math.max(0, now - progress.startedAt) / FOOTER_COMPACTION_DRAIN_STEP_MS);
+	return Math.max(0, initialFilled - drained) / width;
+}
+
+function contextSegment(
+	context: FooterContext,
+	theme: FooterTheme,
+	width: number,
+	compact: boolean,
+	now: number,
+	compaction?: CompactionProgress,
+): string {
+	const w = barWidth(width);
+	if (compaction) {
+		const fraction = compactionFraction(compaction, w, now);
+		const elapsedSeconds = Math.floor(Math.max(0, now - compaction.startedAt) / MILLISECONDS_PER_SECOND);
+		return `ctx ${theme.fg("accent", progressBar(fraction, w))} compact ${elapsedSeconds}s`;
+	}
 	const usage = context.getContextUsage();
 	const window = usage?.contextWindow ?? context.model?.contextWindow ?? 0;
 	const fraction = usage?.percent === null || usage?.percent === undefined ? null : usage.percent / 100;
-	const bar = theme.fg(fillColor(fraction), progressBar(fraction, barWidth(width)));
+	const bar = theme.fg(fillColor(fraction), progressBar(fraction, w));
 	if (usage?.tokens === null || usage?.tokens === undefined) return `ctx ${bar} ?/${formatTokens(window)}`;
 	const value = compact ? `${Math.round((fraction ?? 0) * 100)}%` : `${formatTokens(usage.tokens)}/${formatTokens(window)}`;
 	return `ctx ${bar} ${value}`;
 }
 
+function minimalContextSegment(
+	context: FooterContext,
+	theme: FooterTheme,
+	width: number,
+	now: number,
+	compaction?: CompactionProgress,
+): string {
+	const w = barWidth(width);
+	if (compaction) {
+		const fraction = compactionFraction(compaction, w, now);
+		return `ctx ${theme.fg("accent", progressBar(fraction, w))}`;
+	}
+	const percent = context.getContextUsage()?.percent;
+	const fraction = percent === null || percent === undefined ? null : percent / 100;
+	return `ctx ${theme.fg(fillColor(fraction), progressBar(fraction, w))}`;
+}
+
+function resetLabel(resetsAt: number | undefined, now: number): string | undefined {
+	if (resetsAt === undefined) return undefined;
+	const remaining = resetsAt - now;
+	if (remaining <= 0) return "reset due";
+	if (remaining >= MILLISECONDS_PER_DAY) return `resets in ${Math.floor(remaining / MILLISECONDS_PER_DAY)}d`;
+	if (remaining >= MILLISECONDS_PER_HOUR) return `resets in ${Math.floor(remaining / MILLISECONDS_PER_HOUR)}h`;
+	return `resets in ${Math.max(1, Math.ceil(remaining / MILLISECONDS_PER_MINUTE))}m`;
+}
+
 function budgetSegment(budget: ProviderBudget | null, theme: FooterTheme, width: number, compact: boolean, now: number): string {
 	const w = barWidth(width);
 	if (!budget) return `budget ${theme.fg("dim", progressBar(null, w))} ?`;
-	if (budget.fraction === null) return `${budget.label} ${budget.valueText}`;
-	const bar = theme.fg(fillColor(budget.fraction), progressBar(budget.fraction, w));
-	const value = compact ? `${Math.round(budget.fraction * 100)}%` : budget.valueText;
 	const stale = budget.observedAt !== undefined && now - budget.observedAt > TELEMETRY_STALE_AFTER_MS;
-	return `${budget.label} ${bar} ${value}${stale ? ` ${theme.fg("warning", "stale")}` : ""}`;
+	const staleText = stale ? ` ${theme.fg("warning", "stale")}` : "";
+	if (budget.kind === "unbounded") return `${budget.label} ${budget.valueText}${staleText}`;
+	const remaining = Math.min(1, Math.max(0, budget.remainingFraction));
+	const bar = theme.fg(fillColor(1 - remaining), progressBar(remaining, w));
+	const value = `${(compact ? Math.round(remaining * 100) : (remaining * 100).toFixed(1))}% left`;
+	const reset = compact ? undefined : resetLabel(budget.resetsAt, now) ?? budget.resetText;
+	return `${budget.label} ${bar} ${value}${reset ? ` · ${reset}` : ""}${staleText}`;
 }
 
 function usageSegment(context: FooterContext): string {
@@ -187,14 +252,16 @@ export function renderFooterLines(
 	thinkingLevel: string,
 	width: number,
 	now = Date.now(),
+	compaction?: CompactionProgress,
 ): string[] {
 	const safeWidth = Math.max(1, width);
 	const repository = repositorySegment(context, footerData, theme);
 	const model = modelSegments(context, footerData, theme, thinkingLevel);
 	const usage = usageSegment(context);
 	const compactUsage = compactUsageSegment(context);
-	const fullContext = contextSegment(context, theme, safeWidth, false);
-	const compactContext = contextSegment(context, theme, safeWidth, true);
+	const fullContext = contextSegment(context, theme, safeWidth, false, now, compaction);
+	const compactContext = contextSegment(context, theme, safeWidth, true, now, compaction);
+	const minimalContext = minimalContextSegment(context, theme, safeWidth, now, compaction);
 	const fullBudget = budgetSegment(providerBudget, theme, safeWidth, false, now);
 	const compactBudget = budgetSegment(providerBudget, theme, safeWidth, true, now);
 	const statuses = [...footerData.getExtensionStatuses().entries()]
@@ -211,6 +278,7 @@ export function renderFooterLines(
 		joinSegments([model.full, compactUsage, compactContext, compactBudget]),
 		joinSegments([model.compact, compactUsage, compactContext, compactBudget]),
 		joinSegments([model.compact, compactContext, compactBudget]),
+		joinSegments([model.compact, minimalContext, compactBudget]),
 	];
 	const line = candidates.find((candidate) => visibleWidth(candidate) <= safeWidth) ?? candidates.at(-1) ?? "";
 	return [truncateToWidth(line, safeWidth, "")];
@@ -218,6 +286,7 @@ export function renderFooterLines(
 
 export interface IntegratedFooterState {
 	providerBudget: ProviderBudget | null;
+	compaction?: CompactionProgress;
 	requestRender?: () => void;
 }
 
@@ -229,7 +298,7 @@ export function installIntegratedFooter(ctx: ExtensionContext, state: Integrated
 		return {
 			invalidate() {},
 			render(width: number): string[] {
-				return renderFooterLines(ctx as unknown as FooterContext, footerData, theme, state.providerBudget, getThinkingLevel(), width);
+				return renderFooterLines(ctx as unknown as FooterContext, footerData, theme, state.providerBudget, getThinkingLevel(), width, Date.now(), state.compaction);
 			},
 			dispose() {
 				unsubscribe?.();

package/extension/src/index.ts

@@ -1,12 +1,21 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { MAX_DYNAMIC_ROUTES } from "../../src/constants.ts";
+import {
+	CODEX_RECOVERY_ATTEMPT_WINDOW_MS,
+	CODEX_RECOVERY_BASE_DELAY_MS,
+	CODEX_RECOVERY_JITTER_RATIO,
+	CODEX_RECOVERY_MAX_ATTEMPTS,
+	CODEX_RECOVERY_MAX_DELAY_MS,
+	FOOTER_COMPACTION_RENDER_INTERVAL_MS,
+	MAX_DYNAMIC_ROUTES,
+} from "../../src/constants.ts";
+import { CodexRecoveryPolicy, classifyCodexFailure, type CodexFailureMetadata } from "../../src/domain/codex-recovery.ts";
 import type { MetricObservation, StoredMetricObservation } from "../../src/domain/metric.ts";
 import type { PolicyDecision, Route } from "../../src/policy.ts";
 import type { RouterStatus } from "../../src/ports/router-controller.ts";
 import { parseCodexRateLimitHeaders } from "../../src/providers/codex.ts";
 import { installIntegratedFooter, type IntegratedFooterState } from "./footer.ts";
 import { callJittor } from "./service-client.ts";
-import { persistentEnforcementControl, type EnforcementControl } from "./settings.ts";
+import { persistentEnforcementControl, type CodexRecoveryControl, type EnforcementControl } from "./settings.ts";
 import { buildFooterBudget, formatFooterStatus, showJittorPanel } from "./tui.ts";
 import { showUsagePanel } from "./usage.ts";
 
@@ -23,6 +32,32 @@ const daemonClient: JittorExtensionClient = {
 	call: (operation, input) => callJittor(operation as Parameters<typeof callJittor>[0], input as never),
 };
 
+export interface CodexRecoveryRuntime {
+	now(): number;
+	random(): number;
+	setTimeout(callback: () => void | Promise<void>, delayMs: number): unknown;
+	clearTimeout(handle: unknown): void;
+}
+
+const SYSTEM_RECOVERY_RUNTIME: CodexRecoveryRuntime = {
+	now: Date.now,
+	random: Math.random,
+	setTimeout(callback, delayMs) { return setTimeout(() => { void callback(); }, delayMs); },
+	clearTimeout(handle) { clearTimeout(handle as ReturnType<typeof setTimeout>); },
+};
+
+function recoveryControl(enforcement: EnforcementControl): CodexRecoveryControl {
+	const candidate = enforcement as EnforcementControl & Partial<CodexRecoveryControl>;
+	return typeof candidate.isCodexRecoveryEnabled === "function"
+		? { isCodexRecoveryEnabled: () => candidate.isCodexRecoveryEnabled!() }
+		: { isCodexRecoveryEnabled: () => false };
+}
+
+function header(headers: Record<string, string>, name: string): string | undefined {
+	const expected = name.toLowerCase();
+	return Object.entries(headers).find(([key]) => key.toLowerCase() === expected)?.[1];
+}
+
 async function recordMetrics(client: JittorExtensionClient, metrics: MetricObservation[]): Promise<void> {
 	for (const metric of metrics) await client.call("metrics.record", metric);
 }
@@ -32,7 +67,7 @@ async function refreshFooter(client: JittorExtensionClient, state: IntegratedFoo
 	const provider = status.currentRoute?.provider;
 	const query = provider === "openai-codex"
 		? { source: "codex-subscription", metric: "used-fraction", limit: 100, order: "desc" }
-		: provider === "openrouter" ? { source: "openrouter", metric: "usage", limit: 10, order: "desc" } : null;
+		: provider === "openrouter" ? { source: "openrouter", limit: 20, order: "desc" } : null;
 	const metrics = query ? await client.call("metrics.query", query) as StoredMetricObservation[] : [];
 	state.providerBudget = buildFooterBudget(status, metrics);
 	state.requestRender?.();
@@ -169,8 +204,65 @@ export function registerJittorExtension(
 	pi: ExtensionAPI,
 	client: JittorExtensionClient = daemonClient,
 	enforcement: EnforcementControl = persistentEnforcementControl(),
+	codexRecovery: CodexRecoveryControl = recoveryControl(enforcement),
+	recoveryRuntime: CodexRecoveryRuntime = SYSTEM_RECOVERY_RUNTIME,
 ): void {
 	const footerState: IntegratedFooterState = { providerBudget: null };
+	const recoveryPolicy = new CodexRecoveryPolicy({
+		baseDelayMs: CODEX_RECOVERY_BASE_DELAY_MS,
+		maxDelayMs: CODEX_RECOVERY_MAX_DELAY_MS,
+		maxAttempts: CODEX_RECOVERY_MAX_ATTEMPTS,
+		attemptWindowMs: CODEX_RECOVERY_ATTEMPT_WINDOW_MS,
+		jitterRatio: CODEX_RECOVERY_JITTER_RATIO,
+	}, recoveryRuntime.random);
+	let recoveryTimer: unknown;
+	let lastCodexResponse: CodexFailureMetadata = {};
+	const cancelRecovery = (resetPolicy: boolean): void => {
+		if (recoveryTimer !== undefined) recoveryRuntime.clearTimeout(recoveryTimer);
+		recoveryTimer = undefined;
+		if (resetPolicy) recoveryPolicy.cancel();
+	};
+	const scheduleCodexRecovery = (ctx: ExtensionContext): void => {
+		if (!codexRecovery.isCodexRecoveryEnabled() || recoveryTimer !== undefined || !ctx.isIdle() || ctx.hasPendingMessages()) return;
+		const plan = recoveryPolicy.plan(recoveryRuntime.now());
+		if (plan.action === "exhausted") {
+			recoveryPolicy.abandonFailure();
+			if (ctx.hasUI) ctx.ui.notify(`Jittor Codex recovery stopped: ${plan.reason}.`, "warning");
+			return;
+		}
+		if (plan.action !== "schedule") return;
+		recoveryTimer = recoveryRuntime.setTimeout(async () => {
+			recoveryTimer = undefined;
+			if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
+			const attempt = recoveryPolicy.recordAttempt(recoveryRuntime.now());
+			if (!attempt) return;
+			pi.sendMessage({
+				customType: "jittor-codex-recovery",
+				content: `Retry the previous Codex request after a transient ${attempt.failureKind} failure. Automatic recovery attempt ${attempt.attempt} of ${CODEX_RECOVERY_MAX_ATTEMPTS}.`,
+				display: false,
+				details: { attempt: attempt.attempt, failureKind: attempt.failureKind },
+			}, { triggerTurn: true, deliverAs: "followUp" });
+		}, plan.delayMs);
+	};
+	let compactionTimer: ReturnType<typeof setInterval> | undefined;
+	const finishCompaction = (): void => {
+		if (compactionTimer) clearInterval(compactionTimer);
+		compactionTimer = undefined;
+		footerState.compaction = undefined;
+		footerState.requestRender?.();
+	};
+	const beginCompaction = (ctx: ExtensionContext, signal: AbortSignal): void => {
+		finishCompaction();
+		const usage = ctx.getContextUsage();
+		footerState.compaction = {
+			startedAt: Date.now(),
+			initialFraction: usage?.percent === null || usage?.percent === undefined ? 1 : usage.percent / 100,
+		};
+		compactionTimer = setInterval(() => footerState.requestRender?.(), FOOTER_COMPACTION_RENDER_INTERVAL_MS);
+		signal.addEventListener("abort", finishCompaction, { once: true });
+		if (signal.aborted) finishCompaction();
+		else footerState.requestRender?.();
+	};
 	const showFooter = (ctx: ExtensionContext): void => {
 		if (enforcement.isFooterEnabled()) installIntegratedFooter(ctx, footerState, () => pi.getThinkingLevel());
 		else ctx.ui.setFooter(undefined);
@@ -201,7 +293,7 @@ export function registerJittorExtension(
 	};
 
 	pi.registerCommand("jittor", {
-		description: "Inspect, enable, or disable Jittor routing",
+		description: "Inspect or control Jittor routing, budgets, and usage",
 		handler: async (args, ctx) => {
 			const action = args.trim().toLowerCase();
 			if (action === "off" || action === "disable") { disable(ctx); return; }
@@ -219,6 +311,10 @@ export function registerJittorExtension(
 				ctx.ui.notify("Jittor informational footer enabled; routing enforcement is unchanged.", "info");
 				return;
 			}
+			if (action === "usage") {
+				await showUsagePanel(ctx, client);
+				return;
+			}
 			if (!enforcement.isEnabled()) {
 				ctx.ui.notify("Jittor is monitor-only. Run /jittor on to re-enable blocking.", "info");
 				return;
@@ -226,20 +322,11 @@ export function registerJittorExtension(
 			await showJittorPanel(ctx, client);
 		},
 	});
-	pi.registerCommand("jittor-off", {
-		description: "Emergency local bypass: disable Jittor blocking without daemon access",
-		handler: async (_args, ctx) => { disable(ctx); },
-	});
-	pi.registerCommand("jittor-on", {
-		description: "Enable Jittor only after telemetry and routes pass readiness",
-		handler: async (_args, ctx) => { await enable(ctx); },
-	});
-	pi.registerCommand("usage", {
-		description: "Show Jittor token usage over time",
-		handler: async (_args, ctx) => { await showUsagePanel(ctx, client); },
-	});
 
 	pi.on("session_start", async (_event, ctx) => {
+		finishCompaction();
+		cancelRecovery(true);
+		lastCodexResponse = {};
 		ctx.ui.setStatus("jittor", undefined);
 		showFooter(ctx);
 		try {
@@ -253,7 +340,30 @@ export function registerJittorExtension(
 		}
 	});
 
+	pi.on("session_before_compact", (event, ctx) => {
+		beginCompaction(ctx, event.signal);
+	});
+
+	pi.on("session_compact", () => {
+		finishCompaction();
+	});
+
+	pi.on("agent_settled", async (_event, ctx) => {
+		if (footerState.compaction) finishCompaction();
+		scheduleCodexRecovery(ctx);
+		if (!enforcement.isFooterEnabled()) return;
+		try {
+			await syncCurrentRoute(pi, client, ctx);
+			await syncAvailableRoutes(pi, client, ctx);
+			await refreshFooter(client, footerState);
+		} catch {
+			footerState.providerBudget = null;
+			footerState.requestRender?.();
+		}
+	});
+
 	pi.on("input", async (event, ctx) => {
+		if (event.source !== "extension") cancelRecovery(true);
 		if (event.source === "extension" || !enforcement.isEnabled()) return { action: "continue" as const };
 		try {
 			const next = await client.call("router.decide", {}) as PolicyDecision;
@@ -278,6 +388,7 @@ export function registerJittorExtension(
 	});
 
 	pi.on("turn_start", async (_event, ctx) => {
+		lastCodexResponse = {};
 		if (!enforcement.isEnabled()) return;
 		try {
 			await syncCurrentRoute(pi, client, ctx);
@@ -290,6 +401,9 @@ export function registerJittorExtension(
 	});
 
 	pi.on("after_provider_response", async (event, ctx) => {
+		if (ctx.model?.provider === "openai-codex") {
+			lastCodexResponse = { status: event.status, ...(header(event.headers, "retry-after") ? { retryAfter: header(event.headers, "retry-after") } : {}) };
+		}
 		if (!Object.keys(event.headers).some((name) => name.toLowerCase().startsWith("x-codex-"))) return;
 		try {
 			const updates = parseCodexRateLimitHeaders(new Headers(event.headers), Date.now());
@@ -301,12 +415,25 @@ export function registerJittorExtension(
 	});
 
 	pi.on("message_end", async (event, _ctx) => {
+		if (event.message.role === "assistant" && event.message.provider === "openai-codex") {
+			if (event.message.stopReason === "error") {
+				const failure = classifyCodexFailure(event.message.errorMessage, lastCodexResponse);
+				if (codexRecovery.isCodexRecoveryEnabled() && failure.transient) recoveryPolicy.observeFailure(failure, recoveryRuntime.now());
+				else cancelRecovery(true);
+			} else if (event.message.stopReason !== "aborted") {
+				cancelRecovery(true);
+			}
+			lastCodexResponse = {};
+		}
 		const metrics = assistantUsageMetrics(event.message, Date.now());
 		if (metrics.length > 0) await recordMetrics(client, metrics).catch(() => undefined);
 		if (enforcement.isFooterEnabled()) await refreshFooter(client, footerState).catch(() => undefined);
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
+		finishCompaction();
+		cancelRecovery(true);
+		lastCodexResponse = {};
 		ctx.ui.setStatus("jittor", undefined);
 		ctx.ui.setFooter(undefined);
 	});

package/extension/src/settings.ts

@@ -9,9 +9,18 @@ export interface EnforcementControl {
 	setFooterEnabled(enabled: boolean): void;
 }
 
+export interface CodexRecoveryControl {
+	isCodexRecoveryEnabled(): boolean;
+}
+
+export interface PersistentExtensionControl extends EnforcementControl, CodexRecoveryControl {
+	setCodexRecoveryEnabled(enabled: boolean): void;
+}
+
 interface ExtensionSettings {
 	enforcementEnabled: boolean;
 	footerEnabled: boolean;
+	codexRecoveryEnabled: boolean;
 }
 
 function settingsPath(env: Record<string, string | undefined> = process.env): string {
@@ -22,14 +31,15 @@ function settingsPath(env: Record<string, string | undefined> = process.env): st
 function loadSettings(path: string): ExtensionSettings {
 	try {
 		const value = JSON.parse(readFileSync(path, "utf8")) as unknown;
-		if (typeof value !== "object" || value === null || Array.isArray(value)) return { enforcementEnabled: true, footerEnabled: true };
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return { enforcementEnabled: true, footerEnabled: true, codexRecoveryEnabled: false };
 		const record = value as Record<string, unknown>;
 		return {
 			enforcementEnabled: record["enforcementEnabled"] !== false,
 			footerEnabled: record["footerEnabled"] !== false,
+			codexRecoveryEnabled: record["codexRecoveryEnabled"] === true,
 		};
 	} catch {
-		return { enforcementEnabled: true, footerEnabled: true };
+		return { enforcementEnabled: true, footerEnabled: true, codexRecoveryEnabled: false };
 	}
 }
 
@@ -41,7 +51,7 @@ function persistSettings(path: string, settings: ExtensionSettings): void {
 	renameSync(temporary, path);
 }
 
-export function persistentEnforcementControl(env: Record<string, string | undefined> = process.env): EnforcementControl {
+export function persistentEnforcementControl(env: Record<string, string | undefined> = process.env): PersistentExtensionControl {
 	const path = settingsPath(env);
 	const settings = loadSettings(path);
 	return {
@@ -55,5 +65,10 @@ export function persistentEnforcementControl(env: Record<string, string | undefi
 			settings.footerEnabled = value;
 			persistSettings(path, settings);
 		},
+		isCodexRecoveryEnabled: () => settings.codexRecoveryEnabled,
+		setCodexRecoveryEnabled(value: boolean): void {
+			settings.codexRecoveryEnabled = value;
+			persistSettings(path, settings);
+		},
 	};
 }

package/extension/src/tui.ts

@@ -15,10 +15,35 @@ function latest(rows: StoredMetricObservation[], predicate: (row: StoredMetricOb
 	return rows.filter(predicate).sort((left, right) => right.observedAt - left.observedAt || right.id - left.id)[0];
 }
 
-function longestCodexWindow(rows: StoredMetricObservation[]): StoredMetricObservation | undefined {
-	return rows
-		.filter((row) => row.source === "codex-subscription" && row.metric === "used-fraction" && typeof row.value === "number")
-		.sort((left, right) => Number(right.attributes["windowSeconds"] ?? 0) - Number(left.attributes["windowSeconds"] ?? 0) || right.observedAt - left.observedAt)[0];
+function sanitizedText(value: string): string {
+	return value.replace(/[\r\n\t]/g, " ").replace(/ +/g, " ").trim();
+}
+
+function normalizedIdentity(value: unknown): string {
+	return typeof value === "string" ? value.toLowerCase().replace(/[^a-z0-9]+/g, "") : "";
+}
+
+function longestWindow(rows: StoredMetricObservation[]): StoredMetricObservation | undefined {
+	return [...rows].sort((left, right) =>
+		Number(right.attributes["windowSeconds"] ?? 0) - Number(left.attributes["windowSeconds"] ?? 0)
+		|| right.observedAt - left.observedAt
+		|| right.id - left.id,
+	)[0];
+}
+
+function codexWindowForModel(rows: StoredMetricObservation[], model: string): StoredMetricObservation | undefined {
+	const codexRows = rows.filter((row) => row.source === "codex-subscription" && row.metric === "used-fraction" && typeof row.value === "number");
+	const modelIdentity = normalizedIdentity(model);
+	const matchingAdditional = codexRows.filter((row) => {
+		const limitId = normalizedIdentity(row.attributes["limitId"]);
+		const limitName = normalizedIdentity(row.attributes["limitName"]);
+		return limitId !== "codex" && limitName.length > 0 && limitName === modelIdentity;
+	});
+	if (matchingAdditional.length > 0) return longestWindow(matchingAdditional);
+	return longestWindow(codexRows.filter((row) => {
+		const limitId = normalizedIdentity(row.attributes["limitId"]);
+		return limitId === "codex" || (limitId.length === 0 && row.scope.startsWith("codex:"));
+	}));
 }
 
 function compactWindowName(seconds: number): string {
@@ -36,19 +61,32 @@ function windowName(seconds: number): string {
 export function buildFooterBudget(status: RouterStatus, metrics: StoredMetricObservation[]): ProviderBudget | null {
 	if (!status.ready || !status.currentRoute) return null;
 	if (status.currentRoute.provider === "openai-codex") {
-		const codex = longestCodexWindow(metrics);
+		const codex = codexWindowForModel(metrics, status.currentRoute.model);
 		if (!codex || typeof codex.value !== "number") return null;
+		const resetsAtSeconds = Number(codex.attributes["resetsAt"]);
 		return {
+			kind: "bounded",
 			label: compactWindowName(Number(codex.attributes["windowSeconds"] ?? 0)),
-			fraction: codex.value,
-			valueText: `${(codex.value * 100).toFixed(1)}% used`,
+			remainingFraction: 1 - codex.value,
 			observedAt: codex.observedAt,
+			...(Number.isFinite(resetsAtSeconds) && resetsAtSeconds > 0 ? { resetsAt: resetsAtSeconds * 1_000 } : {}),
 		};
 	}
 	if (status.currentRoute.provider === "openrouter") {
 		const openRouter = latest(metrics, (row) => row.source === "openrouter" && row.metric === "usage" && typeof row.value === "number");
+		const remaining = latest(metrics, (row) => row.source === "openrouter" && row.metric === "remaining-fraction" && typeof row.value === "number");
+		if (remaining && typeof remaining.value === "number" && (!openRouter || remaining.observedAt >= openRouter.observedAt)) {
+			const reset = typeof remaining.attributes["reset"] === "string" ? sanitizedText(remaining.attributes["reset"]) : undefined;
+			return {
+				kind: "bounded",
+				label: "OR",
+				remainingFraction: remaining.value,
+				observedAt: remaining.observedAt,
+				...(reset ? { resetText: `${reset} reset` } : {}),
+			};
+		}
 		if (!openRouter || typeof openRouter.value !== "number") return null;
-		return { label: "spend", fraction: null, valueText: `$${openRouter.value.toFixed(3)}`, observedAt: openRouter.observedAt };
+		return { kind: "unbounded", label: "spend", valueText: `$${openRouter.value.toFixed(3)}`, observedAt: openRouter.observedAt };
 	}
 	return null;
 }
@@ -56,7 +94,7 @@ export function buildFooterBudget(status: RouterStatus, metrics: StoredMetricObs
 export function formatFooterStatus(status: RouterStatus, metrics: StoredMetricObservation[]): string {
 	const budget = buildFooterBudget(status, metrics);
 	if (!budget) return "";
-	return budget.fraction === null ? budget.valueText : `${budget.label} ${(budget.fraction * 100).toFixed(1)}%`;
+	return budget.kind === "unbounded" ? budget.valueText : `${budget.label} ${(budget.remainingFraction * 100).toFixed(1)}% left`;
 }
 
 function nextAction(action: PolicyAction | undefined): string {
@@ -87,10 +125,10 @@ function burnLine(rows: StoredMetricObservation[], current: StoredMetricObservat
 
 export function buildStatusView(status: RouterStatus, metrics: StoredMetricObservation[], now = Date.now()): string[] {
 	const lines = [status.ready ? "Ready" : "Not ready"];
-	const codex = status.currentRoute?.provider === "openai-codex" ? longestCodexWindow(metrics) : undefined;
+	const codex = status.currentRoute?.provider === "openai-codex" ? codexWindowForModel(metrics, status.currentRoute.model) : undefined;
 	if (codex && typeof codex.value === "number") {
 		const seconds = Number(codex.attributes["windowSeconds"] ?? 0);
-		lines.push(`Codex ${windowName(seconds)}: ${(codex.value * 100).toFixed(1)}%`);
+		lines.push(`Codex ${windowName(seconds)}: ${((1 - codex.value) * 100).toFixed(1)}% left`);
 		lines.push(burnLine(metrics, codex, now));
 	}
 	const openRouter = status.currentRoute?.provider === "openrouter"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/jittor",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Just-in-Time Token Optimizing Router for Pi",
   "type": "module",
   "keywords": ["pi-package", "llm-router", "token-budget"],

package/src/constants.ts

@@ -1,4 +1,3 @@
-export const VERSION = "0.1.1";
 export const SQLITE_SCHEMA_VERSION = 1;
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
 export const DEFAULT_QUERY_LIMIT = 1_000;
@@ -13,6 +12,12 @@ export const FOOTER_CONTEXT_ERROR_FRACTION = 0.9;
 export const FOOTER_BAR_MIN_WIDTH = 4;
 export const FOOTER_BAR_MAX_WIDTH = 8;
 export const FOOTER_WIDE_TERMINAL_WIDTH = 100;
+export const FOOTER_COMPACTION_RENDER_INTERVAL_MS = 1_000;
+export const FOOTER_COMPACTION_DRAIN_STEP_MS = 3_000;
+export const MILLISECONDS_PER_SECOND = 1_000;
+export const MILLISECONDS_PER_MINUTE = 60 * MILLISECONDS_PER_SECOND;
+export const MILLISECONDS_PER_HOUR = 60 * MILLISECONDS_PER_MINUTE;
+export const MILLISECONDS_PER_DAY = 24 * MILLISECONDS_PER_HOUR;
 export const LOOPBACK_HOST = "127.0.0.1";
 export const JITTOR_STATE_DIRECTORY = "jittor";
 export const JITTOR_EXTENSION_SETTINGS_FILENAME = "extension.json";
@@ -24,3 +29,10 @@ export const USAGE_CHART_HEIGHT = 8;
 export const USAGE_Y_AXIS_WIDTH = 7;
 export const USAGE_TOKEN_QUERY_LIMIT = 10_000;
 export const MAX_DYNAMIC_ROUTES = 100;
+export const CODEX_ERROR_MESSAGE_LIMIT = 160;
+export const CODEX_RETRY_AFTER_MAX_MS = 5 * MILLISECONDS_PER_MINUTE;
+export const CODEX_RECOVERY_BASE_DELAY_MS = 2 * MILLISECONDS_PER_SECOND;
+export const CODEX_RECOVERY_MAX_DELAY_MS = CODEX_RETRY_AFTER_MAX_MS;
+export const CODEX_RECOVERY_MAX_ATTEMPTS = 3;
+export const CODEX_RECOVERY_ATTEMPT_WINDOW_MS = 10 * MILLISECONDS_PER_MINUTE;
+export const CODEX_RECOVERY_JITTER_RATIO = 0.2;

package/src/domain/codex-recovery.ts

@@ -0,0 +1,195 @@
+import {
+	CODEX_ERROR_MESSAGE_LIMIT,
+	CODEX_RETRY_AFTER_MAX_MS,
+	MILLISECONDS_PER_SECOND,
+} from "../constants.ts";
+
+export type CodexFailureKind =
+	| "concurrency"
+	| "rate-limit"
+	| "overload"
+	| "transport"
+	| "quota"
+	| "authentication"
+	| "invalid-request"
+	| "unknown";
+
+export interface CodexFailure {
+	kind: CodexFailureKind;
+	transient: boolean;
+	code?: string;
+	source?: string;
+	message?: string;
+	retryAfterMs?: number;
+}
+
+export interface CodexFailureMetadata {
+	status?: number;
+	retryAfter?: string;
+}
+
+export interface CodexRecoveryOptions {
+	baseDelayMs: number;
+	maxDelayMs: number;
+	maxAttempts: number;
+	attemptWindowMs: number;
+	jitterRatio: number;
+}
+
+export type CodexRecoveryPlan =
+	| { action: "schedule"; attempt: number; delayMs: number; failureKind: CodexFailureKind }
+	| { action: "wait"; reason: string }
+	| { action: "exhausted"; reason: string };
+
+export interface CodexRecoveryAttempt {
+	attempt: number;
+	failureKind: CodexFailureKind;
+}
+
+export class CodexRecoveryPolicy {
+	private pendingFailure: CodexFailure | undefined;
+	private attempts = 0;
+	private windowStartedAt: number | undefined;
+
+	constructor(
+		private readonly options: CodexRecoveryOptions,
+		private readonly random: () => number = Math.random,
+	) {
+		if (!Number.isFinite(options.baseDelayMs) || options.baseDelayMs < 0) throw new Error("baseDelayMs must be non-negative");
+		if (!Number.isFinite(options.maxDelayMs) || options.maxDelayMs < options.baseDelayMs) throw new Error("maxDelayMs must be at least baseDelayMs");
+		if (!Number.isInteger(options.maxAttempts) || options.maxAttempts < 1) throw new Error("maxAttempts must be a positive integer");
+		if (!Number.isFinite(options.attemptWindowMs) || options.attemptWindowMs <= 0) throw new Error("attemptWindowMs must be positive");
+		if (!Number.isFinite(options.jitterRatio) || options.jitterRatio < 0 || options.jitterRatio > 1) throw new Error("jitterRatio must be between 0 and 1");
+	}
+
+	observeFailure(failure: CodexFailure, now: number): void {
+		this.normalizeWindow(now);
+		this.pendingFailure = failure.transient ? failure : undefined;
+	}
+
+	observeSuccess(): void {
+		this.cancel();
+	}
+
+	cancel(): void {
+		this.pendingFailure = undefined;
+		this.attempts = 0;
+		this.windowStartedAt = undefined;
+	}
+
+	abandonFailure(): void {
+		this.pendingFailure = undefined;
+	}
+
+	plan(now: number): CodexRecoveryPlan {
+		this.normalizeWindow(now);
+		if (!this.pendingFailure) return { action: "wait", reason: "no transient Codex failure is pending" };
+		if (this.attempts >= this.options.maxAttempts) {
+			return { action: "exhausted", reason: `${this.options.maxAttempts} recovery attempts reached within ${this.options.attemptWindowMs}ms` };
+		}
+		const base = this.pendingFailure.retryAfterMs
+			?? this.options.baseDelayMs * (2 ** this.attempts);
+		const sample = this.random();
+		const unit = Number.isFinite(sample) ? Math.min(1, Math.max(0, sample)) : 0;
+		const multiplier = 1 + ((unit * 2) - 1) * this.options.jitterRatio;
+		const jittered = Math.max(0, Math.round(base * multiplier));
+		const delayMs = this.pendingFailure.retryAfterMs === undefined ? jittered : Math.max(base, jittered);
+		return {
+			action: "schedule",
+			attempt: this.attempts + 1,
+			delayMs: Math.min(this.options.maxDelayMs, delayMs),
+			failureKind: this.pendingFailure.kind,
+		};
+	}
+
+	recordAttempt(now: number): CodexRecoveryAttempt | undefined {
+		this.normalizeWindow(now);
+		if (!this.pendingFailure || this.attempts >= this.options.maxAttempts) return undefined;
+		if (this.windowStartedAt === undefined) this.windowStartedAt = now;
+		this.attempts += 1;
+		const attempt = { attempt: this.attempts, failureKind: this.pendingFailure.kind };
+		this.pendingFailure = undefined;
+		return attempt;
+	}
+
+	state(): { attempts: number; pending: boolean } {
+		return { attempts: this.attempts, pending: this.pendingFailure !== undefined };
+	}
+
+	private normalizeWindow(now: number): void {
+		if (this.windowStartedAt !== undefined && now - this.windowStartedAt >= this.options.attemptWindowMs) {
+			this.attempts = 0;
+			this.windowStartedAt = undefined;
+		}
+	}
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+		? value as Record<string, unknown>
+		: undefined;
+}
+
+function firstString(...values: unknown[]): string | undefined {
+	for (const value of values) {
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+	return undefined;
+}
+
+function retryAfterMs(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const seconds = Number(value.trim());
+	if (!Number.isFinite(seconds) || seconds < 0) return undefined;
+	return Math.min(CODEX_RETRY_AFTER_MAX_MS, Math.round(seconds * MILLISECONDS_PER_SECOND));
+}
+
+function matches(value: string, patterns: readonly string[]): boolean {
+	return patterns.some((pattern) => value.includes(pattern));
+}
+
+export function classifyCodexFailure(value: unknown, metadata: CodexFailureMetadata = {}): CodexFailure {
+	const root = asRecord(value);
+	const detail = asRecord(root?.["detail"]);
+	const nestedError = asRecord(root?.["error"]);
+	const code = firstString(detail?.["code"], detail?.["error_code"], nestedError?.["code"], root?.["code"]);
+	const source = firstString(detail?.["source"], nestedError?.["source"], root?.["source"]);
+	const rawMessage = firstString(
+		detail?.["message"],
+		typeof root?.["error"] === "string" ? root["error"] : undefined,
+		nestedError?.["message"],
+		root?.["message"],
+		typeof value === "string" ? value : undefined,
+	);
+	const message = rawMessage?.slice(0, CODEX_ERROR_MESSAGE_LIMIT);
+	const evidence = [code, source, message].filter(Boolean).join(" ").toLowerCase();
+	const base = {
+		...(code ? { code } : {}),
+		...(source ? { source } : {}),
+		...(message ? { message } : {}),
+		...(retryAfterMs(metadata.retryAfter) !== undefined ? { retryAfterMs: retryAfterMs(metadata.retryAfter) } : {}),
+	};
+
+	if (matches(evidence, ["insufficient_quota", "quota exceeded", "out of credits", "billing"])) {
+		return { kind: "quota", transient: false, ...base };
+	}
+	if (metadata.status === 401 || metadata.status === 403 || matches(evidence, ["invalid_api_key", "authentication", "unauthorized", "permission_denied"])) {
+		return { kind: "authentication", transient: false, ...base };
+	}
+	if (matches(evidence, ["invalid_prompt", "invalid_request", "context_length_exceeded"]) || metadata.status === 400 || metadata.status === 422) {
+		return { kind: "invalid-request", transient: false, ...base };
+	}
+	if (matches(evidence, ["concurrency_limit", "too many concurrent requests", "throttled"])) {
+		return { kind: "concurrency", transient: true, ...base };
+	}
+	if (matches(evidence, ["server_is_overloaded", "slow_down", "service unavailable", "overloaded"]) || (metadata.status !== undefined && metadata.status >= 500 && metadata.status <= 599)) {
+		return { kind: "overload", transient: true, ...base };
+	}
+	if (metadata.status === 429 || matches(evidence, ["rate_limit_exceeded", "rate limit", "too many requests"])) {
+		return { kind: "rate-limit", transient: true, ...base };
+	}
+	if (matches(evidence, ["timeout", "timed out", "network", "connection", "websocket", "fetch failed"])) {
+		return { kind: "transport", transient: true, ...base };
+	}
+	return { kind: "unknown", transient: false, ...base };
+}

package/src/providers/openrouter-contracts.ts

@@ -164,7 +164,13 @@ export function parseOpenRouterKey(rootValue: unknown, observedAt: number): Open
 	add("usage-monthly", snapshot.usageMonthly);
 	add("limit", limit);
 	add("limit-remaining", remaining);
-	if (limit !== null && limit > 0) snapshot.metrics.push(metric(scope, "used-fraction", usage / limit, "ratio", observedAt));
+	if (limit !== null && limit > 0 && remaining !== null) {
+		const remainingFraction = remaining / limit;
+		if (remainingFraction < 0 || remainingFraction > 1) throw new Error("OpenRouter key remaining fraction is outside its configured limit");
+		const attributes = { limit, remaining, reset: snapshot.reset };
+		snapshot.metrics.push(metric(scope, "remaining-fraction", remainingFraction, "ratio", observedAt, attributes));
+		snapshot.metrics.push(metric(scope, "used-fraction", 1 - remainingFraction, "ratio", observedAt, attributes));
+	}
 	return snapshot;
 }
 

package/src/service.ts

@@ -1,4 +1,5 @@
-import { SERVICE_MAX_BODY_BYTES, VERSION } from "./constants.ts";
+import { SERVICE_MAX_BODY_BYTES } from "./constants.ts";
+import { VERSION } from "./version.ts";
 import { validateMetricObservation, type MetricObservation, type MetricQuery, type StoredMetricObservation } from "./domain/metric.ts";
 import type { MetricStore } from "./ports/metric-store.ts";
 import type { RouteOverride, RouterController, RouterStatus, TelemetryPollResult } from "./ports/router-controller.ts";

package/src/version.ts

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+
+function packageVersion(): string {
+	const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as unknown;
+	if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+		throw new Error("Jittor package manifest must be an object");
+	}
+	const version = (manifest as Record<string, unknown>)["version"];
+	if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+		throw new Error("Jittor package manifest has an invalid version");
+	}
+	return version;
+}
+
+/** Runtime package version; package.json is the single release source of truth. */
+export const VERSION = packageVersion();