@gtrabanco/pi-agentic-workflow 0.15.2 → 0.16.0

package/dist/config/types.d.ts

@@ -25,10 +25,38 @@ export type ModelChain = readonly ModelRef[];
 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 declare const PROFILE_FALLBACK_APPLY_TO: readonly ["flow", "command"];
+export type ProfileFallbackApplyTo = (typeof PROFILE_FALLBACK_APPLY_TO)[number];
+export declare const PROFILE_FALLBACK_RESUME: readonly ["continue", "restart"];
+export type ProfileFallbackResume = (typeof PROFILE_FALLBACK_RESUME)[number];
+export interface ProfileFile {
+    default?: RouteFile;
+    commands?: Record<string, RouteFile>;
+}
+export interface ProfileFallbackConfig {
+    applyTo: ProfileFallbackApplyTo;
+    resume: ProfileFallbackResume;
+    retryAfterSeconds: number;
+}
+export declare const DEFAULT_PROFILE_FALLBACK: Readonly<ProfileFallbackConfig>;
+export interface ProfileCandidate {
+    profile: string;
+    builtIn: boolean;
+    route: Route;
+    declared: {
+        model: boolean;
+        thinking: boolean;
+    };
+}
 export interface Route {
     model: ModelSetting;
     thinking: ThinkingSetting;
 }
