@danypops/pi-jittor 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# @danypops/pi-jittor
+
+The Pi extension for Jittor: routing enforcement, the integrated footer, settings TUI, usage/cost graphs, and benchmark panels, all through an authenticated loopback client to the [`@danypops/jittor`](../jittor) daemon. See the [repo root README](../../README.md) for the two-package overview.
+
+## Behavior
+
+The 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. Mutable route state is scoped by Pi session, so concurrent sessions cannot replace each other's active provider or footer budget selection. Each session registers an opaque secret with the daemon at `session_start` (best-effort; a registration failure leaves that session unarmored rather than blocked) and presents it on every router-mutating call for the rest of its lifetime; an unregistered `session_id` continues to mutate exactly as before, so this is additive armor, not a breaking change for other callers of the same API. A configured required budget source still fails closed; a provider with no enforceable budget window continues explicitly monitor-only.
+
+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. Anthropic shows the same drain semantics from its most-restrictive-in-effect token bucket, falling back to the request bucket when no token telemetry has been observed yet. During Pi compaction, the context bar drains from its captured fill against a learned median duration estimated from the last few completed compactions (bounded to the most recent 20 samples, requiring at least 3 before trusting it). It never renders a timer. Until enough evidence exists, the bar does not drain; it blinks in place at its captured fill. Run `jittor compaction estimate [--json]` (via the core CLI) to inspect the current estimate and its confidence directly. Unknown and stale telemetry are marked explicitly. Run `/jittor` for the consolidated Settings TUI (its default action), or `/jittor status` for detailed burn pressure, freshness, route state, and confirmed emergency-halt/override controls.
+
+The extension currently registers no model-callable native tools, so Pi's native model `content` versus renderer `details` contract is explicitly not applicable. Daemon JSON, CLI `--json`, human CLI output, command notifications, panels, and the footer remain separate bounded channels. See the core package's [`docs/OUTPUT_CHANNELS.md`](../jittor/docs/OUTPUT_CHANNELS.md) for the conformance matrix and the requirements that apply if a native tool is introduced later.
+
+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.
+
+### Opt-in Codex settled-turn recovery
+
+Transient Codex recovery is securely off by default and controlled through the existing Jittor command surface:
+
+```text
+/jittor recovery status
+/jittor recovery on
+/jittor recovery off
+/jittor recovery cancel
+```
+
+The on/off choice persists privately in `$XDG_CONFIG_HOME/jittor/extension.json` (or `~/.config/jittor/extension.json`). Status reports only enabled state, cooldown, bounded attempt/window counters, and the normalized failure class. `cancel` clears the current cooldown and attempt window without changing the persisted on/off choice.
+
+The extension 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.
+
+### Settings
+
+`/jittor` is the settings and control command. Bare `/jittor` (or `/jittor settings`) opens one keyboard-navigable TUI covering routing enforcement, the informational footer, Codex recovery, and all four token-budget thresholds, with explicit ON/OFF and configured/not-configured labels, bounded rendering on narrow terminals, and confirmation for weaker enforcement/recovery changes. `/jittor status` shows the routing/pressure panel that used to be the bare command's default. Existing non-TUI subcommands (`benchmarks`, `outcome`, `recovery`, `on`/`off`, `footer on`/`off`, `context`) remain available for automation and are unchanged.
+
+### Usage and cost graphs
+
+`/usage` is its own top-level command, separate from `/jittor`. Bare `/usage` opens a colored Unicode cumulative graph with X/Y axes, per-provider/model series, and explicit **Hourly**, **Daily**, **Weekly**, **Monthly**, and **Quarterly** periods; `/usage cost` opens the same graph showing aggregated USD spend instead of tokens, reusing the `cost` metric already recorded content-free on every finalized Pi assistant message (no new instrumentation). Left/Right or Tab/Shift+Tab changes the time frame, `v` toggles between the token and cost views, and `r` refreshes.
+
+The graph fetches metrics per distinct provider/model scope (`jittor metrics distinct-scopes`, bounded to 40 scopes, 250 rows each) rather than one flat "most recent rows" query. A flat query lets one heavy, long-running session monopolize the entire row budget with its own most recent activity, silently hiding every other provider from the chart no matter which time frame is selected, since the query would never reach back far enough in time to see anything else. Fetching per scope guarantees every active provider/model gets its own fair share of the query budget instead.
+
+Series are colored with a categorical palette chosen to avoid this UI's own status colors ("success"/"warning"/"error" already mean something specific elsewhere in this panel, so reusing them for arbitrary model identity would make a model's bar segment look like a warning or a failure) and instead reuses the theme's syntax-highlighting roles. Once more series are active than there are hues, a series reuses a hue in bold rather than repeating an indistinguishable color. Multiple models active within the same cumulative time frame are rendered as one bar stacked by color, not separate bars.
+
+Token-budget thresholds are optional and must be configured by the user; Jittor never infers a token allowance from Codex or another provider's subscription percentage. Configure or clear one period with `/usage budget <hourly|daily|weekly|monthly|quarterly> <positive-tokens|off>`, and inspect all of them with `/usage budget`. A configured budget appears as a horizontal threshold on the cumulative graph with explicit remaining or **OVER BUDGET** state; the cost view does not yet support a budget threshold. These private settings persist in `$XDG_CONFIG_HOME/jittor/extension.json` (or `~/.config/jittor/extension.json`).
+
+See [`docs/USAGE_PRIOR_ART.md`](docs/USAGE_PRIOR_ART.md) for the chart design research.
+
+### Cost per Papyrus task
+
+The extension observes Papyrus's task-focus lifecycle in real time over a shared Pi extension event bus (`papyrus.task-focus.v1`) -- Papyrus never depends on Jittor, it only broadcasts which task is currently focused. Every token/cost metric already recorded on a finalized Pi assistant message is tagged with the currently focused task's id, and the provider/model/thinking level active at that moment, the instant it is recorded (no time-window estimation, no new instrumentation). A paused or cleared focus stops tagging; spend recorded with nothing focused is reported separately as unattributed, never dropped or folded into an invented task. Run `jittor metrics cost-by-task --since <ms> --until <ms> [--json]` (via the core CLI) for a bounded per-task breakdown of cost and input/output/cache tokens, broken down further by which provider/model/thinking combination each task actually spent on.
+
+### Benchmark evidence panel
+
+Run `/jittor benchmarks [coding|general] [research|planning|general]` (either order, either or both omitted) for the responsive recommendation panel over the core daemon's benchmark ranking operation (see `@danypops/jittor`'s README for ingestion sources). Because the released Pi extension API does not expose the exact `/scoped-models` set, the current adapter labels candidates `available-models`; the panel says **ADVISORY** and offers no selection action. Automatic route ordering is allowed only for `exact-session` authority and then narrows/reorders routes already present in the supplied candidate set. `/jittor outcome accepted` or `/jittor outcome rejected` attaches explicit outcome evidence to the latest completed local run; runtime completion alone is not treated as quality success.
+
+### Context pressure
+
+Run `/jittor context` for the in-session summary of Papyrus prompt-injection and Pi compaction telemetry; see `@danypops/jittor`'s README for what is recorded and the equivalent CLI command.
+
+## Development
+
+```bash
+bun test
+bun x tsc --noEmit
+```

