gentle-pi 4.0.0 → 4.2.0

package/lib/status-timing-diagnostics.ts

@@ -0,0 +1,201 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "typebox";
+
+const MAX_STATUSES = 8;
+const MAX_ACTIVE_OBSERVATIONS = 8;
+type Outcome = { kind: "success" | "cli_error" | "native_failure" | "unknown"; code?: string; phase?: string; mutation_outcome?: string; retry_safe?: boolean; next_action?: string };
+interface StatusSample {
+	timeout_ms: number;
+	total_ms: number;
+	resolution_ms: number;
+	adapter_ms: number;
+	decode_ms: number;
+	outcome: Outcome;
+}
+interface Summary {
+	schema: "gentle-pi.status-timing/v1";
+	host_total_ms: number;
+	dispatch_ms: number;
+	sidebar_ms: number;
+	completion_ms: number;
+	truncated: boolean;
+	clock_unavailable?: true;
+	statuses: StatusSample[];
+}
+interface HostObservation {
+	clock: () => number;
+	current: () => boolean;
+	claim: () => boolean;
+	claimed: boolean;
+	started: number;
+	lastNativeEnd: number;
+	summary: Summary;
+}
+interface NativeObservation { host: HostObservation; sample: StatusSample; }
+const hostScope = new AsyncLocalStorage<HostObservation>();
+const nativeScope = new AsyncLocalStorage<NativeObservation>();
+
+// Observer failures must never replace the operation's result or exception.
+function safely<T>(run: () => T): T | undefined {
+	try { return run(); } catch { return undefined; }
+}
+function now(host: HostObservation): number {
+	const value = safely(host.clock);
+	if (value !== undefined && Number.isFinite(value) && value >= 0) return value;
+	host.summary.clock_unavailable = true;
+	return 0;
+}
+function elapsed(start: number, end: number): number { return Math.max(0, end - start); }
+
+// Failure/v2 codes and next_action are extensible strings, not safe diagnostic
+// text. Only recognized values enter this summary; no messages or raw envelopes.
+const CLI_CODES = new Set(["unavailable", "timeout", "non-zero", "signal", "unexpected-stderr", "output-limit", "empty-output", "malformed-json", "schema-incompatible", "identity-mismatch", "version-incompatible", "cancelled", "package-local-binary-missing", "unsupported-transition-operation"]);
+const NATIVE_CODES = new Set(["operation_timeout", "invalid_request", "binding_revision_conflict", "internal_error", "cancelled"]);
+function outcome(error: unknown): Outcome {
+	return safely((): Outcome => {
+		if (typeof error !== "object" || error === null) return { kind: "unknown" };
+		const value = error as { name?: unknown; code?: unknown; failureEnvelope?: Record<string, unknown> };
+		if (value.name === "NativeReviewCliError") return { kind: "cli_error", code: typeof value.code === "string" && CLI_CODES.has(value.code) ? value.code : "other" };
+		if (value.name !== "NativeReviewIntegrationError" || !value.failureEnvelope) return { kind: "unknown" };
+		const failure = value.failureEnvelope;
+		const result: Outcome = { kind: "native_failure", code: typeof failure.code === "string" && NATIVE_CODES.has(failure.code) ? failure.code : "other" };
+		if (["preflight", "pre_native", "native_running", "native_committed", "reconciliation"].includes(String(failure.phase))) result.phase = String(failure.phase);
+		if (["not_started", "committed", "unknown"].includes(String(failure.mutationOutcome))) result.mutation_outcome = String(failure.mutationOutcome);
+		if (typeof failure.retrySafe === "boolean") result.retry_safe = failure.retrySafe;
+		if (["stop", "review.status"].includes(String(failure.nextAction))) result.next_action = String(failure.nextAction);
+		return result;
+	}) ?? { kind: "unknown" };
+}
+
+/** The next already-authorized STATUS-bearing tool call consumes the arm. */
+export class StatusTimingDiagnostics {
+	private armed = false;
+	private epoch = 0;
+	private manager: ExtensionContext["sessionManager"] | undefined;
+	private session: string | undefined;
+	private last: Summary | undefined;
+	private readonly active = new Set<HostObservation>();
+	private readonly clock: () => number;
+	constructor(clock = () => performance.now()) { this.clock = clock; }
+
+	reset(ctx?: ExtensionContext): void {
+		this.epoch++;
+		this.armed = false;
+		this.last = undefined;
+		for (const host of this.active) host.summary.statuses.length = 0;
+		this.active.clear();
+		this.manager = ctx?.sessionManager;
+		this.session = safely(() => ctx?.sessionManager.getSessionId());
+	}
+	private matches(ctx: ExtensionContext): boolean {
+		return safely(() => this.manager === ctx.sessionManager && !!this.session && this.session === ctx.sessionManager.getSessionId()) === true;
+	}
+	command(args: string, ctx: ExtensionContext): void {
+		if (!this.matches(ctx)) this.reset(ctx);
+		const action = args.trim() || "show";
+		if (action === "enable") {
+			this.reset(ctx);
+			this.armed = !!this.session;
+			ctx.ui.notify(this.armed
+				? "STATUS timing armed for the next separately authorized STATUS-bearing tool call. No STATUS is invoked or retried. Use /gentle:status-timing show to consult the completed summary."
+				: "STATUS timing requires a live session.", "info");
+		} else if (action === "disable") {
+			this.reset(ctx);
+			ctx.ui.notify("STATUS timing disabled; in-memory observations cleared.", "info");
+		} else if (action === "show") {
+			ctx.ui.notify(this.last ? JSON.stringify(this.last, null, 2) : `No completed STATUS timing summary. Diagnostic is ${this.armed ? "armed" : "off"}.`, "info");
+		} else {
+			ctx.ui.notify("Unknown /gentle:status-timing sub-action. Use enable, disable, or show.", "warning");
+		}
+	}
+	tool<TParams extends TSchema, TDetails>(definition: ToolDefinition<TParams, TDetails>): ToolDefinition<TParams, TDetails> {
+		return {
+			...definition,
+			execute: async (toolCallId, params, signal, onUpdate, ctx) => {
+				const run = () => definition.execute(toolCallId, params, signal, onUpdate, ctx);
+				if (!this.matches(ctx)) this.reset(ctx);
+				if (!this.armed || this.active.size >= MAX_ACTIVE_OBSERVATIONS) return run();
+				const epoch = this.epoch;
+				const host: HostObservation = {
+					clock: this.clock,
+					current: () => this.epoch === epoch && this.matches(ctx),
+					claim: () => {
+						if (!host.current() || !this.armed) return false;
+						this.armed = false;
+						return true;
+					},
+					claimed: false, started: 0, lastNativeEnd: 0,
+					summary: { schema: "gentle-pi.status-timing/v1", host_total_ms: 0, dispatch_ms: 0, sidebar_ms: 0, completion_ms: 0, truncated: false, statuses: [] },
+				};
+				this.active.add(host);
+				host.started = now(host);
+				return hostScope.run(host, async () => {
+					try { return await run(); }
+					finally {
+						this.active.delete(host);
+						safely(() => {
+							if (!host.claimed || !host.current()) return;
+							const ended = now(host);
+							host.summary.host_total_ms = elapsed(host.started, ended);
+							host.summary.completion_ms = elapsed(host.lastNativeEnd, ended);
+							this.last = host.summary;
+						});
+					}
+				});
+			},
+		};
+	}
+}
+
+/** Only called by the existing STATUS entry points; never invokes one itself. */
+export async function observeNativeStatus<T>(timeoutMs: number, run: () => Promise<T>): Promise<T> {
+	const host = hostScope.getStore();
+	if (!host || !safely(host.current)) return run();
+	if (!host.claimed) {
+		if (!safely(host.claim)) return run();
+		host.claimed = true;
+		host.summary.dispatch_ms = elapsed(host.started, now(host));
+	}
+	const sample: StatusSample = { timeout_ms: timeoutMs, total_ms: 0, resolution_ms: 0, adapter_ms: 0, decode_ms: 0, outcome: { kind: "success" } };
+	if (host.summary.statuses.length < MAX_STATUSES) host.summary.statuses.push(sample);
+	else host.summary.truncated = true;
+	const started = now(host);
+	return nativeScope.run({ host, sample }, async () => {
+		try { return await run(); }
+		catch (error) { safely(() => { sample.outcome = outcome(error); }); throw error; }
+		finally {
+			safely(() => {
+				const ended = now(host);
+				sample.total_ms = elapsed(started, ended);
+				host.lastNativeEnd = ended;
+			});
+		}
+	});
+}
+
+function activeNative(): NativeObservation | undefined {
+	const observation = nativeScope.getStore();
+	return observation && safely(observation.host.current) ? observation : undefined;
+}
+export function measureStatusSync<T>(stage: "resolution" | "decode", run: () => T): T {
+	const observation = activeNative();
+	if (!observation) return run();
+	const started = now(observation.host);
+	try { return run(); }
+	finally { safely(() => { observation.sample[`${stage}_ms`] += elapsed(started, now(observation.host)); }); }
+}
+export async function measureStatusAsync<T>(stage: "adapter", run: () => Promise<T>): Promise<T> {
+	const observation = activeNative();
+	if (!observation) return run();
+	const started = now(observation.host);
+	try { return await run(); }
+	finally { safely(() => { observation.sample[`${stage}_ms`] += elapsed(started, now(observation.host)); }); }
+}
+export function measureStatusSidebar<T>(run: () => T): T {
+	const host = hostScope.getStore();
+	if (!host || !safely(host.current)) return run();
+	const started = now(host);
+	try { return run(); }
+	finally { safely(() => { host.summary.sidebar_ms += elapsed(started, now(host)); }); }
+}

