gentle-pi 3.2.1 → 3.4.0

package/lib/review-integration-v2.ts

@@ -199,6 +199,22 @@ const CAPABILITIES_SCHEMA_IDENTITIES: Readonly<Record<string, { protocolMinor: n
 		requiredMandatoryFeatures: REQUIRED_MANDATORY_FEATURES_V23,
 		optionalFeatureFloor: 14,
 	}),
+	// Ground-truthed against the published v3.4.0 binary: capabilities/v2.6
+	// advertises the same required surface as v2.5 (status/v6 is still
+	// advertised for compatibility) plus the status/v7 and status/v8 schemas,
+	// which are superset-checked additions, not requirements --
+	// decodeReviewStatusV3 already accepts v7/v8/v9 as additive extensions of
+	// v6, so the required-schema floor stays unchanged. `review assess` also
+	// gained review_due/review_due_reason/next_transition, which is unrelated
+	// to this negotiated capabilities surface. The v3.4.0 binary advertised
+	// 15 optional features, same as v2.5's binary (floor stays at 14, its
+	// established minimum).
+	"gentle-ai.review-integration.capabilities/v2.6": Object.freeze({
+		protocolMinor: 6,
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON_V23, "gentle-ai.review-integration.capabilities/v2.6", "gentle-ai.review-integration.consent/v3", "gentle-ai.review-integration.start/v4", "gentle-ai.review-integration.status/v6", "gentle-ai.review-intended-untracked-selection/v1"]),
+		requiredMandatoryFeatures: REQUIRED_MANDATORY_FEATURES_V23,
+		optionalFeatureFloor: 14,
+	}),
 });
 const OPTIONAL_FEATURE_NAMES = Object.freeze([
 	"base_ref_workspace_overlay",
@@ -294,6 +310,7 @@ export interface ChangedPathEntry {
 	readonly typeChanged: boolean;
 	readonly modeOnly: boolean;
 	readonly intendedUntracked: boolean;
+	readonly generated?: true;
 }
 
 export interface ReviewArtifactSubjectV2 {
@@ -438,11 +455,21 @@ export interface ReviewCaptureSubmissionV1 {
 	values: readonly ReviewCaptureSubmissionValueV1[];
 }
 
-// The two Go-owned non-lens provider role capture operations (gentle-pi#311
-// P4-roles; provider side gentle-ai#3264). Their collect inputs are
-// self-contained authority-advancing vectors: binding tokens plus
-// `--agent=pi --execute=true`, with NO submission descriptor. The known set
-// is closed — an unknown role capture operation is never executed.
+// The two non-lens provider role capture operations (gentle-pi#311 P4-roles;
+// provider side gentle-ai#3264). An older gentle-ai still renders each one as
+// a self-contained authority-advancing vector: binding tokens plus
+// `--agent=pi --execute=true`, with NO submission descriptor — executing the
+// exact rendered tokens makes Go materialize the role prompt, run its own
+// locked-down pi subprocess, and admit the verdict itself.
+//
+// gentle-ai's v9 contract makes both roles host-mediated exactly like a lens
+// materialize slot instead (gentle-pi#311 P3): the collect input carries
+// `--materialize=true` (never alongside `--execute`) plus a provider-owned
+// `submission` descriptor, and the host completes the frozen prompt
+// in-process and submits the result through that exact descriptor. The two
+// wire forms are mutually exclusive on one input; see the gating in
+// decodeCollectInput below. The known operation set is closed — an unknown
+// role capture operation is never executed either way.
 export const REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION = {
 	CAPTURE_REFUTER: "review.capture-refuter",
 	CAPTURE_VALIDATION: "review.capture-validation",
@@ -1124,7 +1151,8 @@ export function decodeReviewArtifactSubjectV2(value: unknown): ReviewArtifactSub
 }
 
 function decodeChangedPathEntry(value: unknown, label: string): ChangedPathEntry {
-	const body = exactRecord(value, label, ["path", "status", "old_mode", "new_mode", "deleted", "type_changed", "mode_only", "intended_untracked"]);
+	const body = exactRecord(value, label, ["path", "status", "old_mode", "new_mode", "deleted", "type_changed", "mode_only", "intended_untracked"], ["generated"]);
+	if (body.generated !== undefined && body.generated !== true) throw new TypeError(`${label}.generated must be true when present`);
 	return {
 		path: nonempty(body.path, `${label}.path`),
 		status: enumeration(body.status, ["A", "D", "M", "T"] as const, `${label}.status`),
@@ -1134,6 +1162,7 @@ function decodeChangedPathEntry(value: unknown, label: string): ChangedPathEntry
 		typeChanged: boolean(body.type_changed, `${label}.type_changed`),
 		modeOnly: boolean(body.mode_only, `${label}.mode_only`),
 		intendedUntracked: boolean(body.intended_untracked, `${label}.intended_untracked`),
+		...(body.generated === undefined ? {} : { generated: true }),
 	};
 }
 
@@ -1451,11 +1480,18 @@ function decodeCaptureSubmission(value: unknown, label: string, v5: boolean, v6:
 	// one-entry values array the host relay already consumes. A payload
 	// carrying both wire forms at once matches no captured shape and falls
 	// through to the legacy decoder, which rejects the unknown `value` key.
+	//
+	// gentle-ai's v9 contract renders the same singular-value shape for the
+	// two host-mediated provider role operations (capture-refuter,
+	// capture-validation): they carry a `schema` key exactly like
+	// capture-result, since both bind one artifact-path-or-stdin value, never
+	// the correction-plan's numeric bounds (gentle-pi#311 P3).
 	if (v5 && typeof value === "object" && value !== null && "value" in value && !("values" in value)) {
 		const submission = exactRecord(value, label, ["operation_token", "argument_tokens", "value"]);
-		const operationToken = enumeration(submission.operation_token, ["capture-result", "capture-correction-plan"] as const, `${label}.operation_token`);
+		const operationToken = enumeration(submission.operation_token, ["capture-result", "capture-correction-plan", "capture-refuter", "capture-validation"] as const, `${label}.operation_token`);
 		const argumentTokens = stringArray(submission.argument_tokens, `${label}.argument_tokens`, { minimum: 1 });
-		const row = operationToken === "capture-result"
+		const bindsArtifactSchema = operationToken === "capture-result" || operationToken === "capture-refuter" || operationToken === "capture-validation";
+		const row = bindsArtifactSchema
 			? exactRecord(submission.value, `${label}.value`, ["slot", "domain", "schema", "substitution_location"])
 			: exactRecord(submission.value, `${label}.value`, ["slot", "domain", "minimum", "maximum", "substitution_location"]);
 		return {
@@ -1464,7 +1500,11 @@ function decodeCaptureSubmission(value: unknown, label: string, v5: boolean, v6:
 			values: [{
 				slot: operationToken === "capture-result"
 					? enumeration(row.slot, ["reviewer_result"] as const, `${label}.value.slot`)
-					: enumeration(row.slot, ["correction_lines"] as const, `${label}.value.slot`),
+					: operationToken === "capture-correction-plan"
+					? enumeration(row.slot, ["correction_lines"] as const, `${label}.value.slot`)
+					: operationToken === "capture-refuter"
+					? enumeration(row.slot, ["provider_refuter"] as const, `${label}.value.slot`)
+					: enumeration(row.slot, ["provider_targeted_validator"] as const, `${label}.value.slot`),
 				domain: nonempty(row.domain, `${label}.value.domain`),
 				...(row.schema === undefined ? {} : { schema: nonempty(row.schema, `${label}.value.schema`) }),
 				...(row.minimum === undefined ? {} : { minimum: integer(row.minimum, `${label}.value.minimum`, 1, 200) }),
@@ -1605,7 +1645,7 @@ const CORRECTION_REQUEST_REASON_CODES = Object.freeze(["correction_plan_required
 // v5 capture operations that must carry a submission descriptor.
 const V5_SUBMISSION_CAPTURE_OPERATIONS = Object.freeze(["review.capture-correction-plan"] as const);
 
-function decodeCollectInput(value: unknown, label: string, v5: boolean, v6: boolean): ReviewCollectInputV3 {
+function decodeCollectInput(value: unknown, label: string, v5: boolean, v6: boolean, v9: boolean): ReviewCollectInputV3 {
 	const input = exactRecord(value, label, ["name", "schema", "capture_operation", "arguments"], ["artifact_subject", "base_tree", "candidate_tree", "changed_path_manifest", "submission", ...(v5 ? ["provider_task", "validation_request"] : [])]);
 	const name = text(input.name, `${label}.name`, { minimum: 1, pattern: /^[a-z0-9_]+$/ });
 	const schema = nonempty(input.schema, `${label}.schema`);
@@ -1656,13 +1696,18 @@ function decodeCollectInput(value: unknown, label: string, v5: boolean, v6: bool
 		sha256(argumentsList[5]!.value, `${label}.arguments[5].value`);
 	}
 
-	// gentle-pi#311 P4-roles: the two Go-owned non-lens provider role capture
-	// operations render SELF-CONTAINED authority-advancing vectors. Executing
+	// gentle-pi#311 P4-roles / P3: the two non-lens provider role capture
+	// operations render either wire form on one input, never both at once.
+	// An older gentle-ai renders a SELF-CONTAINED authority-advancing vector
+	// (binding tokens + --agent=pi --execute=true, no submission): executing
 	// the exact rendered tokens makes Go materialize the role prompt, run its
-	// own locked-down pi subprocess, and admit the raw verdict — so a
-	// submission descriptor (the host-mediated completing form) on one of
-	// these inputs would hand the caller a way to author the verdict and is
-	// rejected as a provider contract violation.
+	// own locked-down pi subprocess, and admit the raw verdict. gentle-ai's
+	// v9 contract instead renders a HOST-MEDIATED form: the same binding
+	// tokens plus --materialize=true (never --execute) and a provider-owned
+	// submission descriptor, exactly like a lens capture-result materialize
+	// slot — the host completes the frozen prompt in-process and submits
+	// through that descriptor.
+	const isRoleCaptureOperation = (REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS as readonly string[]).includes(captureOperation);
 	if (captureOperation === REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION.CAPTURE_REFUTER && schema !== "https://gentle-ai.dev/schema/review/refuter/v1") {
 		throw new TypeError(`${label}.schema must be https://gentle-ai.dev/schema/review/refuter/v1`);
 	}
@@ -1693,8 +1738,30 @@ function decodeCollectInput(value: unknown, label: string, v5: boolean, v6: bool
 		if (providerArgument("target") !== validationRequest.correctionTargetIdentity) throw new TypeError(`${label}.arguments target must bind validation_request.correction_target_identity`);
 		if (providerArgument("request-hash") !== validationRequest.requestHash) throw new TypeError(`${label}.arguments request-hash must bind validation_request.request_hash`);
 	}
-	if (input.submission !== undefined && (REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS as readonly string[]).includes(captureOperation)) {
-		throw new TypeError(`${label}.submission is not allowed on the self-contained ${captureOperation} vector`);
+	if (isRoleCaptureOperation && input.submission !== undefined) {
+		// A submission descriptor only ever rides the v9 host-mediated form
+		// (gentle-ai's v9 provider contract; the sibling branch ahead of the
+		// currently-released v8). A v8-or-earlier provider (status/v3..v8) never
+		// renders one, even if it happened to carry a submission-shaped payload,
+		// so this is gated on v9 specifically — not on v5, which v8 already
+		// satisfies. Within a v9 payload the discriminator is exactly the
+		// materialize slot's --materialize=true with no --execute, the same one
+		// a lens capture-result materialize slot already uses. Mixing a
+		// submission with the old self-contained --execute=true vector, or with
+		// neither flag, is a malformed vector.
+		if (!v9) {
+			throw new TypeError(`${label}.submission requires the v9 provider contract for the host-mediated ${captureOperation} form`);
+		}
+		const argumentNamed = (argumentName: string): string | undefined => {
+			const matches = argumentsList.filter((argument) => argument.name === argumentName);
+			return matches.length === 1 ? matches[0]!.value : undefined;
+		};
+		if (argumentNamed("materialize") !== "true") {
+			throw new TypeError(`${label}.submission requires --materialize=true on the host-mediated ${captureOperation} form`);
+		}
+		if (argumentNamed("execute") !== undefined) {
+			throw new TypeError(`${label} must not carry --execute alongside a submission descriptor on ${captureOperation}`);
+		}
 	}
 
 	if (captureOperation === "review.capture-result") {
@@ -1711,7 +1778,12 @@ function decodeCollectInput(value: unknown, label: string, v5: boolean, v6: bool
 	const submissionOperations: readonly string[] = v5
 		? ["review.capture-result", "review.capture-correction-plan", ...(v6 ? ["external.select_intended_untracked"] : [])]
 		: ["review.capture-result"];
-	if (input.submission !== undefined && !submissionOperations.includes(captureOperation)) {
+	// Role operations are gated above by the materialize/execute discriminator
+	// instead of this allowlist: an older gentle-ai's self-contained vector
+	// legitimately carries no submission regardless of v5/v6, so they cannot
+	// simply join the list the way every other submission-carrying operation
+	// does.
+	if (input.submission !== undefined && !isRoleCaptureOperation && !submissionOperations.includes(captureOperation)) {
 		throw new TypeError(v5 ? `${label}.submission is only valid for ${submissionOperations.join(", ")}` : `${label}.submission is only valid for review.capture-result`);
 	}
 	if (intendedUntracked && input.submission === undefined) throw new TypeError(`${label}.submission is required for external.select_intended_untracked`);
@@ -1749,8 +1821,14 @@ export function decodeReviewManagedAssetsContinuationV1(value: unknown, label: s
 	return { operation, command, ...(agent === undefined ? {} : { agent }), ...(staleAssets === undefined ? {} : { staleAssets }) };
 }
 
-export function decodeReviewNextTransitionV3(value: unknown, options: { v5?: boolean; v6?: boolean } = {}): ReviewNextTransitionV3 {
-	const v6 = options.v6 === true;
+export function decodeReviewNextTransitionV3(value: unknown, options: { v5?: boolean; v6?: boolean; v9?: boolean } = {}): ReviewNextTransitionV3 {
+	// v9 (gentle-ai's next contract, ahead of the currently-released v8) is
+	// the only rung this sub-decoder distinguishes beyond v6: v7 and v8 add
+	// nothing to next_transition/collect-input decoding (v8 only extended the
+	// reviewer-result transition for OpenCode provider tasks at the top
+	// status level), so they decode on the exact v6 surface here.
+	const v9 = options.v9 === true;
+	const v6 = options.v6 === true || v9;
 	const v5 = options.v5 === true || v6;
 	const transition = exactRecord(value, "next_transition", ["kind", "reason_code"], ["execute", "collect", ...(v5 ? ["correction_request"] : []), "continuation", "unachievable_lens_slots"]);
 	const kind = enumeration(transition.kind, ["execute", "collect", "stop"] as const, "next_transition.kind");
@@ -1812,7 +1890,7 @@ export function decodeReviewNextTransitionV3(value: unknown, options: { v5?: boo
 	}
 	if (kind === "collect") {
 		const collect = exactRecord(transition.collect, "next_transition.collect", ["inputs"]);
-		const inputs = array(collect.inputs, "next_transition.collect.inputs", (entry, label) => decodeCollectInput(entry, label, v5, v6), { minimum: 1 });
+		const inputs = array(collect.inputs, "next_transition.collect.inputs", (entry, label) => decodeCollectInput(entry, label, v5, v6, v9), { minimum: 1 });
 		if (transition.execute !== undefined) throw new TypeError("next_transition.execute is incompatible with collect");
 		return { kind, reasonCode, collect: { inputs }, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
 	}
@@ -1925,16 +2003,25 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 	// surfaces. status/v6 adds the intended-untracked selection; status/v7
 	// (gentle-ai v2.6.0, advertised through capabilities/v2.5 alongside v6)
 	// adds optional `eligible_untracked_inventory` and escalation metadata,
-	// so it is decoded on the v6 surface. v3 keeps rejecting every v5/v6/v7-only
-	// field.
+	// so it is decoded on the v6 surface. status/v8 (gentle-ai main, PR #4765;
+	// the current released contract) only extended the reviewer-result
+	// transition for OpenCode provider tasks -- no new top-level key -- so it
+	// decodes on the exact v7 surface too. status/v9 (the sibling gentle-ai
+	// branch's contract, ahead of the released v8) adds nothing at this top
+	// level either: its one addition is the host-mediated role `submission`
+	// on a next_transition.collect input (gentle-pi#311 P3), gated on v9 in
+	// decodeCollectInput, not here. v3 keeps rejecting every
+	// v5/v6/v7/v8/v9-only field.
 	const schema = typeof value === "object" && value !== null ? (value as Record<string, unknown>).schema : undefined;
-	const v7 = schema === "gentle-ai.review-integration.status/v7";
+	const v9 = schema === "gentle-ai.review-integration.status/v9";
+	const v8 = v9 || schema === "gentle-ai.review-integration.status/v8";
+	const v7 = v8 || schema === "gentle-ai.review-integration.status/v7";
 	const v6 = v7 || schema === "gentle-ai.review-integration.status/v6";
 	const v5 = v6 || schema === "gentle-ai.review-integration.status/v5";
 	const body = exactRecord(value, "status", [
 		"schema", "contract", "operation", "applicability", "action", "replayability", "target_identity", "projection", "repair", "candidates",
 	], ["authority", "frozen", "action_disposition", "eligibility", "next_transition", "authority_target_identity", ...(v5 ? ["receipt", "forecast", "repository_context", "validation_request"] : []), ...(v7 ? ["eligible_untracked_inventory", "escalation"] : [])]);
-	requireIdentity(body, v7 ? "gentle-ai.review-integration.status/v7" : v6 ? "gentle-ai.review-integration.status/v6" : v5 ? "gentle-ai.review-integration.status/v5" : "gentle-ai.review-integration.status/v3", REVIEW_INTEGRATION_OPERATION.STATUS);
+	requireIdentity(body, v9 ? "gentle-ai.review-integration.status/v9" : v8 ? "gentle-ai.review-integration.status/v8" : v7 ? "gentle-ai.review-integration.status/v7" : v6 ? "gentle-ai.review-integration.status/v6" : v5 ? "gentle-ai.review-integration.status/v5" : "gentle-ai.review-integration.status/v3", REVIEW_INTEGRATION_OPERATION.STATUS);
 
 	const applicability = enumeration(body.applicability, ["current_target", "unrelated", "ambiguous", "corrupted"] as const, "status.applicability");
 	let receipt: ReviewStatusReceiptV1 | undefined;
@@ -1982,7 +2069,7 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 	if (action === "recover" && actionDisposition === undefined) throw new TypeError("recover status requires action_disposition");
 	if (action !== "recover" && actionDisposition !== undefined) throw new TypeError("status.action_disposition is only valid for the recover action");
 	if (body.eligibility !== undefined) decodeEligibility(body.eligibility, "status.eligibility");
-	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition, { v5, v6 });
+	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition, { v5, v6, v9 });
 	const validationRequest = v5 && body.validation_request !== undefined
 		? decodeReviewTargetedValidationRequestV1(body.validation_request, "status.validation_request")
 		: undefined;

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 { allowanceGroupsSupported, groupUsageLimits, renderUsageBar, selectUsageLimit, type ProviderUsage } from "./shell-usage.ts";
+import { renderUsageBar, selectUsageLimit, type ProviderUsage, type UsageWindow } from "./shell-usage.ts";
 import { sanitizeTerminalText } from "./terminal-theme.ts";
 import { CARD_TONE, cardInnerWidth, renderCard } from "./shell-card.ts";
 
@@ -27,6 +27,43 @@ export interface ShellBarModel {
 	statuses: string[];
 }
 
+// The live header row above the fullscreen rail: session identity plus the
+// two counters that tick every frame (context, cost). Deliberately narrower
+// than ShellBarModel — extension statuses and the working/thinking state
+// never reach the header, so there is nothing on this type for them to leak
+// through.
+export interface ShellHeaderModel {
+	cwd: string;
+	branch: string | null;
+	dirty: number | undefined;
+	modelId: string;
+	effort: string | undefined;
+	profile?: string;
+	contextPercent: number | null;
+	costTotal: number;
+	subscription: boolean;
+	// The active provider's subscription usage, shown as its own segment after
+	// cost. Unlike the sidebar's old per-model usage table, this is one
+	// compact line — the same windows the compact bar already meters.
+	usage: ProviderUsage | undefined;
+}
+
+export function buildShellHeaderModel(model: ShellBarModel): ShellHeaderModel {
+	const { cwd, branch, dirty, modelId, effort, profile, contextPercent, costTotal, subscription, usage } = model;
+	return { cwd, branch, dirty, modelId, effort, profile, contextPercent, costTotal, subscription, usage };
+}
+
+/** A column span (`[start, end)`, in the rendered line's visible columns) a click must land in to hit the usage segment. */
+export interface HeaderUsageSpan {
+	start: number;
+	end: number;
+}
+
+export interface ShellHeaderResult {
+	text: string;
+	usageSpan?: HeaderUsageSpan;
+}
+
 export interface ShellBarTheme {
 	fg(color: string, text: string): string;
 	bold(text: string): string;
@@ -53,12 +90,6 @@ 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;
@@ -85,17 +116,36 @@ function sanitizeStatus(text: string): string {
 	return sanitizeTerminalText(text.replace(/[\r\n\t]/g, " ")).replace(/ +/g, " ").trim();
 }
 
-function buildSegments(model: ShellBarModel, theme: ShellBarTheme): string[] {
+// Shared by the compact bar, the sidebar Status card, and the fullscreen
+// header row, so the three surfaces never drift on how they paint the same
+// facts.
+function locationSegment(model: Pick<ShellBarModel, "cwd" | "branch" | "dirty">, theme: ShellBarTheme): string {
 	const dirty = model.dirty ? ` ${theme.fg(ROLE.DIRTY, `±${model.dirty}`)}` : "";
-	const location = model.branch
+	return model.branch
 		? `${theme.fg(ROLE.PATH, model.cwd)} ${theme.fg(ROLE.BRANCH, model.branch)}${dirty}`
 		: theme.fg(ROLE.PATH, model.cwd) + dirty;
-	const modelSegment = model.effort
-		? `${theme.fg(ROLE.MODEL, model.modelId)} ${theme.fg(ROLE.LABEL, "·")} ${theme.fg(ROLE.EFFORT, model.effort)}`
-		: theme.fg(ROLE.MODEL, model.modelId);
-	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));
+}
+
+function executionSegment(modelId: string, effort: string | undefined, theme: ShellBarTheme): string {
+	return effort
+		? `${theme.fg(ROLE.MODEL, modelId)} ${theme.fg(ROLE.LABEL, "·")} ${theme.fg(ROLE.EFFORT, effort)}`
+		: theme.fg(ROLE.MODEL, modelId);
+}
+
+function contextSegment(contextPercent: number | null, theme: ShellBarTheme): string {
+	const percentText = contextPercent === null ? "?%" : `${Math.round(contextPercent)}%`;
+	return `${theme.fg(ROLE.LABEL, "ctx")} ${paintGauge(contextPercent, theme)} ${theme.fg(ROLE.VALUE, percentText)}`;
+}
+
+function costSegment(costTotal: number, subscription: boolean, theme: ShellBarTheme): string {
+	return theme.fg(ROLE.VALUE, formatCost(costTotal, subscription));
+}
+
+function buildSegments(model: ShellBarModel, theme: ShellBarTheme): string[] {
+	const location = locationSegment(model, theme);
+	const modelSegment = executionSegment(model.modelId, model.effort, theme);
+	const context = contextSegment(model.contextPercent, theme);
+	const cost = costSegment(model.costTotal, model.subscription, theme);
 	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];
@@ -125,52 +175,6 @@ 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[] {
@@ -178,13 +182,14 @@ export function renderShellSidebarBar(model: ShellBarModel, theme: ShellBarTheme
 	const label = (text: string) => theme.fg(ROLE.LABEL, text);
 	const changes = model.changes;
 	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`);
 	// 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) : [];
+	// Model, effort, context, cost, and the per-model usage table now live in
+	// the always-visible header row (and /gentle:usage for the full table);
+	// this event-driven card keeps only what a footer/model-switch event does
+	// not already refresh every frame.
 	const groups: Array<{ title: string; lines: string[] }> = [
 		{
 			title: "Project",
@@ -192,8 +197,6 @@ export function renderShellSidebarBar(model: ShellBarModel, theme: ShellBarTheme
 				value(model.cwd),
 				...(branch ? [branch] : []),
 				...(model.sessionName ? [`${label("Session")} ${value(model.sessionName)}`] : []),
-				`${label("Model")} ${value(model.modelId)}`,
-				...(model.effort ? [`${label("Effort")} ${theme.fg(ROLE.EFFORT, model.effort)}`] : []),
 				...(model.profile ? [`${label("Profile")} ${value(sanitizeStatus(model.profile))}`] : []),
 			],
 		},
@@ -207,15 +210,6 @@ export function renderShellSidebarBar(model: ShellBarModel, theme: ShellBarTheme
 				label("/gentle:changes"),
 			],
 		},
-		{
-			title: "Usage",
-			lines: [
-				`${label("Context")} ${paintGauge(model.contextPercent, theme)} ${value(percent)}`,
-				capacity,
-				`${label("Cost")} ${value(formatCost(model.costTotal, model.subscription))}`,
-				...usageLines,
-			],
-		},
 		{ title: "Integrations", lines: model.statuses.length
 			? model.statuses.map((status) => theme.fg(ROLE.STATUS, sanitizeStatus(status)))
 			: [label("No status reported")] },
@@ -230,6 +224,100 @@ export function renderShellSidebarBar(model: ShellBarModel, theme: ShellBarTheme
 	return renderCard({ title: "Status", body, tone: CARD_TONE.INFO }, theme, width, { expanded: true });
 }
 
+const HEADER_BRAND = "✿ Gentle Shell";
+
+// Narrower than the width, widest first: dropping the profile, then the
+// effort, then the whole location keeps the brand and the bare model id
+// alive as long as anything can still share the row with the right-aligned
+// counters.
+function headerLeftStages(model: ShellHeaderModel, theme: ShellBarTheme): string[][] {
+	const brand = theme.fg(ROLE.BRAND, theme.bold(HEADER_BRAND));
+	const location = locationSegment(model, theme);
+	const withEffort = executionSegment(model.modelId, model.effort, theme);
+	const modelOnly = executionSegment(model.modelId, undefined, theme);
+	const withProfile = model.profile ? `${withEffort} ${theme.fg(ROLE.LABEL, "·")} ${theme.fg(ROLE.MODEL, sanitizeStatus(model.profile))}` : withEffort;
+	return [
+		[brand, location, withProfile],
+		[brand, location, withEffort],
+		[brand, location, modelOnly],
+		[brand, modelOnly],
+		[brand],
+	];
+}
+
+const USAGE_LABEL_ROLE = ROLE.LABEL;
+const USAGE_HINT_ROLE = "dim";
+
+function usageWindowText(window: UsageWindow, theme: ShellBarTheme, withGauge: boolean): string {
+	const percent = `${Math.round(window.usedPercent)}%`;
+	const parts = [
+		...(window.label.length > 0 ? [theme.fg(ROLE.LABEL, window.label)] : []),
+		...(withGauge ? [paintGauge(window.usedPercent, theme)] : []),
+		theme.fg(ROLE.VALUE, percent),
+	];
+	return parts.join(" ");
+}
+
+// Three degrading shapes for the same windows, narrowest last: every window
+// with its gauge, every window as text only, or just the first window as
+// text only. A provider with no usage data at all has no windows to shape,
+// so all three collapse to the bare "usage" label plus the shortcut hint.
+type UsageStage = "full" | "text" | "primary";
+function usageSegmentText(windows: UsageWindow[], theme: ShellBarTheme, stage: UsageStage, hint: string | undefined): string {
+	const label = theme.fg(USAGE_LABEL_ROLE, "usage");
+	const shown = stage === "primary" ? windows.slice(0, 1) : windows;
+	const body = shown.map((window) => usageWindowText(window, theme, stage === "full")).join(` ${theme.fg(ROLE.LABEL, "·")} `);
+	const head = body.length > 0 ? `${label} ${body}` : label;
+	return hint ? `${head} ${theme.fg(ROLE.LABEL, "·")} ${theme.fg(USAGE_HINT_ROLE, hint)}` : head;
+}
+
+export function renderShellHeaderBar(model: ShellHeaderModel, theme: ShellBarTheme, width: number, usageHint?: string): ShellHeaderResult {
+	const targetWidth = Math.max(0, Math.floor(width));
+	const ctxCost = joinSegments([contextSegment(model.contextPercent, theme), costSegment(model.costTotal, model.subscription, theme)], theme);
+	const windows = model.usage ? (selectUsageLimit(model.usage, model.modelId)?.windows ?? []) : [];
+	const leftStages = headerLeftStages(model, theme);
+	const minimalLeft = leftStages.length - 2; // brand + bare model id, before dropping the model too
+	// One flat, ordered cascade — never a per-stage nested search — so the
+	// left group fully degrades (profile → effort → location) before usage
+	// ever gives anything up, and usage fully degrades (gauges → secondary
+	// windows → the whole segment) before ctx/cost is touched: every window
+	// with its gauge, then text-only, then the first window only, then gone.
+	// Unlike the compact bar's usage meter (hidden with no data), this is a
+	// standing, clickable affordance — even with nothing to report it still
+	// reads "usage" plus the shortcut hint, unless disabled, width permitting.
+	const usageStages: Array<UsageStage | undefined> = ["full", "text", "primary", undefined];
+	const attempts: Array<{ leftIndex: number; usageStage: UsageStage | undefined }> = [
+		...leftStages.slice(0, minimalLeft).map((_, leftIndex) => ({ leftIndex, usageStage: "full" as UsageStage })),
+		...usageStages.map((usageStage) => ({ leftIndex: minimalLeft, usageStage })),
+		{ leftIndex: leftStages.length - 1, usageStage: undefined },
+	];
+	for (const { leftIndex, usageStage } of attempts) {
+		const usageText = usageStage ? usageSegmentText(windows, theme, usageStage, usageHint) : undefined;
+		const right = usageText ? joinSegments([ctxCost, usageText], theme) : ctxCost;
+		const left = joinSegments(leftStages[leftIndex]!, theme);
+		if (visibleWidth(left) + RIGHT_PADDING + visibleWidth(right) > targetWidth) continue;
+		const text = left + " ".repeat(targetWidth - visibleWidth(left) - visibleWidth(right)) + right;
+		if (!usageText) return { text };
+		const usageStart = visibleWidth(left) + (targetWidth - visibleWidth(left) - visibleWidth(right)) + visibleWidth(ctxCost) + visibleWidth(` ${SHELL_BAR_SEPARATOR} `);
+		return { text, usageSpan: { start: usageStart, end: usageStart + visibleWidth(usageText) } };
+	}
+	const brand = theme.fg(ROLE.BRAND, theme.bold(HEADER_BRAND));
+	return { text: visibleWidth(brand) <= targetWidth ? brand : "" };
+}
+
+// The rule row painted directly under the header bar: one full-width horizontal
+// line in the same theme role as the editor frame (PROMPT_FRAME_ROLE in
+// extensions/gentle-shell.ts), so the status row and the prompt read as one
+// panel. It exists only while the fullscreen sidebar is active — when the
+// sidebar is not shown the header rail never renders and the rule goes away
+// with it.
+const HEADER_RULE_CHAR = "─";
+const HEADER_RULE_ROLE = "border";
+
+export function renderShellHeaderRule(theme: ShellBarTheme, width: number): string {
+	return theme.fg(HEADER_RULE_ROLE, HEADER_RULE_CHAR.repeat(Math.max(0, Math.floor(width))));
+}
+
 export function renderShellBar(model: ShellBarModel, theme: ShellBarTheme, width: number): string[] {
 	let segments = buildSegments(model, theme);
 	const right = model.sessionName ? theme.fg(ROLE.SESSION, model.sessionName) : undefined;

package/lib/shell-card.ts

@@ -32,8 +32,18 @@ export interface CardRenderOptions {
 }
 
 export const CARD_GLYPH = "✿";
-const TONE_ROLE: Record<CardTone, string> = {
-	[CARD_TONE.INFO]: "customMessageLabel",
+// Frame and title paint with the same role for every tone except INFO, whose
+// rounded frame stays in the theme's plain border role while its title
+// carries the accent role — the rose look every informational card (sidebar,
+// review preflight, a quiet Agents widget, ...) uses.
+const FRAME_ROLE: Record<CardTone, string> = {
+	[CARD_TONE.INFO]: "border",
+	[CARD_TONE.SUCCESS]: "success",
+	[CARD_TONE.WARNING]: "warning",
+	[CARD_TONE.ERROR]: "error",
+};
+const TITLE_ROLE: Record<CardTone, string> = {
+	[CARD_TONE.INFO]: "accent",
 	[CARD_TONE.SUCCESS]: "success",
 	[CARD_TONE.WARNING]: "warning",
 	[CARD_TONE.ERROR]: "error",
@@ -51,8 +61,8 @@ function rule(length: number): string {
 function titleText(card: Card, theme: CardTheme): { styled: string; width: number } {
 	const head = `${card.glyph ?? CARD_GLYPH} ${card.title}`;
 	const styled = card.subtitle
-		? `${theme.fg(TONE_ROLE[card.tone], head)} ${theme.fg(SUBTITLE_ROLE, SEPARATOR)} ${theme.fg(SUBTITLE_ROLE, card.subtitle)}`
-		: theme.fg(TONE_ROLE[card.tone], head);
+		? `${theme.fg(TITLE_ROLE[card.tone], head)} ${theme.fg(SUBTITLE_ROLE, SEPARATOR)} ${theme.fg(SUBTITLE_ROLE, card.subtitle)}`
+		: theme.fg(TITLE_ROLE[card.tone], head);
 	return { styled, width: visibleWidth(head) + (card.subtitle ? visibleWidth(card.subtitle) + 3 : 0) };
 }
 
@@ -61,14 +71,14 @@ function bodyLines(card: Card, innerWidth: number): string[] {
 }
 
 function frame(theme: CardTheme, tone: CardTone, text: string): string {
-	return theme.fg(TONE_ROLE[tone], text);
+	return theme.fg(FRAME_ROLE[tone], text);
 }
 
 export function cardTop(card: Card, theme: CardTheme, width: number, hint?: string): string {
 	const targetWidth = Math.max(0, Math.floor(width));
 	if (targetWidth === 0) return "";
 	if (targetWidth < 5) {
-		const left = theme.fg(TONE_ROLE[card.tone], "╭");
+		const left = theme.fg(FRAME_ROLE[card.tone], "╭");
 		if (targetWidth === 1) return left;
 		return left + frame(theme, card.tone, `${rule(targetWidth - 2)}╮`);
 	}
@@ -82,13 +92,13 @@ export function cardTop(card: Card, theme: CardTheme, width: number, hint?: stri
 	const styledTitleWidth = title.width <= titleWidth ? title.width : visibleWidth(styledTitle);
 	const fill = rule(targetWidth - styledTitleWidth - 5 - hintWidth);
 	const tail = shownHint ? ` ${theme.fg(HINT_ROLE, shownHint)} ` : "";
-	return theme.fg(TONE_ROLE[card.tone], "╭") + frame(theme, card.tone, "─ ") + styledTitle + frame(theme, card.tone, ` ${fill}`) + tail + frame(theme, card.tone, "╮");
+	return theme.fg(FRAME_ROLE[card.tone], "╭") + frame(theme, card.tone, "─ ") + styledTitle + frame(theme, card.tone, ` ${fill}`) + tail + frame(theme, card.tone, "╮");
 }
 
 export function cardLine(text: string, tone: CardTone, theme: CardTheme, width: number): string {
 	const targetWidth = Math.max(0, Math.floor(width));
 	if (targetWidth === 0) return "";
-	const left = theme.fg(TONE_ROLE[tone], "│");
+	const left = theme.fg(FRAME_ROLE[tone], "│");
 	if (targetWidth === 1) return left;
 	if (targetWidth === 2) return left + frame(theme, tone, "│");
 	if (targetWidth === 3) return `${left} ${frame(theme, tone, "│")}`;
@@ -102,7 +112,7 @@ export function cardLine(text: string, tone: CardTone, theme: CardTheme, width:
 export function cardBottom(tone: CardTone, theme: CardTheme, width: number): string {
 	const targetWidth = Math.max(0, Math.floor(width));
 	if (targetWidth === 0) return "";
-	const left = theme.fg(TONE_ROLE[tone], "╰");
+	const left = theme.fg(FRAME_ROLE[tone], "╰");
 	if (targetWidth === 1) return left;
 	return left + frame(theme, tone, `${rule(targetWidth - 2)}╯`);
 }