package/docs/USAGE_PRIOR_ART.md

@@ -0,0 +1,64 @@
+# Token-usage TUI prior art
+
+Research performed before implementing Jittor's `/jittor usage` frontend.
+
+## Local agent implementations
+
+### Claude Code
+
+`~/Repositories/claude/src/components/Stats.tsx` contains the strongest terminal chart precedent:
+
+- `generateTokenChart()` renders daily model-token series with an eight-row `asciichart` plot.
+- Width adapts to the terminal and is capped near 52 columns.
+- The top three models receive distinct theme colors.
+- The X axis places three or four date labels at even positions.
+- The Y axis abbreviates values as `k` and `M`.
+
+`~/Repositories/claude/src/utils/heatmap.ts` adds a GitHub-style activity view using percentile-derived `░▒▓█` intensity. `src/components/design-system/ProgressBar.tsx` uses eighth-cell Unicode blocks (`▏▎▍▌▋▊▉█`) for fractional precision.
+
+Useful decisions: adaptive width, short axes, bounded series count, theme colors, Unicode partial cells. The Jittor requirement is a histogram rather than Claude's line chart, so only the layout and scaling ideas are reused.
+
+### OpenCode
+
+`~/Repositories/opencode/packages/stats/core/src/domain/home.ts` keeps usage projection in the domain layer. It defines explicit ranges (`1D`, `1W`, `2W`, `1M`, `2M`, `3M`, `YTD`, `ALL`), computes date windows, creates deterministic buckets, and formats range-appropriate labels.
+
+Useful decision: range/window/bucket projection is separate from rendering and data access.
+
+### Codex
+
+`~/Repositories/codex` exposes turn-level `last` and `total` token usage plus account rate-limit snapshots. Its TUI focuses on compact totals and quota state; no reusable historical token histogram was found.
+
+Useful decision: finalized turn usage is the durable accounting point. Jittor already records Pi assistant usage on `message_end`.
+
+### Cline
+
+Cline tracks accumulated input/output/cache/cost values and presents context/cost in its status area. Its local CLI sources did not contain a historical terminal histogram comparable to the requested chart.
+
+Useful decision: preserve input, output, cache-read, and cache-write categories rather than collapsing accounting at ingestion.
+
+## Pi extensions
+
+Registry and package-source review covered:
+
+- `@pi-vault/pi-usage@0.6.0`: polished framed/tabbed dashboard, Today/This Week/Last Week/All Time tables, live provider quotas, width-safe theme adapters. It has no historical vertical token histogram.
+- `@sreetej510/pi-usage@0.1.20`: `/usage` provider quota reports, cache, retries, statusline, and 20-cell `█░` quota bars.
+- `@narumitw/pi-codex-usage@0.20.0`: Codex 5-hour/weekly quota bars and compact statusline.
+- `@alexanderfortin/pi-token-usage@0.3.0`: session-file aggregation and table/export overlay, but no chart.
+
+Useful decisions: native `registerCommand`, `ctx.ui.custom`, width-bounded rendering, theme-derived colors, keyboard refresh/range navigation, and daemon/cache-backed data rather than synchronous file scans in render.
+
+## OpenRouter visual reference
+
+OpenRouter's authenticated web dashboard is not distributed as reusable terminal source. Its relevant visual grammar is a compact time-bucket histogram with colored model/provider series, readable axes, totals, and a legend. Jittor reproduces that grammar with Unicode blocks rather than copying web implementation details.
+
+## Jittor design
+
+Jittor combines the best applicable patterns:
+
+1. Pure domain projection in `src/domain/usage.ts`.
+2. Explicit `24h`, `7d`, `30d`, and `90d` windows.
+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 `/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/benchmark-tui.ts

@@ -0,0 +1,113 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import {
+	BENCHMARK_TUI_MAX_CANDIDATES,
+	BENCHMARK_TUI_MAX_PROVENANCE_PER_CANDIDATE,
+	MODEL_RANKING_DEFAULT_CONTEXT_WEIGHT,
+	MODEL_RANKING_DEFAULT_COST_WEIGHT,
+	MODEL_RANKING_DEFAULT_LATENCY_WEIGHT,
+	MODEL_RANKING_DEFAULT_QUALITY_WEIGHT,
+	MODEL_RANKING_DEFAULT_RELIABILITY_WEIGHT,
+	type ModelCandidate,
+	type ModelRankingResult,
+	type ModelTaskDomain,
+	type ModelTaskType,
+	type RankedModel,
+	type UtilityComponentName,
+} from "@danypops/jittor";
+import { sessionSecretField } from "./session-identity.ts";
+
+export interface BenchmarkPanelClient {
+	call(operation: string, input: unknown): Promise<any>;
+}
+
+interface BenchmarkTheme {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+type BenchmarkPanelAction = "refresh" | "close";
+
+const COMPONENT_LABELS: Record<UtilityComponentName, string> = { quality: "Q", cost: "$", latency: "L", context: "C", reliability: "R" };
+
+function componentText(item: RankedModel): string {
+	return item.components.map((component) => `${COMPONENT_LABELS[component.name]} ${component.score === null ? "?" : component.score.toFixed(3)}`).join(" · ");
+}
+
+function candidateLines(item: RankedModel, index: number, currentIdentity: string): string[] {
+	const current = item.identity.startsWith(`${currentIdentity}:`);
+	const localSamples = item.components.find((component) => component.name === "reliability")?.evidenceCount ?? 0;
+	const provenance = item.provenance.slice(0, BENCHMARK_TUI_MAX_PROVENANCE_PER_CANDIDATE).map((source) => `${source.sourceId}@${source.revision} ${source.freshness}`).join(" · ");
+	return [
+		` ${index + 1}. ${item.identity}${index === 0 ? "  recommended" : ""}${current ? "  current" : ""}`,
+		`    utility ${item.utility === null ? "?" : item.utility.toFixed(3)} · confidence ${(item.confidence * 100).toFixed(0)}% · ${componentText(item)}`,
+		`    local n=${localSamples}${provenance ? ` · ${provenance}` : " · no external provenance"}`,
+	];
+}
+
+export function renderBenchmarkView(result: ModelRankingResult, currentIdentity: string, width: number, theme: BenchmarkTheme): string[] {
+	const safeWidth = Math.max(1, width);
+	const shown = result.ranked.slice(0, BENCHMARK_TUI_MAX_CANDIDATES);
+	const currentIndex = result.ranked.findIndex((item) => item.identity.startsWith(`${currentIdentity}:`));
+	const recommended = result.ranked[0];
+	const reason = recommended && currentIndex > 0
+		? `Recommendation differs from current: ${recommended.identity} ranks #1; current ranks #${currentIndex + 1}.`
+		: recommended && currentIndex === 0 ? "Current model is the top recommendation." : "Current model is outside the ranked candidates.";
+	const lines = [
+		theme.fg("borderMuted", "─".repeat(safeWidth)),
+		theme.bold("Jittor Benchmark Recommendations"),
+		result.scopeAuthority === "exact-session" ? "Scope: exact session" : "Scope: available models · ADVISORY (exact session scope unavailable)",
+		`Domain: ${result.domain} · Type: ${result.type} · evidence ${result.completeness}`,
+		reason,
+		...shown.flatMap((item, index) => candidateLines(item, index, currentIdentity)),
+		...(result.ranked.length > shown.length ? [` … ${result.ranked.length - shown.length} more candidates omitted`] : []),
+		...(result.scopeWarning ? [result.scopeWarning] : []),
+		theme.fg("dim", "r refresh · Esc close"),
+		theme.fg("borderMuted", "─".repeat(safeWidth)),
+	];
+	return lines.map((line) => truncateToWidth(line, safeWidth, "…"));
+}
+
+export async function showBenchmarkPanel(
+	ctx: ExtensionCommandContext,
+	client: BenchmarkPanelClient,
+	candidates: ModelCandidate[],
+	currentIdentity: string,
+	domain: ModelTaskDomain,
+	type: ModelTaskType,
+): Promise<void> {
+	for (;;) {
+		const session_id = ctx.sessionManager.getSessionId();
+		const result = await client.call("models.rank", {
+			candidates,
+			session_id,
+			...sessionSecretField(session_id),
+			scopeAuthority: "available-models",
+			domain,
+			type,
+			budgetPressure: 0,
+			weights: {
+				quality: MODEL_RANKING_DEFAULT_QUALITY_WEIGHT,
+				cost: MODEL_RANKING_DEFAULT_COST_WEIGHT,
+				latency: MODEL_RANKING_DEFAULT_LATENCY_WEIGHT,
+				context: MODEL_RANKING_DEFAULT_CONTEXT_WEIGHT,
+				reliability: MODEL_RANKING_DEFAULT_RELIABILITY_WEIGHT,
+			},
+			sourceIds: ["openrouter-models", "lmarena-hf", "artificial-analysis-direct", "openrouter-design-arena"],
+		}) as ModelRankingResult;
+		if (ctx.mode !== "tui") {
+			ctx.ui.notify(renderBenchmarkView(result, currentIdentity, 100, { fg: (_color, text) => text, bold: (text) => text }).join("\n"), "info");
+			return;
+		}
+		const action = await ctx.ui.custom<BenchmarkPanelAction>((_tui, theme, _keybindings, done) => ({
+			invalidate() {},
+			render(width: number): string[] { return renderBenchmarkView(result, currentIdentity, width, theme); },
+			handleInput(data: string): void {
+				if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) done("close");
+				else if (data === "r") done("refresh");
+			},
+		}));
+		if (!action || action === "close") return;
+		await client.call("benchmark.refresh", { force: true });
+	}
+}

package/extension/src/capabilities/codex-recovery.ts

@@ -0,0 +1,130 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	CODEX_RECOVERY_ATTEMPT_WINDOW_MS,
+	CODEX_RECOVERY_BASE_DELAY_MS,
+	CODEX_RECOVERY_JITTER_RATIO,
+	CODEX_RECOVERY_MAX_ATTEMPTS,
+	CODEX_RECOVERY_MAX_DELAY_MS,
+	MILLISECONDS_PER_MINUTE,
+	MILLISECONDS_PER_SECOND,
+	CodexRecoveryPolicy,
+	classifyCodexFailure,
+	type CodexFailureKind,
+	type CodexFailureMetadata,
+} from "@danypops/jittor";
+import type { CodexRecoveryControl } from "../settings.ts";
+import { headerValue } from "./http-headers.ts";
+
+export interface CodexRecoveryRuntime {
+	now(): number;
+	random(): number;
+	setTimeout(callback: () => void | Promise<void>, delayMs: number): unknown;
+	clearTimeout(handle: unknown): void;
+}
+
+export 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>); },
+};
+
+/**
+ * Codex's settled-turn hidden-retry recovery, as its own capability: tracks the most recent
+ * Codex response (status/retry-after) across the current turn, classifies a finalized failure,
+ * and schedules at most one bounded, jittered follow-up once Pi's own turn has genuinely
+ * settled. Fully self-contained -- the only external dependencies are Pi's own message-send API,
+ * the persisted on/off control, and a runtime the tests can fake (timers, randomness, clock).
+ */
+export class CodexRecoveryCapability {
+	private readonly policy: CodexRecoveryPolicy;
+	private lastResponse: CodexFailureMetadata = {};
+	private timer: unknown;
+	private cooldown: { until: number; attempt: number; failureKind: CodexFailureKind } | undefined;
+
+	constructor(
+		private readonly pi: ExtensionAPI,
+		private readonly control: CodexRecoveryControl,
+		private readonly runtime: CodexRecoveryRuntime,
+	) {
+		this.policy = 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,
+		}, runtime.random);
+	}
+
+	/** Clears the tracked response at the start of every new turn, before any Codex response for it has arrived. */
+	resetTurn(): void {
+		this.lastResponse = {};
+	}
+
+	notifyResponse(status: number, headers: Record<string, string>): void {
+		this.lastResponse = { status, ...(headerValue(headers, "retry-after") ? { retryAfter: headerValue(headers, "retry-after") } : {}) };
+	}
+
+	notifyMessageEnd(stopReason: string, errorMessage: string | undefined): void {
+		if (stopReason === "error") {
+			const failure = classifyCodexFailure(errorMessage, this.lastResponse);
+			if (this.control.isCodexRecoveryEnabled() && failure.transient) this.policy.observeFailure(failure, this.runtime.now());
+			else this.cancel(true);
+		} else if (stopReason !== "aborted") {
+			this.cancel(true);
+		}
+		this.lastResponse = {};
+	}
+
+	cancel(resetPolicy: boolean): void {
+		if (this.timer !== undefined) this.runtime.clearTimeout(this.timer);
+		this.timer = undefined;
+		this.cooldown = undefined;
+		if (resetPolicy) this.policy.cancel();
+	}
+
+	statusText(): string {
+		const now = this.runtime.now();
+		const state = this.policy.state(now);
+		const enabled = this.control.isCodexRecoveryEnabled();
+		const attempt = this.cooldown?.attempt ?? (state.pending ? state.attempts + 1 : state.attempts);
+		const phase = this.cooldown
+			? `cooldown ${Math.ceil(Math.max(0, this.cooldown.until - now) / MILLISECONDS_PER_SECOND)}s`
+			: state.pending ? "pending"
+				: state.attempts >= CODEX_RECOVERY_MAX_ATTEMPTS ? "exhausted"
+					: state.attempts > 0 ? "waiting" : "idle";
+		const failureKind = this.cooldown?.failureKind ?? state.lastFailureKind;
+		return [
+			`Codex recovery: ${enabled ? "on" : "off"}`,
+			phase,
+			`attempt ${attempt}/${CODEX_RECOVERY_MAX_ATTEMPTS}`,
+			`window ${CODEX_RECOVERY_ATTEMPT_WINDOW_MS / MILLISECONDS_PER_MINUTE}m`,
+			...(failureKind ? [failureKind] : []),
+		].join(" · ");
+	}
+
+	scheduleIfIdle(ctx: ExtensionContext): void {
+		if (!this.control.isCodexRecoveryEnabled() || this.timer !== undefined || !ctx.isIdle() || ctx.hasPendingMessages()) return;
+		const plan = this.policy.plan(this.runtime.now());
+		if (plan.action === "exhausted") {
+			this.policy.abandonFailure();
+			if (ctx.hasUI) ctx.ui.notify(`Jittor Codex recovery stopped: ${plan.reason}.`, "warning");
+			return;
+		}
+		if (plan.action !== "schedule") return;
+		this.cooldown = { until: this.runtime.now() + plan.delayMs, attempt: plan.attempt, failureKind: plan.failureKind };
+		this.timer = this.runtime.setTimeout(async () => {
+			this.timer = undefined;
+			this.cooldown = undefined;
+			if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
+			const attempt = this.policy.recordAttempt(this.runtime.now());
+			if (!attempt) return;
+			this.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);
+	}
+}