package/lib/telemetry-trigger.ts

@@ -1,4 +1,5 @@
 import { spawn as nodeSpawn } from "node:child_process";
+import { gentleAiIsolationEnv } from "./gentle-ai-binary.ts";
 
 // gentle-ai#4309 owns anonymous usage telemetry end to end: install and
 // heartbeat events, the notice, every kill switch, and the wire contract.
@@ -128,7 +129,8 @@ export function spawnTelemetryTrigger(options: SpawnTelemetryTriggerOptions): Te
 	try {
 		const child = spawnImpl(options.executable, ["telemetry", "trigger", "--json"], {
 			cwd: options.cwd,
-			env: options.env,
+			// S9: a bundled install keeps Gentle AI's telemetry state inside its prefix.
+			env: gentleAiIsolationEnv(options.env),
 			detached: true,
 			windowsHide: true,
 			stdio: "ignore",

package/lib/vim-editor-adapter.ts

@@ -1,14 +1,22 @@
 import { CURSOR_MARKER, Editor, visibleWidth } from "@earendil-works/pi-tui";
 import { createRequire } from "node:module";
 
-// Private shape audited against @earendil-works/pi-tui 0.99.1, 0.99.2 and 1.0.0:
+// Private shape audited against @earendil-works/pi-tui 0.99.1, 0.99.2, 1.0.0, 1.1.0 and 1.2.0:
 // editor.js state/pastes/history, sticky cursor reset, layoutText/render geometry,
 // autocomplete cancellation and { state, pastes, pasteCounter } undo restoration;
 // undo-stack.js clone-on-push/pop snapshots. The two 0.99 releases ship identical
 // editor/undo-stack sources; 1.0.0 is a touched-contract audit, not byte identity.
-// Actual 1.0.0 bundled and unbundled tests exercise identity, edit/undo, paste,
+// The 1.1.0 touched-contract audit retains clone-on-push snapshots with the
+// paste registry, cursor resets, layoutText/render geometry and history exit.
+// cancelAutocomplete aborts/debounces requests before clearing its UI;
+// the adapter still calls that host-owned method, never mutating its request state.
+// Actual installed bundled/unbundled tests exercise identity, edit/undo, paste,
 // selection, wrapping/scroll and autocomplete; fabricated metadata tests only
 // prove exact-version admission for the older audited releases.
+// 1.2.0 changes only editor cursor rendering to paired pi:fc/pi:/fc APC
+// markers resolved by the host TUI (including hardware-cursor suppression).
+// Keep these markers intact and rearm selection after their reverse-off;
+// state, undo, paste, layout and autocomplete contracts remain unchanged.
 // Never silently adapt another build: undo also owns the paste registry.
 interface Position { line: number; col: number }
 interface State { lines: string[]; cursorLine: number; cursorCol: number }
@@ -47,7 +55,7 @@ interface PrivateEditor {
 
 // The single audited-release source for the adapter and Gentle Shell's runtime
 // identity gates. Add a release only after re-auditing the files named above.
-export const AUDITED_PI_EDITOR_VERSIONS = Object.freeze(["0.99.1", "0.99.2", "1.0.0"] as const);
+export const AUDITED_PI_EDITOR_VERSIONS = Object.freeze(["0.99.1", "0.99.2", "1.0.0", "1.1.0", "1.2.0"] as const);
 export type AuditedPiEditorVersion = (typeof AUDITED_PI_EDITOR_VERSIONS)[number];
 
 export function isAuditedPiEditorVersion(version: unknown): version is AuditedPiEditorVersion {
@@ -79,7 +87,7 @@ function hasEditorIdentity(value: unknown, version: string, editorClass: typeof
 const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 const marker = /\[paste #(\d+)(?: (?:\+\d+ lines|\d+ chars))?\]/g;
 
-// Only CSI SGR and Pi's own zero-width cursor marker are expected in editor
+// Only CSI SGR and Pi's own zero-width cursor markers are expected in editor
 // text. Unknown escapes leave the unmodified frame intact (fail closed).
 function highlightRenderedRow(row: string, chunk: LayoutLine, left: number, right: number, padding: number): string | undefined {
   const cursor = chunk.hasCursor ? chunk.cursorPos : undefined;
@@ -110,8 +118,22 @@ function highlightRenderedRow(row: string, chunk: LayoutLine, left: number, righ
       result += token;
       if (selected && !inverse) { result += "\x1b[7m"; inverse = true; }
     } else if (token.startsWith("\x1b")) {
-      if (token !== CURSOR_MARKER) return undefined;
+      if (token !== CURSOR_MARKER && token !== "\x1b_pi:fc\x07" && token !== "\x1b_pi:/fc\x07") return undefined;
+      // Close selection *before* the cursor pair, never inside its cell:
+      // otherwise a later host SGR 7 would immediately meet our SGR 27.
+      // Closing before CURSOR_MARKER also keeps it adjacent to pi:fc so
+      // hardware-cursor suppression can still recognize the focused pair.
+      const local = col - padding;
+      if ((token === CURSOR_MARKER || token === "\x1b_pi:fc\x07") && selected &&
+          !(local >= left && local < right && local < chunk.text.length)) {
+        if (!nativeInverse && inverse) result += "\x1b[27m";
+        selected = false;
+        inverse = nativeInverse;
+      }
       result += token;
+      // The host resolves pi:/fc to SGR 27, or drops the pair when the
+      // hardware cursor owns this cell. Selection must survive either path.
+      if (token === "\x1b_pi:/fc\x07" && selected) result += "\x1b[7m";
     } else {
       const local = col - padding;
       const shouldSelect = local >= left && local < right && local < chunk.text.length;

package/lib/visual-customization-policy.ts

@@ -18,6 +18,8 @@ export interface VisualVisibility {
 	todo: boolean;
 	usageCost: boolean;
 	modelDetails: boolean;
+	/** High-context warning notice; independent from audio notifications. */
+	contextWarning: boolean;
 }
 export interface VisualSettings {
 	statusPlacement: StatusPlacement;
@@ -29,13 +31,13 @@ export const DEFAULT_VISUAL_SETTINGS: VisualSettings = {
 	statusPlacement: STATUS_PLACEMENT.AUTO,
 	headerPlacement: HEADER_PLACEMENT.TOP,
 	density: DENSITY.COMFORTABLE,
-	visibility: { changes: true, rdd: true, agents: true, todo: true, usageCost: true, modelDetails: true },
+	visibility: { changes: true, rdd: true, agents: true, todo: true, usageCost: true, modelDetails: true, contextWarning: true },
 };
 /** Sections row order; `rdd` follows `changes` as the RDD group follows Changes in the Status card. */
-export const VISUAL_SECTION_KEYS = ["changes", "rdd", "agents", "todo", "usageCost", "modelDetails"] as const satisfies readonly (keyof VisualVisibility)[];
-/** Keys added after v1 shipped: stored settings may omit them together, and they default to shown. */
-const ADDED_SECTION_KEYS: readonly (keyof VisualVisibility)[] = ["rdd"];
-const LEGACY_SECTION_KEYS = VISUAL_SECTION_KEYS.filter((key) => !ADDED_SECTION_KEYS.includes(key));
+export const VISUAL_SECTION_KEYS = ["changes", "rdd", "agents", "todo", "usageCost", "modelDetails", "contextWarning"] as const satisfies readonly (keyof VisualVisibility)[];
+/** Keys added after v1 shipped: stored settings may omit them together or one at a time, and they default to shown. */
+const ADDED_SECTION_KEYS: readonly (keyof VisualVisibility)[] = ["rdd", "contextWarning"];
+const BASE_SECTION_KEYS = VISUAL_SECTION_KEYS.filter((key) => !ADDED_SECTION_KEYS.includes(key));
 interface VisualOptions { gentlePiConfigHome?: string }
 export interface VisualResolution {
 	settings: VisualSettings;
@@ -64,13 +66,22 @@ export function isVisualSettings(value: unknown): value is VisualSettings {
 		&& keysMatch(visibility, VISUAL_SECTION_KEYS)
 		&& Object.values(visibility).every((item) => typeof item === "boolean");
 }
-/** Reader-side validation: accepts the current shape and legacy visibility that predates added sections. Writers stay strict. */
+/**
+ * Reader-side validation: accepts the current shape plus every historical one.
+ * Every key must be known, every base key present, and every present value a
+ * boolean; missing added keys (`rdd`, `contextWarning`) then default to shown,
+ * while present values (including `rdd: false`) are preserved. Writers stay strict.
+ */
 export function normalizeVisualSettings(value: unknown): VisualSettings | undefined {
 	if (!record(value) || !record(value.visibility)) return undefined;
 	const visibility = value.visibility;
-	const candidate = keysMatch(visibility, LEGACY_SECTION_KEYS)
-		? { ...value, visibility: Object.fromEntries(VISUAL_SECTION_KEYS.map((key) => [key, visibility[key] ?? true])) }
-		: value;
+	if (!Object.keys(visibility).every((key) => (VISUAL_SECTION_KEYS as readonly string[]).includes(key))) return undefined;
+	if (!BASE_SECTION_KEYS.every((key) => Object.hasOwn(visibility, key))) return undefined;
+	// A key that is present is authoritative: only a missing added key may default to shown.
+	if (!Object.keys(visibility).every((key) => typeof visibility[key] === "boolean")) return undefined;
+	const candidate = keysMatch(visibility, VISUAL_SECTION_KEYS)
+		? value
+		: { ...value, visibility: Object.fromEntries(VISUAL_SECTION_KEYS.map((key) => [key, visibility[key] ?? true])) };
 	return isVisualSettings(candidate) ? candidate : undefined;
 }
 export function parseVisualSettingsFile(raw: string): VisualSettings | undefined {

package/lib/visual-customize-view.ts

@@ -29,14 +29,45 @@ function dropLastGrapheme(text: string): string {
 	return segments.length ? text.slice(0, segments[segments.length - 1]!.index) : text;
 }
 
-export type CustomizeCategory = "Animations" | "Banner" | "Themes" | "Editor" | "History" | "Layout" | "Cards" | "Sections" | "Profiles" | "Reset";
+/** Category-aware footer; the audio card advertises audio keys, never the visual profiles pane. */
+function footerHint(category: string, navOnly: boolean, previewLines: number, keyhint?: string): string {
+	if (navOnly) return "↑/↓ categories · → open · Esc close";
+	if (category === "Notifications") return keyhint ?? "Tab panes · Enter change · p test · Esc close";
+	return previewLines ? "←/→ or Tab panes · ↑/↓ move · Enter apply · p profiles · Esc close" : "Preview omitted · ←/→ panes · ↑/↓ move · Enter apply · Esc close";
+}
+
+/** A row is interactive only while its `visible()` check passes; a throwing check fails closed. */
+function rowVisible(row: CustomizeRow): boolean {
+	if (!row.visible) return true;
+	try { return row.visible() !== false; } catch { return false; }
+}
+
+export type CustomizeCategory = "Animations" | "Banner" | "Themes" | "Editor" | "History" | "Notifications" | "Layout" | "Cards" | "Sections" | "Profiles" | "Reset";
 
 export interface CustomizeRow {
 	category?: CustomizeCategory;
 	label: string | (() => string);
 	/** Read-only representation of the highlighted choice, never an application. */
 	preview?: () => { title: string; sample: string };
-	action(): void | Promise<void>;
+	/** When present and it returns false the row is hidden from its category; an exception fails closed. */
+	visible?: () => boolean;
+	/** Audio-footer hint for this row; omitted rows use the category default (never advertising `f WAV`). */
+	keyhint?: string;
+	/** Runs on Enter/Space. May await the inline bridge for a row-scoped edit or consent. */
+	action(inline: CustomizeInline): void | Promise<void>;
+	/** Row-scoped shortcuts, checked before panel shortcuts. Return `true` for a synchronous
+	 *  consumption, or a Promise for an asynchronous task (e.g. the inline WAV field) the view
+	 *  must keep busy until it settles so overlapping keys/actions cannot write stale state. */
+	key?(data: string, inline: CustomizeInline): boolean | Promise<unknown>;
+}
+/** Minimal in-card bridge so a row never opens a nested native dialog. */
+export interface CustomizeInline {
+	/** Opens an inline field on the highlighted row; resolves on submit or undefined when cancelled. */
+	input(request: { prompt: string; value: string }): Promise<string | undefined>;
+	/** Opens an inline confirmation; resolves true only after an explicit, fully visible yes. */
+	confirm(message: string): Promise<boolean>;
+	/** Set once the owning card is disposed; a row must never persist after this. */
+	disposed: boolean;
 }
 export interface ProfileActions {
 	list(): VisualProfile[];
@@ -75,6 +106,98 @@ export class VisualCustomizeView {
 	private confirmation?: { action: "replace" | "apply" | "delete" | "reset"; name?: string; fingerprint?: string };
 	private confirmationVisible = false;
 	private profileBusy = false;
+	private inlineInput?: { prompt: string; value: string; resolve: (value: string | undefined) => void; visible: boolean };
+	private inlineConfirm?: { message: string; resolve: (value: boolean) => void; visible: boolean };
+	private readonly inline: CustomizeInline = {
+		input: request => this.openInlineInput(request),
+		confirm: message => this.openInlineConfirm(message),
+		disposed: false,
+	};
+	/** Header and diagnostic context for the active pane; Notifications is explicitly audio. */
+	title(): string { return (this.categories[this.categoryIndex] ?? "Settings") === "Notifications" ? "Audio notifications" : "Customization"; }
+	/** Ends the interaction and resolves any pending inline field/consent as cancelled. */
+	dispose(): void { this.closed = true; this.inline.disposed = true; this.cancelInline(); }
+	private cancelInline(): void {
+		const input = this.inlineInput;
+		if (input) { this.inlineInput = undefined; input.resolve(undefined); }
+		const confirm = this.inlineConfirm;
+		if (confirm) { this.inlineConfirm = undefined; confirm.resolve(false); }
+	}
+	private openInlineInput(request: { prompt: string; value: string }): Promise<string | undefined> {
+		if (this.closed) return Promise.resolve(undefined);
+		return new Promise(resolve => { this.inlineInput = { prompt: request.prompt, value: request.value, resolve, visible: false }; });
+	}
+	private openInlineConfirm(message: string): Promise<boolean> {
+		if (this.closed) return Promise.resolve(false);
+		return new Promise(resolve => { this.inlineConfirm = { message, resolve, visible: false }; });
+	}
+	/** Runs one exclusive row task, keeping `busy` set until it settles so no stale write can win. */
+	private withBusy(run: () => void | Promise<unknown>): void {
+		if (this.busy) return;
+		this.busy = true;
+		try {
+			void Promise.resolve(run()).catch((error: unknown) => {
+				this.options.onError?.(error instanceof Error ? error : new Error(String(error)));
+			}).finally(() => { this.busy = false; if (!this.closed) this.options.requestRender(); });
+		} catch (error) {
+			this.busy = false;
+			this.options.onError?.(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	/** Wraps an inline prompt into at most `capacity` fully visible lines. */
+	private wrapInline(text: string, inner: number, capacity: number): string[] | undefined {
+		if (capacity < 1 || inner < 1) return undefined;
+		const lines: string[] = [];
+		let remaining = text;
+		while (remaining.length) {
+			if (lines.length >= capacity) return undefined;
+			if (visibleWidth(remaining) <= inner) { lines.push(remaining); return lines; }
+			let chunk = "";
+			for (const { segment } of graphemes.segment(remaining)) {
+				if (visibleWidth(chunk + segment) > inner) break;
+				chunk += segment;
+			}
+			if (!chunk) return undefined;
+			lines.push(chunk);
+			remaining = remaining.slice(chunk.length);
+		}
+		return lines.length ? lines : undefined;
+	}
+	/** Recomputes the inline area from the live terminal height, never from stale render state. */
+	private previewCapacity(): { inner: number; lines: number; navOnly: boolean } | undefined {
+		const width = this.mainWidth;
+		if (width === undefined || width <= 0) return undefined;
+		const available = this.options.rowsAvailable?.() ?? 24;
+		const height = Number.isFinite(available) ? Math.max(0, Math.min(24, Math.floor(available))) : 0;
+		if (width < CARD_PADDING + 1 || height < 4) return undefined;
+		const navOnly = width < 60 && this.pane === "categories" && this.categories.length > 1;
+		return { inner: width - CARD_PADDING, lines: height >= 11 ? 3 : height >= 8 ? 1 : 0, navOnly };
+	}
+	private handleInlineInput(data: string): void {
+		const field = this.inlineInput!;
+		if (matchesKey(data, Key.escape)) { this.inlineInput = undefined; field.resolve(undefined); }
+		else if (data.startsWith("\x1b[200~")) {
+			const pasted = pastedText(data);
+			if (pasted !== undefined) field.value = appendInput(field.value, pasted);
+		} else if (matchesKey(data, Key.enter) || data.endsWith("\r") && safeText(data.slice(0, -1))) {
+			if (!matchesKey(data, Key.enter)) field.value = appendInput(field.value, data.slice(0, -1));
+			// Guard against a resize that hides the field before this Enter: an unseen value never submits.
+			const area = this.previewCapacity();
+			field.visible = area !== undefined && !area.navOnly && area.lines > 0 && visibleWidth(`${field.prompt}: ${field.value}▏`) <= area.inner;
+			if (field.visible) { this.inlineInput = undefined; field.resolve(field.value); }
+		} else if (matchesKey(data, Key.backspace) || data === "\x7f") field.value = dropLastGrapheme(field.value);
+		else { const text = decodeKittyPrintable(data) ?? data; if (safeText(text)) field.value = appendInput(field.value, text); }
+		this.options.requestRender();
+	}
+	private handleInlineConfirm(data: string): void {
+		const confirm = this.inlineConfirm!;
+		const area = this.previewCapacity();
+		confirm.visible = area !== undefined && !area.navOnly && area.lines > 0
+			&& this.wrapInline(`${confirm.message} y yes · any other key cancel`, area.inner, area.lines) !== undefined;
+		this.inlineConfirm = undefined;
+		confirm.resolve(matchesKey(data, "y") && confirm.visible);
+		this.options.requestRender();
+	}
 	openProfiles(): void { this.profileOpen = true; this.error = undefined; this.options.requestRender(); }
 	private profileAction(action: () => void | Promise<void>): void {
 		if (this.profileBusy) return;
@@ -176,18 +299,41 @@ export class VisualCustomizeView {
 	}
 
 	private categoryRows(): CustomizeRow[] {
-		return this.options.rows.filter(row => (row.category ?? "Settings") === this.categories[this.categoryIndex]);
+		return this.options.rows.filter(row => (row.category ?? "Settings") === this.categories[this.categoryIndex] && rowVisible(row));
 	}
 
 	handleInput(data: string): void {
 		if (this.closed || isKeyRelease(data)) return;
+		if (this.inlineInput) { this.handleInlineInput(data); return; }
+		if (this.inlineConfirm) { this.handleInlineConfirm(data); return; }
 		if (this.profileOpen && this.options.profiles) { this.handleProfiles(data); return; }
-		if (matchesKey(data, Key.escape)) { this.closed = true; this.options.onClose(); return; }
-		if (this.options.profiles && matchesKey(data, "p")) { this.openProfiles(); return; }
+		if (matchesKey(data, Key.escape)) { this.dispose(); this.options.onClose(); return; }
 		const rows = this.categoryRows();
 		const length = this.pane === "categories" ? this.categories.length : rows.length;
+		if (length) {
+			this.selected = Math.min(this.controls.get(this.categories[this.categoryIndex]!) ?? 0, Math.max(0, rows.length - 1));
+			// Row shortcuts outrank panel shortcuts (Notifications `p` previews instead of opening profiles).
+			if (this.pane === "controls" && !this.busy) {
+				let consumed = false;
+				try {
+					const keyed = rows[this.selected]?.key?.(data, this.inline);
+					if (keyed !== undefined && keyed !== false) {
+						consumed = true;
+						// An async key (local WAV field + validation) owns the card until it settles.
+						if (typeof (keyed as Promise<unknown>).then === "function") this.withBusy(() => keyed as Promise<unknown>);
+					}
+				} catch (error) {
+					consumed = true;
+					this.options.onError?.(error instanceof Error ? error : new Error(String(error)));
+				}
+				if (consumed) { this.options.requestRender(); return; }
+			}
+		}
+		// Notifications rows own `p` for a per-event preview. When no event row is
+		// selected the panel must consume it instead of opening visual profiles.
+		if (matchesKey(data, "p") && this.pane === "controls" && (this.categories[this.categoryIndex] ?? "Settings") === "Notifications") { this.options.requestRender(); return; }
+		if (this.options.profiles && matchesKey(data, "p")) { this.openProfiles(); return; }
 		if (!length) return;
-		this.selected = Math.min(this.controls.get(this.categories[this.categoryIndex]!) ?? 0, Math.max(0, rows.length - 1));
 		if (matchesKey(data, Key.left) || matchesKey(data, Key.tab) && this.pane === "controls") this.pane = "categories";
 		else if (matchesKey(data, Key.right) || matchesKey(data, Key.tab) && this.pane === "categories") this.pane = "controls";
 		else if (matchesKey(data, Key.up) || matchesKey(data, "k")) {
@@ -200,15 +346,7 @@ export class VisualCustomizeView {
 		else if ((matchesKey(data, Key.enter) || matchesKey(data, Key.space)) && !this.busy &&
 			this.mainWidth !== undefined && this.mainWidth >= CARD_PADDING + 3 &&
 			(this.options.rowsAvailable?.() ?? 24) >= 4 && rows[this.selected]) {
-			this.busy = true;
-			try {
-				void Promise.resolve(rows[this.selected]?.action()).catch((error: unknown) => {
-					this.options.onError?.(error instanceof Error ? error : new Error(String(error)));
-				}).finally(() => { this.busy = false; if (!this.closed) this.options.requestRender(); });
-			} catch (error) {
-				this.busy = false;
-				this.options.onError?.(error instanceof Error ? error : new Error(String(error)));
-			}
+			this.withBusy(() => rows[this.selected]!.action(this.inline));
 		}
 		this.options.requestRender();
 	}
@@ -225,7 +363,7 @@ export class VisualCustomizeView {
 		if (!height) return [];
 		// A card needs two border rows. At extreme dimensions keep the old
 		// read-only heading rather than letting invisible controls be activated.
-		if (width < CARD_PADDING + 1 || height < 4) return Array.from({ length: Math.min(height, 2) }, (_, i) => truncateToWidth(i ? "Enlarge terminal" : "Visual customization", width, ""));
+		if (width < CARD_PADDING + 1 || height < 4) return Array.from({ length: Math.min(height, 2) }, (_, i) => truncateToWidth(i ? "Enlarge terminal" : this.title(), width, ""));
 		const inner = width - CARD_PADDING;
 		const category = this.categories[this.categoryIndex] ?? "Settings";
 		const rows = this.categoryRows();
@@ -250,7 +388,7 @@ export class VisualCustomizeView {
 		};
 		const join = (left: string, right: string) => leftWidth ? `${left}${" ".repeat(Math.max(0, leftWidth - visibleWidth(stripAnsi(left))))} ${paint("│", 1, "border")} ${right}` : right;
 		const heading = navOnly ? "Categories · choose a category →" : `${category} · ${rows.length ? `${this.selected + 1}/${rows.length}` : "empty"}`;
-		const lines: string[] = [paint("Visual customization", inner, "accent")];
+		const lines: string[] = [paint(this.title(), inner, "accent")];
 		// Commands uses a header, grouped section labels, whitespace and a footer.
 		if (showHeading) lines.push(join(leftWidth ? paint("CATEGORIES", leftWidth, "accent") : "", paint(heading, rightWidth, "accent")));
 		if (showTopGap) lines.push("");
@@ -262,7 +400,19 @@ export class VisualCustomizeView {
 			const right = item ? renderPaletteSelection(item, rightWidth, start + i === position, navOnly || this.pane === "controls" ? this.options.theme : { fg: this.options.theme.fg.bind(this.options.theme) }) : rows.length ? "" : paint("No settings available", rightWidth, "muted");
 			lines.push(join(left, right));
 		}
-		if (previewLines === 3) {
+		if (this.inlineConfirm) {
+			const shows = !navOnly && previewLines > 0 ? this.wrapInline(`${this.inlineConfirm.message} y yes · any other key cancel`, inner, previewLines) : undefined;
+			this.inlineConfirm.visible = shows !== undefined;
+			if (shows) for (const line of shows) lines.push(paint(line, inner, "warning"));
+			else if (previewLines > 0) lines.push(paint("Confirmation needs more space · enlarge terminal", inner, "warning"));
+		} else if (this.inlineInput) {
+			const field = `${this.inlineInput.prompt}: ${this.inlineInput.value}▏`;
+			this.inlineInput.visible = !navOnly && previewLines > 0 && visibleWidth(field) <= inner;
+			if (previewLines > 0) {
+				lines.push(paint(field, inner, "accent"));
+				if (previewLines === 3) lines.push(paint(this.inlineInput.visible ? "Enter confirm · Esc cancel" : "Value too wide · enlarge terminal · Esc cancel", inner, "muted"));
+			}
+		} else if (previewLines === 3) {
 			let preview: ReturnType<NonNullable<CustomizeRow["preview"]>> | undefined;
 			try { if (!navOnly) preview = rows[this.selected]?.preview?.(); } catch { /* Never substitute the active theme for an unreadable source. */ }
 			lines.push("");
@@ -270,9 +420,10 @@ export class VisualCustomizeView {
 			lines.push(paint(navOnly ? "" : preview?.sample ?? "No read-only sample for this choice", inner, "muted"));
 		} else if (previewLines === 1) lines.push(paint(navOnly ? "→ controls · Esc close" : "Preview omitted · enlarge terminal", inner, "muted"));
 		if (showBottomGap) lines.push("");
-		if (showHeading) lines.push(paint(navOnly ? "↑/↓ categories · → open · Esc close" : previewLines ? "←/→ or Tab panes · ↑/↓ move · Enter apply · p profiles · Esc close" : "Preview omitted · ←/→ panes · ↑/↓ move · Enter apply · Esc close", inner, "muted"));
+		if (showHeading) lines.push(paint(footerHint(category, navOnly, previewLines, rows[this.selected]?.keyhint), inner, "muted"));
 		// The top-right close hint mirrors Commands without consuming another row.
-		lines[0] = paint("Visual customization" + " ".repeat(Math.max(1, inner - visibleWidth("Visual customization") - 3)) + "esc", inner, "accent");
+		const title = this.title();
+		lines[0] = paint(title + " ".repeat(Math.max(1, inner - visibleWidth(title) - 3)) + "esc", inner, "accent");
 		return renderPaletteCard(lines.slice(0, height - 2), width, this.options.theme);
 	}
 	private detailSize(width: number): { height: number; inner: number; capacity: number } {