@mjasnikovs/pi-task 0.38.30 → 0.38.32

package/dist/config/option-picker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The submenu a /task-config row opens on Enter, when cycling is the wrong verb.
+ *
+ * WHY A SUBMENU AND NOT `ctx.ui.select`
+ * -------------------------------------
+ * The settings panel already lives inside `ctx.ui.custom` with `overlay: true`.
+ * Opening a second dialog from inside a component's input handler races two
+ * overlays for focus. `SettingsList` already solves this: it renders the submenu
+ * in place of the list and delegates input to it. And its `done(v)` calls
+ * `onChange(id, v)` with exactly the returned value while `done(undefined)`
+ * writes nothing — the same one-value contract every cycling row uses, so the
+ * panel's dispatch needs no branch and a model list of 200 costs one write
+ * instead of 200.
+ *
+ * WHY NOT A BARE `SelectList`
+ * ---------------------------
+ * `SelectList.handleInput` matches up, down, confirm and cancel and DROPS every
+ * other key, so it can never fill its own `setFilter`. `Container` has no
+ * `handleInput` at all — it composes `render` and nothing else. pi's own model
+ * picker (`modes/interactive/components/model-selector.js`) hand-rolls exactly
+ * this: an `Input`, a filtered list, and a `handleInput` that routes between
+ * them. The three components that DO use `SelectList` bare — theme, thinking,
+ * show-images — are short fixed lists with no filter. A model list is not.
+ */
+import { Container } from '@earendil-works/pi-tui';
+import type { SelectItem } from '@earendil-works/pi-tui';
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+type Theme = ExtensionCommandContext['ui']['theme'];
+/**
+ * A filterable one-of picker.
+ *
+ * `currentValue` may match NO option — that is the vanished-model case, where
+ * the stored spec is still shown by the row and must still be openable. It
+ * simply starts at the top rather than refusing to render.
+ */
+export declare class OptionPicker extends Container {
+    private readonly input;
+    private readonly list;
+    constructor(options: readonly SelectItem[], currentValue: string, theme: Theme, done: (value?: string) => void);
+    handleInput(data: string): void;
+}
+export {};

package/dist/config/option-picker.js

@@ -0,0 +1,73 @@
+/**
+ * The submenu a /task-config row opens on Enter, when cycling is the wrong verb.
+ *
+ * WHY A SUBMENU AND NOT `ctx.ui.select`
+ * -------------------------------------
+ * The settings panel already lives inside `ctx.ui.custom` with `overlay: true`.
+ * Opening a second dialog from inside a component's input handler races two
+ * overlays for focus. `SettingsList` already solves this: it renders the submenu
+ * in place of the list and delegates input to it. And its `done(v)` calls
+ * `onChange(id, v)` with exactly the returned value while `done(undefined)`
+ * writes nothing — the same one-value contract every cycling row uses, so the
+ * panel's dispatch needs no branch and a model list of 200 costs one write
+ * instead of 200.
+ *
+ * WHY NOT A BARE `SelectList`
+ * ---------------------------
+ * `SelectList.handleInput` matches up, down, confirm and cancel and DROPS every
+ * other key, so it can never fill its own `setFilter`. `Container` has no
+ * `handleInput` at all — it composes `render` and nothing else. pi's own model
+ * picker (`modes/interactive/components/model-selector.js`) hand-rolls exactly
+ * this: an `Input`, a filtered list, and a `handleInput` that routes between
+ * them. The three components that DO use `SelectList` bare — theme, thinking,
+ * show-images — are short fixed lists with no filter. A model list is not.
+ */
+import { Container, getKeybindings, Input, SelectList } from '@earendil-works/pi-tui';
+/** Rows visible before the list scrolls. Matches the panel's own MAX_VISIBLE. */
+const PICKER_VISIBLE = 11;
+function selectTheme(theme) {
+    return {
+        selectedPrefix: text => theme.fg('accent', text),
+        selectedText: text => theme.fg('accent', theme.bold(text)),
+        description: text => theme.fg('muted', text),
+        scrollInfo: text => theme.fg('dim', text),
+        noMatch: text => theme.fg('dim', text)
+    };
+}
+/**
+ * A filterable one-of picker.
+ *
+ * `currentValue` may match NO option — that is the vanished-model case, where
+ * the stored spec is still shown by the row and must still be openable. It
+ * simply starts at the top rather than refusing to render.
+ */
+export class OptionPicker extends Container {
+    input = new Input();
+    list;
+    constructor(options, currentValue, theme, done) {
+        super();
+        this.list = new SelectList([...options], PICKER_VISIBLE, selectTheme(theme));
+        const at = options.findIndex(o => o.value === currentValue);
+        if (at !== -1)
+            this.list.setSelectedIndex(at);
+        this.list.onSelect = item => done(item.value);
+        this.list.onCancel = () => done(undefined);
+        this.addChild(this.input);
+        this.addChild(this.list);
+    }
+    handleInput(data) {
+        const kb = getKeybindings();
+        const forList = kb.matches(data, 'tui.select.up')
+            || kb.matches(data, 'tui.select.down')
+            || kb.matches(data, 'tui.select.confirm')
+            || kb.matches(data, 'tui.select.cancel');
+        if (forList) {
+            this.list.handleInput(data);
+            return;
+        }
+        // Everything else is typing. The list re-filters on every keystroke,
+        // which is what `setFilter` is for and what nothing else calls.
+        this.input.handleInput(data);
+        this.list.setFilter(this.input.getValue());
+    }
+}

