gentle-pi 3.2.0 → 3.2.1

package/lib/opaque-pi-reviewer-adapter.ts

@@ -5,7 +5,11 @@ import { join, posix, win32 } from "node:path";
 
 export const OPAQUE_PI_REVIEWER_ARGV = Object.freeze([
 	"--print",
-	"--mode", "text",
+	// #1140: text mode turns a run that spent its turn on a tool call into zero
+	// bytes and exit 0. JSON mode emits pi's own event stream, so the transport
+	// can always tell a silent child from an assistant answer, and can recover
+	// the answer text even when tool calls interleaved with it.
+	"--mode", "json",
 	"--no-session",
 	"--no-tools",
 	"--no-extensions",
@@ -32,6 +36,12 @@ export interface OpaquePiReviewerOptions {
 	readonly environment?: NodeJS.ProcessEnv;
 	readonly timeoutMs?: number;
 	readonly signal?: AbortSignal;
+	/**
+	 * Caller-owned tokens appended verbatim after the frozen argv (spawn keeps
+	 * shell:false, so every token is one argv entry). The adapter never
+	 * interprets them; its caller owns their meaning and validation.
+	 */
+	readonly extraArguments?: readonly string[];
 }
 
 export interface OpaquePiReviewerResult {
@@ -49,6 +59,8 @@ export interface OpaquePiReviewerTransportDetails {
 	readonly elapsedMs?: number;
 	/** The bound applied to a launched Pi process; absent when no process was launched. */
 	readonly timeoutMs?: number;
+	/** What the child's output stream revealed when no assistant answer could be recovered. */
+	readonly evidence?: PiReviewOutputEvidence;
 }
 
 export class OpaquePiReviewerTransportError extends Error {
@@ -59,6 +71,7 @@ export class OpaquePiReviewerTransportError extends Error {
 	readonly cancelled: boolean;
 	readonly elapsedMs: number | null;
 	readonly timeoutMs: number | null;
+	readonly evidence: PiReviewOutputEvidence | undefined;
 
 	constructor(kind: OpaquePiReviewerTransportFailureKind, message: string, details: OpaquePiReviewerTransportDetails = {}) {
 		super(message);
@@ -70,6 +83,7 @@ export class OpaquePiReviewerTransportError extends Error {
 		this.cancelled = details.cancelled ?? false;
 		this.elapsedMs = details.elapsedMs ?? null;
 		this.timeoutMs = details.timeoutMs ?? null;
+		this.evidence = details.evidence;
 	}
 }
 
@@ -107,25 +121,126 @@ export function resolvePiLaunch(
 	piExecutable: string | undefined,
 	platform: NodeJS.Platform = process.platform,
 	host: PiHostProcess = { execPath: process.execPath, entry: process.argv[1] },
+	extraArguments: readonly string[] = [],
 ): PiLaunch {
-	if (piExecutable !== undefined) return { file: piExecutable, arguments: [...OPAQUE_PI_REVIEWER_ARGV] };
-	if (platform !== "win32") return { file: "pi", arguments: [...OPAQUE_PI_REVIEWER_ARGV] };
+	const arguments_ = [...OPAQUE_PI_REVIEWER_ARGV, ...extraArguments];
+	if (piExecutable !== undefined) return { file: piExecutable, arguments: arguments_ };
+	if (platform !== "win32") return { file: "pi", arguments: arguments_ };
 	if (typeof host.entry !== "string" || host.entry.length === 0 || !(platform === "win32" ? win32 : posix).isAbsolute(host.entry)) {
 		throw new Error(`Pi host entry could not be resolved from the running process (received ${JSON.stringify(host.entry ?? null)}); a bare pi launcher cannot be spawned on Windows without a shell`);
 	}
-	return { file: host.execPath, arguments: [host.entry, ...OPAQUE_PI_REVIEWER_ARGV] };
+	return { file: host.execPath, arguments: [host.entry, ...arguments_] };
 }
 
 function errorMessage(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
+// ---------------------------------------------------------------------------
+// The child runs `pi --mode json`, so its stdout is a newline-delimited pi
+// event stream. The transport's output is the assistant text of that stream —
+// the same bytes an interactive run would have rendered — and everything else
+// about the stream becomes typed evidence. A run whose turn was spent on a
+// tool call therefore reports what happened (which reviewer selection ran,
+// that a tool call was attempted) instead of exiting 0 in silence (#1140).
+// ---------------------------------------------------------------------------
+
+export interface PiReviewOutputEvidence {
+	readonly stdoutKind: "no-output" | "not-a-pi-event-stream" | "no-assistant-text";
+	/** The reviewer selection the child itself reported in its events, when it named one. */
+	readonly reviewerModel?: string;
+	readonly toolCallAttempted?: boolean;
+}
+
+export type PiReviewExtraction =
+	| { readonly kind: "text"; readonly text: string }
+	| { readonly kind: "none"; readonly evidence: PiReviewOutputEvidence };
+
+interface PiEventMessagePart {
+	type?: unknown;
+	text?: unknown;
+}
+
+interface PiEventMessage {
+	role?: unknown;
+	content?: unknown;
+}
+
+interface PiEventEnvelope {
+	type?: unknown;
+	message?: unknown;
+}
+
+function parsePiEventLines(stdout: Buffer): PiEventEnvelope[] | undefined {
+	const lines = stdout.toString("utf8").split("\n").filter((line) => line.trim().length > 0);
+	if (lines.length === 0) return undefined;
+	const events: PiEventEnvelope[] = [];
+	for (const line of lines) {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			return undefined;
+		}
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+		events.push(parsed as PiEventEnvelope);
+	}
+	return events;
+}
+
+export function extractPiAssistantText(stdout: Buffer): PiReviewExtraction {
+	if (stdout.length === 0) return { kind: "none", evidence: { stdoutKind: "no-output" } };
+	const events = parsePiEventLines(stdout);
+	if (events === undefined) return { kind: "none", evidence: { stdoutKind: "not-a-pi-event-stream" } };
+	const parts: string[] = [];
+	let reviewerModel: string | undefined;
+	let toolCallAttempted = false;
+	for (const event of events) {
+		// The final content of one assistant message lives in its end event;
+		// start and update events repeat or stream the same parts.
+		if (event.type !== "message_end") continue;
+		const message = event.message;
+		if (!message || typeof message !== "object" || Array.isArray(message)) continue;
+		const candidate = message as PiEventMessage;
+		if (candidate.role !== "assistant") continue;
+		// The event envelope names the selection the child itself ran with the wire
+		// key pi uses for it; read as quoted data, never as an identifier.
+		const reported = (candidate as Record<string, unknown>)["model"];
+		if (typeof reported === "string" && reported.length > 0 && reviewerModel === undefined) reviewerModel = reported;
+		if (!Array.isArray(candidate.content)) continue;
+		for (const part of candidate.content as PiEventMessagePart[]) {
+			if (!part || typeof part !== "object") continue;
+			if (typeof part.type === "string" && part.type.startsWith("tool")) toolCallAttempted = true;
+			if (part.type === "text" && typeof part.text === "string") parts.push(part.text);
+		}
+	}
+	const text = parts.join("");
+	if (text.length === 0) {
+		return {
+			kind: "none",
+			evidence: {
+				stdoutKind: "no-assistant-text",
+				...(reviewerModel === undefined ? {} : { reviewerModel }),
+				...(toolCallAttempted ? { toolCallAttempted } : {}),
+			},
+		};
+	}
+	return { kind: "text", text };
+}
+
+function emptyOutputMessage(evidence: PiReviewOutputEvidence): string {
+	const details = [`stdout kind: ${evidence.stdoutKind}`];
+	if (evidence.reviewerModel !== undefined) details.push(`reviewer selection: ${evidence.reviewerModel}`);
+	if (evidence.toolCallAttempted) details.push("a tool call was attempted");
+	return `Pi process produced no assistant text (${details.join("; ")})`;
+}
+
 function runPiProcess(prompt: Buffer, scratchDirectory: string, options: OpaquePiReviewerOptions): Promise<OpaquePiProcessResult> {
 	return new Promise((resolve, reject) => {
 		const startedAt = Date.now();
 		let launch: PiLaunch;
 		try {
-			launch = resolvePiLaunch(options.piExecutable);
+			launch = resolvePiLaunch(options.piExecutable, process.platform, { execPath: process.execPath, entry: process.argv[1] }, options.extraArguments ?? []);
 		} catch (error) {
 			reject(error);
 			return;
@@ -197,6 +312,9 @@ export async function runOpaquePiReviewer(prompt: Buffer, options: OpaquePiRevie
 			{ cancelled: true },
 		);
 	}
+	if (options.extraArguments !== undefined && options.extraArguments.some((token) => typeof token !== "string" || token.length === 0)) {
+		throw new TypeError("Pi reviewer launch arguments must all be non-empty strings");
+	}
 
 	let scratchDirectory: string | undefined;
 	let primaryFailure = false;
@@ -252,17 +370,19 @@ export async function runOpaquePiReviewer(prompt: Buffer, options: OpaquePiRevie
 				{ exitCode: processResult.exitCode, stderr: processResult.stderr, ...timing },
 			);
 		}
-		if (processResult.stdout.length === 0) {
+		const extraction = extractPiAssistantText(processResult.stdout);
+		if (extraction.kind === "none") {
 			throw new OpaquePiReviewerTransportError(
 				OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.EMPTY_OUTPUT,
-				"Pi process produced no output bytes",
-				{ exitCode: 0, stderr: processResult.stderr, ...timing },
+				emptyOutputMessage(extraction.evidence),
+				{ exitCode: 0, stderr: processResult.stderr, evidence: extraction.evidence, ...timing },
 			);
 		}
+		const stdout = Buffer.from(extraction.text, "utf8");
 		return {
-			stdout: processResult.stdout,
+			stdout,
 			promptByteLength: prompt.length,
-			stdoutByteLength: processResult.stdout.length,
+			stdoutByteLength: stdout.length,
 		};
 	} catch (error) {
 		primaryFailure = true;

package/lib/review-host-relay.ts

@@ -30,10 +30,14 @@ import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { resolveGentleAiBinary } from "./gentle-ai-binary.ts";
+import { SAFE_MODEL_ID_PATTERN } from "./model-routing-authority.ts";
+import { existsSync } from "node:fs";
+import { delimiter as pathDelimiter } from "node:path";
 import {
 	OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE,
 	OpaquePiReviewerTransportError,
 	runOpaquePiReviewer,
+	type PiReviewOutputEvidence,
 	type OpaquePiReviewerResult,
 } from "./opaque-pi-reviewer-adapter.ts";
 import { REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION, REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS, type ReviewCaptureSubmissionV1, type ReviewCollectInputV3 } from "./review-integration-v2.ts";
@@ -60,6 +64,11 @@ export const REVIEW_HOST_RELAY_FAILURE = {
 	// continuation instead of hiding inside `pi-failed`.
 	PI_TIMED_OUT: "pi-timed-out",
 	PI_EMPTY_OUTPUT: "pi-empty-output",
+	// gentle-shell#1158 / #1136: a caller-owned reviewer selection that cannot
+	// possibly launch (a malformed selection id, a relative or missing extension
+	// path) is a configuration failure, refused typed before anything runs —
+	// never a mid-review transport mystery.
+	REVIEWER_CONFIG_INVALID: "reviewer-config-invalid",
 	SUBMISSION_REFUSED: "submission-refused",
 } as const;
 export type ReviewHostRelayFailureKind = (typeof REVIEW_HOST_RELAY_FAILURE)[keyof typeof REVIEW_HOST_RELAY_FAILURE];
@@ -90,7 +99,9 @@ export class ReviewHostRelayError extends Error {
 	// "none" again: the provider states that the lens slot was not consumed
 	// (gentle-pi#522 / #524).
 	readonly mutationOutcome: "none" | "unknown";
-	constructor(kind: ReviewHostRelayFailureKind, stage: ReviewHostRelayStage, message: string, details?: { exitCode?: number | null; stderr?: string; timedOut?: boolean; elapsedMs?: number; timeoutMs?: number; mutationOutcome?: "none" | "unknown" }) {
+	/** What the reviewer child's own event stream revealed on an empty-output failure. */
+	readonly reviewerEvidence: PiReviewOutputEvidence | undefined;
+	constructor(kind: ReviewHostRelayFailureKind, stage: ReviewHostRelayStage, message: string, details?: { exitCode?: number | null; stderr?: string; timedOut?: boolean; elapsedMs?: number; timeoutMs?: number; mutationOutcome?: "none" | "unknown"; reviewerEvidence?: PiReviewOutputEvidence }) {
 		super(message);
 		this.name = "ReviewHostRelayError";
 		this.kind = kind;
@@ -101,6 +112,7 @@ export class ReviewHostRelayError extends Error {
 		this.elapsedMs = details?.elapsedMs ?? null;
 		this.timeoutMs = details?.timeoutMs ?? null;
 		this.mutationOutcome = details?.mutationOutcome ?? (stage === "submit" ? "unknown" : "none");
+		this.reviewerEvidence = details?.reviewerEvidence;
 	}
 }
 
@@ -295,6 +307,21 @@ export interface ReviewHostRelayRequest {
 	readonly piExecutable?: string;
 	readonly environment?: NodeJS.ProcessEnv;
 	readonly gentleAiTimeoutMs?: number;
+	/**
+	 * User-owned reviewer selection forwarded to the child as `--model`. The
+	 * relay never invents one; the default launch stays selection-free. Must
+	 * match {@link SAFE_MODEL_ID_PATTERN}; anything else is refused typed
+	 * before any process launches (gentle-shell#1136).
+	 */
+	readonly reviewerModel?: string;
+	/**
+	 * User-owned extension files loaded into the isolated child through
+	 * explicit `-e` paths (pi keeps explicit loads under `--no-extensions`),
+	 * so a subscription provider's auth adapter can ride along without
+	 * re-enabling extension discovery (gentle-shell#1158). Every path must be
+	 * absolute and exist; anything else is refused typed before launch.
+	 */
+	readonly reviewerExtensionPaths?: readonly string[];
 	/**
 	 * Overrides the reviewer bound entirely. Production leaves it unset and the
 	 * relay derives the bound from the materialized prompt bytes and
@@ -464,7 +491,18 @@ function relayPiTransportError(error: unknown, promptByteLength: number, piTimeo
 		);
 	}
 	if (error.kind === OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.EMPTY_OUTPUT) {
-		return new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_EMPTY_OUTPUT, "pi", "pi subprocess produced no output bytes", details);
+		// #1156: the envelope says what the child's own stream revealed, and the
+		// message names the remedies, because a bare kind code is what sent the
+		// #1140 reporter into a retry loop with nothing to inspect.
+		const evidence = error.evidence;
+		const summary: string[] = [`stdout kind: ${evidence?.stdoutKind ?? "unknown"}`];
+		if (evidence?.reviewerModel !== undefined) summary.push(`reviewer selection: ${evidence.reviewerModel}`);
+		if (evidence?.toolCallAttempted) summary.push("a tool call was attempted");
+		const stderrExcerpt = details.stderr.length > 0 ? ` child stderr: ${details.stderr.slice(0, 400).replace(/\s+/g, " ").trim()}` : "";
+		const message = `pi subprocess produced no assistant text (${summary.join("; ")}).${stderrExcerpt}`
+			+ " A reviewer that spent its turn on a tool call, a selection the child could not resolve, or a stream pi did not produce all land here; the evidence above says which."
+			+ " Assign the lens a reviewer selection that answers in text (the lens's entry in the agent model routing config), and when the provider needs an auth adapter, name its absolute file path in " + REVIEW_HOST_RELAY_EXTENSIONS_ENV + ".";
+		return new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_EMPTY_OUTPUT, "pi", message, { ...details, ...(evidence === undefined ? {} : { reviewerEvidence: evidence }) });
 	}
 	if (
 		error.kind === OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.LAUNCH_FAILED
@@ -482,8 +520,60 @@ function assertTokens(name: string, tokens: readonly string[]): void {
 	}
 }
 
+export const REVIEW_HOST_RELAY_EXTENSIONS_ENV = "GENTLE_PI_REVIEW_RELAY_EXTENSIONS";
+
+/**
+ * The user-owned extension allowlist for the reviewer child, read from the
+ * environment (gentle-shell#1158). Entries are split on the platform path
+ * delimiter; empty entries are skipped. Validation of each path happens at
+ * snapshot time, so a broken entry is refused typed before anything launches.
+ */
+export function resolveReviewHostRelayExtensionPaths(environment: NodeJS.ProcessEnv = process.env): readonly string[] {
+	const configured = environment[REVIEW_HOST_RELAY_EXTENSIONS_ENV];
+	if (configured === undefined || configured.trim().length === 0) return [];
+	return configured.split(pathDelimiter).map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
+
+// The tokens a validated caller-owned selection contributes to the child's
+// argv. Only these two shapes may ride the forwarding path.
+function reviewerLaunchArguments(reviewerModel: string | undefined, reviewerExtensionPaths: readonly string[] | undefined): readonly string[] {
+	return [
+		...(reviewerModel === undefined ? [] : ["--model", reviewerModel]),
+		...(reviewerExtensionPaths ?? []).flatMap((path) => ["-e", path]),
+	];
+}
+
+function validateReviewerLaunchConfiguration(request: ReviewHostRelayRequest): { reviewerModel?: string; reviewerExtensionPaths?: readonly string[] } {
+	if (request.reviewerModel !== undefined) {
+		if (typeof request.reviewerModel !== "string" || request.reviewerModel.length === 0 || !SAFE_MODEL_ID_PATTERN.test(request.reviewerModel)) {
+			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.REVIEWER_CONFIG_INVALID, "pi", `Pi host relay reviewer launch configuration is invalid: the caller-owned reviewer selection ${JSON.stringify(request.reviewerModel)} is not a safe model id`);
+		}
+	}
+	if (request.reviewerExtensionPaths !== undefined) {
+		if (!Array.isArray(request.reviewerExtensionPaths) || request.reviewerExtensionPaths.some((path) => typeof path !== "string" || path.length === 0)) {
+			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.REVIEWER_CONFIG_INVALID, "pi", "Pi host relay reviewer launch configuration is invalid: extension paths must all be non-empty strings");
+		}
+		for (const path of request.reviewerExtensionPaths) {
+			if (!isAbsolute(path)) {
+				throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.REVIEWER_CONFIG_INVALID, "pi", `Pi host relay reviewer launch configuration is invalid: the extension path ${JSON.stringify(path)} is not absolute`);
+			}
+			if (!existsSync(path)) {
+				throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.REVIEWER_CONFIG_INVALID, "pi", `Pi host relay reviewer launch configuration is invalid: the extension path ${JSON.stringify(path)} does not exist`);
+			}
+		}
+	}
+	return {
+		...(request.reviewerModel === undefined ? {} : { reviewerModel: request.reviewerModel }),
+		...(request.reviewerExtensionPaths === undefined || request.reviewerExtensionPaths.length === 0 ? {} : { reviewerExtensionPaths: Object.freeze([...request.reviewerExtensionPaths]) }),
+	};
+}
+
 function snapshotReviewHostRelayRequest(request: ReviewHostRelayRequest): ReviewHostRelayRequest {
 	assertTokens("capture", request.captureArgumentTokens);
+	// Caller-owned reviewer selection is validated before any process launches:
+	// a broken configuration is a typed refusal, never a mid-review transport
+	// failure (gentle-shell#1158 / #1136).
+	const reviewerLaunch = validateReviewerLaunchConfiguration(request);
 	// The completing form is validated before any process launches: a materialize
 	// slot without a provider-owned submission is a typed contract mismatch,
 	// never a synthesized invocation.
@@ -500,6 +590,7 @@ function snapshotReviewHostRelayRequest(request: ReviewHostRelayRequest): Review
 		...request,
 		captureArgumentTokens: Object.freeze([...request.captureArgumentTokens]),
 		...(submission === undefined ? {} : { submission }),
+		...reviewerLaunch,
 		gentleAiExecutable,
 		environment,
 		gentleAiTimeoutMs: request.gentleAiTimeoutMs ?? DEFAULT_GENTLE_AI_TIMEOUT_MS,
@@ -574,6 +665,7 @@ export async function prepareReviewHostRelaySlot(
 
 	// The pure adapter owns the fresh isolated Pi process. Its input and output
 	// are opaque bytes; this coordinator only maps transport failures.
+	const launchArguments = reviewerLaunchArguments(preparedRequest.reviewerModel, preparedRequest.reviewerExtensionPaths);
 	let piResult: OpaquePiReviewerResult;
 	try {
 		piResult = await reviewer(promptBytes, {
@@ -581,6 +673,7 @@ export async function prepareReviewHostRelaySlot(
 			environment: preparedRequest.environment,
 			timeoutMs: piTimeoutMs,
 			...(preparedRequest.signal === undefined ? {} : { signal: preparedRequest.signal }),
+			...(launchArguments.length === 0 ? {} : { extraArguments: launchArguments }),
 		});
 	} catch (error) {
 		throw relayPiTransportError(error, promptBytes.length, piTimeoutMs);

package/lib/shell-bar.ts

@@ -1,6 +1,6 @@
 import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { GAUGE_CELLS, gaugeTone, paintGauge, renderGauge, type GaugeTone } from "./shell-gauge.ts";
-import { renderUsageBar, type ProviderUsage } from "./shell-usage.ts";
+import { allowanceGroupsSupported, groupUsageLimits, renderUsageBar, selectUsageLimit, type ProviderUsage } from "./shell-usage.ts";
 import { sanitizeTerminalText } from "./terminal-theme.ts";
 import { CARD_TONE, cardInnerWidth, renderCard } from "./shell-card.ts";
 
@@ -48,11 +48,17 @@ const ROLE = {
 	SESSION: "dim",
 } as const;
 
-export const SHELL_BAR_BRAND = "✿ gentle-pi";
+export const SHELL_BAR_BRAND = "✿ gentle shell";
 export const SHELL_BAR_SEPARATOR = "⟡";
 export const SHELL_BAR_GAUGE_CELLS = GAUGE_CELLS;
 const RIGHT_PADDING = 2;
 const COMPACT_BRANCH_WIDTH = 15;
+// The rows the sidebar prints for a provider with per-model allowances use the
+// bar's shorter meter: the rail is 50 columns wide, and the panel's 16 cells
+// would leave no room for the model ids.
+const SIDEBAR_USAGE_METER_CELLS = GAUGE_CELLS;
+// Meter, its two spaces and the right-aligned percentage.
+const SIDEBAR_USAGE_ROW_FIXED = SIDEBAR_USAGE_METER_CELLS + 6;
 
 export function shellEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
 	if (env.GENTLE_PI_AGENTS_CHILD === "1") return false;
@@ -90,7 +96,7 @@ function buildSegments(model: ShellBarModel, theme: ShellBarTheme): string[] {
 	const percentText = model.contextPercent === null ? "?%" : `${Math.round(model.contextPercent)}%`;
 	const context = `${theme.fg(ROLE.LABEL, "ctx")} ${paintGauge(model.contextPercent, theme)} ${theme.fg(ROLE.VALUE, percentText)}`;
 	const cost = theme.fg(ROLE.VALUE, formatCost(model.costTotal, model.subscription));
-	const usage = model.usage ? renderUsageBar(model.usage, theme) : undefined;
+	const usage = model.usage ? renderUsageBar(model.usage, theme, model.modelId) : undefined;
 	const statuses = model.statuses.map((status) => theme.fg(ROLE.STATUS, sanitizeStatus(status)));
 	return [theme.fg(ROLE.BRAND, SHELL_BAR_BRAND), location, modelSegment, context, cost, ...(usage ? [usage] : []), ...statuses];
 }
@@ -119,6 +125,52 @@ function joinSegments(segments: string[], theme: ShellBarTheme): string {
 	return segments.join(` ${theme.fg(ROLE.SEPARATOR, SHELL_BAR_SEPARATOR)} `);
 }
 
+// A row exists to show what is being consumed, so a window that consumed
+// nothing is noise the sidebar drops. The threshold is the row's own number and
+// nothing else: the render path prints `Math.round(percent)`, so a fraction
+// below half a percent prints `0%` and disappears while half a percent keeps its
+// row and prints `1%` — no second scale and no separate epsilon. A window whose
+// percent is not a number never equals zero, so it keeps its row instead of
+// being dropped in silence. The bar and the panel keep their own contract and
+// still print a zero allowance.
+function consumedNothing(usedPercent: number): boolean {
+	return Math.round(usedPercent) === 0;
+}
+
+// The sidebar is the surface that never needs opening, so a provider with
+// per-model allowances prints the panel's model rows there too — the most
+// consumed family first, its models inside it — and leaves the aggregate totals
+// and the reset dates to the bar and the panel. Providers without raw
+// allowances keep the one aggregate line the bar has always drawn for the model
+// in use.
+function sidebarUsageLines(usage: ProviderUsage, modelId: string, theme: ShellBarTheme, available: number): string[] {
+	if (!allowanceGroupsSupported(usage.limits)) {
+		// The aggregate line is one row, so its windows decide together: one
+		// consumed window keeps the sharing row, all of them zero drop it. A limit
+		// with no windows is not "zero consumption" — there is nothing to draw, and
+		// renderUsageBar already answers that — so the rule only speaks when there
+		// is a window to judge.
+		const windows = selectUsageLimit(usage, modelId)?.windows ?? [];
+		if (windows.length > 0 && windows.every((window) => consumedNothing(window.usedPercent))) return [];
+		const line = renderUsageBar(usage, theme, modelId);
+		return line ? [line] : [];
+	}
+	const rows = groupUsageLimits(usage.limits)
+		.flatMap((limit) =>
+			limit.windows.map((window) => ({ name: [limit.name, window.label].filter((part) => part.length > 0).join(" "), window })),
+		)
+		.filter((row) => !consumedNothing(row.window.usedPercent));
+	// The name column gives way first: it is the only part that can be clipped
+	// without losing the number the row exists to show.
+	const widest = rows.reduce((width, row) => Math.max(width, row.name.length), 0);
+	const nameWidth = Math.min(widest, Math.max(1, available - SIDEBAR_USAGE_ROW_FIXED));
+	return rows.map((row) => {
+		const name = row.name.length > nameWidth ? clipText(row.name, nameWidth) : row.name.padEnd(nameWidth);
+		const percent = `${Math.round(row.window.usedPercent)}%`.padStart(4);
+		return `${theme.fg(ROLE.LABEL, name)} ${paintGauge(row.window.usedPercent, theme, SIDEBAR_USAGE_METER_CELLS)} ${theme.fg(ROLE.VALUE, percent)}`;
+	});
+}
+
 // Sidebar groups use structured fields, never positional compact-bar segments
 // or inferred meanings from opaque extension status strings.
 export function renderShellSidebarBar(model: ShellBarModel, theme: ShellBarTheme, width: number): string[] {
@@ -128,7 +180,11 @@ export function renderShellSidebarBar(model: ShellBarModel, theme: ShellBarTheme
 	const branch = model.branch ? `${label("Branch")} ${value(model.branch)}` : "";
 	const percent = model.contextPercent === null ? "?%" : `${Math.round(model.contextPercent)}%`;
 	const capacity = label(`${formatTokens(model.contextWindow)} tokens`);
-	const usage = model.usage ? renderUsageBar(model.usage, theme) : undefined;
+	// Pre-wrap values before indenting so Unicode/ANSI continuation lines keep
+	// the same inset without consuming the card's right border.
+	const innerWidth = cardInnerWidth(width);
+	const inset = Math.min(1, innerWidth - 1);
+	const usageLines = model.usage ? sidebarUsageLines(model.usage, model.modelId, theme, innerWidth - inset) : [];
 	const groups: Array<{ title: string; lines: string[] }> = [
 		{
 			title: "Project",
@@ -157,17 +213,15 @@ export function renderShellSidebarBar(model: ShellBarModel, theme: ShellBarTheme
 				`${label("Context")} ${paintGauge(model.contextPercent, theme)} ${value(percent)}`,
 				capacity,
 				`${label("Cost")} ${value(formatCost(model.costTotal, model.subscription))}`,
-				...(usage ? [usage] : []),
+				...usageLines,
 			],
 		},
 		{ title: "Integrations", lines: model.statuses.length
 			? model.statuses.map((status) => theme.fg(ROLE.STATUS, sanitizeStatus(status)))
 			: [label("No status reported")] },
 	];
-	// Pre-wrap values before indenting so Unicode/ANSI continuation lines keep
-	// the same inset without consuming the card's right border.
-	const innerWidth = cardInnerWidth(width);
-	const inset = Math.min(1, innerWidth - 1);
+	// Wrap and indent every group line before it reaches the card, so Unicode and
+	// ANSI continuation lines keep the same inset without consuming the right border.
 	const body = groups.flatMap((group, index) => [
 		...(index ? [""] : []),
 		label(group.title),