gentle-pi 3.2.0 → 3.2.1

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.2.1",
 	"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,15 @@ 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 }),
 });
 
 

package/scripts/gentle-ai-installer.mjs

@@ -36,7 +36,7 @@ const WINDOWS_SYSTEM_ROOT = "C:\\Windows";
 // version check below) derives from this constant instead of repeating the
 // literal, so a pin bump cannot leave a stale copy behind. See
 // scripts/install-gentle-ai.mjs for the incident that motivated this.
-export const INSTALLER_VERSION = "3.1.0";
+export const INSTALLER_VERSION = "3.2.1";
 export const RELEASE_BASE_URL = `https://github.com/Gentleman-Programming/gentle-ai/releases/download/v${INSTALLER_VERSION}/`;
 export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 	SIGNED_RELEASE_ASSET: "signed-release-asset",
@@ -45,10 +45,10 @@ export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH = "github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai";
 export const GENTLE_AI_WINDOWS_SOURCE_MODULE = "github.com/gentleman-programming/gentle-ai/v3";
 export const GENTLE_AI_WINDOWS_SOURCE_TAG = `v${INSTALLER_VERSION}`;
-// `go mod download -json github.com/gentleman-programming/gentle-ai/v3@v3.1.0`
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v3@v3.2.1`
 // with GOSUMDB=sum.golang.org reports this exact module SumDB checksum, and the
-// tag resolves to commit cfc415ce, the published v3.1.0 release head.
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:CrZlui5N8/RSmxvn/7usKe6q1EvRt7y6dyfEwjstmJw=";
+// tag resolves to commit e7729359, the published v3.2.1 release head.
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:0QFo0ERv8/3lgTepEG0E/P7yD9qXXCx2M7ppQviVHMo=";
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE = `${GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH}@${GENTLE_AI_WINDOWS_SOURCE_TAG}`;
 export const GENTLE_AI_WINDOWS_MINIMUM_GO_VERSION = "1.25.10";
 export const GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE_CODE = "GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE";
@@ -67,7 +67,7 @@ export class GentleAiInstallerError extends Error {
 // Sentinel used while a re-pinned gentle-ai release is not yet published. A
 // sentinel digest can never match a real SHA-256, so installation fails closed,
 // and verify-package-files.mjs refuses to pack/publish while any digest below
-// still holds it. The v3.1.0 digests are pinned from the published release:
+// still holds it. The v3.2.1 digests are pinned from the published release:
 // archive sha256 values verified against the minisign-signed checksums.txt and
 // freshly computed hashes; binary sha256 values computed from the extracted
 // executables.
@@ -109,15 +109,15 @@ async function downloadPinnedGentleAiAsset(asset, destination, options) {
 }
 
 // Windows is absent from signed release archives on purpose. gentle-ai stopped
-// distributing unsigned Windows builds in c4b764d0, so v3.1.0 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v3.2.1 publishes signed
 // Darwin/Linux archives only. Windows x64/arm64 uses the separately verified
 // exact-tag Go SumDB source-build path below; restore archive rows only when
 // upstream ships signed Windows assets.
 export const GENTLE_AI_RELEASE_ASSETS = Object.freeze({
-	"darwin/amd64": asset("gentle-ai_3.1.0_darwin_amd64.tar.gz", "613f0e11adeebb421daae4c68cb9f207f55c559a70595549ff25f988559226e4", "98340df0102825072431a2c0373ea4d9db1bacafced234f51fb58661ed3d731f", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_3.1.0_darwin_arm64.tar.gz", "bfcbf8df2682fcf1535b26c604e8dbb445df0ca00a651de204fdc2d013dfe472", "3cdc9689ea0d71186b896341b4181e2df13a82b64d236a26a3273171150d802f", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_3.1.0_linux_amd64.tar.gz", "dc55c44a2eb46212a38eca0dfd4d778481ec37e765f40d5a0752d03c28e1ee49", "70e335d25809a0d358c12f48b2f0d1da00741e725584ceeb8c1318c60d0a6e9e", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_3.1.0_linux_arm64.tar.gz", "3a89d5f5a549004cc2b01949014ed59f9c28e1ff0c9958531bb539504286e407", "6cf9f20fc390b13e2b9b427ca1c2df404d1bbb9248201f9a592c7f0a37ef5416", "gentle-ai"),
+	"darwin/amd64": asset("gentle-ai_3.2.1_darwin_amd64.tar.gz", "1696a4852435920ebae351a5173adead6da17db6762359dcb12dc3971d983c3f", "ed7d18b7446c63f265a827a736ed4465ec562cc3c07c470743d3740fb4d2f4a9", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_3.2.1_darwin_arm64.tar.gz", "e3a991a03c6fb6373f6a254b808c3fabf36330634d93704c9d9ba365467fc6f8", "2ae66cfa11f8ab93ea46c20e79bd191dedde40a4898f0b312330a0790f802ca3", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_3.2.1_linux_amd64.tar.gz", "e2e3171377c040c27a93ae66b4adf824626f23cacd398b3b652af0d87ff65807", "3464525775b60cad6358a589c298a2d4098466bc0a5ae5f0d1e578ab10134659", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_3.2.1_linux_arm64.tar.gz", "342c7fc60cf062730c8f593f09269f75485b3b1fa2907b2b188eafded1a0e222", "d2c4d8ebfdc681ceece254d0d12cd04dd7af3b435c945e42623e3475981c2f8f", "gentle-ai"),
 });
 
 // A pinned asset is either a signed archive or, for a prerelease pin only,

package/scripts/mirror-odd-routing.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+// ODD routing drift ratchet — canonical fixture regeneration.
+//
+// gentle-pi hand-mirrors the always-on ODD routing block rendered by gentle-ai
+// `internal/components/agentguidance/routing.go` (RenderRouting). There is no
+// automated sync, so a canonical change leaves the pi mirror stale with nothing
+// catching it. This script renders the canonical block from a LOCAL gentle-ai
+// checkout and vendors it into `fixtures/odd-routing-canonical.md` with managed
+// provenance, where `tests/odd-routing-canonical-ratchet.test.ts` turns drift
+// into a failing test.
+//
+// This script NEVER fetches anything from the network (GOPROXY=off), NEVER
+// modifies the gentle-ai checkout beyond a transient temporary Go entrypoint
+// that it always deletes, and NEVER touches the installer release pin
+// (scripts/gentle-ai-installer.mjs INSTALLER_VERSION). Regeneration writes ONLY
+// the fixture; it never auto-rewrites the pi mirror assets.
+//
+// Usage:
+//   node scripts/mirror-odd-routing.mjs [--gentle-ai <path to local checkout>]
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export const ODD_ROUTING_FIXTURE_RELATIVE = "fixtures/odd-routing-canonical.md";
+export const ODD_ROUTING_SOURCE_REPO = "https://github.com/Gentleman-Programming/gentle-ai";
+export const ODD_ROUTING_SOURCE_PATH = "internal/components/agentguidance/routing.go";
+export const ODD_ROUTING_HEADER_OPEN = "<!-- gentle-pi:managed-odd-routing-canonical\n";
+export const ODD_ROUTING_HEADER_CLOSE = "\n-->\n";
+export const ODD_ROUTING_TEMP_DIR = "tmp-odd-routing-dump";
+export const ODD_ROUTING_BLOCK_PREFIX = "## Implementation Routing";
+
+const GO_ENTRYPOINT = `package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/gentleman-programming/gentle-ai/v3/internal/components/agentguidance"
+	"github.com/gentleman-programming/gentle-ai/v3/internal/model"
+)
+
+func main() {
+	rendered, err := agentguidance.RenderRouting(model.AgentPi)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	fmt.Print(rendered)
+}
+`;
+
+export function sha256Hex(value) {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+export function parseOddRoutingFixture(raw) {
+	if (!raw.startsWith(ODD_ROUTING_HEADER_OPEN)) {
+		throw new Error(`fixture does not start with the managed header ${JSON.stringify(ODD_ROUTING_HEADER_OPEN)}`);
+	}
+	const headerEnd = raw.indexOf(ODD_ROUTING_HEADER_CLOSE, ODD_ROUTING_HEADER_OPEN.length);
+	if (headerEnd === -1) {
+		throw new Error(`fixture managed header is not terminated by ${JSON.stringify(ODD_ROUTING_HEADER_CLOSE)}`);
+	}
+	const headerText = raw.slice(ODD_ROUTING_HEADER_OPEN.length, headerEnd);
+	const body = raw.slice(headerEnd + ODD_ROUTING_HEADER_CLOSE.length);
+	const header = {};
+	for (const line of headerText.split("\n")) {
+		const separator = line.indexOf(": ");
+		if (separator === -1) continue;
+		header[line.slice(0, separator)] = line.slice(separator + 2);
+	}
+	return { header, body };
+}
+
+export function renderOddRoutingFixture(block, { sourceCommit, generatedAt }) {
+	const body = block.endsWith("\n") ? block : `${block}\n`;
+	const header = [
+		ODD_ROUTING_HEADER_OPEN.trimEnd(),
+		`source_repo: ${ODD_ROUTING_SOURCE_REPO}`,
+		`source_path: ${ODD_ROUTING_SOURCE_PATH}`,
+		`source_commit: ${sourceCommit}`,
+		`generated_at: ${generatedAt}`,
+		`block_sha256: ${sha256Hex(body)}`,
+		"-->",
+	].join("\n");
+	return `${header}\n${body}`;
+}
+
+// `git status --porcelain --untracked-files=no` emits one `XY PATH` line per
+// modified tracked file. Extract just the repository-relative path so the
+// fail-closed error can name what would make provenance unverifiable.
+export function parsePorcelainPaths(porcelainOutput) {
+	return porcelainOutput
+		.split("\n")
+		.map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line))
+		.filter((line) => line.length > 0)
+		.map((line) => line.slice(3).trim())
+		.filter((path) => path.length > 0);
+}
+
+// Fail closed when the checkout carries uncommitted changes to tracked files.
+// The fixture header asserts the rendered block came from the committed tree;
+// rendering a dirty tree under that claim would make the provenance a lie.
+// Untracked files never reach this guard because the git call excludes them.
+export function assertCleanGentleAiCheckout(porcelainOutput) {
+	const dirtyPaths = parsePorcelainPaths(porcelainOutput);
+	if (dirtyPaths.length > 0) {
+		throw new Error(
+			`gentle-ai checkout is dirty; provenance would be unverifiable: ${dirtyPaths.join(", ")}. Commit or stash first.`,
+		);
+	}
+}
+
+function parseArguments(argv) {
+	const values = { gentleAi: undefined };
+	for (let index = 0; index < argv.length; index += 2) {
+		const flag = argv[index];
+		const value = argv[index + 1];
+		if (flag !== "--gentle-ai" || value === undefined) {
+			throw new Error("usage: node scripts/mirror-odd-routing.mjs [--gentle-ai <path to local checkout>]");
+		}
+		if (values.gentleAi !== undefined) throw new Error("duplicate --gentle-ai argument");
+		values.gentleAi = value;
+	}
+	return values;
+}
+
+function requireGentleAiCheckout(gentleAiRoot) {
+	if (!existsSync(gentleAiRoot)) {
+		throw new Error(
+			`no gentle-ai checkout at ${gentleAiRoot}; pass --gentle-ai <path> or clone ${ODD_ROUTING_SOURCE_REPO} as a sibling of gentle-pi`,
+		);
+	}
+	const routingPath = join(gentleAiRoot, ...ODD_ROUTING_SOURCE_PATH.split("/"));
+	if (!existsSync(routingPath)) {
+		throw new Error(`not a gentle-ai checkout: missing ${routingPath}`);
+	}
+}
+
+export function renderCanonicalRouting(gentleAiRoot) {
+	const tempRoot = join(gentleAiRoot, ODD_ROUTING_TEMP_DIR);
+	// Clear any stale temp entrypoint from a previous crash so the render is clean.
+	rmSync(tempRoot, { recursive: true, force: true });
+	mkdirSync(tempRoot, { recursive: true });
+	try {
+		writeFileSync(join(tempRoot, "main.go"), GO_ENTRYPOINT, { encoding: "utf8" });
+		const rendered = execFileSync("go", ["run", `./${ODD_ROUTING_TEMP_DIR}`], {
+			cwd: gentleAiRoot,
+			encoding: "utf8",
+			// GOPROXY=off fails closed instead of downloading: this script must
+			// never touch the network.
+			env: { ...process.env, GOPROXY: "off" },
+			stdio: ["ignore", "pipe", "inherit"],
+		});
+		if (!rendered.startsWith(ODD_ROUTING_BLOCK_PREFIX)) {
+			throw new Error(
+				`RenderRouting(model.AgentPi) did not return the expected routing block (starts with ${JSON.stringify(ODD_ROUTING_BLOCK_PREFIX)})`,
+			);
+		}
+		return rendered;
+	} finally {
+		rmSync(tempRoot, { recursive: true, force: true });
+	}
+}
+
+// Resolve fixture provenance from the committed gentle-ai tree. `generatedAt`
+// is the committer date, not wall-clock time, so rendering the same commit
+// twice yields byte-identical fixture files. `execGit` is injectable for tests.
+export function resolveOddRoutingProvenance(gentleAiRoot, execGit) {
+	const git = execGit ?? ((args) => execFileSync("git", args, { cwd: gentleAiRoot, encoding: "utf8" }));
+	assertCleanGentleAiCheckout(git(["status", "--porcelain", "--untracked-files=no"]));
+	return {
+		sourceCommit: git(["rev-parse", "HEAD"]).trim(),
+		generatedAt: git(["show", "-s", "--format=%cI", "HEAD"]).trim(),
+	};
+}
+
+export function mirrorOddRouting(packageRoot, gentleAiRoot) {
+	requireGentleAiCheckout(gentleAiRoot);
+	// Resolve (and fail closed on dirty) provenance BEFORE rendering: the
+	// transient Go entrypoint must not run against a tree whose commit hash the
+	// fixture would misrepresent.
+	const provenance = resolveOddRoutingProvenance(gentleAiRoot);
+	const block = renderCanonicalRouting(gentleAiRoot);
+	const contents = renderOddRoutingFixture(block, provenance);
+
+	const fixturePath = join(resolve(packageRoot), ...ODD_ROUTING_FIXTURE_RELATIVE.split("/"));
+	const previous = readPreviousFixture(fixturePath);
+	mkdirSync(dirname(fixturePath), { recursive: true });
+
+	// Atomic overwrite: write a sibling temp file, then rename it into place.
+	const stagingPath = `${fixturePath}.tmp`;
+	try {
+		writeFileSync(stagingPath, contents, { encoding: "utf8" });
+		renameSync(stagingPath, fixturePath);
+	} finally {
+		rmSync(stagingPath, { force: true });
+	}
+
+	const next = parseOddRoutingFixture(contents);
+	return {
+		fixturePath,
+		sourceCommit: next.header.source_commit,
+		blockSha256: next.header.block_sha256,
+		changed: previous === undefined || previous.body !== next.body || previous.header.source_commit !== next.header.source_commit,
+		previous,
+	};
+}
+
+function readPreviousFixture(fixturePath) {
+	if (!existsSync(fixturePath)) return undefined;
+	const raw = readFileSync(fixturePath, "utf8");
+	// Verify the existing fixture before clobbering it: an unparseable file is a
+	// signal to inspect, not to silently overwrite.
+	const parsed = parseOddRoutingFixture(raw);
+	const recorded = parsed.header.block_sha256;
+	const actual = sha256Hex(parsed.body);
+	if (recorded !== undefined && recorded !== actual) {
+		console.warn(`warning: existing fixture body does not match its recorded digest (${recorded}); regenerating from canonical`);
+	}
+	return parsed;
+}
+
+async function main() {
+	const packageRoot = join(fileURLToPath(new URL("..", import.meta.url)));
+	const { gentleAi } = parseArguments(process.argv.slice(2));
+	const gentleAiRoot = resolve(gentleAi ?? join(packageRoot, "..", "gentle-ai"));
+	const result = mirrorOddRouting(packageRoot, gentleAiRoot);
+	console.log(`${result.changed ? "Wrote" : "Refreshed"} ${result.fixturePath}`);
+	console.log(`source commit ${result.sourceCommit}; block sha256 ${result.blockSha256}`);
+	if (result.previous !== undefined) {
+		console.log(`previous commit ${result.previous.header.source_commit}; previous block sha256 ${result.previous.header.block_sha256}`);
+	}
+}
+
+const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+	await main();
+}

package/scripts/verify-package-files.mjs

@@ -181,7 +181,7 @@ const contractHashes = {
   "contracts/review-integration/v2/schemas/start.schema.json": "2991e3fcca672d9257d61b6a336fb34e58b15a8e03f8a09a7adf892cae6a8085",
   "contracts/review-integration/v2/schemas/status.schema.json": "c4dcc736cfc6300560a3c4262d2d982368529d5c49d58d499552a3b0beef9212",
   "contracts/telemetry/runtime-aggregate-v1.schema.json": "eb0f2993d9271f55cb42eca343e6fbb601a733fb90bd40daeebc92ee60ae1ba9",
-  "docs/review-integration.md": "95a3df92785bc4d9f3b99e702aaf817ae0440bd16c83218d2c3f2aca67c280fb",
+  "docs/review-integration.md": "9868cd52ae8f15cc2e6a6757014d5b12ff0904e06725d1a4cf29e9bcc3a7bae2",
 };
 
 requiredPaths.push(...Object.keys(contractHashes));
@@ -339,7 +339,7 @@ async function main() {
   });
 
   if (driftedContracts.length > 0) {
-    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v3.1.0 runtime's vendored Gentle AI contract artifacts:");
+    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v3.2.1 runtime's vendored Gentle AI contract artifacts:");
     for (const drift of driftedContracts) console.error(`- ${drift.relativePath}: expected ${drift.expected}, got ${drift.actual}`);
     process.exit(1);
   }
@@ -384,7 +384,7 @@ async function main() {
     process.exit(1);
   }
 
-  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v3.1.0 runtime).`);
+  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v3.2.1 runtime).`);
 }
 
 const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;

package/tests/gentle-ai-binary.test.ts

@@ -97,7 +97,7 @@ async function writeWindowsSourceBinary(packageRoot: string): Promise<{ binaryPa
 		method: "go-sumdb-source-build",
 		package: "github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai",
 		module: "github.com/gentleman-programming/gentle-ai/v3",
-		tag: "v3.1.0",
+		tag: "v3.2.1",
 		architecture: process.arch === "x64" ? "x64" : "arm64",
 		binarySha256: createHash("sha256").update(binary).digest("hex"),
 		moduleChecksum: GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM,