@gtrabanco/pi-agentic-workflow 0.7.2 → 0.8.0

package/README.es.md

@@ -74,7 +74,7 @@ Dos archivos JSON, ambos opcionales:
 {
   "default": { "model": "anthropic/claude-opus-4-5", "thinking": "high" },
   "commands": {
-    "plan-feature": { "model": "anthropic/claude-sonnet-4-5", "thinking": "medium" },
+    "plan-feature": { "model": ["anthropic/claude-sonnet-4-5", "openai/gpt-5.2"], "thinking": "medium" },
     "review-change": { "thinking": "max" }
   },
   "onUnavailableRoute": "stop"
@@ -87,8 +87,14 @@ de arriba usa el modelo del default con thinking `max`; todo lo demás corre con
 que ya tuviera la sesión, porque la ruta por defecto del paquete es
 `{"model": "inherit", "thinking": "inherit"}`.
 
-- `model` debe ser `provider/modelId` — la referencia exacta que muestra
-  `/model` — o `"inherit"`.
+- `model` puede ser `provider/modelId` — la referencia exacta que muestra
+  `/model` — `"inherit"`, o un **array** ordenado de 1–4 referencias (una cadena
+  de respaldo). Para una cadena, el dispatch prueba cada referencia en orden y
+  aplica la primera que se resuelve y tiene credenciales, sin tocar la sesión
+  mientras prueba; cuando todas las entradas son inservibles el comando se
+  detiene (o, con `onUnavailableRoute` en `inherit`, avisa y corre con el modelo
+  actual), nombrando cada candidato y por qué se saltó. `plan-feature` de arriba
+  prueba `anthropic/claude-sonnet-4-5` primero y luego `openai/gpt-5.2`.
 - `thinking` es uno de `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`,
   o `"inherit"`.
 - Claves desconocidas, `null` y referencias mal formadas se **rechazan**, no se
@@ -125,11 +131,24 @@ vuelve.
 /agentic-workflow-settings
 ```
 
+`/aw-settings` es un atajo para la misma consola.
+
 Muestra en qué corre cada comando ahora mismo, y qué archivo se niega a parsearse,
 y luego deja editar **un archivo a la vez** y guardar en alcance global o de
 proyecto. No guarda encima de un archivo que no sabe leer, y no toca el
 archivo de proyecto mientras el proyecto no sea de confianza.
 
+Los selectores de modelo y thinking de la consola son buscables y con ventana:
+escribir estrecha la lista, el cursor se queda en pantalla, un indicador de
+posición muestra dónde estás y el valor en vigor viene preseleccionado y
+etiquetado `(current)` / `(default route)`. Una edición de ruta pregunta qué
+campo cambiar (model, thinking), así que guardar sin cambios deja el archivo
+byte a byte idéntico; el campo de modelo puede construir una cadena de respaldo
+ordenada (`a/m1 → b/m2`); y una sola pasada puede aplicar o limpiar una ruta en
+varios comandos, avisando por comando cuando una referencia falta del registro
+vivo. Fuera de una sesión TUI los selectores caen a un prompt simple, así que la
+consola nunca se queda sin salida.
+
 ## Diagnóstico
 
 | Ves | Significa |

package/README.md

@@ -72,7 +72,7 @@ Two JSON files, both optional:
 {
   "default": { "model": "anthropic/claude-opus-4-5", "thinking": "high" },
   "commands": {
-    "plan-feature": { "model": "anthropic/claude-sonnet-4-5", "thinking": "medium" },
+    "plan-feature": { "model": ["anthropic/claude-sonnet-4-5", "openai/gpt-5.2"], "thinking": "medium" },
     "review-change": { "thinking": "max" }
   },
   "onUnavailableRoute": "stop"
@@ -85,8 +85,14 @@ above runs on the default model with `max` thinking; anything else runs on
 whatever the session already had, because the shipped default route is
 `{"model": "inherit", "thinking": "inherit"}`.
 
-- `model` must be `provider/modelId` — the exact reference `/model` shows — or
-  `"inherit"`.
+- `model` can be `provider/modelId` — the exact reference `/model` shows —
+  `"inherit"`, or an ordered **array** of 1–4 references (a fallback chain). For
+  a chain, dispatch probes each reference in order and applies the first one that
+  resolves and has credentials, without touching the session while probing; when
+  every entry is unusable the command stops (or, with `onUnavailableRoute`
+  `inherit`, warns and runs on the current model), naming each candidate and why
+  it was skipped. `plan-feature` above tries `anthropic/claude-sonnet-4-5` first,
+  then `openai/gpt-5.2`.
 - `thinking` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`,
   or `"inherit"`.
 - Unknown keys, `null`s and malformed references are **rejected**, not ignored: a
@@ -120,10 +126,22 @@ thinking level and you keep it while the model still comes back.
 /agentic-workflow-settings
 ```
 
+`/aw-settings` is a shorthand for the same console.
+
 Shows what each command runs on right now, and which file is refusing to parse,
 then lets you edit **one file at a time** and save to global or project scope. It will not save over a file it cannot parse, and it will not
 touch the project file while the project is untrusted.
 
+The console's model and thinking pickers are searchable and windowed: typing
+narrows the list, the cursor stays on screen, a position indicator shows where
+you are, and the value currently in force is pre-selected and labelled
+`(current)` / `(default route)`. A route edit asks which field to change
+(model, thinking), so a no-change save leaves the file byte-identical; the
+model field can build an ordered fallback chain (`a/m1 → b/m2`); and one pass
+can apply or clear a route across several commands, warning per command when a
+reference is missing from the live registry. Outside a TUI session the pickers
+fall back to a plain prompt, so the console never dead-ends.
+
 ## Troubleshooting
 
 | You see | Means |

package/dist/config/schema.js

@@ -1,4 +1,4 @@
-import { THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "./types.js";
+import { MAX_MODEL_CHAIN, THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "./types.js";
 /**
  * Strict validator for one config file (SPEC S5-S8, D-E5).
  *
@@ -52,6 +52,37 @@ function checkRoute(value, path, issues) {
             continue;
         }
         if (key === "model") {
+            if (Array.isArray(entry)) {
+                // A chain must be non-empty, hold only references, and stay within the cap.
+                if (entry.length === 0) {
+                    issues.push({
+                        path: `${path}.model`,
+                        message: `must be "inherit", "provider/modelId", or a non-empty chain of references, got an empty array`,
+                    });
+                    continue;
+                }
+                if (entry.length > MAX_MODEL_CHAIN) {
+                    issues.push({
+                        path: `${path}.model`,
+                        message: `chain holds ${entry.length} entries; ${MAX_MODEL_CHAIN} is the maximum`,
+                    });
+                    continue;
+                }
+                let chainValid = true;
+                for (let index = 0; index < entry.length; index += 1) {
+                    if (!isModelReference(entry[index])) {
+                        issues.push({
+                            path: `${path}.model`,
+                            message: `chain entry ${index + 1} (${describe(entry[index])}) must be "provider/modelId"`,
+                        });
+                        chainValid = false;
+                        break;
+                    }
+                }
+                if (chainValid)
+                    route.model = entry;
+                continue;
+            }
             if (entry !== "inherit" && !isModelReference(entry)) {
                 issues.push({
                     path: `${path}.model`,

package/dist/config/types.d.ts

@@ -14,7 +14,16 @@ export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 export type ThinkingSetting = ThinkingLevel | "inherit";
 /** `"inherit"` or an exact `provider/modelId` reference (split at the first slash). */
 export type ModelRef = `${string}/${string}`;
-export type ModelSetting = "inherit" | ModelRef;
+/** An ordered fallback chain of references; the first resolvable + configured entry wins (issue #154, root cause E). */
+export type ModelChain = readonly ModelRef[];
+/**
+ * `"inherit"`, one reference, or an ordered fallback chain of 1–4 references.
+ * A chain is probed by order, and the first entry that resolves AND has
+ * configured auth is applied (OB-6, OB-8, OB-9).
+ */
+export type ModelSetting = "inherit" | ModelRef | ModelChain;
+/** Cap on chain length (issue deliberation: 8 was "almost certainly a mistake"; 4 keeps the view readable). */
+export declare const MAX_MODEL_CHAIN = 4;
 export interface Route {
     model: ModelSetting;
     thinking: ThinkingSetting;

package/dist/config/types.js

@@ -9,4 +9,6 @@
  */
 /** Pi's thinking levels, mirrored here so the domain layer stays Pi-free. */
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+/** Cap on chain length (issue deliberation: 8 was "almost certainly a mistake"; 4 keeps the view readable). */
+export const MAX_MODEL_CHAIN = 4;
 export const UNAVAILABLE_ROUTE_POLICIES = ["stop", "inherit"];

package/dist/extension/factory.js

@@ -1,7 +1,7 @@
 import { loadConfig } from "../config/load.js";
 import { readCatalogue } from "../routing/catalogue.js";
 import { createRouter } from "../routing/dispatch.js";
-import { SETTINGS_COMMAND } from "../routing/types.js";
+import { SETTINGS_COMMAND, SETTINGS_COMMAND_ALIAS } from "../routing/types.js";
 export function createExtension(deps) {
     const { registrar, surface, skillsDir, agentDir, hint, settings } = deps;
     const catalogue = readCatalogue(skillsDir);
@@ -18,7 +18,11 @@ export function createExtension(deps) {
             ctx.notify(`pi-agentic-workflow: skills/${issue.dir}: ${issue.message}`, "warning");
         }
     };
-    const knownCommands = new Set([...catalogue.commands.map((entry) => entry.name), SETTINGS_COMMAND]);
+    const knownCommands = new Set([
+        ...catalogue.commands.map((entry) => entry.name),
+        SETTINGS_COMMAND,
+        SETTINGS_COMMAND_ALIAS,
+    ]);
     const router = createRouter({ surface, loadConfig: read, hint, settingsCommand: SETTINGS_COMMAND, knownCommands });
     for (const command of catalogue.commands) {
         registrar.registerCommand(command.name, {
@@ -29,21 +33,28 @@ export function createExtension(deps) {
             },
         });
     }
+    // One handler for both names — `/aw-settings` is a pointer to the same console
+    // and the same two config files, never a separate route surface (OB-5, AC6).
+    const settingsHandler = async (_args, ctx) => {
+        reportCatalogueIssues(ctx);
+        // Bound for the console: two verbs and the session they act on, so it cannot
+        // reach for `settle` or `dispatch` by accident.
+        const routing = { inFlight: () => router.inFlight(), undoInFlight: () => router.undoInFlight(ctx) };
+        try {
+            await settings({ catalogue, ctx, routing });
+        }
+        catch (error) {
+            // A console that dies mid-question must say so, not take the session down.
+            ctx.notify(`Settings could not be opened: ${error.message}`, "error");
+        }
+    };
     registrar.registerCommand(SETTINGS_COMMAND, {
         description: "Show and configure per-command model routing",
-        handler: async (_args, ctx) => {
-            reportCatalogueIssues(ctx);
-            // Bound for the console: two verbs and the session they act on, so it cannot
-            // reach for `settle` or `dispatch` by accident.
-            const routing = { inFlight: () => router.inFlight(), undoInFlight: () => router.undoInFlight(ctx) };
-            try {
-                await settings({ catalogue, ctx, routing });
-            }
-            catch (error) {
-                // A console that dies mid-question must say so, not take the session down.
-                ctx.notify(`Settings could not be opened: ${error.message}`, "error");
-            }
-        },
+        handler: settingsHandler,
+    });
+    registrar.registerCommand(SETTINGS_COMMAND_ALIAS, {
+        description: "Show and configure per-command model routing",
+        handler: settingsHandler,
     });
     return { router, catalogue };
 }

package/dist/extension/index.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "../config/load.js";
 import { createExtension } from "./factory.js";
+import { createPickerComponent, PICKER_MAX_VISIBLE } from "../settings/picker.js";
 import { createHintStore, stateFilePath } from "../routing/state.js";
 import { runSettingsConsole } from "../settings/console.js";
 import { readConfigFile, writeConfigFile } from "../settings/store.js";
@@ -20,6 +21,48 @@ import { SETTINGS_COMMAND } from "../routing/types.js";
  */
 const skillsDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
 const thinkingLevelsInSyncWithPi = true;
+/**
+ * The interactive slice the settings console sees: Pi's own `ui` plus the rich
+ * picker (P4). The picker is terminal-only, so a non-TUI mode (headless/RPC)
+ * gets the plain `select` path — the console never dead-ends (OB-12, PE-004).
+ */
+function richUi(ctx) {
+    const base = ctx.ui;
+    return {
+        select: (title, options) => base.select(title, [...options]),
+        input: (title, placeholder) => base.input(title, placeholder),
+        confirm: (title, message) => base.confirm(title, message),
+        notify: (message, kind) => base.notify(message, kind),
+        pick: async (title, options, opts = {}) => {
+            if (ctx.mode !== "tui") {
+                const picked = await base.select(title, [...options]);
+                if (opts.multiple)
+                    return picked ? [picked] : undefined;
+                return picked;
+            }
+            const items = options.map((value) => ({ value, label: value }));
+            const result = await base.custom((_tui, theme, _keybindings, done) => {
+                const selectListTheme = {
+                    selectedPrefix: (text) => theme.bold(`› ${text}`),
+                    selectedText: (text) => theme.inverse(text),
+                    description: (text) => `  ${text}`,
+                    scrollInfo: (text) => theme.bold(text),
+                    noMatch: (text) => theme.italic(text),
+                };
+                return createPickerComponent({
+                    items,
+                    maxVisible: PICKER_MAX_VISIBLE,
+                    theme: selectListTheme,
+                    onSelect: (value) => done(value),
+                    onCancel: () => done(undefined),
+                });
+            }, { overlay: true });
+            if (opts.multiple)
+                return result === undefined ? undefined : [result];
+            return result;
+        },
+    };
+}
 function toInvocationContext(ctx) {
     return {
         cwd: ctx.cwd,
@@ -29,7 +72,7 @@ function toInvocationContext(ctx) {
         isIdle: () => ctx.isIdle(),
         isProjectTrusted: () => ctx.isProjectTrusted(),
         notify: (message, kind) => ctx.ui.notify(message, kind),
-        ui: ctx.ui,
+        ui: richUi(ctx),
         availableModels: () => ctx.modelRegistry.getAll(),
         find: (provider, modelId) => ctx.modelRegistry.find(provider, modelId),
         hasConfiguredAuth: (model) => ctx.modelRegistry.hasConfiguredAuth(model),

package/dist/routing/dispatch.js

@@ -111,7 +111,13 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
             const session = surface(ctx);
             const route = effectiveRoute(loaded.config, command.name);
             let target;
-            if (route.model !== "inherit") {
+            /** The reference string behind `target`, for the select-failure message (a chain names the chosen entry). */
+            let chosenRef;
+            if (route.model === "inherit") {
+                // inherit: no probe — run on the session model (OB-9).
+            }
+            else if (typeof route.model === "string") {
+                // Single reference: behaviour and message shape unchanged (OB-9).
                 const reference = parseModelReference(route.model);
                 const found = reference ? ctx.find(reference.provider, reference.id) : undefined;
                 const blocker = !found
@@ -127,6 +133,36 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
                 }
                 else {
                     target = found;
+                    chosenRef = route.model;
+                }
+            }
+            else {
+                // Chain: probe entries in order with only ctx.find + hasConfiguredAuth
+                // (no session mutation), collecting one skip reason per entry, and apply
+                // the first usable one (OB-8, OB-9, OB-10).
+                const reasons = [];
+                for (const reference of route.model) {
+                    const parsed = parseModelReference(reference);
+                    const found = parsed ? ctx.find(parsed.provider, parsed.id) : undefined;
+                    if (!found) {
+                        reasons.push(`${reference} is not in the model registry`);
+                        continue;
+                    }
+                    if (!ctx.hasConfiguredAuth(found)) {
+                        reasons.push(`${reference} has no configured credentials`);
+                        continue;
+                    }
+                    target = found;
+                    chosenRef = reference;
+                    break;
+                }
+                if (!target) {
+                    const tried = route.model.join(", ");
+                    const detail = reasons.join("; ");
+                    if (loaded.config.onUnavailableRoute !== "inherit") {
+                        return refuse(ctx, "unavailable-route", `/${command.name} stopped: the configured model chain ${tried} is unavailable (${detail}). ${configureHint}`);
+                    }
+                    ctx.notify(`/${command.name}: the configured model chain ${tried} is unavailable (${detail}), so it runs on the current session model. ${configureHint}`, "warning");
                 }
             }
             const snapshot = { model: ctx.model, thinking: session.getThinkingLevel() };
@@ -135,9 +171,9 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
                 const selected = await session.setModel(target);
                 if (!selected) {
                     if (loaded.config.onUnavailableRoute !== "inherit") {
-                        return refuse(ctx, "unavailable-route", `/${command.name} stopped: ${route.model} could not be selected. ${configureHint}`);
+                        return refuse(ctx, "unavailable-route", `/${command.name} stopped: ${chosenRef} could not be selected. ${configureHint}`);
                     }
-                    ctx.notify(`/${command.name}: ${route.model} could not be selected, so it runs on the current session model. ${configureHint}`, "warning");
+                    ctx.notify(`/${command.name}: ${chosenRef} could not be selected, so it runs on the current session model. ${configureHint}`, "warning");
                 }
                 else {
                     applied.model = target;

package/dist/routing/types.d.ts

@@ -39,12 +39,25 @@ export interface ExtensionSurface<M extends ModelRef = ModelRef> {
     getThinkingLevel(): ThinkingLevel;
     setThinkingLevel(level: ThinkingLevel): void;
 }
+/** Options for the optional rich picker (OB-1, OB-3, P4/P6). */
+export interface PickerOptions {
+    /** The value already in force, preselected when the picker opens (OB-3). */
+    initial?: string;
+    /** Allow selecting several entries (bulk apply/clear, P6). */
+    multiple?: boolean;
+}
 /** The interactive slice of `ctx.ui` the settings console uses (AC10). */
 export interface SettingsUi {
     select(title: string, options: readonly string[]): Promise<string | undefined> | string | undefined;
     input(title: string, placeholder?: string): Promise<string | undefined> | string | undefined;
     confirm(title: string, message: string): Promise<boolean> | boolean;
     notify(message: string, kind?: "info" | "warning" | "error"): void;
+    /**
+     * Optional rich picker: filterable, windowed, with a position indicator and a
+     * preselected current value. A structural superset — a caller without it
+     * falls back to `select`/`input`. Returns `readonly string[]` when `multiple`.
+     */
+    pick?(title: string, options: readonly string[], opts?: PickerOptions): Promise<string | readonly string[] | undefined> | string | readonly string[] | undefined;
 }
 /**
  * Everything a command handler needs from the invocation, reduced to what we
@@ -78,6 +91,8 @@ export type DispatchOutcome = {
 };
 /** Slash name of the settings console (SPEC S4, AC3, AC10). */
 export declare const SETTINGS_COMMAND = "agentic-workflow-settings";
+/** Shorthand alias for the same console — a pointer to the same handler, never a separate route (OB-5, AC6). */
+export declare const SETTINGS_COMMAND_ALIAS = "aw-settings";
 /**
  * The router, as the settings console needs it: two verbs, already bound to the
  * session they act on. Declared once because both the console's deps and the

package/dist/routing/types.js

@@ -1,3 +1,5 @@
 export const modelRefKey = (model) => `${model.provider}/${model.id}`;
 /** Slash name of the settings console (SPEC S4, AC3, AC10). */
 export const SETTINGS_COMMAND = "agentic-workflow-settings";
+/** Shorthand alias for the same console — a pointer to the same handler, never a separate route (OB-5, AC6). */
+export const SETTINGS_COMMAND_ALIAS = "aw-settings";

package/dist/settings/console.d.ts

@@ -45,11 +45,22 @@ export declare const prompts: {
     readonly setDefaultRoute: "Set the default route";
     readonly setOverride: "Set a command override";
     readonly clearOverride: "Clear a command override";
+    readonly bulkApply: "Apply one route to several commands";
+    readonly bulkClear: "Clear several overrides";
+    readonly addAnother: "Add another?";
     readonly policy: "Set the unavailable-route policy";
     readonly save: "Save";
     readonly cancel: "Cancel";
     readonly model: (target: string) => string;
     readonly modelPicked: (target: string) => string;
     readonly thinking: (target: string) => string;
+    readonly fields: "Which fields should change?";
+    readonly fieldsBoth: "model and thinking";
+    readonly fieldsModel: "model only";
+    readonly fieldsThinking: "thinking only";
+    readonly chainAction: (target: string) => string;
+    readonly chainAppend: "Add a fallback";
+    readonly chainRemoveLast: "Remove the last";
+    readonly chainDone: "Done";
 };
 export declare function runSettingsConsole(deps: SettingsDeps): Promise<ConsoleOutcome>;

package/dist/settings/console.js

@@ -8,8 +8,9 @@
 // the operator must fix, not noise to clobber), and the project scope is refused
 // while the project is untrusted — the same gate the loader applies (AC13).
 import { loadConfig, configFilePaths } from "../config/load.js";
+import { effectiveRoute } from "../config/merge.js";
 import { parseConfigFile, parseModelReference } from "../config/schema.js";
-import { THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "../config/types.js";
+import { MAX_MODEL_CHAIN, THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "../config/types.js";
 import { renderMergedConfig, routePath, DEFAULT_ROUTE } from "./view.js";
 /** The console's questions. `test/settings-console.test.mjs` drives the flow
  * through these strings, so renaming one fails the tests that use it rather than
@@ -27,12 +28,23 @@ export const prompts = {
     setDefaultRoute: "Set the default route",
     setOverride: "Set a command override",
     clearOverride: "Clear a command override",
+    bulkApply: "Apply one route to several commands",
+    bulkClear: "Clear several overrides",
+    addAnother: "Add another?",
     policy: "Set the unavailable-route policy",
     save: "Save",
     cancel: "Cancel",
     model: (target) => `Model for ${target}?`,
     modelPicked: (target) => `Which model for ${target}?`,
     thinking: (target) => `Thinking level for ${target}?`,
+    fields: "Which fields should change?",
+    fieldsBoth: "model and thinking",
+    fieldsModel: "model only",
+    fieldsThinking: "thinking only",
+    chainAction: (target) => `Model chain for ${target}?`,
+    chainAppend: "Add a fallback",
+    chainRemoveLast: "Remove the last",
+    chainDone: "Done",
 };
 const GLOBAL_LABEL = "Global";
 const PROJECT_LABEL = "Project";
@@ -40,7 +52,10 @@ const TYPED = "Type another reference…";
 const INHERIT = "inherit";
 export async function runSettingsConsole(deps) {
     const paths = configFilePaths(deps.agentDir, deps.cwd);
-    deps.ui.notify(renderMergedConfig(loadConfig({ agentDir: deps.agentDir, cwd: deps.cwd, projectTrusted: deps.projectTrusted, readFile: deps.readFile }), deps.commands).join("\n"), "info");
+    const merged = loadConfig({ agentDir: deps.agentDir, cwd: deps.cwd, projectTrusted: deps.projectTrusted, readFile: deps.readFile });
+    deps.ui.notify(renderMergedConfig(merged, deps.commands).join("\n"), "info");
+    /** The value in force for a target (the merged route, or the default when the target is "the default route"). */
+    const currentFor = (target) => effectiveRoute(merged.config, target);
     const opened = await openAScope(deps, paths.global, paths.project);
     if (!opened)
         return { status: "cancelled", edited: false };
@@ -53,6 +68,8 @@ export async function runSettingsConsole(deps) {
             prompts.setDefaultRoute,
             prompts.setOverride,
             prompts.clearOverride,
+            prompts.bulkApply,
+            prompts.bulkClear,
             prompts.policy,
             ...(deps.routing?.inFlight() ? [prompts.undoInFlight] : []),
             prompts.save,
@@ -67,7 +84,7 @@ export async function runSettingsConsole(deps) {
             return { status: "cancelled", edited: dirty(draft, original) ? await discard(deps.ui) : false };
         }
         if (choice === prompts.setDefaultRoute) {
-            const edited = await editRoute(deps, DEFAULT_ROUTE);
+            const edited = await editRoute(deps, DEFAULT_ROUTE, currentFor(DEFAULT_ROUTE));
             if (edited)
                 draft = { ...draft, default: edited };
             continue;
@@ -76,7 +93,7 @@ export async function runSettingsConsole(deps) {
             const name = await pickCommand(deps, commandChoices(deps, draft));
             if (name === undefined)
                 continue;
-            const route = await editRoute(deps, name);
+            const route = await editRoute(deps, name, currentFor(name));
             if (route)
                 draft = { ...draft, commands: { ...draft.commands, [name]: route } };
             continue;
@@ -90,6 +107,35 @@ export async function runSettingsConsole(deps) {
             draft = { ...draft, commands: rest };
             continue;
         }
+        if (choice === prompts.bulkApply) {
+            // One field pass (model via the chain builder + thinking), applied to every
+            // selected command. A reference missing from the live registry warns per
+            // command but never blocks the write (OB-4 — dispatch's probe stays the
+            // authoritative availability gate).
+            const selected = await pickCommandsMulti(deps, commandChoices(deps, draft));
+            if (selected === undefined || selected.length === 0)
+                continue;
+            const route = await editRoute(deps, selected[0], currentFor(selected[0]));
+            if (route === undefined)
+                continue;
+            const nextCommands = { ...draft.commands };
+            for (const name of selected) {
+                nextCommands[name] = route;
+                warnMissingModel(deps, name, route.model ?? INHERIT);
+            }
+            draft = { ...draft, commands: nextCommands };
+            continue;
+        }
+        if (choice === prompts.bulkClear) {
+            const names = await pickCommandsMulti(deps, Object.keys(draft.commands ?? {}));
+            if (names === undefined || names.length === 0)
+                continue;
+            const rest = { ...draft.commands };
+            for (const name of names)
+                delete rest[name];
+            draft = { ...draft, commands: rest };
+            continue;
+        }
         if (choice === prompts.policy) {
             const picked = await deps.ui.select(prompts.policyChoice, [...UNAVAILABLE_ROUTE_POLICIES]);
             if (isPolicy(picked))
@@ -133,18 +179,54 @@ async function openAScope(deps, globalPath, projectPath) {
     }
 }
 /** Ask for a model and a thinking level; `undefined` means nothing changed. */
-async function editRoute(deps, target) {
-    const model = await askModel(deps, target);
-    if (model === undefined)
-        return undefined;
-    const thinking = await askThinking(deps, target);
-    if (thinking === undefined)
-        return undefined;
-    return { model, thinking };
+async function editRoute(deps, target, current) {
+    const fields = await askFields(deps);
+    if (fields === undefined)
+        return undefined; // nothing marked — the route is left untouched (OB-3)
+    // Start from the value in force so only the marked field is replaced; the other
+    // keeps its merged value (AC4: changing only model asks no thinking question).
+    const route = {
+        ...(current.model !== undefined ? { model: current.model } : {}),
+        ...(current.thinking !== undefined ? { thinking: current.thinking } : {}),
+    };
+    if (fields.model) {
+        const model = await askModel(deps, target, current.model);
+        if (model === undefined)
+            return undefined;
+        route.model = model;
+    }
+    if (fields.thinking) {
+        const thinking = await askThinking(deps, target, current.thinking);
+        if (thinking === undefined)
+            return undefined;
+        route.thinking = thinking;
+    }
+    return route;
+}
+/** Which fields the operator wants to change; `undefined` means none (leave untouched). */
+async function askFields(deps) {
+    const choice = await deps.ui.select(prompts.fields, [prompts.fieldsBoth, prompts.fieldsModel, prompts.fieldsThinking]);
+    if (choice === prompts.fieldsBoth)
+        return { model: true, thinking: true };
+    if (choice === prompts.fieldsModel)
+        return { model: true, thinking: false };
+    if (choice === prompts.fieldsThinking)
+        return { model: false, thinking: true };
+    return undefined;
 }
-async function askModel(deps, target) {
+/** Ask for one model entry; `undefined` means cancelled/skipped, `"inherit"` means the whole-route setting. */
+async function pickModelEntry(deps, target, current) {
     let answer;
-    if (deps.models && deps.models.length > 0) {
+    if (typeof deps.ui.pick === "function" && deps.models && deps.models.length > 0) {
+        // Rich seam: filterable, windowed, preselected to the value in force (OB-1).
+        const picked = await deps.ui.pick(prompts.modelPicked(target), [...deps.models, TYPED], {
+            initial: typeof current === "string" ? current : undefined,
+        });
+        answer = typeof picked === "string" ? picked : undefined;
+        if (answer === TYPED || answer === undefined)
+            answer = await deps.ui.input(prompts.model(target), "provider/modelId or inherit");
+    }
+    else if (deps.models && deps.models.length > 0) {
         answer = await deps.ui.select(prompts.modelPicked(target), [...deps.models, TYPED]);
         if (answer === TYPED || answer === undefined)
             answer = await deps.ui.input(prompts.model(target), "provider/modelId or inherit");
@@ -157,17 +239,80 @@ async function askModel(deps, target) {
     const value = answer.trim();
     if (value === INHERIT)
         return INHERIT;
-    if (!/^[^/\s]+\/[^/\s]+$/.test(value)) {
+    const parts = parseModelReference(value);
+    if (!parts) {
         // Rejected in the operator's terms and in the schema's: the value, and the
         // field path the loader would name for the same mistake in a file (AC5).
         deps.ui.notify(`Rejected: model must be "provider/modelId" or "inherit" — nothing was changed (${routePath(target)}.model).`, "error");
         return undefined;
     }
-    const parts = parseModelReference(value);
-    return parts ? `${parts.provider}/${parts.id}` : undefined;
+    return `${parts.provider}/${parts.id}`;
+}
+/** Ask for a model; a lone reference is returned as-is, several references are returned as an ordered chain. */
+async function askModel(deps, target, current) {
+    // The value in force (OB-3). For a route whose model is already a chain, seed
+    // the builder with the current references so the operator sees and edits the
+    // chain instead of rebuilding it blind (OB-17 / F2, amendment A1). Fresh and
+    // single-string editing keep the existing flow: the picker is preselected to
+    // the string value in force.
+    const seed = Array.isArray(current) ? [...current] : [];
+    if (seed.length > 0) {
+        // Already a chain: label the current chain, then let the operator append,
+        // trim, or keep it. Done with no change leaves the chain byte-identical.
+        deps.ui.notify(`Current ${target} model chain: ${seed.join(" → ")}`, "info");
+        return buildModelChain(deps, target, [...seed]);
+    }
+    const first = await pickModelEntry(deps, target, typeof current === "string" ? current : undefined);
+    if (first === undefined)
+        return undefined;
+    if (first === INHERIT)
+        return INHERIT;
+    return buildModelChain(deps, target, [first]);
 }
-async function askThinking(deps, target) {
-    const answer = await deps.ui.select(prompts.thinking(target), [...THINKING_LEVELS, INHERIT]);
+/** Drive the ordered chain builder over the given starting chain; a single entry collapses to a bare reference. */
+async function buildModelChain(deps, target, chain) {
+    for (;;) {
+        const atCap = chain.length >= MAX_MODEL_CHAIN;
+        if (atCap) {
+            deps.ui.notify(`A model chain is capped at ${MAX_MODEL_CHAIN} references — remove the last to make room (${routePath(target)}.model).`, "info");
+        }
+        const action = await deps.ui.select(prompts.chainAction(target), [
+            ...(atCap ? [] : [prompts.chainAppend]),
+            prompts.chainRemoveLast,
+            prompts.chainDone,
+        ]);
+        if (action === prompts.chainAppend) {
+            const next = await pickModelEntry(deps, target);
+            if (next === undefined)
+                continue;
+            if (next === INHERIT) {
+                deps.ui.notify(`Only "provider/modelId" references can be chain entries; "inherit" is a whole-route setting (${routePath(target)}.model).`, "error");
+                continue;
+            }
+            chain.push(next);
+        }
+        else if (action === prompts.chainRemoveLast) {
+            if (chain.length > 1)
+                chain.pop();
+        }
+        else {
+            break;
+        }
+    }
+    return chain.length === 1 ? chain[0] : chain;
+}
+async function askThinking(deps, target, current) {
+    const options = [...THINKING_LEVELS, INHERIT];
+    let answer;
+    if (typeof deps.ui.pick === "function") {
+        const picked = await deps.ui.pick(prompts.thinking(target), options, {
+            initial: typeof current === "string" ? current : undefined,
+        });
+        answer = typeof picked === "string" ? picked : undefined;
+    }
+    else {
+        answer = await deps.ui.select(prompts.thinking(target), options);
+    }
     if (answer === undefined)
         return undefined;
     if (answer === INHERIT || isThinkingLevel(answer))
@@ -182,6 +327,45 @@ async function pickCommand(deps, options) {
     }
     return deps.ui.select(prompts.command, [...options].sort((a, b) => a.localeCompare(b)));
 }
+/** Multi-select command picker over the seam's `multiple` mode; a non-rich UI falls back to repeated single selects. */
+async function pickCommandsMulti(deps, options) {
+    if (options.length === 0) {
+        deps.ui.notify("There is no command to pick here.", "warning");
+        return undefined;
+    }
+    const sorted = [...options].sort((a, b) => a.localeCompare(b));
+    if (typeof deps.ui.pick === "function") {
+        const picked = await deps.ui.pick(prompts.command, sorted, { multiple: true });
+        if (picked === undefined)
+            return undefined;
+        return typeof picked === "string" ? [picked] : picked;
+    }
+    // Non-rich fallback: repeatedly select one candidate until the operator stops.
+    const chosen = [];
+    for (;;) {
+        const remaining = sorted.filter((option) => !chosen.includes(option));
+        if (remaining.length === 0)
+            break;
+        const picked = await deps.ui.select(prompts.command, remaining);
+        if (picked === undefined)
+            break;
+        chosen.push(picked);
+        if (!(await deps.ui.confirm(prompts.addAnother, `Picked ${chosen.join(", ")}.`)))
+            break;
+    }
+    return chosen.length > 0 ? chosen : undefined;
+}
+/** Advisory per-command warning when a chosen reference is absent from the live registry (OB-4). */
+function warnMissingModel(deps, target, model) {
+    if (!deps.models || deps.models.length === 0)
+        return;
+    const refs = typeof model === "string" ? [model] : model;
+    for (const ref of refs) {
+        if (ref !== INHERIT && !deps.models.includes(ref)) {
+            deps.ui.notify(`/${target}: ${ref} is not in the live model registry — dispatch will decide availability when the route runs.`, "warning");
+        }
+    }
+}
 function commandChoices(deps, draft) {
     return [...new Set([...deps.commands, ...Object.keys(draft.commands ?? {})])];
 }

package/dist/settings/picker.d.ts

@@ -0,0 +1,31 @@
+import { type Component, type SelectItem, type SelectListTheme } from "@earendil-works/pi-tui";
+/** Default window height for the SelectList (the built-in position indicator scales to the list). */
+export declare const PICKER_MAX_VISIBLE = 10;
+/**
+ * Token/subsequence, slash-aware reference filter (OB-2).
+ *
+ * - An empty query returns every reference.
+ * - The query is split on whitespace; every token must match for a reference to
+ *   survive.
+ * - A token matched as a *subsequence* (characters in order, not necessarily
+ *   contiguous): `flash` matches any reference containing `flash`, `a/c`
+ *   matches `anthropic/claude`.
+ * - A token ending in `/` constrains to the provider: `nan/` matches provider
+ *   `nan` only, never a model id that merely contains `nan`.
+ */
+export declare function filterReferences(query: string, refs: readonly string[]): string[];
+/**
+ * Wrap a `SelectList` as a pi-tui `Component`, rebuilding it client-side from
+ * `filterReferences` as the operator types so the subsequence/slash-aware
+ * filter (OB-2) — not `SelectList`'s own prefix `setFilter` — drives what the
+ * window shows. Control keys (arrows, Enter, Escape) forward to the list.
+ */
+export declare function createPickerComponent(options: {
+    items: readonly SelectItem[];
+    maxVisible: number;
+    theme: SelectListTheme;
+    onSelect: (value: string) => void;
+    onCancel?: () => void;
+}): Component & {
+    dispose?(): void;
+};

package/dist/settings/picker.js

@@ -0,0 +1,93 @@
+// src/settings/picker.ts
+// The searchable windowed picker primitive (OB-1, OB-2, OB-12, PE-004).
+//
+// Two concerns live here on purpose:
+//  - `filterReferences` is the pure, session-free subsequence/slash-aware filter
+//    (OB-2). It is unit-tested in `test/picker-filter.test.mjs`.
+//  - `createPickerComponent` wraps `@earendil-works/pi-tui`'s `SelectList` as a
+//    `Component` so the adapter (extension/index.ts) can drive it through
+//    `ctx.ui.custom()` — windowed rendering with a position indicator, typing
+//    to narrow the list, selection, and cancel. The Pi-free `SettingsUi.pick`
+//    seam stays separated so the filter and the component are exercisable
+//    without a live session.
+//
+// The filter is implemented in this package (not imported from Pi): PE-004
+// confirmed pi-coding-agent's `fuzzyFilter` is internal, so the same
+// token/subsequence, slash-aware semantics the acceptance criteria pin live here.
+import { SelectList } from "@earendil-works/pi-tui";
+/** Default window height for the SelectList (the built-in position indicator scales to the list). */
+export const PICKER_MAX_VISIBLE = 10;
+/**
+ * Token/subsequence, slash-aware reference filter (OB-2).
+ *
+ * - An empty query returns every reference.
+ * - The query is split on whitespace; every token must match for a reference to
+ *   survive.
+ * - A token matched as a *subsequence* (characters in order, not necessarily
+ *   contiguous): `flash` matches any reference containing `flash`, `a/c`
+ *   matches `anthropic/claude`.
+ * - A token ending in `/` constrains to the provider: `nan/` matches provider
+ *   `nan` only, never a model id that merely contains `nan`.
+ */
+export function filterReferences(query, refs) {
+    const tokens = query.trim().split(/\s+/u).filter((token) => token !== "");
+    if (tokens.length === 0)
+        return [...refs];
+    return refs.filter((ref) => tokens.every((token) => matchesToken(token, ref)));
+}
+function matchesToken(token, ref) {
+    // Slash-aware: a trailing slash makes the token a provider prefix.
+    if (token.endsWith("/")) {
+        const provider = token.slice(0, -1);
+        if (provider === "")
+            return true;
+        const refProvider = ref.split("/")[0] ?? "";
+        return refProvider.startsWith(provider);
+    }
+    return isSubsequence(token, ref);
+}
+/** True when `needle` appears in `haystack` with its characters in order. */
+function isSubsequence(needle, haystack) {
+    let i = 0;
+    for (let j = 0; j < haystack.length && i < needle.length; j += 1) {
+        if (haystack.charCodeAt(j) === needle.charCodeAt(i))
+            i += 1;
+    }
+    return i === needle.length;
+}
+/**
+ * Wrap a `SelectList` as a pi-tui `Component`, rebuilding it client-side from
+ * `filterReferences` as the operator types so the subsequence/slash-aware
+ * filter (OB-2) — not `SelectList`'s own prefix `setFilter` — drives what the
+ * window shows. Control keys (arrows, Enter, Escape) forward to the list.
+ */
+export function createPickerComponent(options) {
+    const { items, maxVisible, theme, onSelect, onCancel } = options;
+    let filterText = "";
+    const byValue = new Map(items.map((item) => [item.value, item]));
+    const buildList = () => {
+        const visible = filterReferences(filterText, items.map((item) => item.value)).map((value) => byValue.get(value) ?? { value, label: value });
+        const list = new SelectList(visible, maxVisible, theme);
+        list.onSelect = (item) => onSelect(item.value);
+        list.onCancel = onCancel;
+        return list;
+    };
+    let list = buildList();
+    return {
+        render: (width) => list.render(width),
+        invalidate: () => list.invalidate(),
+        handleInput(data) {
+            // Enter / Ctrl+C / ANSI sequences (arrows) go to the SelectList; any other
+            // single character narrows the in-package filter and rebuilds the window.
+            if (data === "\r" || data === "\u0003" || data.startsWith("\u001b") || data.length > 1) {
+                list.handleInput(data);
+                return;
+            }
+            filterText += data;
+            list = buildList();
+        },
+        dispose: () => {
+            // The SelectList holds no resources beyond the rendered lines.
+        },
+    };
+}

package/dist/settings/view.js

@@ -34,7 +34,10 @@ function configLines(config, commands) {
     ];
 }
 function route(value) {
-    return `${value.model} / ${value.thinking}`;
+    // A chain renders its references in order, with the fallback arrow the spec
+    // names (OB-14); a single reference and `inherit` keep their existing render.
+    const model = Array.isArray(value.model) ? value.model.join(" → ") : value.model;
+    return `${model} / ${value.thinking}`;
 }
 function problems(list) {
     if (list.length === 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",
@@ -54,6 +54,9 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.85.1"
   },
+  "dependencies": {
+    "@earendil-works/pi-tui": "0.85.1"
+  },
   "devDependencies": {
     "@types/node": "24.13.3",
     "typescript": "6"