package/dist/config/reasoning.d.ts

@@ -17,35 +17,21 @@
  *
  * PURE MODULE — no imports with runtime side effects, so `config.ts` can import
  * the table and the sanitizers during its own module evaluation. `getConfig()`
- * lives one hop away in `reasoning-args.ts` for exactly this reason: importing
+ * lives one hop away in `group-args.ts` for exactly this reason: importing
  * it here would make config.ts ⇄ reasoning.ts a real cycle, and whichever module
  * a caller reached first would decide whether `DEFAULT_REASONING_TABLE` was
  * initialised before `DEFAULT_CONFIG` read it.
  */
 import type { PiTaskConfig } from './config.js';
+import { CHILD_GROUPS, type ChildGroup } from './groups.js';
 /**
- * The child roles that share one reasoning setting.
- *
- * Grouped by JOB, not by spawn mechanism — two children that both go through
- * `runWorker` (a research worker and a verify gate) want different amounts of
- * thinking, while `refine` in phases.ts and `compress-label` in title-label.ts
- * want the same amount and share the `phase` cell.
- *
- * - `research`     the ad-hoc `pi-worker` subagent tool, and the fallback the four
- *                  research workers use when their own cell is unset
- * - `research:files` / `research:apis` / `research:context` / `research:tooling`
- *                  one cell per research worker, so a level can be paid for in
- *                  one worker without paying for it in the other three
- * - `phase`        refine, verify-tooling, grill, compose, critique, compress-label
- * - `planning`     /task-auto's planning children — clarify, decompose, and the
- *                  extract/coverage passes around them
- * - `plan`         /task-plan's question and answer children
- * - `gate`         enforce, verify, lint-fix, final-fix, recommend
- * - `extraction`   the --no-tools focused docs/fetch extractors
- * - `implementation` the host-session turn that writes the code (not a child)
+ * Re-exported because this module's whole public surface — the default table,
+ * `resolveReasoning`, `effectiveReasoning` — is typed on them, so an importer of
+ * those already needs them. The roster itself lives in groups.ts; `GROUP_BY_CHILD`
+ * and `groupForChild` are deliberately NOT re-exported, so a caller that wants
+ * the roster reaches for the roster.
  */
-export type ReasoningGroup = 'research' | 'research:files' | 'research:apis' | 'research:context' | 'research:tooling' | 'phase' | 'planning' | 'plan' | 'gate' | 'extraction' | 'implementation';
-export declare const REASONING_GROUPS: readonly ReasoningGroup[];
+export { CHILD_GROUPS, type ChildGroup };
 /**
  * The four profiles offered by /task-config.
  * - `default` the per-group table below
@@ -82,44 +68,9 @@ export declare const REASONING_ON_LEVEL: GroupSetting;
  * host's level. Any other value is a decision this project made for that
  * group's job, and `/task-config` mode `custom` overrides all of it.
  */
-export declare const DEFAULT_REASONING_TABLE: Readonly<Record<ReasoningGroup, GroupSetting>>;
+export declare const DEFAULT_REASONING_TABLE: Readonly<Record<ChildGroup, GroupSetting>>;
 /** A stored mode, or `default` when the value is not one. */
 export declare function sanitizeReasoningMode(value: unknown): ReasoningMode;
-/**
- * Child NAME → reasoning group, for every child spawned under a name:
- * `runPhaseChild`, `runPlanningChild`, and the research workers' `spec.label`.
- *
- * WHY KEYED ON THE NAME
- * ---------------------
- * The name is the only identifier in scope at all three spawn paths (phases,
- * /task-auto planning, /task-plan), it is what the loader and the debug trail
- * already print, and it is the one thing a reader can check against the phase
- * list without following the call graph. Threading a group parameter through
- * `PhaseDeps` / `AutoDeps` instead would touch both orchestrators' dep bags to
- * express something the call site already says out loud.
- *
- * AN UNMAPPED NAME IS A BUILD FAILURE, not a silent `inherit`.
- * `reasoning-groups.test.ts` scans every literal child name under `src/task`
- * and fails if it is missing here. A defaulting lookup would let a phase added
- * later opt itself out of the table without anyone deciding to.
- *
- * The gate and extraction groups are NOT here: those children reach the model
- * through `groupThinkingArgs('gate' | 'extraction')` at call sites with no name
- * in scope (gate-deps.ts, fetch-core.ts, docs-core.ts, pi-worker-docs.ts). The
- * four research workers do have a name — their `spec.label` — so they are here.
- */
-export declare const REASONING_GROUP_BY_CHILD: Readonly<Record<string, ReasoningGroup>>;
-/**
- * The group a named child belongs to.
- *
- * Returns `undefined` for a name the table does not know, and the CALLER decides
- * what that means. `runPhaseChild` treats it as `inherit` — a child that reaches
- * the model with today's argv is always safe — while the test treats it as a
- * failure. That split is deliberate: the guard belongs at build time, where
- * someone can fix it, not at run time, where it would abort a user's task over a
- * missing table row.
- */
-export declare function reasoningGroupForChild(name: string): ReasoningGroup | undefined;
 /**
  * Always returns a COMPLETE record, never a partial one.
  *
@@ -128,16 +79,16 @@ export declare function reasoningGroupForChild(name: string): ReasoningGroup | u
  * `undefined`, and every call site would need its own fallback. Filling the gaps
  * here means the type is true at the only place that constructs the value.
  */
-export declare function sanitizeReasoningLevels(value: unknown): Record<ReasoningGroup, GroupSetting>;
+export declare function sanitizeReasoningLevels(value: unknown): Record<ChildGroup, GroupSetting>;
 /**
  * What one group is actually set to, given a config. The ONLY place the four
  * modes are interpreted.
  *
  * `cfg` is required rather than defaulted to `getConfig()` so this module stays
  * import-free (see the header). Callers that want the live config use
- * `groupThinkingArgs` from reasoning-args.ts.
+ * `groupThinkingArgs` from group-args.ts.
  */
-export declare function resolveReasoning(group: ReasoningGroup, cfg: PiTaskConfig): GroupSetting;
+export declare function resolveReasoning(group: ChildGroup, cfg: PiTaskConfig): GroupSetting;
 /**
  * The WHOLE table, as this config will actually run it.
  *
@@ -146,7 +97,7 @@ export declare function resolveReasoning(group: ReasoningGroup, cfg: PiTaskConfi
  * asks the single-group question instead, through `resolveReasoning` — which is
  * the only place the four modes are interpreted.
  */
-export declare function effectiveReasoning(cfg: PiTaskConfig): Record<ReasoningGroup, GroupSetting>;
+export declare function effectiveReasoning(cfg: PiTaskConfig): Record<ChildGroup, GroupSetting>;
 /**
  * The argv fragment for a setting. `inherit` is the empty fragment — no flag at
  * all — which is what makes an all-`inherit` config byte-identical to the
@@ -154,4 +105,12 @@ export declare function effectiveReasoning(cfg: PiTaskConfig): Record<ReasoningG
  */
 export declare function thinkingArgs(setting: GroupSetting): string[];
 /** One honest sentence per group, for the /task-config rows. */
-export declare const REASONING_GROUP_HELP: Readonly<Record<ReasoningGroup, string>>;
+export declare const REASONING_GROUP_HELP: Readonly<Record<ChildGroup, string>>;
+/**
+ * One honest sentence per model row.
+ *
+ * They are NOT the reasoning help reworded. A model cell answers a different
+ * question — which machine does this work — and one of them costs money every
+ * turn rather than once per change, which is a thing the row has to say.
+ */
+export declare const MODEL_GROUP_HELP: Readonly<Record<ChildGroup, string>>;

package/dist/config/reasoning.js

@@ -1,16 +1,12 @@
-export const REASONING_GROUPS = [
-    'research',
-    'research:files',
-    'research:apis',
-    'research:context',
-    'research:tooling',
-    'phase',
-    'planning',
-    'plan',
-    'gate',
-    'extraction',
-    'implementation'
-];
+import { CHILD_GROUPS, sanitizeGroupRecord } from './groups.js';
+/**
+ * Re-exported because this module's whole public surface — the default table,
+ * `resolveReasoning`, `effectiveReasoning` — is typed on them, so an importer of
+ * those already needs them. The roster itself lives in groups.ts; `GROUP_BY_CHILD`
+ * and `groupForChild` are deliberately NOT re-exported, so a caller that wants
+ * the roster reaches for the roster.
+ */
+export { CHILD_GROUPS };
 export const REASONING_MODES = ['default', 'on', 'off', 'custom'];
 /**
  * The settings offered in /task-config: `inherit` plus the standard part of pi's
@@ -56,80 +52,6 @@ export const DEFAULT_REASONING_TABLE = {
 export function sanitizeReasoningMode(value) {
     return REASONING_MODES.includes(value) ? value : 'default';
 }
-/**
- * Child NAME → reasoning group, for every child spawned under a name:
- * `runPhaseChild`, `runPlanningChild`, and the research workers' `spec.label`.
- *
- * WHY KEYED ON THE NAME
- * ---------------------
- * The name is the only identifier in scope at all three spawn paths (phases,
- * /task-auto planning, /task-plan), it is what the loader and the debug trail
- * already print, and it is the one thing a reader can check against the phase
- * list without following the call graph. Threading a group parameter through
- * `PhaseDeps` / `AutoDeps` instead would touch both orchestrators' dep bags to
- * express something the call site already says out loud.
- *
- * AN UNMAPPED NAME IS A BUILD FAILURE, not a silent `inherit`.
- * `reasoning-groups.test.ts` scans every literal child name under `src/task`
- * and fails if it is missing here. A defaulting lookup would let a phase added
- * later opt itself out of the table without anyone deciding to.
- *
- * The gate and extraction groups are NOT here: those children reach the model
- * through `groupThinkingArgs('gate' | 'extraction')` at call sites with no name
- * in scope (gate-deps.ts, fetch-core.ts, docs-core.ts, pi-worker-docs.ts). The
- * four research workers do have a name — their `spec.label` — so they are here.
- */
-export const REASONING_GROUP_BY_CHILD = {
-    // ── phase: task/phases.ts + task/title-label.ts ──────────────────────────
-    refine: 'phase',
-    'verify-tooling': 'phase',
-    'grill-auto': 'phase',
-    'grill-gen': 'phase',
-    compose: 'phase',
-    critique: 'phase',
-    'critique-triage': 'phase',
-    'compress-label': 'phase',
-    // ── planning: task/auto-orchestrator.ts ──────────────────────────────────
-    'clarify-triage': 'planning',
-    'auto-clarify': 'planning',
-    'auto-decompose': 'planning',
-    'requirement-extract': 'planning',
-    'decompose-coverage': 'planning',
-    'coverage-map': 'planning',
-    'contract-extract': 'planning',
-    'launch-extract': 'planning',
-    // ── plan: task/plan-orchestrator.ts ──────────────────────────────────────
-    'plan-question': 'plan',
-    'plan-answer': 'plan',
-    // ── research: task/phases.ts `workerSpecs`, keyed on the spec's LABEL ─────
-    'worker:files': 'research:files',
-    'worker:apis': 'research:apis',
-    'worker:context': 'research:context',
-    'worker:tooling': 'research:tooling'
-};
-/**
- * The group a named child belongs to.
- *
- * Returns `undefined` for a name the table does not know, and the CALLER decides
- * what that means. `runPhaseChild` treats it as `inherit` — a child that reaches
- * the model with today's argv is always safe — while the test treats it as a
- * failure. That split is deliberate: the guard belongs at build time, where
- * someone can fix it, not at run time, where it would abort a user's task over a
- * missing table row.
- */
-export function reasoningGroupForChild(name) {
-    return REASONING_GROUP_BY_CHILD[name];
-}
-/**
- * For a `research:*` group, the group a stored config falls back to when its own
- * key is missing. Every other group maps to `undefined`.
- */
-const RESEARCH_SUBGROUP_PARENT = {
-    'research:files': 'research',
-    'research:apis': 'research',
-    'research:context': 'research',
-    'research:tooling': 'research'
-};
 /**
  * Always returns a COMPLETE record, never a partial one.
  *
@@ -139,25 +61,7 @@ const RESEARCH_SUBGROUP_PARENT = {
  * here means the type is true at the only place that constructs the value.
  */
 export function sanitizeReasoningLevels(value) {
-    const stored = typeof value === 'object' && value !== null && !Array.isArray(value) ?
-        value
-        : {};
-    const valid = (v) => REASONING_SETTINGS.includes(v);
-    const out = {};
-    for (const group of REASONING_GROUPS) {
-        const stored_ = stored[group];
-        if (valid(stored_)) {
-            out[group] = stored_;
-            continue;
-        }
-        // A `research:*` key the stored config never had falls back to its
-        // parent `research` value, so a config written before the split keeps
-        // meaning what it meant.
-        const parent = RESEARCH_SUBGROUP_PARENT[group];
-        out[group] =
-            parent && valid(stored[parent]) ? stored[parent] : DEFAULT_REASONING_TABLE[group];
-    }
-    return out;
+    return sanitizeGroupRecord(value, (v) => REASONING_SETTINGS.includes(v), group => DEFAULT_REASONING_TABLE[group]);
 }
 /**
  * What one group is actually set to, given a config. The ONLY place the four
@@ -165,7 +69,7 @@ export function sanitizeReasoningLevels(value) {
  *
  * `cfg` is required rather than defaulted to `getConfig()` so this module stays
  * import-free (see the header). Callers that want the live config use
- * `groupThinkingArgs` from reasoning-args.ts.
+ * `groupThinkingArgs` from group-args.ts.
  */
 export function resolveReasoning(group, cfg) {
     switch (cfg.reasoningMode) {
@@ -189,7 +93,7 @@ export function resolveReasoning(group, cfg) {
  */
 export function effectiveReasoning(cfg) {
     const out = {};
-    for (const group of REASONING_GROUPS)
+    for (const group of CHILD_GROUPS)
         out[group] = resolveReasoning(group, cfg);
     return out;
 }
@@ -224,3 +128,28 @@ export const REASONING_GROUP_HELP = {
     implementation: 'The main session turn that actually writes the code. Changing this briefly '
         + "changes pi's own thinking level, and puts it back afterwards."
 };
+/**
+ * One honest sentence per model row.
+ *
+ * They are NOT the reasoning help reworded. A model cell answers a different
+ * question — which machine does this work — and one of them costs money every
+ * turn rather than once per change, which is a thing the row has to say.
+ */
+export const MODEL_GROUP_HELP = {
+    research: 'The pi-worker subagent tool, and the fallback for any research worker below. '
+        + 'Long read-only loops: a cheap fast model pays off here.',
+    'research:files': 'Research worker 1 of 4: maps which files the task will touch.',
+    'research:apis': 'Research worker 2 of 4: the symbols and signatures the task must call.',
+    'research:context': 'Research worker 3 of 4: how the project is put together.',
+    'research:tooling': 'Research worker 4 of 4: the commands that build, test and run it.',
+    phase: 'Refining your request, generating and answering the clarifying questions, '
+        + 'writing the spec, and critiquing it.',
+    planning: "/task-auto's planners: splitting a design document into tasks.",
+    plan: "/task-plan's interactive question-and-answer children.",
+    gate: 'The checks that run after code is written: verify, enforce, lint-fix, autofix.',
+    extraction: 'The small no-tools children that pull one answer out of a page or a docs chunk.',
+    implementation: 'The main session turn that writes the code — YOUR session, switched for the turn and '
+        + 'switched back. Unlike every row above, this one is not free: a model switch re-bills '
+        + 'the whole prompt as a cache miss, twice per task. Leave it on inherit unless you '
+        + 'want a different model than the one you are reading this in.'
+};

package/dist/config/register.d.ts

@@ -1,10 +1,11 @@
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { SettingsList } from '@earendil-works/pi-tui';
-import type { Component } from '@earendil-works/pi-tui';
+import type { Component, SelectItem } from '@earendil-works/pi-tui';
+import { type ReasoningModelFacts } from '../shared/reasoning-capability.js';
 import { type PiTaskConfig } from './config.js';
 import { type InstalledExtension } from './extension-list.js';
 import { type GuardableTool } from './tool-list.js';
-import { type ReasoningGroup } from './reasoning.js';
+import { type GroupSetting, type ChildGroup } from './reasoning.js';
 type Theme = ExtensionCommandContext['ui']['theme'];
 /**
  * Frames a child component (the settings list) in a rounded border with a title
@@ -73,6 +74,17 @@ export interface ConfigItem {
     description: string;
     /** Offered values. Omitted for a boolean, which is always on/off. */
     values?: string[];
+    /**
+     * Rows whose choice is a LIST, not a cycle. Present ⇒ Enter opens a picker
+     * instead of stepping `values`.
+     *
+     * A FUNCTION of the draft config, evaluated at Enter-time, because what a row
+     * may offer can depend on another row the user changed while the panel was
+     * open: a group's thinking options narrow to what its chosen model declares.
+     * `values` stays the STATIC complete vocabulary, because that is what the
+     * round-trip property in config-items.test.ts quantifies over.
+     */
+    submenu?: (cfg: PiTaskConfig) => SelectItem[];
     /** What the panel shows for the current value. */
     format: (cfg: PiTaskConfig) => string;
     /** Write the chosen label back. A value it does not recognise is ignored. */
@@ -92,7 +104,7 @@ export interface ConfigItem {
  * exemptions from it) end up separated by rows that have nothing to do with
  * them. The headers are inert rows: no `values`, so Enter does nothing on them.
  */
-export type Section = 'session' | 'checks' | 'research' | 'reasoning' | 'timeouts' | 'unattended' | 'logging' | 'extensions';
+export type Section = 'session' | 'checks' | 'research' | 'models' | 'reasoning' | 'timeouts' | 'unattended' | 'logging' | 'extensions';
 /** Section order, and the label each header renders. */
 export declare const SECTIONS: ReadonlyArray<{
     key: Section;
@@ -100,6 +112,18 @@ export declare const SECTIONS: ReadonlyArray<{
 }>;
 /** Marks a header row, so onChange can ignore one and tests can find them. */
 export declare const SECTION_ID_PREFIX = "section:";
+/**
+ * Is this row scenery rather than a setting?
+ *
+ * Reads the ID, not `values`. Those two agreed only while every real row cycled
+ * a list: a picker row has a `submenu` and may carry `values` purely for the
+ * round-trip contract, so "no values" stopped meaning "not a row". Both
+ * `sectionHeader` and `sectionGap` already stamp the prefix, so this is exact
+ * rather than a heuristic, and all three consumers ask the same question.
+ */
+export declare const isSectionRow: (item: {
+    id: string;
+}) => boolean;
 /**
  * Every setting rendered by /task-config, in display order.
  *
@@ -125,13 +149,60 @@ export declare function applyToolToggle(exempt: readonly string[], toolName: str
  * So a child is drawn as a tree branch under its parent and loses the repeated
  * `think: research:` prefix, the same text at the head of four consecutive
  * lines. `└─` on the last child, `├─` on the rest, decided from the group's
- * position in {@link REASONING_GROUPS} rather than a hand-kept list — adding a
+ * position in {@link CHILD_GROUPS} rather than a hand-kept list — adding a
  * fifth worker moves the corner on its own.
  *
  * Leading spaces survive: SettingsList pads the label right, never trims it.
  */
-export declare function reasoningRowLabel(group: ReasoningGroup): string;
-export declare function reasoningItems(): ConfigItem[];
+export declare function reasoningRowLabel(group: ChildGroup): string;
+/**
+ * What this machine can offer a model row, and what each offer can DO.
+ *
+ * `facts` is what lets the thinking rows narrow: a group pinned to a
+ * `reasoning: false` model may only be offered `off`. It answers `undefined` for
+ * a spec it cannot resolve — a vanished model, or `inherit` before a session
+ * exists — and every consumer reads that as "offer everything", which is exactly
+ * today's behaviour.
+ */
+export interface ModelCatalog {
+    /** Offerable `provider/id` specs, without `inherit`. */
+    specs: readonly string[];
+    /** Human note per spec, e.g. an extension-provided provider's warning. */
+    note?: (spec: string) => string | undefined;
+    facts: (spec: string) => ReasoningModelFacts | undefined;
+}
+/** No registry reachable. Every row still renders; nothing narrows. */
+export declare const EMPTY_CATALOG: ModelCatalog;
+export declare function modelItems(catalog: ModelCatalog): ConfigItem[];
+/**
+ * Write a group's model, and RE-CLAMP its thinking cell in the same write.
+ *
+ * Narrowing the picker does nothing about a level already stored from before the
+ * model was chosen: on its own it would freeze a lie into a cell it has just
+ * made unconfigurable. `syncRows` re-renders every row, so the user sees the
+ * level move.
+ *
+ * The clamp reads `resolveReasoning`, NOT `cfg.reasoningLevels[group]`. In mode
+ * `on` or `off` the stored table is ignored entirely, so a user in `on` who
+ * picks a non-reasoning model has a stored cell that says nothing and an
+ * effective `medium` the model will erase — and comparing the stored cell would
+ * see no clamp and stay silent about a real lie.
+ *
+ * Guarded on the clamp actually MOVING something, because `applyReasoningLevel`
+ * flips the whole table to `custom`, and picking a fully-capable model must not
+ * do that as a side effect.
+ */
+export declare function applyGroupModel(cfg: PiTaskConfig, group: ChildGroup, chosen: string, catalog: ModelCatalog): void;
+/**
+ * The levels a row may offer, given the model that row's group will run on.
+ *
+ * The INTERSECTION with `REASONING_SETTINGS`, not `supportedThinkingLevels`
+ * directly: that returns the whole ladder including `xhigh` and `max`, which
+ * this menu excludes on purpose (see reasoning.ts) because pi's own UI may not
+ * offer them. A model declaring `xhigh` must not smuggle it in here.
+ */
+export declare function offeredLevels(facts: ReasoningModelFacts | undefined): GroupSetting[];
+export declare function reasoningItems(catalog?: ModelCatalog): ConfigItem[];
 /**
  * Apply one group row's new value.
  *
@@ -142,7 +213,7 @@ export declare function reasoningItems(): ConfigItem[];
  * it, nudging `research` while in `off` would silently return every other group
  * to whatever the stored table happened to hold.
  */
-export declare function applyReasoningLevel(cfg: PiTaskConfig, group: ReasoningGroup, chosen: string): void;
+export declare function applyReasoningLevel(cfg: PiTaskConfig, group: ChildGroup, chosen: string): void;
 /**
  * Tallest body the settings list can render, so {@link BorderedBox} can pad
  * every frame to it and hold the border still. Mirrors SettingsList's own
@@ -157,11 +228,26 @@ export type PanelItem = {
     description: string;
     currentValue: string;
     /**
-     * Omitted ONLY by a section header. SettingsList cycles a row on Enter when
-     * this is a non-empty array, so leaving it off is what makes a header inert
-     * — the header does not need its own branch anywhere.
+     * The values a cycling row steps through. A section header carries none.
+     *
+     * It is NOT what marks a header any more — {@link isSectionRow} reads the id
+     * for that. A model row legitimately has both a `values` list and a
+     * `submenu`, so "no values" and "not a row" stopped being the same fact the
+     * moment pickers existed.
      */
     values?: string[];
+    /**
+     * Enter-time options for a picker row, already closed over the draft config
+     * by {@link renderRows}.
+     *
+     * Deliberately NOT called `submenu`: pi-tui's `SettingItem.submenu` is a
+     * COMPONENT FACTORY, and a PanelItem is handed to `SettingsList` directly by
+     * tests and by the headless path. Two different things under one name would
+     * make PanelItem stop being assignable to SettingItem, for no gain.
+     * {@link createSettingsPanel} is where a theme exists, so it is where these
+     * options become a component.
+     */
+    submenuOptions?: () => SelectItem[];
     /**
      * What the headless one-line rendering calls this row, when `label` reads
      * only in the panel. A tree branch means nothing on a line of `|`-joined
@@ -198,11 +284,11 @@ onChange: (id: string, newValue: string, list: SettingsList) => void, onCancel:
  * Fixed rows come before discovered ones within a section, so a freshly
  * installed extension appends rather than reshuffling the menu.
  */
-export declare function configRows(installed: InstalledExtension[], tools?: readonly GuardableTool[]): ConfigItem[];
+export declare function configRows(installed: InstalledExtension[], tools?: readonly GuardableTool[], catalog?: ModelCatalog): ConfigItem[];
 /** Render `rows` for the current config, grouped under their section headers. */
 export declare function renderRows(cfg: PiTaskConfig, rows: readonly ConfigItem[]): PanelItem[];
 /** The full settings row list for the current config, in menu order. */
-export declare function panelItems(cfg: PiTaskConfig, installed: InstalledExtension[], tools?: readonly GuardableTool[]): PanelItem[];
+export declare function panelItems(cfg: PiTaskConfig, installed: InstalledExtension[], tools?: readonly GuardableTool[], catalog?: ModelCatalog): PanelItem[];
 /**
  * Re-ask every row what it now displays, and write the answers back.
  *