gentle-pi 3.2.0 → 3.3.0

package/lib/shell-usage-view.ts

@@ -1,5 +1,6 @@
-import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { Key, matchesKey, truncateToWidth, visibleWidth, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
 import { renderUsagePanel, type ActiveProvider, type UsageStore, type UsageTheme } from "./shell-usage.ts";
+import { paintHoverable } from "./shell-hover.ts";
 
 // Gentle Shell subscriptions overlay: a framed panel over the usage store.
 // It reads the store on every render, so a refresh only needs to record.
@@ -33,10 +34,32 @@ function fit(text: string, width: number): string {
 	return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
 }
 
+// Column offset of the footer's hint text within the rendered line: the
+// frame draws "│ " before the fitted content starts.
+const HINT_CONTENT_OFFSET = 2;
+const HINT_GAP = "   ";
+
+type HintAction = "refresh" | "close";
+
+interface HintSpan {
+	start: number;
+	end: number;
+	action: HintAction;
+}
+
+interface PointerLayout {
+	width: number;
+	height: number;
+	row: number;
+	spans: HintSpan[];
+}
+
 export class UsageView {
 	private readonly store: UsageStore;
 	private readonly deps: UsageViewDeps;
 	private refreshing = false;
+	private pointer: PointerLayout | undefined;
+	private hoveredHint: HintAction | undefined;
 
 	constructor(store: UsageStore, deps: UsageViewDeps) {
 		this.store = store;
@@ -48,13 +71,25 @@ export class UsageView {
 			this.deps.onClose();
 			return;
 		}
-		if (data === "r" && !this.refreshing) {
-			this.refreshing = true;
+		if (data === "r") this.refresh();
+	}
+
+	// A failing usage fetch is the store's problem to report (its rows already
+	// carry the last error); the panel only clears its "refreshing" state. The
+	// rejection must never leave this method: an unhandled rejection is fatal
+	// to the whole shell on current Node.
+	private refresh(): void {
+		if (this.refreshing) return;
+		this.refreshing = true;
+		this.deps.requestRender();
+		const settle = () => {
+			this.refreshing = false;
 			this.deps.requestRender();
-			void this.deps.onRefresh().finally(() => {
-				this.refreshing = false;
-				this.deps.requestRender();
-			});
+		};
+		try {
+			this.deps.onRefresh().then(settle, settle);
+		} catch {
+			settle();
 		}
 	}
 
@@ -66,11 +101,64 @@ export class UsageView {
 		const body = renderUsagePanel(this.store.all(), theme, inner - 2, this.deps.now(), this.deps.active()).map(
 			(line) => `${theme.fg(FRAME_ROLE, "│")} ${fit(line, inner - 2)} ${theme.fg(FRAME_ROLE, "│")}`,
 		);
-		const keys = KEYS.map(([key, label]) => `${theme.fg(KEY_ROLE, key)} ${theme.fg(KEY_TEXT_ROLE, label)}`).join("   ");
+		const hints = KEYS.map(([key, label]) => ({ key, label, text: `${key} ${label}`, action: (key === "r" ? "refresh" : "close") as HintAction }));
+		// The hovered hint paints entirely in the shared hover role (key and
+		// label together, one color) instead of its ordinary two-role split --
+		// the same treatment every other clickable surface uses.
+		const keys = hints
+			.map(({ key, label, action }) =>
+				this.hoveredHint === action ? paintHoverable(theme, `${key} ${label}`, true) : `${theme.fg(KEY_ROLE, key)} ${theme.fg(KEY_TEXT_ROLE, label)}`,
+			)
+			.join(HINT_GAP);
 		const keysLine = `${theme.fg(FRAME_ROLE, "│")} ${fit(keys, inner - 2)} ${theme.fg(FRAME_ROLE, "│")}`;
 		const bottom = theme.fg(FRAME_ROLE, `╰${rule(inner)}╯`);
-		return [top, ...body, keysLine, bottom];
+		const lines = [top, ...body, keysLine, bottom];
+		this.pointer = this.hintLayout(width, lines.length, body.length + 1, hints, inner - 2);
+		return lines;
 	}
 
-	invalidate(): void {}
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		if (event.type === "move" && event.button === "none") {
+			const layout = this.pointer;
+			const action = layout && event.width === layout.width && event.height === layout.height && event.y === layout.row
+				? layout.spans.find((candidate) => event.x >= candidate.start && event.x < candidate.end)?.action
+				: undefined;
+			if (action === this.hoveredHint) return action ? { handled: true } : undefined;
+			this.hoveredHint = action;
+			return { handled: true, render: true };
+		}
+		if (event.type !== "click" || event.button !== "left") return undefined;
+		const layout = this.pointer;
+		if (!layout || event.width !== layout.width || event.height !== layout.height || event.y !== layout.row) return undefined;
+		const span = layout.spans.find((candidate) => event.x >= candidate.start && event.x < candidate.end);
+		if (!span) return undefined;
+		if (span.action === "close") {
+			this.deps.onClose();
+			return { handled: true, render: true };
+		}
+		this.refresh();
+		return { handled: true, render: true };
+	}
+
+	invalidate(): void {
+		this.pointer = undefined;
+		this.hoveredHint = undefined;
+	}
+
+	// Spans are only registered when the hints text fits without truncation:
+	// past that point `fit` clips it with an ellipsis and per-hint columns no
+	// longer line up with the plain "key label" text used here.
+	private hintLayout(width: number, height: number, row: number, hints: Array<{ text: string; action: HintAction }>, contentWidth: number): PointerLayout | undefined {
+		const plainWidth = hints.reduce((total, hint) => total + hint.text.length, 0) + HINT_GAP.length * Math.max(0, hints.length - 1);
+		if (plainWidth > contentWidth) return undefined;
+		const spans: HintSpan[] = [];
+		let cursor = HINT_CONTENT_OFFSET;
+		for (const hint of hints) {
+			const start = cursor;
+			const end = start + hint.text.length;
+			spans.push({ start, end, action: hint.action });
+			cursor = end + HINT_GAP.length;
+		}
+		return { width, height, row, spans };
+	}
 }

package/lib/shell-usage.ts

@@ -11,6 +11,11 @@ export interface UsageWindow {
 	usedPercent: number;
 	windowSeconds: number;
 	resetAt: number | null;
+	// Raw allowance numbers, kept only by providers that report them (NaN).
+	// Aggregates are weighted by budget, so averaging percentages is never
+	// needed; nothing renders these fields directly.
+	used?: number;
+	budget?: number;
 }
 
 export interface UsageLimit {
@@ -54,8 +59,27 @@ interface RawCodexUsage {
 	additional_rate_limits?: RawAdditionalLimit[] | null;
 }
 
+interface RawNanModel {
+	model?: unknown;
+	cap?: unknown;
+	fullCap?: unknown;
+	tokensUsed?: unknown;
+	periodEnd?: unknown;
+	windowHours?: unknown;
+	windowTokens?: unknown;
+	fullWindowTokens?: unknown;
+	windowTokensUsed?: unknown;
+	windowResetsAt?: unknown;
+}
+
+interface RawNanQuota {
+	models?: unknown;
+	periodEnd?: unknown;
+}
+
 export const CODEX_PROVIDER = "openai-codex";
 export const ANTHROPIC_PROVIDER = "anthropic";
+export const NAN_PROVIDER = "nan";
 const ANTHROPIC_MAIN_LIMIT = "claude";
 const ANTHROPIC_PREFIX = "anthropic-ratelimit-unified-";
 const ANTHROPIC_WINDOWS: ReadonlyArray<[key: string, seconds: number]> = [
@@ -63,6 +87,17 @@ const ANTHROPIC_WINDOWS: ReadonlyArray<[key: string, seconds: number]> = [
 	["7d", 604_800],
 ];
 export const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+// The NaN Cloud dashboard backend; not part of NaN's published OpenAPI, so the
+// fetch that uses it is fixed-origin, redirect-refusing, and schema-validated.
+export const NAN_QUOTA_URL = "https://cloud-api.nan.builders/api/usage/quota";
+// The model's own allowance for the billing period carries no label: the model
+// id names it in the bar, and the reset text says what the window is in the
+// panel. Only a sub-window on top of it (a rolling `4h`) needs a name.
+const NAN_PERIOD_LABEL = "";
+// The dashboard's own published fallbacks for a model that reports rolling
+// numbers without naming its budget.
+const NAN_DEFAULT_WINDOW_TOKENS = 400_000_000;
+const NAN_DEFAULT_WINDOW_HOURS = 4;
 const CODEX_MAIN_LIMIT = "codex";
 const CODEX_ACCOUNT_CLAIM = "https://api.openai.com/auth";
 const HEADER_PREFIX = "x-codex-";
@@ -81,9 +116,10 @@ const ROLE = {
 	SEPARATOR: "muted",
 } as const;
 export const USAGE_EMPTY_MESSAGE = "No subscription usage yet. Usage arrives with the next response, or press r to fetch it.";
-export const SUPPORTED_USAGE_PROVIDERS: readonly string[] = [CODEX_PROVIDER, ANTHROPIC_PROVIDER];
+export const SUPPORTED_USAGE_PROVIDERS: readonly string[] = [CODEX_PROVIDER, ANTHROPIC_PROVIDER, NAN_PROVIDER];
 const PENDING_NOTE: Record<string, string> = {
 	[CODEX_PROVIDER]: "no usage yet · r to fetch",
+	[NAN_PROVIDER]: "no usage yet · r to fetch",
 	[ANTHROPIC_PROVIDER]: "usage arrives with the first response",
 };
 const UNSUPPORTED_NOTE = "no subscription usage for this provider";
@@ -174,6 +210,178 @@ export function parseUsageHeaders(headers: Record<string, string>, now: number):
 	return parseCodexHeaders(headers, now) ?? parseAnthropicHeaders(headers, now);
 }
 
+// NaN Cloud reports one allowance per model for the billing period, plus the
+// rolling window the model applies on top of it. Percentages follow the
+// dashboard exactly: tokens used over the period allowance, and window tokens
+// over the full window budget. Every field is optional, because this payload
+// lives outside NaN's published contract.
+function quotaTimestamp(value: unknown): number | null {
+	if (typeof value === "number" && Number.isFinite(value) && value > 0) return value * 1000;
+	if (typeof value !== "string") return null;
+	const parsed = Date.parse(value);
+	return Number.isNaN(parsed) ? null : parsed;
+}
+
+function quotaNumber(value: unknown, positive: boolean): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+	return positive ? (value > 0 ? value : undefined) : value >= 0 ? value : undefined;
+}
+
+function nanRollingWindow(raw: RawNanModel): UsageWindow | undefined {
+	const used = quotaNumber(raw.windowTokensUsed, false);
+	if (used === undefined) return undefined;
+	const budget = quotaNumber(raw.fullWindowTokens, true) ?? quotaNumber(raw.windowTokens, true) ?? NAN_DEFAULT_WINDOW_TOKENS;
+	const hours = quotaNumber(raw.windowHours, true) ?? NAN_DEFAULT_WINDOW_HOURS;
+	return { label: windowLabel(hours * HOUR), usedPercent: (used / budget) * 100, windowSeconds: hours * HOUR, resetAt: quotaTimestamp(raw.windowResetsAt) };
+}
+
+// The allowance the dashboard divides by is the full-period cap, because `cap`
+// is the allowance of the period in progress and comes back prorated on a first
+// period. A model that reports neither figure reports no allowance at all, which
+// is a state the surfaces already know how to draw nothing for.
+function nanEffectiveAllowance(raw: RawNanModel): number | undefined {
+	return quotaNumber(raw.fullCap, true) ?? quotaNumber(raw.cap, true);
+}
+
+// One allowance per metered model, weighted by that model's own cap. The raw
+// numbers travel with the period window so the bar and the panel can aggregate
+// without ever averaging percentages.
+function nanPeriodWindow(tokensUsed: number, cap: number, resetAt: number | null, now: number): UsageWindow {
+	return {
+		label: NAN_PERIOD_LABEL,
+		usedPercent: (tokensUsed / cap) * 100,
+		windowSeconds: resetAt === null ? 0 : Math.max(0, Math.round((resetAt - now) / 1000)),
+		resetAt,
+		used: tokensUsed,
+		budget: cap,
+	};
+}
+
+export function parseNanQuota(payload: unknown, now: number): ProviderUsage {
+	const raw = (payload ?? {}) as RawNanQuota;
+	const fallbackResetAt = quotaTimestamp(raw.periodEnd);
+	const limits: UsageLimit[] = [];
+	if (Array.isArray(raw.models)) {
+		for (const entry of raw.models) {
+			if (!entry || typeof entry !== "object") continue;
+			const model = entry as RawNanModel;
+			if (typeof model.model !== "string" || model.model.length === 0) continue;
+			const allowance = nanEffectiveAllowance(model);
+			// A model that reports no allowance is not drift — the dashboard draws
+			// nothing for it either, and the live payload carries such entries. A metered
+			// allowance whose usage cannot be read is drift: a partial snapshot would
+			// understate every aggregate it feeds, so the read fails whole and the last
+			// valid snapshot survives instead.
+			if (allowance === undefined) continue;
+			const tokensUsed = quotaNumber(model.tokensUsed, false);
+			if (tokensUsed === undefined) return { provider: NAN_PROVIDER, plan: undefined, limits: [], fetchedAt: now };
+			const resetAt = quotaTimestamp(model.periodEnd) ?? fallbackResetAt;
+			const windows: UsageWindow[] = [nanPeriodWindow(tokensUsed, allowance, resetAt, now)];
+			const rolling = nanRollingWindow(model);
+			if (rolling) windows.push(rolling);
+			limits.push({ name: model.model, windows, limitReached: tokensUsed >= allowance });
+		}
+	}
+	return { provider: NAN_PROVIDER, plan: undefined, limits, fetchedAt: now };
+}
+
+// Aggregation. NaN reports one allowance per metered model and the payload
+// order is the server's business, so surfaces pick by meaning, not by position.
+function rawAllowance(limit: UsageLimit): UsageWindow | undefined {
+	const [first] = limit.windows;
+	if (!first || first.used === undefined || first.budget === undefined) return undefined;
+	return first.budget > 0 ? first : undefined;
+}
+
+// The leading alphabetic run of a model id: glm5.3-flash and glm5.2 are both
+// "glm". Derived from the id the payload reports, never from a vendor list.
+export function modelFamily(modelId: string): string {
+	return (/^[a-z]+/i.exec(modelId)?.[0] ?? modelId).toLowerCase();
+}
+
+// Only NaN carries raw allowance numbers, so this one gate is what keeps Codex
+// and Anthropic on exactly the rows and the meter they had before. One metered
+// model is still a payload that carries them: the gate answers "does this
+// provider report allowances", never "are there enough rows to sort", because
+// a single allowance read as "no allowances" sent the bar back to whichever
+// model the payload listed first.
+export function allowanceGroupsSupported(limits: readonly UsageLimit[]): boolean {
+	return limits.length > 0 && limits.every((limit) => rawAllowance(limit) !== undefined);
+}
+
+function percentOf(limit: UsageLimit): number {
+	return limit.windows[0]?.usedPercent ?? 0;
+}
+
+const GROUP_SUFFIX = " total";
+
+// A group is an allowance share, never an average of shares: Σused / Σbudget.
+// It carries no reset, because its members close their own billing period on
+// their own date, and a single reset would be a lie.
+function allowanceTotal(name: string, limits: readonly UsageLimit[]): UsageLimit | undefined {
+	const windows = limits.map(rawAllowance).filter((window): window is UsageWindow => window !== undefined);
+	if (windows.length === 0 || windows.length !== limits.length) return undefined;
+	const used = windows.reduce((total, window) => total + (window.used ?? 0), 0);
+	const budget = windows.reduce((total, window) => total + (window.budget ?? 0), 0);
+	if (budget <= 0) return undefined;
+	return {
+		name,
+		windows: [{ label: NAN_PERIOD_LABEL, usedPercent: (used / budget) * 100, windowSeconds: 0, resetAt: null }],
+		limitReached: limits.some((limit) => limit.limitReached),
+	};
+}
+
+// What the grouping is for now that the totals are gone: the order. A family
+// stays together, families sort by what they consume and the members inside one
+// follow the same rule, most used first. The account and family totals are the
+// bar's fallback ladder only — they are never rows, because a total nobody can
+// act on only costs space. Every row is a limit block, so nothing here
+// introduces a shape the other providers do not already use.
+export function groupUsageLimits(limits: readonly UsageLimit[]): UsageLimit[] {
+	if (!allowanceGroupsSupported(limits)) return [...limits];
+	const order: string[] = [];
+	const members = new Map<string, UsageLimit[]>();
+	for (const limit of limits) {
+		const family = modelFamily(limit.name);
+		if (!members.has(family)) {
+			members.set(family, []);
+			order.push(family);
+		}
+		members.get(family)?.push(limit);
+	}
+	return order
+		.map((family) => {
+			const sorted = [...(members.get(family) ?? [])].sort((a, b) => percentOf(b) - percentOf(a));
+			const total = allowanceTotal(`${family}${GROUP_SUFFIX}`, sorted);
+			return { percent: total?.windows[0]?.usedPercent ?? percentOf(sorted[0]), sorted };
+		})
+		.sort((a, b) => b.percent - a.percent)
+		.flatMap((family) => family.sorted);
+}
+
+// The bar follows the model the session is using: exact allowance, then its
+// family, then the account total, then the first limit (which is what every
+// provider without raw numbers keeps using, and what a missing model keeps).
+export function selectUsageLimit(usage: ProviderUsage, activeModelId?: string): UsageLimit | undefined {
+	if (!activeModelId) return usage.limits[0];
+	const exact = usage.limits.find((limit) => limit.name === activeModelId);
+	if (exact) return exact;
+	if (allowanceGroupsSupported(usage.limits)) {
+		const family = modelFamily(activeModelId);
+		const members = usage.limits.filter((limit) => modelFamily(limit.name) === family);
+		// The family rung is about the name of the meter, not about printing a row,
+		// so a single member counts: its family is a closer statement of what the
+		// session is drawing from than the whole account.
+		if (members.length > 0) {
+			const total = allowanceTotal(`${family}${GROUP_SUFFIX}`, members);
+			if (total) return total;
+		}
+		const account = allowanceTotal(`${usage.provider}${GROUP_SUFFIX}`, usage.limits);
+		if (account) return account;
+	}
+	return usage.limits[0];
+}
+
 export function accountIdFromToken(token: string): string | undefined {
 	const parts = token.split(".");
 	if (parts.length !== 3) return undefined;
@@ -190,11 +398,12 @@ function paintMeter(percent: number, cells: number, theme: UsageTheme): string {
 	return paintGauge(percent, theme, cells);
 }
 
-export function renderUsageBar(usage: ProviderUsage, theme: UsageTheme): string | undefined {
-	const main = usage.limits[0];
+export function renderUsageBar(usage: ProviderUsage, theme: UsageTheme, activeModelId?: string): string | undefined {
+	const main = selectUsageLimit(usage, activeModelId);
 	const [first, ...rest] = main?.windows ?? [];
 	if (!first) return undefined;
-	const head = `${theme.fg(ROLE.LABEL, main.name)} ${theme.fg(ROLE.LABEL, first.label)} ${paintMeter(first.usedPercent, 8, theme)} ${theme.fg(ROLE.PERCENT, `${Math.round(first.usedPercent)}%`)}`;
+	// An unlabeled window prints as the name, the meter and the percentage.
+	const head = [theme.fg(ROLE.LABEL, main.name), ...(first.label.length === 0 ? [] : [theme.fg(ROLE.LABEL, first.label)]), paintMeter(first.usedPercent, 8, theme), theme.fg(ROLE.PERCENT, `${Math.round(first.usedPercent)}%`)].join(" ");
 	const tail = rest.map((window) => `${theme.fg(ROLE.SEPARATOR, "·")} ${theme.fg(ROLE.LABEL, window.label)} ${theme.fg(ROLE.PERCENT, `${Math.round(window.usedPercent)}%`)}`);
 	return [head, ...tail].join(" ");
 }
@@ -218,12 +427,19 @@ export function renderUsagePanel(usages: ProviderUsage[], theme: UsageTheme, wid
 		const mark = usage === activeUsage ? `${theme.fg(ROLE.LIMIT, ACTIVE_MARK)} ` : "";
 		const plan = usage.plan ? ` ${theme.fg(ROLE.SEPARATOR, "·")} ${theme.fg(ROLE.PLAN, usage.plan)}` : "";
 		lines.push(`${mark}${theme.fg(ROLE.PROVIDER, usage.provider)}${plan} ${theme.fg(ROLE.SEPARATOR, "·")} ${theme.fg(ROLE.RESET, updatedAgo(usage.fetchedAt, now))}`);
-		for (const limit of usage.limits) {
-			lines.push(`  ${theme.fg(ROLE.LIMIT, limit.name)}`);
-			for (const window of limit.windows) {
-				const percent = `${Math.round(window.usedPercent)}%`.padStart(4);
-				lines.push(`    ${theme.fg(ROLE.LABEL, window.label.padEnd(5))} ${paintMeter(window.usedPercent, PANEL_METER_CELLS, theme)} ${theme.fg(ROLE.PERCENT, percent)}  ${theme.fg(ROLE.RESET, formatReset(window.resetAt, now))}`);
-			}
+		// One row per window: the limit name, its meter, its percentage and the reset
+		// that window reports, all on one line. A window without its own label (the
+		// model's allowance) is named by its limit alone, and one without a reset ends
+		// at its percentage, never on a dangling separator.
+		const rows = groupUsageLimits(usage.limits).flatMap((limit) =>
+			limit.windows.map((window) => ({ name: [limit.name, window.label].filter((part) => part.length > 0).join(" "), window })),
+		);
+		const nameWidth = rows.reduce((widest, row) => Math.max(widest, row.name.length), 0);
+		for (const row of rows) {
+			const percent = `${Math.round(row.window.usedPercent)}%`.padStart(4);
+			const reset = formatReset(row.window.resetAt, now);
+			const tail = reset.length > 0 ? ` ${theme.fg(ROLE.SEPARATOR, "·")} ${theme.fg(ROLE.RESET, reset)}` : "";
+			lines.push(`  ${theme.fg(ROLE.LABEL, row.name.padEnd(nameWidth))} ${paintMeter(row.window.usedPercent, PANEL_METER_CELLS, theme)} ${theme.fg(ROLE.PERCENT, percent)}${tail}`);
 		}
 	}
 	return lines.map((line) => truncateToWidth(line, width, "…"));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gentle-pi",
-	"version": "3.2.0",
+	"version": "3.3.0",
 	"description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
 	"license": "MIT",
 	"type": "module",
@@ -38,6 +38,7 @@
 	],
 	"scripts": {
 		"check:provider-contract": "node scripts/check-provider-contract.mjs",
+		"mirror:odd-routing": "node scripts/mirror-odd-routing.mjs",
 		"postinstall": "node scripts/install-gentle-ai.mjs",
 		"test": "node --experimental-strip-types --test tests/*.test.ts && pnpm run check:provider-contract && pnpm run test:harness",
 		"test:harness": "node --experimental-strip-types tests/runtime-harness.mjs",

package/runtime/native-review-cli.mjs

@@ -996,6 +996,29 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// remain dark because neither is proven to reach the negotiated START
 	// path Pi consumes.
 	"3.1.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v3.2.1 changed the ODD orchestrator contract only (gentle-ai #4714
+	// follow-up). Ground-truthed by diffing contracts/review-integration/v2 and
+	// contracts/review-provider-contract between the v3.1.0 and v3.2.1 tags
+	// in the gentle-ai source tree: zero bytes changed (provider contract
+	// stays 1.2.0). Neither change touches the closed START/STATUS fields
+	// this row negotiates, so it repeats 3.1.0 exactly. riskEvidence and hint
+	// remain dark because neither is proven to reach the negotiated START
+	// path Pi consumes.
+	"3.2.1": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v3.4.0 (gentle-pi never pinned the intervening v3.3.0 tag, so it gets no
+	// row here) added capabilities/v2.6 and status/v8-v9, and extended
+	// `review assess` with review_due/review_due_reason/next_transition
+	// (gentle-ai #4714 follow-up). Ground-truthed by diffing
+	// contracts/review-integration/v2 and contracts/review-provider-contract
+	// between the v3.2.1 and v3.4.0 tags in the gentle-ai source tree: the
+	// provider contract stays byte-identical at 1.2.0, and every
+	// review-integration/v2 change is an additive superset (new optional
+	// schema/fields) that decodeReviewStatusV3 and the capabilities
+	// negotiator already accept without touching the closed START/STATUS
+	// fields this row negotiates, so it repeats 3.2.1 exactly. riskEvidence
+	// and hint remain dark because neither is proven to reach the negotiated
+	// START path Pi consumes.
+	"3.4.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });