@oh-my-pi/pi-coding-agent 15.11.3 → 15.11.6

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/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";
@@ -433,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"],
@@ -443,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,
 	};
 
@@ -469,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,
 			},
 		};
@@ -499,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

@@ -421,6 +421,12 @@ export class MnemopiSessionState {
 // `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/reset-usage-selector.ts

@@ -0,0 +1,161 @@
+import { Container, matchesKey, ScrollView, Spacer, TruncatedText } from "@oh-my-pi/pi-tui";
+import { theme } from "../../modes/theme/theme";
+import { matchesSelectCancel, matchesSelectDown, matchesSelectUp } from "../../modes/utils/keybinding-matchers";
+import type { ResetUsageAccount } from "../../slash-commands/helpers/reset-usage";
+import { DynamicBorder } from "./dynamic-border";
+
+const RESET_SELECTOR_MAX_VISIBLE = 10;
+
+/**
+ * Account picker for `/usage reset`. Lists Codex accounts with their saved
+ * rate-limit reset counts; selecting one redeems a reset. Because a reset is a
+ * scarce, irreversible credit, Enter requires a second press to confirm.
+ */
+export class ResetUsageSelectorComponent extends Container {
+	#listContainer: Container;
+	#accounts: ResetUsageAccount[];
+	#selectedIndex = 0;
+	#pendingIndex: number | null = null;
+	#statusMessage: string | undefined;
+	#onSelectCallback: (account: ResetUsageAccount) => void;
+	#onCancelCallback: () => void;
+
+	constructor(accounts: ResetUsageAccount[], onSelect: (account: ResetUsageAccount) => void, onCancel: () => void) {
+		super();
+		this.#accounts = accounts;
+		this.#onSelectCallback = onSelect;
+		this.#onCancelCallback = onCancel;
+		const firstRedeemable = accounts.findIndex(account => account.availableCount > 0);
+		this.#selectedIndex = firstRedeemable >= 0 ? firstRedeemable : 0;
+
+		this.addChild(new DynamicBorder());
+		this.addChild(new Spacer(1));
+		this.addChild(new TruncatedText(theme.bold("Spend a saved rate-limit reset:")));
+		this.addChild(new Spacer(1));
+		this.#listContainer = new Container();
+		this.addChild(this.#listContainer);
+		this.addChild(new Spacer(1));
+		this.addChild(new DynamicBorder());
+		this.#updateList();
+	}
+
+	#updateList(): void {
+		this.#listContainer.clear();
+
+		const total = this.#accounts.length;
+		const maxVisible = RESET_SELECTOR_MAX_VISIBLE;
+		const startIndex =
+			total <= maxVisible
+				? 0
+				: Math.max(0, Math.min(this.#selectedIndex - Math.floor(maxVisible / 2), total - maxVisible));
+		const endIndex = Math.min(startIndex + maxVisible, total);
+
+		const rows: string[] = [];
+		for (let i = startIndex; i < endIndex; i++) {
+			const account = this.#accounts[i];
+			if (!account) continue;
+			const isSelected = i === this.#selectedIndex;
+			const redeemable = account.availableCount > 0;
+			const countLabel = account.error
+				? account.error
+				: `${account.availableCount} saved reset${account.availableCount === 1 ? "" : "s"}`;
+			const countText = account.error
+				? theme.fg("error", countLabel)
+				: redeemable
+					? theme.fg("success", countLabel)
+					: theme.fg("dim", countLabel);
+			const activeTag = account.active ? theme.fg("muted", " (active)") : "";
+			if (isSelected) {
+				const name = redeemable ? theme.fg("accent", account.label) : theme.fg("dim", account.label);
+				rows.push(`${theme.fg("accent", `${theme.nav.cursor} `)}${name}${activeTag}  ${countText}`);
+			} else {
+				const name = redeemable ? `  ${account.label}` : theme.fg("dim", `  ${account.label}`);
+				rows.push(`${name}${activeTag}  ${countText}`);
+			}
+		}
+
+		if (rows.length > 0) {
+			const sv = new ScrollView(rows, {
+				height: rows.length,
+				scrollbar: "auto",
+				totalRows: total,
+				theme: { track: t => theme.fg("muted", t), thumb: t => theme.fg("accent", t) },
+			});
+			sv.setScrollOffset(startIndex);
+			this.#listContainer.addChild(sv);
+		}
+
+		if (total === 0) {
+			this.#listContainer.addChild(
+				new TruncatedText(theme.fg("muted", "  No Codex accounts with saved resets"), 0, 0),
+			);
+		}
+
+		const pending = this.#pendingIndex !== null ? this.#accounts[this.#pendingIndex] : undefined;
+		const hint = pending
+			? theme.fg("warning", `  Press Enter again to spend 1 reset for ${pending.label}, Esc to cancel`)
+			: theme.fg("muted", "  ↑/↓ select · ↵ spend a reset · Esc cancel");
+		this.#listContainer.addChild(new TruncatedText(hint, 0, 0));
+
+		if (this.#statusMessage) {
+			this.#listContainer.addChild(new Spacer(1));
+			this.#listContainer.addChild(new TruncatedText(theme.fg("warning", `  ${this.#statusMessage}`), 0, 0));
+		}
+	}
+
+	handleInput(keyData: string): void {
+		if (matchesSelectCancel(keyData)) {
+			if (this.#pendingIndex !== null) {
+				this.#pendingIndex = null;
+				this.#statusMessage = undefined;
+				this.#updateList();
+				return;
+			}
+			this.#onCancelCallback();
+			return;
+		}
+
+		if (matchesSelectUp(keyData)) {
+			if (this.#accounts.length > 0) {
+				this.#selectedIndex = this.#selectedIndex === 0 ? this.#accounts.length - 1 : this.#selectedIndex - 1;
+			}
+			this.#pendingIndex = null;
+			this.#statusMessage = undefined;
+			this.#updateList();
+		} else if (matchesSelectDown(keyData)) {
+			if (this.#accounts.length > 0) {
+				this.#selectedIndex = this.#selectedIndex === this.#accounts.length - 1 ? 0 : this.#selectedIndex + 1;
+			}
+			this.#pendingIndex = null;
+			this.#statusMessage = undefined;
+			this.#updateList();
+		} else if (matchesKey(keyData, "pageUp")) {
+			if (this.#accounts.length > 0) {
+				this.#selectedIndex = Math.max(0, this.#selectedIndex - RESET_SELECTOR_MAX_VISIBLE);
+			}
+			this.#pendingIndex = null;
+			this.#updateList();
+		} else if (matchesKey(keyData, "pageDown")) {
+			if (this.#accounts.length > 0) {
+				this.#selectedIndex = Math.min(this.#accounts.length - 1, this.#selectedIndex + RESET_SELECTOR_MAX_VISIBLE);
+			}
+			this.#pendingIndex = null;
+			this.#updateList();
+		} else if (matchesKey(keyData, "enter") || matchesKey(keyData, "return") || keyData === "\n") {
+			const account = this.#accounts[this.#selectedIndex];
+			if (!account) return;
+			if (account.availableCount <= 0) {
+				this.#statusMessage = "That account has no saved resets to spend.";
+				this.#updateList();
+				return;
+			}
+			if (this.#pendingIndex === this.#selectedIndex) {
+				this.#onSelectCallback(account);
+				return;
+			}
+			this.#pendingIndex = this.#selectedIndex;
+			this.#statusMessage = undefined;
+			this.#updateList();
+		}
+	}
+}

package/src/modes/components/session-selector.ts

@@ -67,13 +67,15 @@ function compareSessionRecency(a: SessionInfo, b: SessionInfo): number {
 	return b.modified.getTime() - a.modified.getTime();
 }
 
+const MIN_PURE_FUZZY_TOKEN_SCORE = -20;
+
 /**
  * Filter and rank session picker search results.
  *
  * Resume search narrows a recency-sorted list: once every query token appears
  * as a literal substring, newer sessions should beat a slightly better fuzzy
  * position match. Pure fuzzy/acronym matches still sort by fuzzy score after
- * literal matches.
+ * literal matches, but weak pure fuzzy tokens are dropped as noise.
  */
 export function rankSessionSearchMatches(allSessions: SessionInfo[], query: string): SessionInfo[] {
 	const tokens = tokenizeSessionQuery(query);
@@ -85,6 +87,7 @@ export function rankSessionSearchMatches(allSessions: SessionInfo[], query: stri
 		const text = sessionSearchText(session);
 		const textLower = text.toLowerCase();
 		let score = 0;
+		let worstTokenScore = Number.NEGATIVE_INFINITY;
 		let literal = true;
 		let matches = true;
 
@@ -95,10 +98,13 @@ export function rankSessionSearchMatches(allSessions: SessionInfo[], query: stri
 				break;
 			}
 			score += match.score;
+			worstTokenScore = Math.max(worstTokenScore, match.score);
 			if (!textLower.includes(token)) literal = false;
 		}
 
-		if (matches) results.push({ session, score, literal, index });
+		if (matches && (literal || worstTokenScore < MIN_PURE_FUZZY_TOKEN_SCORE)) {
+			results.push({ session, score, literal, index });
+		}
 	}
 
 	results.sort((a, b) => {

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 */