gentle-pi 3.3.0 → 3.5.0

package/lib/questionnaire/validate.ts

@@ -0,0 +1,141 @@
+import {
+	CUSTOM_ROW_LABEL,
+	MAX_HEADER_LENGTH,
+	MAX_LABEL_LENGTH,
+	MAX_OPTIONS,
+	MAX_QUESTIONS,
+	MIN_OPTIONS,
+	type QuestionParams,
+} from "./schema.ts";
+
+/**
+ * A single questionnaire validation violation, keyed by `code` so callers can
+ * branch without parsing the human-readable message.
+ */
+export type QuestionnaireError =
+	| { code: "no_questions"; message: string }
+	| { code: "empty_options"; message: string; questionIndex: number }
+	| { code: "option_count"; message: string; questionIndex: number; count: number }
+	| { code: "too_many_questions"; message: string; count: number }
+	| { code: "duplicate_question"; message: string; questionIndex: number }
+	| { code: "duplicate_option_label"; message: string; questionIndex: number; optionIndex: number; label: string }
+	| { code: "label_too_long"; message: string; questionIndex: number; optionIndex: number; length: number }
+	| { code: "header_too_long"; message: string; questionIndex: number; length: number }
+	| { code: "reserved_label"; message: string; questionIndex: number; optionIndex: number; label: string };
+
+/**
+ * Validate questionnaire parameters and return the first violation in a fixed
+ * precedence order, or `undefined` when the parameters are valid.
+ *
+ * Precedence: no questions, empty options, option count, question count,
+ * duplicate question text, duplicate option label, label length, header
+ * length, then reserved custom-row labels.
+ */
+export function validateQuestionnaire(params: QuestionParams): QuestionnaireError | undefined {
+	const questions = Array.isArray(params?.questions) ? params.questions : [];
+
+	if (questions.length === 0) {
+		return { code: "no_questions", message: "At least one question is required." };
+	}
+
+	for (const [questionIndex, question] of questions.entries()) {
+		if (!Array.isArray(question?.options) || question.options.length === 0) {
+			return {
+				code: "empty_options",
+				message: `Question ${questionIndex + 1} must declare at least one option.`,
+				questionIndex,
+			};
+		}
+	}
+
+	for (const [questionIndex, question] of questions.entries()) {
+		const count = question.options.length;
+		if (count < MIN_OPTIONS || count > MAX_OPTIONS) {
+			return {
+				code: "option_count",
+				message: `Question ${questionIndex + 1} must have between ${MIN_OPTIONS} and ${MAX_OPTIONS} options, received ${count}.`,
+				questionIndex,
+				count,
+			};
+		}
+	}
+
+	if (questions.length > MAX_QUESTIONS) {
+		return {
+			code: "too_many_questions",
+			message: `A questionnaire accepts at most ${MAX_QUESTIONS} questions, received ${questions.length}.`,
+			count: questions.length,
+		};
+	}
+
+	const seenQuestions = new Set<string>();
+	for (const [questionIndex, question] of questions.entries()) {
+		if (seenQuestions.has(question.question)) {
+			return {
+				code: "duplicate_question",
+				message: `Question ${questionIndex + 1} duplicates an earlier question text.`,
+				questionIndex,
+			};
+		}
+		seenQuestions.add(question.question);
+	}
+
+	// Checked after duplicate questions so a repeated question points at the
+	// duplicate itself rather than one of its option labels.
+	for (const [questionIndex, question] of questions.entries()) {
+		const seenLabels = new Set<string>();
+		for (const [optionIndex, option] of question.options.entries()) {
+			if (seenLabels.has(option.label)) {
+				return {
+					code: "duplicate_option_label",
+					message: `Question ${questionIndex + 1} option ${optionIndex + 1} duplicates the label "${option.label}".`,
+					questionIndex,
+					optionIndex,
+					label: option.label,
+				};
+			}
+			seenLabels.add(option.label);
+		}
+	}
+
+	for (const [questionIndex, question] of questions.entries()) {
+		for (const [optionIndex, option] of question.options.entries()) {
+			if (option.label.length > MAX_LABEL_LENGTH) {
+				return {
+					code: "label_too_long",
+					message: `Question ${questionIndex + 1} option ${optionIndex + 1} label exceeds ${MAX_LABEL_LENGTH} characters.`,
+					questionIndex,
+					optionIndex,
+					length: option.label.length,
+				};
+			}
+		}
+	}
+
+	for (const [questionIndex, question] of questions.entries()) {
+		if (question.header.length > MAX_HEADER_LENGTH) {
+			return {
+				code: "header_too_long",
+				message: `Question ${questionIndex + 1} header exceeds ${MAX_HEADER_LENGTH} characters.`,
+				questionIndex,
+				length: question.header.length,
+			};
+		}
+	}
+
+	for (const [questionIndex, question] of questions.entries()) {
+		for (const [optionIndex, option] of question.options.entries()) {
+			if (option.label === "Other" || option.label === CUSTOM_ROW_LABEL) {
+				return {
+					code: "reserved_label",
+					message: `Question ${questionIndex + 1} option ${optionIndex + 1} uses the reserved label "${option.label}".`,
+					questionIndex,
+					optionIndex,
+					label: option.label,
+				};
+			}
+		}
+	}
+
+	return undefined;
+}