+/** Feature 63: which route keys a scope actually declared (vs. the shipped inherit). */
+export interface RouteDeclaration {
+    model: boolean;
+    thinking: boolean;
+}
 /** What one config file may declare (SPEC "Config schema"). */
 export interface RouteFile {
     model?: ModelSetting;
@@ -44,6 +72,16 @@ export interface ConfigFile {
     pathProtection?: PathProtectionOverride;
     /** Conductor (advance) knobs (feature 62). */
     advance?: AdvanceConfigFile;
+    /** When true (default), the built-in provider profiles are included in the
+     *  resolution chain (feature 63, AC1). */
+    recommendedModels?: boolean;
+    /** Named user profiles keyed by profile name (feature 63, AC5). */
+    profiles?: Record<string, ProfileFile>;
+    /** Ordered list of profile names to probe; empty means ["default"] only
+     *  (feature 63, AC6). */
+    profileOrder?: string[];
+    /** Partial override for the profile-fallback demotion policy (feature 63). */
+    profileFallback?: Partial<ProfileFallbackConfig>;
 }
 export type UnavailableRoutePolicy = "stop" | "inherit";
 /**
@@ -71,6 +109,20 @@ export interface EffectiveConfig {
      *  mergeConfigs; the shipped DEFAULT_CONFIG predates it and leaves it
      *  absent — consumers fall back to DEFAULT_ADVANCE_CONFIG. */
     advance?: AdvanceConfig;
+    /** Whether the built-in provider profiles (currently only "nan") are
+     *  included in the resolution chain (feature 63, AC1). */
+    recommendedModels: boolean;
+    /** Named user profiles keyed by profile name (feature 63, AC5). */
+    profiles: Record<string, ProfileFile>;
+    /** Ordered list of profile names to probe (feature 63, AC6). */
+    profileOrder: string[];
+    /** The effective profile-fallback demotion policy (feature 63). */
+    profileFallback: ProfileFallbackConfig;
+    /** Feature 63: declaredness of the implicit `default` profile. */
+    declared: {
+        default: RouteDeclaration;
+        commands: Record<string, RouteDeclaration>;
+    };
 }
 export interface ConfigProblem {
     scope: "global" | "project";

package/dist/config/types.js

@@ -11,6 +11,16 @@
 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;
+// ---------------------------------------------------------------------------
+// Model-profiles fields (feature 63)
+// ---------------------------------------------------------------------------
+export const PROFILE_FALLBACK_APPLY_TO = ["flow", "command"];
+export const PROFILE_FALLBACK_RESUME = ["continue", "restart"];
+export const DEFAULT_PROFILE_FALLBACK = {
+    applyTo: "flow",
+    resume: "continue",
+    retryAfterSeconds: 86400,
+};
 export const UNAVAILABLE_ROUTE_POLICIES = ["stop", "inherit"];
 export const SETTLE_POLICIES = ["keep", "restore"];
 /** The shipped advance defaults (mirrors conductor DEFAULT_CONDUCTOR_CONFIG). */

package/dist/extension/conductor-command.d.ts

@@ -11,13 +11,10 @@
 import type { LoadedConfig } from "../config/load.js";
 import type { CommandRegistrar } from "./factory.js";
 import type { InvocationContext, ModelRef } from "../routing/types.js";
+import type { Router } from "../routing/dispatch.js";
 /** Register the native `advance` command on the shared registrar. */
 export declare function registerAdvanceCommand<M extends ModelRef = ModelRef>(registrar: CommandRegistrar<M>, deps: {
-    surface: (ctx: InvocationContext<M>) => {
-        sendUserMessage(content: string, options?: {
-            expandPromptTemplates?: boolean;
-        }): void;
-    };
+    router: Router<M>;
     /** The same bound config reader the router uses (factory's `read`). */
     readConfig: (ctx: InvocationContext<M>) => LoadedConfig;
 }, commandNames: Set<string>): void;

package/dist/extension/conductor-command.js

@@ -56,16 +56,20 @@ export function registerAdvanceCommand(registrar, deps, commandNames) {
             // The effective advance knobs: the merged config when it carries the
             // key, the shipped defaults otherwise.
             let config = { ...DEFAULT_ADVANCE_CONFIG };
+            let resume = "continue";
             try {
                 const loaded = deps.readConfig(ctx);
-                if (loaded.ok && loaded.config.advance)
-                    config = loaded.config.advance;
+                if (loaded.ok) {
+                    if (loaded.config.advance)
+                        config = loaded.config.advance;
+                    resume = loaded.config.profileFallback?.resume ?? "continue";
+                }
             }
             catch {
                 // Config trouble falls back to the shipped advance defaults; the loop
                 // itself is fail-closed on the sensor side anyway.
+                // `resume` stays "continue".
             }
-            const surface = deps.surface(ctx);
             const result = await runConductorLoop({
                 cwd: ctx.cwd,
                 runtimeBin: runtimeBin(),
@@ -77,10 +81,18 @@ export function registerAdvanceCommand(registrar, deps, commandNames) {
                 decide: decideFromEnvelope,
                 invocation: invocationFromDecision,
                 judgeUrgency,
-                sendUserMessage: (invocation) => {
-                    surface.sendUserMessage(invocation, { expandPromptTemplates: true });
-                    return Promise.resolve({ ok: true });
+                sendUserMessage: async (invocation) => {
+                    const match = /^\/skill:(\S+)(?:\s+([\s\S]*))?$/u.exec(invocation);
+                    const verb = match?.[1] ?? invocation.replace(/^\/skill:/u, "").split(" ")[0];
+                    const args = match?.[2] ?? "";
+                    const dispatchResult = await deps.router.dispatch({ name: verb, skill: verb }, args, ctx, { onProfileSwitch: resume });
+                    return {
+                        ok: dispatchResult.status === "dispatched",
+                        ...(dispatchResult.status === "dispatched" && dispatchResult.profileSwitched ? { profileSwitched: dispatchResult.profileSwitched } : {}),
+                        ...(dispatchResult.status === "dispatched" && dispatchResult.deferred ? { deferred: true } : {}),
+                    };
                 },
+                profileResume: resume,
                 gitProbe: () => gitProbe(ctx.cwd),
                 appendRunLog: (line) => appendRunLog(config, ctx.cwd, line),
                 parkInFlight: () => {

package/dist/extension/factory.d.ts

@@ -40,6 +40,8 @@ export interface ExtensionDeps<M extends ModelRef = ModelRef> {
     settings: SettingsHandler<M>;
     /** Overridable so a test can hand the router an in-memory configuration. */
     loadConfig?: (ctx: InvocationContext<M>) => LoadedConfig;
+    /** P4: profile demotion state store (optional — defaults to file-backed). */
+    profileState?: import("../routing/state.js").ProfileStateStore;
 }
 export interface ExtensionHandle<M extends ModelRef = ModelRef> {
     router: Router<M>;

package/dist/extension/factory.js

@@ -4,6 +4,7 @@ import { createRouter } from "../routing/dispatch.js";
 import { dirtyWorktreeWarning, receiptGuard } from "./receipt-guard.js";
 import { ADVANCE_COMMAND, SETTINGS_COMMAND, SETTINGS_COMMAND_ALIAS } from "../routing/types.js";
 import { registerAdvanceCommand } from "./conductor-command.js";
+import { createProfileStateStore, stateFilePath } from "../routing/state.js";
 export function createExtension(deps) {
     const { registrar, surface, skillsDir, agentDir, hint, settings } = deps;
     const catalogue = readCatalogue(skillsDir);
@@ -26,7 +27,9 @@ export function createExtension(deps) {
         SETTINGS_COMMAND,
         SETTINGS_COMMAND_ALIAS,
     ]);
-    const router = createRouter({ surface, loadConfig: read, hint, settingsCommand: SETTINGS_COMMAND, knownCommands });
+    // P4: build the profile state store when not provided.
+    const profileState = deps.profileState ?? createProfileStateStore({ path: stateFilePath(agentDir) });
+    const router = createRouter({ surface, loadConfig: read, hint, settingsCommand: SETTINGS_COMMAND, knownCommands, profileState });
     for (const command of catalogue.commands) {
         registrar.registerCommand(command.name, {
             ...(command.description ? { description: command.description } : {}),
@@ -42,7 +45,11 @@ export function createExtension(deps) {
         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) };
+        const routing = {
+            inFlight: () => router.inFlight(),
+            undoInFlight: () => router.undoInFlight(ctx),
+            clearProfileDemotion: () => profileState.clear(),
+        };
         try {
             await settings({ catalogue, ctx, routing });
         }
@@ -53,7 +60,7 @@ export function createExtension(deps) {
     };
     // The native conductor command (feature 62): registered in code, not derived
     // from a skill dir, and able to invoke every catalogue command by name.
-    registerAdvanceCommand(registrar, { surface, readConfig: read }, knownCommands);
+    registerAdvanceCommand(registrar, { router, readConfig: read }, knownCommands);
     registrar.registerCommand(SETTINGS_COMMAND, {
         description: "Show and configure per-command model routing",
         handler: settingsHandler,

package/dist/routing/dispatch.d.ts

@@ -1,6 +1,7 @@
 import type { LoadedConfig } from "../config/load.js";
 import type { ThinkingLevel } from "../config/types.js";
 import type { DispatchOutcome, ExtensionSurface, InvocationContext, ModelRef, WorkflowCommand } from "./types.js";
+import type { ProfileStateStore } from "./state.js";
 export interface RouterDeps<M extends ModelRef = ModelRef> {
     /** Pi's API is session-bound, so the surface is resolved per call. */
     surface: (ctx: InvocationContext<M>) => ExtensionSurface<M>;
@@ -14,9 +15,15 @@ export interface RouterDeps<M extends ModelRef = ModelRef> {
     settingsCommand: string;
     /** Command names that actually exist — a route for anything else is a typo. */
     knownCommands: ReadonlySet<string>;
+    /** Profile demotion state store (P4, feature 63). */
+    profileState?: ProfileStateStore;
+    /** Wall-clock now (P4). Default: Date.now. */
+    now?: () => number;
 }
 export interface Router<M extends ModelRef = ModelRef> {
-    dispatch(command: WorkflowCommand, args: string, ctx: InvocationContext<M>): Promise<DispatchOutcome>;
+    dispatch(command: WorkflowCommand, args: string, ctx: InvocationContext<M>, opts?: {
+        onProfileSwitch?: "continue" | "restart";
+    }): Promise<DispatchOutcome>;
     /** Pi `model_select` — distinguishes our own switch from the operator's. */
     noteModelSelect(model: M): void;
     /** Pi `thinking_level_select` — same distinction for the thinking level. */
@@ -31,4 +38,4 @@ export interface Router<M extends ModelRef = ModelRef> {
      */
     undoInFlight(ctx: InvocationContext<M>): Promise<boolean>;
 }
-export declare function createRouter<M extends ModelRef = ModelRef>({ surface, loadConfig, hint, settingsCommand, knownCommands, }: RouterDeps<M>): Router<M>;
+export declare function createRouter<M extends ModelRef = ModelRef>({ surface, loadConfig, hint, settingsCommand, knownCommands, profileState, now, }: RouterDeps<M>): Router<M>;

package/dist/routing/dispatch.js

@@ -1,4 +1,4 @@
-import { effectiveRoute } from "../config/merge.js";
+import { resolveProfileChain, effectiveProfileOrder } from "../config/profiles.js";
 import { parseModelReference } from "../config/schema.js";
 import { modelRefKey } from "./types.js";
 /**
@@ -30,11 +30,18 @@ async function restore(turn, session, ctx, why) {
     if (session.getThinkingLevel() !== wanted)
         session.setThinkingLevel(wanted);
 }
-export function createRouter({ surface, loadConfig, hint, settingsCommand, knownCommands, }) {
+export function createRouter({ surface, loadConfig, hint, settingsCommand, knownCommands, profileState, now, }) {
     let pending;
     // Reported once per session: an operator who ignores it once does not need it
     // on every command, and a route that matches nothing must not fail silently.
     let unknownRoutesReported = false;
+    // P4: in-memory no-op for profileState when not provided.
+    const ps = profileState ?? {
+        demotion: () => undefined,
+        record: () => true,
+        clear: () => true,
+    };
+    const nowFn = now ?? Date.now;
     const refuse = (ctx, reason, message) => {
         ctx.notify(message, "error");
         return { status: "refused", reason, message };
@@ -87,7 +94,7 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
                 return;
             await restore(turn, surface(ctx), ctx, "finished");
         },
-        async dispatch(command, args, ctx) {
+        async dispatch(command, args, ctx, opts) {
             if (pending) {
                 // Refuse even when `ctx.isIdle()` reads true: idleness says the agent loop
                 // is quiet, not that the routed turn is over, and guessing here is how a
@@ -115,39 +122,53 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
                 }
             }
             const session = surface(ctx);
-            const route = effectiveRoute(loaded.config, command.name);
+            // -----------------------------------------------------------------
+            // P4: Profile-chain probing (feature 63, AC7–AC9)
+            // -----------------------------------------------------------------
+            const fallbackCfg = loaded.config.profileFallback;
+            // Demotion window — only when applyTo is "flow".
+            const chainOpts = { providerAvailable: (provider) => {
+                    const available = ctx.availableModels;
+                    return available && available().some((m) => m.provider === provider);
+                } };
+            let demotion = fallbackCfg.applyTo === "flow" ? ps.demotion() : undefined;
+            if (demotion) {
+                const age = nowFn() - Date.parse(demotion.at);
+                const windowMs = fallbackCfg.retryAfterSeconds * 1000;
+                if (!Number.isFinite(age) || age >= windowMs) {
+                    ps.clear();
+                    demotion = undefined;
+                }
+            }
+            const order = effectiveProfileOrder(loaded.config, chainOpts);
+            const startIndex = demotion ? order.indexOf(demotion.profile) : -1;
+            let demotionStart = startIndex;
+            if (demotion && demotionStart < 0) {
+                // The demoted profile is no longer in the order — drop the stale record.
+                ps.clear();
+                demotion = undefined;
+                demotionStart = -1;
+            }
+            const candidates = resolveProfileChain(loaded.config, command.name, chainOpts);
+            const considered = demotionStart > 0 ? candidates.filter((c) => order.indexOf(c.profile) >= demotionStart) : candidates;
+            // Find the preferred candidate (first with a declared model).
+            const preferred = considered.find((c) => c.declared.model);
+            // Model resolution: first candidate with a declared, usable model.
+            let chosen;
             let target;
-            /** The reference string behind `target`, for the select-failure message (a chain names the chosen entry). */
+            /** The reference string behind `target`, for the select-failure message. */
             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
-                    ? "is not in the model registry"
-                    : !ctx.hasConfiguredAuth(found)
-                        ? "has no configured credentials"
-                        : undefined;
-                if (blocker) {
-                    if (loaded.config.onUnavailableRoute !== "inherit") {
-                        return refuse(ctx, "unavailable-route", `/${command.name} stopped: the configured model ${route.model} ${blocker}. ${configureHint}`);
-                    }
-                    ctx.notify(`/${command.name}: ${route.model} ${blocker}, so it runs on the current session model. ${configureHint}`, "warning");
-                }
-                else {
-                    target = found;
-                    chosenRef = route.model;
+            const reasons = [];
+            for (const c of considered) {
+                if (!c.declared.model)
+                    continue;
+                if (c.route.model === "inherit") {
+                    chosen = c;
+                    break;
                 }
-            }
-            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) {
+                // Probe c.route.model (string or chain) — reuse the existing probe shape.
+                const refs = typeof c.route.model === "string" ? [c.route.model] : c.route.model;
+                for (const reference of refs) {
                     const parsed = parseModelReference(reference);
                     const found = parsed ? ctx.find(parsed.provider, parsed.id) : undefined;
                     if (!found) {
@@ -158,19 +179,67 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
                         reasons.push(`${reference} has no configured credentials`);
                         continue;
                     }
+                    // First usable entry for this candidate.
+                    chosen = c;
                     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");
+                if (chosen)
+                    break;
+                // Every entry in this candidate's chain was unusable.
+                const tried = refs.join(", ");
+                reasons.push(`${c.profile}: all models in [${tried}] unavailable`);
+            }
+            // Thinking: the first candidate that declares thinking, else "inherit".
+            const thinkingCandidate = considered.find((c) => c.declared.thinking);
+            const routeThinking = thinkingCandidate?.route.thinking ?? "inherit";
+            // Handle no chosen candidate — fallback to onUnavailableRoute.
+            if (!chosen && preferred) {
+                // Build the chain detail for the notification, matching the old shape.
+                const triedRefs = [];
+                const detailParts = [];
+                for (const c of considered) {
+                    if (!c.declared.model)
+                        continue;
+                    if (c.route.model === "inherit")
+                        continue;
+                    const refs = typeof c.route.model === "string" ? [c.route.model] : c.route.model;
+                    triedRefs.push(...refs);
+                    // Collect the first skip reason per entry for the detail.
+                    const entryReasons = reasons.filter((r) => refs.some((ref) => r.startsWith(ref)));
+                    detailParts.push(...entryReasons);
+                }
+                const tried = triedRefs.join(", ");
+                const detail = detailParts.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");
+            }
+            let profileSwitched;
+            if (chosen && preferred && chosen.profile !== preferred.profile) {
+                profileSwitched = { from: preferred.profile, to: chosen.profile };
+                if (fallbackCfg.applyTo === "flow")
+                    ps.record(chosen.profile);
+            }
+            // AC10 restart: when onProfileSwitch === "restart" AND applyTo === "flow",
+            // record the demotion but do NOT apply the model or send — return deferred
+            // so the loop re-runs the iteration under the fallback profile.
+            if (opts?.onProfileSwitch === "restart"
+                && fallbackCfg.applyTo === "flow"
+                && profileSwitched) {
+                return {
+                    status: "dispatched",
+                    routed: false,
+                    hintShown: false,
+                    profileSwitched,
+                    deferred: true,
+                };
             }
+            // -----------------------------------------------------------------
+            // Legacy: model application (target + thinking)
+            // -----------------------------------------------------------------
             const snapshot = { model: ctx.model, thinking: session.getThinkingLevel() };
             const applied = { model: undefined, thinking: undefined };
             if (target) {
@@ -180,22 +249,22 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
                         return refuse(ctx, "unavailable-route", `/${command.name} stopped: ${chosenRef} could not be selected. ${configureHint}`);
                     }
                     ctx.notify(`/${command.name}: ${chosenRef} could not be selected, so it runs on the current session model. ${configureHint}`, "warning");
+                    // A failed select must not clear the demotion.
+                    // Demotion is cleared only by expiry (top of dispatch), manual rotation/clear, or the console.
                 }
                 else {
                     applied.model = target;
-                    // Pi re-derives thinking inside `setModel`; whatever level the session
-                    // holds now came from us, not from the operator.
                     applied.modelThinking = session.getThinkingLevel();
                 }
             }
-            if (route.thinking !== "inherit") {
-                session.setThinkingLevel(route.thinking);
+            if (routeThinking !== "inherit") {
+                session.setThinkingLevel(routeThinking);
                 // The *effective* level, never the requested one: Pi clamps a level the model
                 // cannot run (`_modelSupportsThinking` → `clampThinkingLevel`) and announces
                 // that one a microtask later. Bookkeeping the request made our own clamped
                 // write read as an operator move, so the restore preserved the clamp instead
                 // of the operator's level (N-3).
-                applied.thinking = session.getThinkingLevel() ?? route.thinking;
+                applied.thinking = session.getThinkingLevel() ?? routeThinking;
             }
             let hintShown = false;
             if (hint.pending()) {
@@ -243,7 +312,7 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
                 }
                 return refuse(ctx, "dispatch-failed", `/${command.name} was not dispatched: ${error.message}. Nothing was sent${rolledBack ? ", and the session model was put back" : ""}.`);
             }
-            return { status: "dispatched", routed: Boolean(applied.model || applied.thinking), hintShown };
+            return { status: "dispatched", routed: Boolean(applied.model || applied.thinking), hintShown, ...(profileSwitched ? { profileSwitched } : {}) };
         },
     };
 }

package/dist/routing/state.d.ts

@@ -11,3 +11,29 @@ export interface HintStoreOptions {
     writeFile?: (path: string, text: string) => void;
 }
 export declare function createHintStore({ path, readFile, writeFile, }: HintStoreOptions): HintStore;
+/** A profile that was demoted because its model was unusable. */
+export interface ProfileDemotion {
+    profile: string;
+    /** ISO-8601 timestamp of when the demotion was recorded. */
+    at: string;
+}
+export interface ProfileStateStore {
+    /** Returns the current demotion, or undefined if no demotion is active. */
+    demotion(): ProfileDemotion | undefined;
+    /**
+     * Record that the given profile was chosen (demoting it for a retry window).
+     * Returns false if the write failed.
+     */
+    record(profile: string, now?: Date): boolean;
+    /**
+     * Clear any demotion record without touching other keys in the state file.
+     * Returns false if the write failed.
+     */
+    clear(): boolean;
+}
+export interface ProfileStateStoreOptions {
+    path: string;
+    readFile?: (path: string) => string | null;
+    writeFile?: (path: string, text: string) => void;
+}
+export declare function createProfileStateStore({ path, readFile, writeFile, }: ProfileStateStoreOptions): ProfileStateStore;

package/dist/routing/state.js

@@ -54,7 +54,73 @@ export function createHintStore({ path, readFile = readOrNull, writeFile = write
             // next command in this same session.
             acknowledged = true;
             try {
-                writeFile(path, `${JSON.stringify({ firstRunHintShownAt: now }, null, 2)}\n`);
+                // Read-merge-write: preserve any other keys already in the state file.
+                const existing = readFile(path);
+                let merged = {};
+                if (existing && existing.trim() !== "") {
+                    try {
+                        const parsed = JSON.parse(existing);
+                        if (typeof parsed === "object" && parsed !== null)
+                            merged = parsed;
+                    }
+                    catch {
+                        // Corrupt state: discard and start fresh.
+                    }
+                }
+                merged.firstRunHintShownAt = now;
+                writeFile(path, `${JSON.stringify(merged, null, 2)}\n`);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+export function createProfileStateStore({ path, readFile = readOrNull, writeFile = writeThrough, }) {
+    const readState = () => {
+        const text = readFile(path);
+        if (text === null || text.trim() === "")
+            return {};
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed === "object" && parsed !== null)
+                return parsed;
+        }
+        catch {
+            // Corrupt state: treat as empty.
+        }
+        return {};
+    };
+    return {
+        demotion() {
+            const state = readState();
+            const pd = state.profileDemotion;
+            if (pd && typeof pd === "object" && "profile" in pd && "at" in pd) {
+                const profile = pd.profile;
+                const at = pd.at;
+                if (typeof profile === "string" && typeof at === "string") {
+                    return { profile, at };
+                }
+            }
+            return undefined;
+        },
+        record(profile, now = new Date()) {
+            const state = readState();
+            state.profileDemotion = { profile, at: now.toISOString() };
+            try {
+                writeFile(path, `${JSON.stringify(state, null, 2)}\n`);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        clear() {
+            const state = readState();
+            delete state.profileDemotion;
+            try {
+                writeFile(path, `${JSON.stringify(state, null, 2)}\n`);
                 return true;
             }
             catch {

package/dist/routing/types.d.ts

@@ -84,6 +84,11 @@ export type DispatchOutcome = {
     status: "dispatched";
     routed: boolean;
     hintShown: boolean;
+    profileSwitched?: {
+        from: string;
+        to: string;
+    };
+    deferred?: boolean;
 } | {
     status: "refused";
     reason: RefusalReason;
@@ -104,4 +109,6 @@ export declare const SETTINGS_COMMAND_ALIAS = "aw-settings";
 export interface RoutingControls {
     inFlight(): boolean;
     undoInFlight(): Promise<boolean>;
+    /** Clear the recorded profile demotion (feature 63 rotate action). */
+    clearProfileDemotion?(): boolean;
 }

package/dist/settings/console.d.ts

@@ -48,6 +48,13 @@ export declare const prompts: {
     readonly clearOverride: "Clear a command override";
     readonly bulkApply: "Apply one route to several commands";
     readonly bulkClear: "Clear several overrides";
+    readonly switchProfile: "Switch the profile being edited";
+    readonly rotateProfile: "Rotate the active profile";
+    readonly toggleRecommended: "Toggle recommended models";
+    readonly profile: "Which profile?";
+    readonly newProfile: "Name the new profile";
+    readonly profileBuiltIn: (name: string) => string;
+    readonly profileNamed: (name: string) => string;
     readonly addAnother: "Add another?";
     readonly policy: "Set the unavailable-route policy";
     readonly settle: "Set the post-command model keep/restore policy";