@oh-my-pi/pi-coding-agent 15.11.2 → 15.11.4

package/src/internal-urls/issue-pr-protocol.ts

@@ -23,6 +23,7 @@ import {
 	getOrFetchIssue,
 	getOrFetchPr,
 	getOrFetchPrDiff,
+	githubIssueJsonWithStateReasonFallback,
 	type PrDiffFile,
 	parsePositiveDecimalInt,
 	resolveDefaultRepoMemoized,
@@ -294,7 +295,7 @@ async function fetchAndRenderList(
 	const cwd = resolveCwd(context);
 	const fields =
 		scheme === "issue"
-			? ["number", "title", "state", "stateReason", "author", "labels", "createdAt", "updatedAt", "url"]
+			? ["number", "title", "state", "author", "labels", "createdAt", "updatedAt", "url"]
 			: [
 					"number",
 					"title",
@@ -323,9 +324,14 @@ async function fetchAndRenderList(
 	if (options.author) args.push("--author", options.author);
 	if (options.label) args.push("--label", options.label);
 
-	const items = await git.github.json<Array<IssueListItem | PrListItem>>(cwd, args, context?.signal, {
-		repoProvided: true,
-	});
+	const items =
+		scheme === "issue"
+			? await githubIssueJsonWithStateReasonFallback<Array<IssueListItem>>(cwd, args, context?.signal, {
+					repoProvided: true,
+				})
+			: await git.github.json<Array<PrListItem>>(cwd, args, context?.signal, {
+					repoProvided: true,
+				});
 	const header =
 		scheme === "issue"
 			? `# Issues in ${repo} (${options.state}, up to ${options.limit})`

package/src/lsp/clients/lsp-linter-client.ts

@@ -4,18 +4,10 @@
  */
 import { getOrCreateClient, notifySaved, sendRequest, syncContent } from "../../lsp/client";
 import { applyTextEditsToString } from "../../lsp/edits";
+import { resolveFormatOptions } from "../../lsp/format-options";
 import type { Diagnostic, LinterClient, LspClient, ServerConfig, TextEdit } from "../../lsp/types";
 import { fileToUri } from "../../lsp/utils";
 
-/** Default formatting options for LSP */
-const DEFAULT_FORMAT_OPTIONS = {
-	tabSize: 3,
-	insertSpaces: true,
-	trimTrailingWhitespace: true,
-	insertFinalNewline: true,
-	trimFinalNewlines: true,
-};
-
 /**
  * LSP-based linter client implementation.
  * Wraps the existing LSP client infrastructure.
@@ -56,7 +48,7 @@ export class LspLinterClient implements LinterClient {
 		// Request formatting
 		const edits = (await sendRequest(client, "textDocument/formatting", {
 			textDocument: { uri },
-			options: DEFAULT_FORMAT_OPTIONS,
+			options: resolveFormatOptions(filePath, content),
 		})) as TextEdit[] | null;
 
 		if (!edits || edits.length === 0) {

package/src/lsp/format-options.ts

@@ -0,0 +1,119 @@
+/**
+ * Per-file LSP `FormattingOptions` resolution.
+ *
+ * Replaces the historical hardcoded `{ tabSize: 3, insertSpaces: true }` default
+ * that fed every `textDocument/formatting` request — it silently re-indented
+ * 2-space YAML (and any LSP-formatted file) on every write/edit (issue #2329).
+ *
+ * Precedence, highest to lowest:
+ *   1. `.editorconfig` in the file's chain (`indent_style`, `indent_size`, `tab_width`).
+ *   2. Indent detected from the file content the agent is about to write.
+ *   3. Hardcoded fallback — 2 spaces, matching the dominant convention for YAML,
+ *      JSON, JS/TS, Python (PEP 8 is 4 but most LSP servers honour their own
+ *      defaults when ours don't disagree), and most config formats. The previous
+ *      `3` default was an unusual stride that actively damaged every file with
+ *      a 2/4-space convention.
+ */
+import { getEditorConfigFormatting } from "@oh-my-pi/pi-utils";
+
+/** Subset of the LSP `FormattingOptions` we send. */
+export interface LspFormattingOptions {
+	tabSize: number;
+	insertSpaces: boolean;
+	trimTrailingWhitespace: boolean;
+	insertFinalNewline: boolean;
+	trimFinalNewlines: boolean;
+}
+
+/** Sensible fallback when neither `.editorconfig` nor file content pins the indent. */
+const FALLBACK_TAB_SIZE = 2;
+const FALLBACK_INSERT_SPACES = true;
+
+/** Static flags we always pass — these have no per-file analogue and match common formatter expectations. */
+const TRIM_OPTIONS = {
+	trimTrailingWhitespace: true,
+	insertFinalNewline: true,
+	trimFinalNewlines: true,
+} as const;
+
+interface DetectedIndent {
+	tabSize?: number;
+	insertSpaces?: boolean;
+}
+
+/**
+ * Sniff `insertSpaces` and the indent unit from `content`.
+ *
+ * Walks the buffer once: the first indented line decides spaces vs tabs; for
+ * space indents, the GCD of all space-indent widths gives the stride (so a
+ * 2/4/6 file reports `2`, a 4/8 file reports `4`). Returns `undefined` for any
+ * field the content does not pin so a higher-precedence override (editorconfig)
+ * can win without being overwritten by sniffing noise.
+ */
+export function detectIndentFromContent(content: string): DetectedIndent {
+	if (content.length === 0) return {};
+
+	let insertSpaces: boolean | undefined;
+	let unit = 0;
+
+	// Split is the cheapest reliable line walk on arbitrary text; the
+	// per-line regex matches are O(leading whitespace) so total cost is
+	// linear in the file's indented prefix bytes.
+	for (const line of content.split("\n")) {
+		// Skip blank/whitespace-only lines — they carry no indent signal.
+		if (line.length === 0 || line.trim().length === 0) continue;
+
+		const first = line[0];
+		if (first !== " " && first !== "\t") continue;
+
+		if (insertSpaces === undefined) {
+			insertSpaces = first === " ";
+		}
+
+		// Tab-indented file: the unit is one tab per level; tabSize is a
+		// display concern, leave it to caller defaults / editorconfig.
+		if (first === "\t") continue;
+
+		// Space-indented: count the leading spaces (stop at first tab to avoid
+		// mixing). GCD across non-zero widths converges on the stride.
+		let n = 0;
+		while (n < line.length && line[n] === " ") n++;
+		if (n === 0) continue;
+		unit = unit === 0 ? n : gcd(unit, n);
+	}
+
+	const result: DetectedIndent = {};
+	if (insertSpaces !== undefined) result.insertSpaces = insertSpaces;
+	if (unit > 0 && insertSpaces === true) result.tabSize = unit;
+	return result;
+}
+
+function gcd(a: number, b: number): number {
+	let x = a;
+	let y = b;
+	while (y !== 0) {
+		const t = y;
+		y = x % y;
+		x = t;
+	}
+	return x;
+}
+
+/**
+ * Resolve the `FormattingOptions` payload for a `textDocument/formatting` request
+ * targeting `filePath` with `content`.
+ *
+ * The two fields that actually affect on-disk bytes (`tabSize`, `insertSpaces`)
+ * are layered: editorconfig wins, then content sniffing, then the fallback.
+ * Trim/final-newline flags are static.
+ */
+export function resolveFormatOptions(filePath: string, content: string): LspFormattingOptions {
+	const fromConfig = getEditorConfigFormatting(filePath);
+	const detected = detectIndentFromContent(content);
+
+	return {
+		tabSize: fromConfig.tabSize ?? detected.tabSize ?? FALLBACK_TAB_SIZE,
+		insertSpaces: fromConfig.insertSpaces ?? detected.insertSpaces ?? FALLBACK_INSERT_SPACES,
+		...TRIM_OPTIONS,
+	};
+}

package/src/lsp/index.ts

@@ -39,6 +39,7 @@ import {
 	flattenWorkspaceTextEdits,
 	rangesOverlap,
 } from "./edits";
+import { resolveFormatOptions } from "./format-options";
 import { detectLspmux } from "./lspmux";
 import {
 	type CodeAction,
@@ -779,15 +780,6 @@ export enum FileFormatResult {
 	FORMATTED = "formatted",
 }
 
-/** Default formatting options for LSP */
-const DEFAULT_FORMAT_OPTIONS = {
-	tabSize: 3,
-	insertSpaces: true,
-	trimTrailingWhitespace: true,
-	insertFinalNewline: true,
-	trimFinalNewlines: true,
-};
-
 /**
  * Format content using LSP or custom linter client.
  *
@@ -834,7 +826,7 @@ async function formatContent(
 				"textDocument/formatting",
 				{
 					textDocument: { uri },
-					options: DEFAULT_FORMAT_OPTIONS,
+					options: resolveFormatOptions(absolutePath, content),
 				},
 				signal,
 			)) as TextEdit[] | null;

package/src/memories/index.ts

@@ -274,11 +274,7 @@ async function runPhase1(options: {
 			const result = await runStage1Job({
 				claim,
 				model: phase1Model,
-				apiKey: modelRegistry.resolver(phase1Model.provider, {
-					sessionId: session.sessionId,
-					baseUrl: phase1Model.baseUrl,
-					modelId: phase1Model.id,
-				}),
+				apiKey: modelRegistry.resolver(phase1Model, session.sessionId),
 				modelMaxTokens: computeModelTokenBudget(phase1Model, config),
 				config,
 				metadata: session.agent?.metadataForProvider(phase1Model.provider),
@@ -435,11 +431,7 @@ async function runPhase2(options: {
 			const consolidated = await runConsolidationModel({
 				memoryRoot,
 				model: phase2Model,
-				apiKey: modelRegistry.resolver(phase2Model.provider, {
-					sessionId: session.sessionId,
-					baseUrl: phase2Model.baseUrl,
-					modelId: phase2Model.id,
-				}),
+				apiKey: modelRegistry.resolver(phase2Model, session.sessionId),
 				metadata: session.agent?.metadataForProvider(phase2Model.provider),
 			});
 			await applyConsolidation(memoryRoot, consolidated);

package/src/mnemopi/backend.ts

@@ -1,6 +1,7 @@
 import { rm } from "node:fs/promises";
 import * as path from "node:path";
-import { completeSimple } from "@oh-my-pi/pi-ai";
+import { type ApiKeyResolver, completeSimple } from "@oh-my-pi/pi-ai";
+import { hostMatchesUrl } from "@oh-my-pi/pi-catalog/hosts";
 import type { Mnemopi } from "@oh-my-pi/pi-mnemopi";
 import type * as MnemopiDiagnoseNs from "@oh-my-pi/pi-mnemopi/diagnose";
 import type { DiagnosticSummary } from "@oh-my-pi/pi-mnemopi/diagnose";
@@ -82,7 +83,7 @@ export const mnemopiBackend: MemoryBackend = {
 					hasRecalledForFirstTurn: true,
 				}),
 			);
-			previous?.dispose();
+			await previous?.dispose();
 			return;
 		}
 
@@ -91,7 +92,7 @@ export const mnemopiBackend: MemoryBackend = {
 			await Promise.all([loadMnemopi(), loadMnemopiCore()]);
 			const state = new MnemopiSessionState({ sessionId, config, session });
 			const previous = setMnemopiSessionState(session, state);
-			previous?.dispose();
+			await previous?.dispose();
 			state.attachSessionListeners();
 		} catch (error) {
 			logger.warn("Mnemopi: backend startup failed; memory backend inert.", { error: String(error) });
@@ -115,7 +116,7 @@ export const mnemopiBackend: MemoryBackend = {
 
 	async clear(agentDir, _cwd, session): Promise<void> {
 		const previous = session ? setMnemopiSessionState(session, undefined) : undefined;
-		previous?.dispose();
+		await previous?.dispose({ consolidate: false });
 		const config = previous?.config ?? (session ? loadMnemopiConfig(session.settings, agentDir) : undefined);
 		if (!config) return;
 		await loadMnemopiCore();
@@ -136,11 +137,7 @@ export const mnemopiBackend: MemoryBackend = {
 				state = new MnemopiSessionState({ sessionId: session.sessionId, config, session });
 				setMnemopiSessionState(session, state);
 			}
-			await state?.forceRetainCurrentSession();
-			// Drain the background fact extraction scheduled by the final retain
-			// before the process can exit, otherwise the last turn's facts are lost.
-			await state?.memory.flushExtractions();
-			state?.memory.sleepAllSessions(false);
+			await state?.consolidate();
 		} catch (error) {
 			logger.warn("Mnemopi: enqueue failed.", { error: String(error) });
 		}
@@ -437,6 +434,25 @@ async function loadMnemopiConfigWithProviders(
 	return config;
 }
 
+/**
+ * When mnemopi targets OpenRouter (its default embedding host) without a
+ * user-pinned key, hand it the central {@link ApiKeyResolver} so requests pick
+ * up AuthStorage credentials, force-refresh on 401, and rotate across sibling
+ * keys. Returns undefined when the URL points elsewhere or when no OpenRouter
+ * credential exists, preserving mnemopi's env-key fallback and its
+ * "no key -> API embeddings unavailable" gating.
+ */
+async function openrouterKeyResolver(
+	modelRegistry: ModelRegistry,
+	sessionId: string,
+	baseUrl: string | undefined,
+): Promise<ApiKeyResolver | undefined> {
+	if (baseUrl !== undefined && !hostMatchesUrl(baseUrl, "openrouter")) return undefined;
+	const key = await modelRegistry.getApiKeyForProvider("openrouter", sessionId);
+	if (key === undefined || key === "") return undefined;
+	return modelRegistry.resolver("openrouter", { sessionId });
+}
+
 async function resolveMnemopiProviderOptions(
 	config: MnemopiBackendConfig,
 	settings: MemoryBackendStartOptions["settings"],
@@ -447,7 +463,9 @@ async function resolveMnemopiProviderOptions(
 		noEmbeddings: config.providerOptions.noEmbeddings,
 		embeddingModel: config.providerOptions.embeddingModel,
 		embeddingApiUrl: config.providerOptions.embeddingApiUrl,
-		embeddingApiKey: config.providerOptions.embeddingApiKey,
+		embeddingApiKey:
+			config.providerOptions.embeddingApiKey ??
+			(await openrouterKeyResolver(modelRegistry, sessionId, config.providerOptions.embeddingApiUrl)),
 		llm: false,
 	};
 
@@ -473,7 +491,11 @@ async function resolveMnemopiProviderOptions(
 			...base,
 			llm: {
 				baseUrl: config.llmBaseUrl,
-				apiKey: config.llmApiKey,
+				apiKey:
+					config.llmApiKey ??
+					(config.llmBaseUrl === undefined
+						? undefined
+						: await openrouterKeyResolver(modelRegistry, sessionId, config.llmBaseUrl)),
 				model: config.llmModel,
 			},
 		};
@@ -503,11 +525,7 @@ async function resolveMnemopiProviderOptions(
 						messages: [{ role: "user", content: prompt, timestamp: Date.now() }],
 					},
 					{
-						apiKey: modelRegistry.resolver(model.provider, {
-							sessionId,
-							baseUrl: model.baseUrl,
-							modelId: model.id,
-						}),
+						apiKey: modelRegistry.resolver(model, sessionId),
 						maxTokens: opts?.maxTokens,
 						temperature: opts?.temperature,
 					},

package/src/mnemopi/config.ts

@@ -10,7 +10,7 @@ export type MnemopiScoping = "global" | "per-project" | "per-project-tagged";
 
 export type MnemopiProviderOptions = Pick<
 	MnemopiOptions,
-	"noEmbeddings" | "embeddingModel" | "embeddingApiUrl" | "embeddingApiKey" | "llm"
+	"noEmbeddings" | "embeddingModel" | "embeddingApiUrl" | "embeddingApiKey" | "llm" | "debug"
 >;
 
 export interface MnemopiBackendConfig {
@@ -23,6 +23,8 @@ export interface MnemopiBackendConfig {
 	scoping?: MnemopiScoping;
 	autoRecall: boolean;
 	autoRetain: boolean;
+	polyphonicRecall: boolean;
+	enhancedRecall: boolean;
 	retainEveryNTurns: number;
 	recallLimit: number;
 	recallContextTurns: number;
@@ -52,6 +54,8 @@ export function loadMnemopiConfig(settings: Settings, agentDir: string): Mnemopi
 		scoping,
 		autoRecall: settings.get("mnemopi.autoRecall"),
 		autoRetain: settings.get("mnemopi.autoRetain"),
+		polyphonicRecall: settings.get("mnemopi.polyphonicRecall"),
+		enhancedRecall: settings.get("mnemopi.enhancedRecall"),
 		retainEveryNTurns: Math.max(1, Math.floor(settings.get("mnemopi.retainEveryNTurns"))),
 		recallLimit: Math.max(1, Math.floor(settings.get("mnemopi.recallLimit"))),
 		recallContextTurns: Math.max(1, Math.floor(settings.get("mnemopi.recallContextTurns"))),
@@ -60,6 +64,7 @@ export function loadMnemopiConfig(settings: Settings, agentDir: string): Mnemopi
 		debug: settings.get("mnemopi.debug"),
 		providerOptions: {
 			noEmbeddings: settings.get("mnemopi.noEmbeddings"),
+			debug: settings.get("mnemopi.debug"),
 			embeddingModel: settings.get("mnemopi.embeddingModel"),
 			embeddingApiUrl: settings.get("mnemopi.embeddingApiUrl"),
 			embeddingApiKey: settings.get("mnemopi.embeddingApiKey"),

package/src/mnemopi/state.ts

@@ -370,18 +370,63 @@ export class MnemopiSessionState {
 		}
 	}
 
-	dispose(): void {
+	/**
+	 * Drain in-flight fact extraction and run beam consolidation on every owned
+	 * bank, after capturing the current transcript. Mirrors the manual
+	 * `/memory enqueue` slash command, but stops short of closing the DBs so
+	 * callers can keep using the state. {@link dispose} composes this with the
+	 * close step so normal session shutdown promotes working memory to
+	 * episodic/gists/graph automatically (see issue #2320).
+	 *
+	 * Aliased subagent states share `scoped` (and therefore the actual SQLite
+	 * banks) with their parent. `consolidate()` deliberately does NOT
+	 * short-circuit on `aliasOf`: `forceRetainCurrentSession` already guards
+	 * itself, and an explicit `/memory enqueue` invoked from within a subagent
+	 * still needs to flush extractions and sleep the parent's shared banks —
+	 * otherwise enqueue would report success while leaving the subagent's
+	 * retained memories unconsolidated until the parent eventually shuts down
+	 * (PR #2327 review).
+	 */
+	async consolidate(): Promise<void> {
+		await this.forceRetainCurrentSession();
+		for (const memory of this.scoped.owned) {
+			await memory.flushExtractions();
+			memory.sleepAllSessions(false);
+		}
+	}
+
+	/**
+	 * Release the per-session resources. Defaults to running {@link consolidate}
+	 * before closing handles so normal session shutdown promotes working memory
+	 * into long-term storage. Callers that are about to delete the DB files —
+	 * e.g. `mnemopiBackend.clear` — pass `{ consolidate: false }` to skip the
+	 * extraction/sleep pass, since spending tokens on memories that will be
+	 * wiped on the next line is wasted work (PR #2327 review).
+	 */
+	async dispose(options: { consolidate?: boolean } = {}): Promise<void> {
 		this.unsubscribe?.();
 		this.unsubscribe = undefined;
-		if (!this.aliasOf) {
-			for (const memory of this.scoped.owned) memory.close();
+		if (this.aliasOf) return;
+		if (options.consolidate !== false) {
+			try {
+				await this.consolidate();
+			} catch (error) {
+				logger.warn("Mnemopi: consolidation on dispose failed.", { error: String(error) });
+			}
 		}
+		for (const memory of this.scoped.owned) memory.close();
 	}
 }
 
 // `per-project-tagged` is implemented by opening both the project bank and the
 // shared bank, then merging recall results while keeping writes project-local.
 function createScopedResources(config: MnemopiBackendConfig): MnemopiScopedResources {
+	// Env vars (MNEMOPI_POLYPHONIC_RECALL / MNEMOPI_ENHANCED_RECALL) still override
+	// these config-driven defaults inside the core gates.
+	requireMnemopi().configureRecallFeatures({
+		polyphonicRecall: config.polyphonicRecall,
+		enhancedRecall: config.enhancedRecall,
+	});
 	const banks = resolveScopedBanks(config);
 	const memories = new Map<string, MnemopiScopedMemory>();
 	const open = (bank: string): MnemopiScopedMemory => {

package/src/modes/components/extensions/inspector-panel.ts

@@ -4,6 +4,7 @@
  * Shows name, description, origin, status, and kind-specific preview.
  */
 import * as os from "node:os";
+import { isZodSchema, zodToWireSchema } from "@oh-my-pi/pi-ai/utils/schema";
 import { type Component, truncateToWidth, wrapTextWithAnsi } from "@oh-my-pi/pi-tui";
 import { theme } from "../../../modes/theme/theme";
 import { shortenPath } from "../../../tools/render-utils";
@@ -168,12 +169,15 @@ export class InspectorPanel implements Component {
 
 		try {
 			const tool = raw as any;
-			const params = tool?.parameters?.properties || tool?.inputSchema?.properties || {};
+			const wire = (s: unknown): any => (isZodSchema(s) ? zodToWireSchema(s) : s);
+			const paramSchema = wire(tool?.parameters);
+			const inputSchema = wire(tool?.inputSchema);
+			const params = paramSchema?.properties || inputSchema?.properties || {};
 
 			if (Object.keys(params).length === 0) {
 				lines.push(theme.fg("dim", "  (no arguments)"));
 			} else {
-				const required = new Set(tool?.parameters?.required || tool?.inputSchema?.required || []);
+				const required = new Set(paramSchema?.required || inputSchema?.required || []);
 
 				for (const [name, spec] of Object.entries(params)) {
 					const param = spec as any;

package/src/modes/components/plan-review-overlay.ts

@@ -23,6 +23,7 @@ import {
 	Markdown,
 	type MarkdownTheme,
 	matchesKey,
+	parseSgrMouse,
 	ScrollView,
 	truncateToWidth,
 	visibleWidth,
@@ -141,7 +142,7 @@ export class PlanReviewOverlay implements Component {
 	#optionClickRows = new Map<number, number>();
 	#tocClickRows = new Map<number, number>();
 	#bodyClickRows = new Set<number>();
-	/** 1-based column at/under which a region-row click targets the sidebar. */
+	/** Exclusive 0-based column bound below which a region-row click targets the sidebar. */
 	#sidebarClickMaxCol = 0;
 	/** Option index the pointer is currently hovering, or undefined. Updated from
 	 *  motion mouse reports and cleared when the pointer leaves the option rows. */
@@ -332,26 +333,23 @@ export class PlanReviewOverlay implements Component {
 	 * the body.
 	 */
 	#handleMouse(data: string): boolean {
-		const match = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/.exec(data);
-		if (!match) return false;
-		const button = Number(match[1]);
-		const x = Number(match[2]);
-		const row = Number(match[3]) - 1;
-		if (button & 64) {
-			// Scroll wheel: low bit selects direction (64 up, 65 down).
-			this.#scrollView.scroll(button & 1 ? 3 : -3);
+		const event = parseSgrMouse(data);
+		if (!event) return false;
+		if (event.wheel !== null) {
+			// Scroll wheel: three rows per notch.
+			this.#scrollView.scroll(event.wheel * 3);
 			return true;
 		}
-		if (match[4] !== "M") return true; // release
-		if (button & 32) {
+		if (event.release) return true;
+		if (event.motion) {
 			// Motion (hover or drag): light up the option row under the pointer so a
 			// mouse user gets the same affordance the keyboard cursor gives. Any
 			// non-option row clears the highlight.
-			this.#setHoveredOption(this.#optionClickRows.get(row));
+			this.#setHoveredOption(this.#optionClickRows.get(event.row));
 			return true;
 		}
-		if ((button & 3) !== 0) return true; // not the left button
-		const optionIndex = this.#optionClickRows.get(row);
+		if (!event.leftClick) return true;
+		const optionIndex = this.#optionClickRows.get(event.row);
 		if (optionIndex !== undefined) {
 			if (!this.#disabled.has(optionIndex)) {
 				this.#focus = "actions";
@@ -360,14 +358,14 @@ export class PlanReviewOverlay implements Component {
 			}
 			return true;
 		}
-		const tocPos = this.#tocClickRows.get(row);
-		if (tocPos !== undefined && x <= this.#sidebarClickMaxCol) {
+		const tocPos = this.#tocClickRows.get(event.row);
+		if (tocPos !== undefined && event.col < this.#sidebarClickMaxCol) {
 			this.#focus = "toc";
 			this.#tocCursor = tocPos;
 			this.#scrubBodyToToc();
 			return true;
 		}
-		if (this.#bodyClickRows.has(row)) {
+		if (this.#bodyClickRows.has(event.row)) {
 			this.#setFocus("body");
 		}
 		return true;

package/src/modes/components/plugin-settings.ts

@@ -629,11 +629,18 @@ export class PluginSettingsComponent extends Container {
 		this.#currentMarketplacePlugin = null;
 		this.clear();
 
-		// Surface marketplace failures without taking the npm path down with it —
-		// the registry can fail to load (corrupt JSON, missing project root) and
-		// the user still benefits from seeing their npm plugins.
+		// Surface registry failures without taking the whole tab down — either
+		// registry can fail to load (corrupt JSON, missing project root) and the
+		// user still benefits from the other half. An uncaught rejection here
+		// would also leave the tab permanently blank: this method is invoked
+		// fire-and-forget from the constructor, so nothing awaits it.
 		const [npmPlugins, marketplacePlugins] = await Promise.all([
-			this.#manager.list(),
+			this.#manager.list().catch(err => {
+				logger.error("Settings → Plugins: failed to list npm plugins", {
+					error: err instanceof Error ? err.message : String(err),
+				});
+				return [] as InstalledPlugin[];
+			}),
 			this.#buildMarketplaceManager()
 				.then(mgr => mgr.listInstalledPlugins())
 				.catch(err => {
@@ -717,6 +724,16 @@ export class PluginSettingsComponent extends Container {
 	}
 
 	handleInput(data: string): void {
-		this.#viewComponent?.handleInput(data);
+		if (!this.#viewComponent) {
+			// The list view mounts asynchronously (npm + marketplace listing).
+			// Until it does — or if listing rejected and no view ever mounted —
+			// Escape must still close the panel instead of leaving /settings
+			// non-dismissible.
+			if (data === "\x1b" || data === "\x1b\x1b") {
+				this.callbacks.onClose();
+			}
+			return;
+		}
+		this.#viewComponent.handleInput(data);
 	}
 }

package/src/modes/components/settings-defs.ts

@@ -4,7 +4,8 @@
  * settings selector.
  *
  * To add a new setting to the UI: declare it in `settings-schema.ts`
- * with a `ui` block. If it needs a submenu, include `options: [...]`
+ * with a `ui` block carrying `tab` and `group` (the group must be listed
+ * in `TAB_GROUPS[tab]`). If it needs a submenu, include `options: [...]`
  * (or `options: "runtime"` for runtime-injected lists like themes).
  */
 
@@ -21,6 +22,7 @@ import {
 	type SettingPath,
 	type SettingTab,
 	type SubmenuOption,
+	TAB_GROUPS,
 } from "../../config/settings-schema";
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -34,6 +36,8 @@ interface BaseSettingDef {
 	label: string;
 	description: string;
 	tab: SettingTab;
+	/** Section within the tab; items are ordered by TAB_GROUPS[tab] and rendered under a heading row. */
+	group?: string;
 	/**
 	 * Optional visibility predicate. When supplied and returning false, the
 	 * setting is hidden from the UI. Applies to every variant — booleans,
@@ -111,7 +115,7 @@ function pathToSettingDef(path: SettingPath): SettingDef | null {
 
 	const schemaType = getType(path);
 	const condition = ui.condition ? CONDITIONS[ui.condition] : undefined;
-	const base = { path, label: ui.label, description: ui.description, tab: ui.tab, condition };
+	const base = { path, label: ui.label, description: ui.description, tab: ui.tab, group: ui.group, condition };
 
 	if (schemaType === "boolean") {
 		return { ...base, type: "boolean" };
@@ -170,9 +174,20 @@ export function getAllSettingDefs(): SettingDef[] {
 	return defs;
 }
 
-/** Get settings for a specific tab */
+/**
+ * Get settings for a specific tab, ordered by the tab's group layout
+ * (TAB_GROUPS). Ungrouped settings sort first; within a group, schema
+ * declaration order is preserved.
+ */
 export function getSettingsForTab(tab: SettingTab): SettingDef[] {
-	return getAllSettingDefs().filter(def => def.tab === tab);
+	const defs = getAllSettingDefs().filter(def => def.tab === tab);
+	const order = TAB_GROUPS[tab];
+	const rank = (def: SettingDef): number => {
+		if (!def.group) return -1;
+		const index = order.indexOf(def.group);
+		return index >= 0 ? index : order.length;
+	};
+	return defs.sort((a, b) => rank(a) - rank(b));
 }
 
 /** Get a setting definition by path */