package/lib/review-candidate-view-owner.ts

@@ -27,6 +27,21 @@ const WINDOWS_SYSTEM = "S-1-5-18";
 const WINDOWS_ADMINISTRATORS = "S-1-5-32-544";
 const WINDOWS_SYSTEM_DIRECTORY = "\\\\?\\GLOBALROOT\\SystemRoot\\System32";
 
+// Cold Windows runners occasionally exceed the bounded 5-second probe timeout
+// on first process start (whoami/PowerShell/icacls). One bounded retry of an
+// idempotent system probe recovers that transient; authority validation is
+// never retried or weakened because it happens after the probe returns.
+const TRANSIENT_WINDOWS_PROBE_CODES = new Set(["ETIMEDOUT", "EAGAIN", "EBUSY"]);
+
+export function withWindowsSystemProbeRetry<T>(probe: () => T): T {
+	try {
+		return probe();
+	} catch (error) {
+		if (!TRANSIENT_WINDOWS_PROBE_CODES.has((error as NodeJS.ErrnoException | undefined)?.code ?? "")) throw error;
+		return probe();
+	}
+}
+
 function windowsSystemExecutable(name: "whoami.exe" | "icacls.exe" | "WindowsPowerShell\\v1.0\\powershell.exe"): string {
 	try {
 		return realpathSync.native(join(WINDOWS_SYSTEM_DIRECTORY, name));
@@ -36,7 +51,7 @@ function windowsSystemExecutable(name: "whoami.exe" | "icacls.exe" | "WindowsPow
 }
 
 function windowsUserSid(): string {
-	const output = execFileSync(windowsSystemExecutable("whoami.exe"), ["/user", "/fo", "csv", "/nh"], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+	const output = withWindowsSystemProbeRetry(() => execFileSync(windowsSystemExecutable("whoami.exe"), ["/user", "/fo", "csv", "/nh"], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"], windowsHide: true }));
 	const matches = output.match(/S-\d+(?:-\d+)+/gi) ?? [];
 	if (matches.length !== 1) throw new Error("Windows user SID is unavailable");
 	return matches[0]!.toUpperCase();
@@ -45,7 +60,7 @@ function windowsUserSid(): string {
 function windowsLocalAdministratorSid(): string {
 	const script = "$ErrorActionPreference='Stop';$descriptor=New-Object System.Security.AccessControl.RawSecurityDescriptor 'D:(A;;FA;;;LA)';$descriptor.DiscretionaryAcl[0].SecurityIdentifier.Value";
 	const systemRoot = dirname(dirname(windowsSystemExecutable("whoami.exe")));
-	const output = execFileSync(windowsSystemExecutable("WindowsPowerShell\\v1.0\\powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, env: { ...process.env, SystemRoot: systemRoot } });
+	const output = withWindowsSystemProbeRetry(() => execFileSync(windowsSystemExecutable("WindowsPowerShell\\v1.0\\powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, env: { ...process.env, SystemRoot: systemRoot } }));
 	const matches = output.match(/S-\d+(?:-\d+)+/gi) ?? [];
 	if (matches.length !== 1 || !isWindowsSid(matches[0]!)) throw new Error("Windows local Administrator SID is unavailable");
 	return matches[0]!.toUpperCase();
@@ -55,7 +70,7 @@ function windowsDacl(path: string): string {
 	const archive = `.gentle-ai-acl-${randomUUID()}.txt`;
 	const archivePath = join(dirname(path), archive);
 	try {
-		execFileSync(windowsSystemExecutable("icacls.exe"), [path, "/save", archive, "/c"], { cwd: dirname(path), encoding: "utf8", timeout: 5000, maxBuffer: 16384, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+		withWindowsSystemProbeRetry(() => execFileSync(windowsSystemExecutable("icacls.exe"), [path, "/save", archive, "/c"], { cwd: dirname(path), encoding: "utf8", timeout: 5000, maxBuffer: 16384, stdio: ["ignore", "pipe", "pipe"], windowsHide: true }));
 		const sddl = readFileSync(archivePath, "utf16le").match(/D:[^\r\n]+/)?.[0];
 		if (sddl === undefined) throw new Error("Windows DACL is unavailable");
 		return sddl;
@@ -151,7 +166,7 @@ function windowsOwnerSid(path: string, kind: WindowsObjectKind): string {
 	const systemRoot = dirname(dirname(windowsSystemExecutable("whoami.exe")));
 	let output: string;
 	try {
-		output = execFileSync(windowsSystemExecutable("WindowsPowerShell\\v1.0\\powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, env: { ...process.env, SystemRoot: systemRoot, GENTLE_PI_CANDIDATE_OWNER_PATH: path } });
+		output = withWindowsSystemProbeRetry(() => execFileSync(windowsSystemExecutable("WindowsPowerShell\\v1.0\\powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, env: { ...process.env, SystemRoot: systemRoot, GENTLE_PI_CANDIDATE_OWNER_PATH: path } }));
 	} catch {
 		throw new WindowsOwnerValidationError();
 	}
@@ -175,7 +190,7 @@ function enforcePrivateWindowsDacl(path: string, identity: WindowsAclIdentity =
 	const sddl = `D:P(A;OICI;FA;;;${user})(A;OICI;FA;;;${WINDOWS_SYSTEM})(A;OICI;FA;;;${WINDOWS_ADMINISTRATORS})`;
 	const script = "$ErrorActionPreference='Stop';$acl=New-Object System.Security.AccessControl.DirectorySecurity;$acl.SetSecurityDescriptorSddlForm($env:GENTLE_PI_CANDIDATE_ACL_SDDL,[System.Security.AccessControl.AccessControlSections]::Access);[System.IO.Directory]::SetAccessControl($env:GENTLE_PI_CANDIDATE_ACL_PATH,$acl)";
 	const systemRoot = dirname(dirname(windowsSystemExecutable("whoami.exe")));
-	execFileSync(windowsSystemExecutable("WindowsPowerShell\\v1.0\\powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { encoding: "utf8", timeout: 5000, maxBuffer: 16384, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, env: { ...process.env, SystemRoot: systemRoot, GENTLE_PI_CANDIDATE_ACL_PATH: path, GENTLE_PI_CANDIDATE_ACL_SDDL: sddl } });
+	withWindowsSystemProbeRetry(() => execFileSync(windowsSystemExecutable("WindowsPowerShell\\v1.0\\powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { encoding: "utf8", timeout: 5000, maxBuffer: 16384, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, env: { ...process.env, SystemRoot: systemRoot, GENTLE_PI_CANDIDATE_ACL_PATH: path, GENTLE_PI_CANDIDATE_ACL_SDDL: sddl } }));
 	assertPrivateWindowsDacl(path, "directory", true, identity);
 }
 

package/lib/review-candidate-view.ts

@@ -634,6 +634,13 @@ function makeWritableForCleanup(path: string): void {
 	chmodSync(path, 0o644);
 }
 
+function candidateOwnerPreparationError(error: unknown): CandidateViewError {
+	// Surface the bounded errno of the underlying failure directly in the
+	// message so CI logs are self-diagnosing without TAP printing the cause.
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return new CandidateViewError(`candidate view owner preparation failed${typeof code === "string" && code ? ` (${code})` : ""}`, "candidate-owner-preparation-failed", undefined, { cause: error });
+}
+
 function candidateViewParent(commonDir: string, platform: NodeJS.Platform): string {
 	const control = join(commonDir, "gentle-ai");
 	mkdirSync(control, { recursive: true, mode: 0o700 });
@@ -646,7 +653,7 @@ function candidateViewParent(commonDir: string, platform: NodeJS.Platform): stri
 	try {
 		return prepareCandidateOwnerParent(commonDir, platform);
 	} catch (error) {
-		throw new CandidateViewError("candidate view owner preparation failed", "candidate-owner-preparation-failed", undefined, { cause: error });
+		throw candidateOwnerPreparationError(error);
 	}
 }
 
@@ -916,7 +923,7 @@ function materializeCandidateView(request: CreateCandidateViewRequest, executor:
 		try {
 			owner = createCandidateOwner(canonicalCommonDir, root, platform);
 		} catch (error) {
-			throw new CandidateViewError("candidate view owner preparation failed", "candidate-owner-preparation-failed", undefined, { cause: error });
+			throw candidateOwnerPreparationError(error);
 		}
 		// The worktree is created under the same try/catch cleanup boundary as
 		// the read-tree materialization that follows. addUnbornWorktree's

package/lib/review-host-relay.ts

@@ -386,6 +386,14 @@ export interface ReviewHostRelayRequest {
 	readonly selection?: string;
 	/** The routing entry's thinking label, forwarded verbatim to the completion. */
 	readonly thinking?: string;
+	/**
+	 * The caller's live pi session id, forwarded into the in-process completion
+	 * request so an OpenCode-routed reviewer model carries its
+	 * `x-opencode-session` attribution header (a side-call bypasses pi's main
+	 * agent loop, where pi adds those headers itself). Absent forwards nothing:
+	 * no invented header, no error.
+	 */
+	readonly reviewerSessionId?: string;
 	/** Names the routing config key (e.g. "review-risk") in refusal messages; defaults to a generic label when absent. */
 	readonly routingKey?: string;
 	/**
@@ -608,6 +616,7 @@ function validateReviewerSelectionConfiguration(request: ReviewHostRelayRequest)
 		reviewerRegistry: request.reviewerRegistry,
 		selection: request.selection,
 		...(request.thinking === undefined ? {} : { thinking: request.thinking }),
+		...(request.reviewerSessionId === undefined ? {} : { reviewerSessionId: request.reviewerSessionId }),
 		routingKey,
 	};
 }
@@ -728,6 +737,7 @@ export async function prepareReviewHostRelaySlot(
 			{
 				selection: preparedRequest.selection!,
 				...(preparedRequest.thinking === undefined ? {} : { thinking: preparedRequest.thinking }),
+				...(preparedRequest.reviewerSessionId === undefined ? {} : { sessionId: preparedRequest.reviewerSessionId }),
 				prompt: promptBytes,
 				timeoutMs: piTimeoutMs,
 				...(preparedRequest.signal === undefined ? {} : { signal: preparedRequest.signal }),

package/lib/review-integration-v2.ts

@@ -310,6 +310,7 @@ export interface ChangedPathEntry {
 	readonly typeChanged: boolean;
 	readonly modeOnly: boolean;
 	readonly intendedUntracked: boolean;
+	readonly generated?: true;
 }
 
 export interface ReviewArtifactSubjectV2 {
@@ -1150,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`),
@@ -1160,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 }),
 	};
 }
 

package/lib/rpc-host.ts

@@ -0,0 +1,36 @@
+// Interactive RPC host signal: the desktop app sets this environment variable
+// on the pi process it spawns directly (`--mode rpc`), letting Gentle answer
+// ask-user tools through pi's RPC dialogs and publish live subagent state.
+// `lib/agents-runner.ts` strips it from every subagent child env so headless
+// RPC children never see it and stay unaffected by this feature.
+
+/** Environment variable the desktop app sets on its own interactive pi process. */
+export const INTERACTIVE_HOST_ENV = "GENTLE_SHELL_INTERACTIVE_HOST";
+
+/**
+ * True only when running under `--mode rpc` with the interactive host
+ * variable set to exactly `"1"`. Any other value, or its absence, keeps RPC
+ * headless (the existing subagent behaviour).
+ */
+export function isInteractiveRpcHost(mode: string, env: NodeJS.ProcessEnv = process.env): boolean {
+	return mode === "rpc" && env[INTERACTIVE_HOST_ENV] === "1";
+}
+
+/**
+ * True for the interactive TUI, or for an interactive RPC host. Extensions
+ * use this to offer dialog-capable behaviour without special-casing RPC.
+ */
+export function isInteractiveMode(mode: string, env: NodeJS.ProcessEnv = process.env): boolean {
+	return mode === "tui" || isInteractiveRpcHost(mode, env);
+}
+
+/**
+ * Copy of `env` with the interactive host variable removed. Used when
+ * assembling a subagent child's environment so it never inherits the
+ * parent's interactive-host signal, even when the parent itself is one.
+ */
+export function withoutInteractiveHost(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+	const next = { ...env };
+	delete next[INTERACTIVE_HOST_ENV];
+	return next;
+}

package/lib/shell-bar.ts

@@ -305,6 +305,19 @@ export function renderShellHeaderBar(model: ShellHeaderModel, theme: ShellBarThe
 	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-sidebar-layout.ts

@@ -68,6 +68,7 @@ function railDigest(rail: SidebarRail): string | undefined {
 	}
 }
 
+/** Installs the fullscreen rail: wraps the host layout root with the [rail, transcript] hstack and returns a disposer restoring the original layout. */
 export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 	if (!tui.terminal) return () => {};
 	const host = tui as Host;
@@ -96,8 +97,10 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 			for (const part of state.parts.values()) part.invalidate();
 		},
 	};
-	// The header row: a plain leaf component, one line tall, painted above the
-	// hstack when a "header" part is registered and has something to show.
+	// The header row: a plain leaf component measured from its rendered lines
+	// (one line with just the status bar; two once the rule row joins it),
+	// painted full-width above the hstack when a "header" part is registered
+	// and has something to show.
 	// The header is not inside the rail's ScrollView, so it never goes through
 	// dispatchPartMouse: it is its own leaf in the layout tree (no [NODE]),
 	// and pi-tui's mouse dispatch (tui-alt-screen.js dispatchMouseToLayout)
@@ -113,7 +116,10 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 		follow: "none",
 		primary: false,
 		overscroll: "contain",
-		scrollbar: "always",
+		// "always" re-slices the scrollbar column of every rail line on every
+		// render pass (grapheme measurement per row). "auto" keeps the rail
+		// scrollbar transient like pi's own fullscreen scrollbar.
+		scrollbar: "auto",
 		scrollbarTrackStyle: (text) => theme.fg("border", text),
 		scrollbarThumbStyle: (text) => theme.fg("accent", text),
 	});
@@ -277,7 +283,7 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 				if (current.presentation?.scrollTop === scroll.scrollTop) return current.presentation.output;
 				const output: LayoutNode = current.headerActive
 					? { type: "vstack", gap: 0, align: "stretch", entries: [
-						{ component: header, basis: 1, grow: 0, shrink: 0, minSize: 1 },
+						{ component: header, basis: "auto", grow: 0, shrink: 0, minSize: 1 },
 						{ component: hstackHost, basis: 0, grow: 1, shrink: 1, minSize: 1 },
 					] }
 					: hstackHost[NODE]();

package/lib/shell-usage-view.ts

@@ -1,5 +1,5 @@
 import { Key, matchesKey, truncateToWidth, visibleWidth, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
-import { renderUsagePanel, type ActiveProvider, type UsageStore, type UsageTheme } from "./shell-usage.ts";
+import { renderUsagePanel, type ActiveProvider, type UsageSourceRegistry, type UsageStore, type UsageTheme } from "./shell-usage.ts";
 import { paintHoverable } from "./shell-hover.ts";
 
 // Gentle Shell subscriptions overlay: a framed panel over the usage store.
@@ -9,6 +9,9 @@ export interface UsageViewDeps {
 	theme: UsageTheme;
 	now(): number;
 	active(): ActiveProvider | undefined;
+	// Optional: lets the panel resolve the pending note of a provider whose
+	// usage source was registered at runtime instead of built in.
+	registry?(): UsageSourceRegistry | undefined;
 	onRefresh(): Promise<void>;
 	onClose(): void;
 	requestRender(): void;
@@ -98,7 +101,7 @@ export class UsageView {
 		const inner = width - 2;
 		const title = this.refreshing ? REFRESHING : TITLE;
 		const top = theme.fg(FRAME_ROLE, "╭─ ") + theme.fg(TITLE_ROLE, title) + theme.fg(FRAME_ROLE, ` ${rule(inner - visibleWidth(title) - 3)}╮`);
-		const body = renderUsagePanel(this.store.all(), theme, inner - 2, this.deps.now(), this.deps.active()).map(
+		const body = renderUsagePanel(this.store.all(), theme, inner - 2, this.deps.now(), this.deps.active(), this.deps.registry?.()).map(
 			(line) => `${theme.fg(FRAME_ROLE, "│")} ${fit(line, inner - 2)} ${theme.fg(FRAME_ROLE, "│")}`,
 		);
 		const hints = KEYS.map(([key, label]) => ({ key, label, text: `${key} ${label}`, action: (key === "r" ? "refresh" : "close") as HintAction }));

package/lib/shell-usage.ts

@@ -117,9 +117,10 @@ const ROLE = {
 } 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, NAN_PROVIDER];
+const DEFAULT_PENDING_NOTE = "no usage yet · r to fetch";
 const PENDING_NOTE: Record<string, string> = {
-	[CODEX_PROVIDER]: "no usage yet · r to fetch",
-	[NAN_PROVIDER]: "no usage yet · r to fetch",
+	[CODEX_PROVIDER]: DEFAULT_PENDING_NOTE,
+	[NAN_PROVIDER]: DEFAULT_PENDING_NOTE,
 	[ANTHROPIC_PROVIDER]: "usage arrives with the first response",
 };
 const UNSUPPORTED_NOTE = "no subscription usage for this provider";
@@ -129,8 +130,121 @@ export interface ActiveProvider {
 	provider: string;
 }
 
-export function providerNote(provider: string): string {
-	return PENDING_NOTE[provider] ?? UNSUPPORTED_NOTE;
+// A generic hook so an extension holding its own provider (its own API token,
+// its own usage endpoint) can plug a usage source into the shell without the
+// shell ever knowing that provider's name. Emitted on `pi.events` as payload
+// under `USAGE_SOURCE_EVENT`; gentle-shell validates the shape below and
+// ignores anything else, so a malformed or foreign event never reaches a
+// fetch call. Re-registration for the same provider replaces the previous
+// source, so a second `session_start` emitting the same payload is a no-op
+// in effect, not an accumulation.
+export const USAGE_SOURCE_EVENT = "gentle-pi:usage-source/v1";
+export const USAGE_SOURCE_SCHEMA = "gentle-pi.usage-source/v1";
+const USAGE_SOURCE_PROVIDER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export interface UsageSource {
+	schema: typeof USAGE_SOURCE_SCHEMA;
+	provider: string;
+	pendingNote?: string;
+	fetch(apiKey: string | undefined, fetchFn: typeof fetch, now: number): Promise<ProviderUsage | undefined>;
+}
+
+// Pure and defensive: the payload crosses an event bus from another
+// extension, so nothing here is trusted until every field is checked. Any
+// mismatch returns undefined rather than throwing, exactly like the other
+// payload parsers in this file.
+export function parseUsageSource(value: unknown): UsageSource | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const raw = value as Record<string, unknown>;
+	if (raw.schema !== USAGE_SOURCE_SCHEMA) return undefined;
+	if (typeof raw.provider !== "string" || !USAGE_SOURCE_PROVIDER_PATTERN.test(raw.provider)) return undefined;
+	if (typeof raw.fetch !== "function") return undefined;
+	if (raw.pendingNote !== undefined && typeof raw.pendingNote !== "string") return undefined;
+	const source: UsageSource = { schema: USAGE_SOURCE_SCHEMA, provider: raw.provider, fetch: raw.fetch as UsageSource["fetch"] };
+	if (typeof raw.pendingNote === "string") source.pendingNote = raw.pendingNote;
+	return source;
+}
+
+// One source per provider, most recent registration wins. Nothing here fetches
+// or touches the network; it only remembers who to ask.
+export class UsageSourceRegistry {
+	private readonly sources = new Map<string, UsageSource>();
+
+	register(source: UsageSource): void {
+		this.sources.set(source.provider, source);
+	}
+
+	get(provider: string): UsageSource | undefined {
+		return this.sources.get(provider);
+	}
+
+	has(provider: string): boolean {
+		return this.sources.has(provider);
+	}
+
+	note(provider: string): string | undefined {
+		const source = this.sources.get(provider);
+		return source ? (source.pendingNote ?? DEFAULT_PENDING_NOTE) : undefined;
+	}
+}
+
+export function providerNote(provider: string, registry?: UsageSourceRegistry): string {
+	return PENDING_NOTE[provider] ?? registry?.note(provider) ?? UNSUPPORTED_NOTE;
+}
+
+function isFiniteNumber(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value);
+}
+
+function parseSourceUsageWindow(value: unknown): UsageWindow | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const raw = value as Record<string, unknown>;
+	if (typeof raw.label !== "string") return undefined;
+	if (!isFiniteNumber(raw.usedPercent)) return undefined;
+	if (!isFiniteNumber(raw.windowSeconds)) return undefined;
+	if (raw.resetAt !== null && !isFiniteNumber(raw.resetAt)) return undefined;
+	if (raw.used !== undefined && !isFiniteNumber(raw.used)) return undefined;
+	if (raw.budget !== undefined && !isFiniteNumber(raw.budget)) return undefined;
+	const window: UsageWindow = { label: raw.label, usedPercent: raw.usedPercent, windowSeconds: raw.windowSeconds, resetAt: raw.resetAt as number | null };
+	if (raw.used !== undefined) window.used = raw.used as number;
+	if (raw.budget !== undefined) window.budget = raw.budget as number;
+	return window;
+}
+
+function parseSourceUsageLimit(value: unknown): UsageLimit | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const raw = value as Record<string, unknown>;
+	if (typeof raw.name !== "string") return undefined;
+	if (typeof raw.limitReached !== "boolean") return undefined;
+	if (!Array.isArray(raw.windows)) return undefined;
+	const windows: UsageWindow[] = [];
+	for (const entry of raw.windows) {
+		const window = parseSourceUsageWindow(entry);
+		if (!window) return undefined;
+		windows.push(window);
+	}
+	return { name: raw.name, limitReached: raw.limitReached, windows };
+}
+
+// A registered source's resolved value crosses the same trust boundary a
+// parsed HTTP payload does: it is foreign code's own object, so it is
+// validated field by field and never recorded by reference. Every accepted
+// shape is rebuilt from scratch, so a source mutating its own object after
+// returning it can never reach a snapshot gentle-shell already recorded.
+export function parseProviderUsage(value: unknown, expectedProvider: string): ProviderUsage | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const raw = value as Record<string, unknown>;
+	if (raw.provider !== expectedProvider) return undefined;
+	if (raw.plan !== undefined && typeof raw.plan !== "string") return undefined;
+	if (!isFiniteNumber(raw.fetchedAt)) return undefined;
+	if (!Array.isArray(raw.limits)) return undefined;
+	const limits: UsageLimit[] = [];
+	for (const entry of raw.limits) {
+		const limit = parseSourceUsageLimit(entry);
+		if (!limit) return undefined;
+		limits.push(limit);
+	}
+	return { provider: raw.provider, plan: typeof raw.plan === "string" ? raw.plan : undefined, limits, fetchedAt: raw.fetchedAt };
 }
 
 export function windowLabel(seconds: number): string {
@@ -415,13 +529,13 @@ function updatedAgo(fetchedAt: number, now: number): string {
 
 // The active provider comes first, marked with the petal, and explains
 // itself when it has no data yet. Other providers seen this session follow.
-export function renderUsagePanel(usages: ProviderUsage[], theme: UsageTheme, width: number, now: number, active?: ActiveProvider): string[] {
+export function renderUsagePanel(usages: ProviderUsage[], theme: UsageTheme, width: number, now: number, active?: ActiveProvider, registry?: UsageSourceRegistry): string[] {
 	const activeUsage = active ? usages.find((usage) => usage.provider === active.provider) : undefined;
 	const others = usages.filter((usage) => usage !== activeUsage);
 	if (!active && usages.length === 0) return [truncateToWidth(USAGE_EMPTY_MESSAGE, width, "…")];
 	const lines: string[] = [];
 	if (active && !activeUsage) {
-		lines.push(`${theme.fg(ROLE.LIMIT, ACTIVE_MARK)} ${theme.fg(ROLE.PROVIDER, active.provider)} ${theme.fg(ROLE.SEPARATOR, "·")} ${theme.fg(ROLE.RESET, providerNote(active.provider))}`);
+		lines.push(`${theme.fg(ROLE.LIMIT, ACTIVE_MARK)} ${theme.fg(ROLE.PROVIDER, active.provider)} ${theme.fg(ROLE.SEPARATOR, "·")} ${theme.fg(ROLE.RESET, providerNote(active.provider, registry))}`);
 	}
 	for (const usage of [...(activeUsage ? [activeUsage] : []), ...others]) {
 		const mark = usage === activeUsage ? `${theme.fg(ROLE.LIMIT, ACTIVE_MARK)} ` : "";

package/package.json

@@ -1,9 +1,12 @@
 {
 	"name": "gentle-pi",
-	"version": "3.3.0",
+	"version": "3.5.0",
 	"description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
 	"license": "MIT",
 	"type": "module",
+	"bin": {
+		"gentle-shell": "bin/gentle-shell.mjs"
+	},
 	"keywords": [
 		"pi-package",
 		"pi",
@@ -24,6 +27,7 @@
 	},
 	"files": [
 		"assets/",
+		"bin/",
 		"contracts/",
 		"docs/",
 		"extensions/",