package/extension/src/capabilities/http-headers.ts

@@ -0,0 +1,5 @@
+/** Case-insensitive header lookup -- Pi's provider-response event headers are a plain Record, not a Headers instance. */
+export function headerValue(headers: Record<string, string>, name: string): string | undefined {
+	const expected = name.toLowerCase();
+	return Object.entries(headers).find(([key]) => key.toLowerCase() === expected)?.[1];
+}

package/extension/src/capabilities/local-run-telemetry.ts

@@ -0,0 +1,103 @@
+import { classifyTaskFromTools, modelRunMetrics, type MetricObservation, type ModelRunObservation } from "@danypops/jittor";
+
+export interface ActiveLocalModelRun {
+	runId: string;
+	startedAt: number;
+	firstTokenAt: number | null;
+	providerResponses: number;
+	toolNames: string[];
+	toolCalls: number;
+	toolFailures: number;
+}
+
+/**
+ * Content-free local model observations derived only from Pi's public lifecycle: TTFT, wall
+ * latency, tool-loop counts and failures, and a bounded tool-name list used only to derive
+ * domain/type classification -- never prompts, responses, tool arguments/results, or project
+ * paths. Owns the one in-flight run plus the most recently completed one (for `/jittor outcome`).
+ */
+export class LocalRunTelemetry {
+	private active: ActiveLocalModelRun | undefined;
+	private lastCompleted: ModelRunObservation | undefined;
+	private sequence = 0;
+
+	beginTurn(timestamp: number): void {
+		this.active = {
+			runId: `local-${timestamp}-${++this.sequence}`,
+			startedAt: timestamp,
+			firstTokenAt: null,
+			providerResponses: 0,
+			toolNames: [],
+			toolCalls: 0,
+			toolFailures: 0,
+		};
+	}
+
+	discardTurn(): void {
+		this.active = undefined;
+	}
+
+	onMessageUpdate(assistantMessageEventType: string): void {
+		if (!this.active || this.active.firstTokenAt !== null) return;
+		if (["text_delta", "thinking_delta", "toolcall_delta"].includes(assistantMessageEventType)) this.active.firstTokenAt = Date.now();
+	}
+
+	onToolExecutionEnd(toolName: string, isError: boolean): void {
+		if (!this.active) return;
+		this.active.toolCalls += 1;
+		if (isError) this.active.toolFailures += 1;
+		if (this.active.toolNames.length < 100) this.active.toolNames.push(toolName);
+	}
+
+	onProviderResponse(): void {
+		if (this.active) this.active.providerResponses += 1;
+	}
+
+	/** Finalizes the active run against a completed assistant turn_end message, returning metrics to record (empty if the message shape doesn't match a completed assistant turn). */
+	completeTurn(message: unknown, thinkingLevel: string): MetricObservation[] {
+		const active = this.active;
+		this.active = undefined;
+		if (!active || typeof message !== "object" || message === null || Array.isArray(message)) return [];
+		const value = message as Record<string, unknown>;
+		if (value["role"] !== "assistant" || typeof value["provider"] !== "string" || typeof value["model"] !== "string") return [];
+		const usage = typeof value["usage"] === "object" && value["usage"] !== null ? value["usage"] as Record<string, unknown> : {};
+		const amount = (name: string): number => typeof usage[name] === "number" && Number.isFinite(usage[name]) ? usage[name] as number : 0;
+		const cost = typeof usage["cost"] === "object" && usage["cost"] !== null && typeof (usage["cost"] as Record<string, unknown>)["total"] === "number"
+			? (usage["cost"] as Record<string, number>)["total"] ?? 0 : 0;
+		const stopReason = ["stop", "length", "toolUse", "error", "aborted"].includes(String(value["stopReason"]))
+			? value["stopReason"] as ModelRunObservation["stopReason"] : "unknown";
+		const completedAt = Math.max(Date.now(), active.firstTokenAt ?? active.startedAt, active.startedAt);
+		this.lastCompleted = {
+			runId: active.runId,
+			provider: value["provider"],
+			model: value["model"],
+			thinking: thinkingLevel,
+			...classifyTaskFromTools(active.toolNames),
+			startedAt: active.startedAt,
+			firstTokenAt: active.firstTokenAt,
+			completedAt,
+			inputTokens: amount("input"),
+			outputTokens: amount("output"),
+			cacheReadTokens: amount("cacheRead"),
+			cacheWriteTokens: amount("cacheWrite"),
+			costUsd: Number.isFinite(cost) && cost >= 0 ? cost : 0,
+			providerResponses: Math.max(1, active.providerResponses),
+			toolCalls: active.toolCalls,
+			toolFailures: active.toolFailures,
+			stopReason,
+			explicitOutcome: "unknown",
+		};
+		return modelRunMetrics(this.lastCompleted);
+	}
+
+	/** Builds the single outcome-accepted/outcome-accepted=0 metric for the most recently completed run, or null if none exists yet. */
+	explicitOutcomeMetric(explicitOutcome: "accepted" | "rejected"): MetricObservation | null {
+		if (!this.lastCompleted) return null;
+		return modelRunMetrics({ ...this.lastCompleted, explicitOutcome }).find((metric) => metric.metric === "outcome-accepted") ?? null;
+	}
+
+	reset(): void {
+		this.active = undefined;
+		this.lastCompleted = undefined;
+	}
+}

package/extension/src/capabilities/provider-response-telemetry.ts

@@ -0,0 +1,101 @@
+import {
+	classifyGoogleVertexFailure,
+	googleVertexFailureMetrics,
+	hasAnthropicRateLimitHeaders,
+	parseAnthropicRateLimitHeaders,
+	parseCodexRateLimitHeaders,
+	type GoogleVertexFailureMetadata,
+	type MetricObservation,
+} from "@danypops/jittor";
+import { headerValue } from "./http-headers.ts";
+
+export interface ProviderTelemetryClient {
+	call(operation: string, input: unknown): Promise<any>;
+}
+
+async function recordMetrics(client: ProviderTelemetryClient, metrics: MetricObservation[]): Promise<void> {
+	if (metrics.length === 0) return;
+	await client.call("metrics.record_batch", { observations: metrics });
+}
+
+/**
+ * Bounded telemetry derived directly from provider HTTP responses and finalized messages, for
+ * every provider except Codex (whose response tracking is settled-turn-recovery's own concern --
+ * see codex-recovery.ts). Anthropic and anthropic-vertex official rate-limit headers become
+ * budget metrics; Google Vertex and anthropic-vertex failures become bounded, content-free
+ * failure-count metrics classified from GCP's own `google.rpc.Status` shape. anthropic-vertex is
+ * tracked distinctly from both google-vertex (different code path, different quota pool) and
+ * direct anthropic (different transport), never conflated with either.
+ */
+export class ProviderResponseTelemetry {
+	private lastGoogleVertexResponse: GoogleVertexFailureMetadata = {};
+	private lastAnthropicVertexResponse: GoogleVertexFailureMetadata = {};
+
+	resetTurn(): void {
+		this.lastGoogleVertexResponse = {};
+		this.lastAnthropicVertexResponse = {};
+	}
+
+	async handleProviderResponse(
+		client: ProviderTelemetryClient,
+		provider: string | undefined,
+		status: number,
+		headers: Record<string, string>,
+		notifySchemaDrift: (message: string) => void,
+	): Promise<void> {
+		if (provider === "anthropic") {
+			const parsedHeaders = new Headers(headers);
+			if (hasAnthropicRateLimitHeaders(parsedHeaders)) {
+				try {
+					await recordMetrics(client, parseAnthropicRateLimitHeaders(parsedHeaders, Date.now()).metrics);
+				} catch {
+					notifySchemaDrift("Anthropic telemetry schema drift");
+				}
+			}
+		}
+		if (provider === "anthropic-vertex") {
+			// Best-effort only: unverified whether this passthrough ever forwards Anthropic's own
+			// rate-limit headers. If it doesn't, hasAnthropicRateLimitHeaders is false and nothing is
+			// recorded -- the same honest default as every other unconfirmed signal in this module.
+			const parsedHeaders = new Headers(headers);
+			if (hasAnthropicRateLimitHeaders(parsedHeaders)) {
+				try {
+					await recordMetrics(client, parseAnthropicRateLimitHeaders(parsedHeaders, Date.now(), "anthropic-vertex").metrics);
+				} catch {
+					notifySchemaDrift("Anthropic-on-Vertex telemetry schema drift");
+				}
+			}
+			// Well-evidenced regardless of headers: GCP's own quota system fronts this transport, so the
+			// same failure classification as google-vertex applies below.
+			this.lastAnthropicVertexResponse = { status, ...(headerValue(headers, "retry-after") ? { retryAfter: headerValue(headers, "retry-after") } : {}) };
+		}
+		if (provider === "google-vertex") {
+			this.lastGoogleVertexResponse = { status, ...(headerValue(headers, "retry-after") ? { retryAfter: headerValue(headers, "retry-after") } : {}) };
+		}
+		if (Object.keys(headers).some((name) => name.toLowerCase().startsWith("x-codex-"))) {
+			try {
+				const updates = parseCodexRateLimitHeaders(new Headers(headers), Date.now());
+				await recordMetrics(client, updates.flatMap((update) => update.metrics));
+			} catch {
+				notifySchemaDrift("Codex telemetry schema drift");
+			}
+		}
+	}
+
+	async handleMessageEnd(client: ProviderTelemetryClient, provider: string | undefined, stopReason: string | undefined, errorMessage: string | undefined): Promise<void> {
+		if (provider === "google-vertex") {
+			if (stopReason === "error") {
+				const failure = classifyGoogleVertexFailure(errorMessage, this.lastGoogleVertexResponse);
+				await recordMetrics(client, googleVertexFailureMetrics(failure, Date.now())).catch(() => undefined);
+			}
+			this.lastGoogleVertexResponse = {};
+		}
+		if (provider === "anthropic-vertex") {
+			if (stopReason === "error") {
+				const failure = classifyGoogleVertexFailure(errorMessage, this.lastAnthropicVertexResponse);
+				await recordMetrics(client, googleVertexFailureMetrics(failure, Date.now(), "anthropic-vertex")).catch(() => undefined);
+			}
+			this.lastAnthropicVertexResponse = {};
+		}
+	}
+}