pi-advisor-flow 0.4.0 → 0.5.1

package/src/commands.ts

@@ -2,8 +2,9 @@ import {
   type ExtensionAPI,
   type ExtensionContext,
   getMarkdownTheme,
+  type Theme,
 } from "@earendil-works/pi-coding-agent";
-import { Box, Markdown, Text } from "@earendil-works/pi-tui";
+import { Box, type Component, Markdown, Text } from "@earendil-works/pi-tui";
 import {
   advisorEffortRef,
   advisorRef,
@@ -13,6 +14,7 @@ import {
   executorRef,
   getAdvisorMaxCallsPerSession,
   getAdvisorSettings,
+  getPersistedModelRefs,
   isSimpleMode,
   loadConfig,
   parseArgs,
@@ -46,9 +48,12 @@ import {
   setContextMaxCharsRef,
   setExecutorEffortRef,
   setExecutorRef,
+  setShowUsageDetailsRef,
+  setShowUsageFooterRef,
   setSimpleModeRef,
   splitRef,
 } from "./config.js";
+import type { GitContextLevel } from "./git.js";
 import { herdrAdvisorActivity, notifyHerdrAdvisorFailure } from "./herdr.js";
 import type { ScoutLifecycleEvent } from "./scout.js";
 import type { AdvisorSessionState } from "./session-state.js";
@@ -60,13 +65,19 @@ import {
   hasSoundVerdict,
   renderAdvisorCallBox,
   renderAdvisorResponseHeader,
+  renderScoutDetails,
+  renderThinkingMarkdown,
   resolveAdvisorRequest,
   ScoutStatusManager,
+  type ScoutToolDetails,
+  SPINNER_FRAMES,
 } from "./tools.js";
 import {
   type AdvisorSettings,
   AdvisorSettingsSelector,
   type ContextPreset,
+  ManualAdvisorDialog,
+  type ManualAdvisorRequest,
   SearchableModelSelector,
 } from "./ui.js";
 import {
@@ -102,6 +113,20 @@ const selectedEffort = (choice: string): string | undefined => {
     : choice;
   return effort === DEFAULT_EFFORT_LEVEL ? undefined : effort;
 };
+const ADVISOR_ACTIVATION_EXPLANATION =
+  "The Advisor is a second-opinion model that reviews the Executor's context and returns risks, alternatives, and verification steps without changing files or running tools.";
+const ARGUMENT_WHITESPACE = /\s+/;
+const hasModelOverride = (args: string, key: "advisor" | "executor") =>
+  args
+    .trim()
+    .split(ARGUMENT_WHITESPACE)
+    .some((token) => {
+      const [tokenKey, value] = token.split("=");
+      return tokenKey === key && Boolean(value);
+    });
+const hasExecutorOverride = (args: string) =>
+  hasModelOverride(args, "executor");
+const hasAdvisorOverride = (args: string) => hasModelOverride(args, "advisor");
 
 const CONTEXT_PRESETS: ContextPreset[] = [
   {
@@ -143,7 +168,8 @@ type ManualConsult = (
   question?: string,
   signal?: AbortSignal,
   onChunk?: (thinking: string, text: string) => void,
-  onScout?: (event: ScoutLifecycleEvent) => void
+  onScout?: (event: ScoutLifecycleEvent) => void,
+  gitContext?: GitContextLevel
 ) => Promise<{
   markdown: string;
   thinkingText: string;
@@ -163,11 +189,348 @@ const notify = (
   }
 };
 
-const findConfiguredModel = (ctx: ExtensionContext, ref: string) => {
+type ManualAdvisorProgressPhase =
+  | "preparing"
+  | "active"
+  | "complete"
+  | "cancelled"
+  | "error";
+interface ManualAdvisorProgressState {
+  phase: ManualAdvisorProgressPhase;
+  scout?: ScoutToolDetails;
+  text?: string;
+  thinking?: string;
+}
+
+class ManualAdvisorProgressComponent implements Component {
+  private readonly question: string | undefined;
+  private readonly state: ManualAdvisorProgressState;
+  private readonly expanded: boolean;
+  private readonly theme: Theme;
+
+  constructor(
+    question: string | undefined,
+    state: ManualAdvisorProgressState,
+    expanded: boolean,
+    theme: Theme
+  ) {
+    this.question = question;
+    this.state = state;
+    this.expanded = expanded;
+    this.theme = theme;
+  }
+
+  render(width: number): string[] {
+    const box = renderAdvisorCallBox(this.question, this.theme);
+    if (this.state.phase === "complete" || this.state.phase === "cancelled") {
+      return box.render(width);
+    }
+
+    const { scout } = this.state;
+    const scoutActive =
+      scout?.status === "calling" || scout?.status === "streaming";
+    if (scoutActive) {
+      renderScoutDetails(box, scout, this.expanded, this.theme);
+      return box.render(width);
+    }
+    if (scout?.status === "cancelled") {
+      return box.render(width);
+    }
+    if (this.state.phase === "error") {
+      box.addChild(
+        new Text(
+          this.theme.fg("error", this.theme.bold("◆ ADVISOR · FAILED")),
+          0,
+          0
+        )
+      );
+      return box.render(width);
+    }
+
+    const frame =
+      SPINNER_FRAMES[Math.floor(Date.now() / 80) % SPINNER_FRAMES.length];
+    let status = "Working…";
+    if (this.state.phase === "preparing") {
+      status = "Preparing…";
+    } else if (this.state.text?.trim()) {
+      status = "Responding…";
+    }
+    box.addChild(
+      new Text(
+        `${this.theme.fg("warning", this.theme.bold(`◆ ADVISOR ${frame}`))} ${this.theme.fg("dim", `· ${status}`)}`,
+        0,
+        0
+      )
+    );
+    if (this.state.thinking?.trim()) {
+      box.addChild(
+        renderThinkingMarkdown(this.state.thinking.slice(-200), this.theme)
+      );
+    }
+    if (this.state.text) {
+      box.addChild(
+        new Markdown(
+          adviceForDisplay(this.state.text, this.expanded),
+          0,
+          0,
+          getMarkdownTheme()
+        )
+      );
+    }
+    return box.render(width);
+  }
+
+  invalidate(): void {
+    // The live progress state is read during each render.
+  }
+}
+
+const findConfiguredModel = (
+  ctx: ExtensionContext,
+  ref: string | undefined
+) => {
+  if (!ref) {
+    return;
+  }
   const [provider, modelId] = splitRef(ref);
   return ctx.modelRegistry.find(provider, modelId);
 };
 
+const getAvailableModelRefs = (ctx: ExtensionContext): string[] | undefined => {
+  if (typeof ctx.modelRegistry.getAvailable !== "function") {
+    return undefined;
+  }
+  return ctx.modelRegistry
+    .getAvailable()
+    .map((model) => `${model.provider}/${model.id}`);
+};
+
+const isSelectableModel = (
+  ctx: ExtensionContext,
+  ref: string | undefined,
+  availableRefs: Set<string> | undefined
+) => {
+  if (!ref) {
+    return false;
+  }
+  if (availableRefs) {
+    const [provider, modelId] = splitRef(ref);
+    return availableRefs.has(`${provider}/${modelId}`);
+  }
+  return Boolean(findConfiguredModel(ctx, ref));
+};
+
+const getExplicitModelError = (
+  ctx: ExtensionContext,
+  ref: string | undefined,
+  label: "Advisor" | "Executor",
+  overridden: boolean,
+  availableRefs: Set<string> | undefined
+) => {
+  if (overridden) {
+    if (!ref) {
+      return `${label} model not configured`;
+    }
+    if (!findConfiguredModel(ctx, ref)) {
+      return `${label} model not found: ${ref}`;
+    }
+    if (availableRefs && !isSelectableModel(ctx, ref, availableRefs)) {
+      return `${label} model unavailable: ${ref}`;
+    }
+  }
+};
+
+interface ActivationModelPlan {
+  pendingExecutor: string | undefined;
+  selectAdvisor: boolean;
+  selectExecutor: boolean;
+}
+
+const planActivationModels = (
+  ctx: ExtensionContext,
+  executor: string | undefined,
+  advisor: string | undefined,
+  pendingExecutorRef: string | undefined,
+  persisted: ReturnType<typeof getPersistedModelRefs>,
+  executorOverride: boolean,
+  advisorOverride: boolean,
+  availableRefs: Set<string> | undefined
+): ActivationModelPlan => {
+  const pendingExecutor =
+    !executorOverride &&
+    pendingExecutorRef &&
+    isSelectableModel(ctx, pendingExecutorRef, availableRefs)
+      ? pendingExecutorRef
+      : undefined;
+  const executorConfigured =
+    executorOverride ||
+    Boolean(pendingExecutor) ||
+    Boolean(
+      persisted.executor && isSelectableModel(ctx, executor, availableRefs)
+    );
+  const advisorConfigured =
+    advisorOverride ||
+    Boolean(
+      persisted.advisor && isSelectableModel(ctx, advisor, availableRefs)
+    );
+  return {
+    pendingExecutor,
+    selectAdvisor: !advisorConfigured,
+    selectExecutor: !executorConfigured,
+  };
+};
+
+interface AdvisorModelSelection {
+  advisor: string;
+  advisorEffort: string | undefined;
+  executor: string;
+  executorEffort: string | undefined;
+}
+
+interface AdvisorModelPickerOptions {
+  advisor: string | undefined;
+  advisorEffort: string | undefined;
+  executor: string | undefined;
+  executorEffort: string | undefined;
+  selectAdvisor: boolean;
+  selectExecutor: boolean;
+}
+
+const selectAdvisorModels = async (
+  ctx: ExtensionContext,
+  options: AdvisorModelPickerOptions
+): Promise<AdvisorModelSelection | undefined> => {
+  if (!ctx.hasUI) {
+    return undefined;
+  }
+  const refs = getAvailableModelRefs(ctx);
+  if (refs && refs.length === 0) {
+    notify(
+      ctx,
+      "No selectable models are available. Configure a provider with /login or models.json, then retry.",
+      "error"
+    );
+    return undefined;
+  }
+  const allOptions = [
+    ...new Set(
+      refs ??
+        [options.executor, options.advisor].filter((ref): ref is string =>
+          Boolean(ref)
+        )
+    ),
+  ];
+  let { advisor, advisorEffort, executor, executorEffort } = options;
+
+  if (options.selectExecutor) {
+    const selectedExecutor = await ctx.ui.custom<string | undefined>(
+      (tui, theme, keybindings, done) =>
+        new SearchableModelSelector({
+          allOptions,
+          currentOption: executor || undefined,
+          keybindings,
+          onCancel: () => done(undefined),
+          onSelect: done,
+          theme,
+          title: "Select Executor Model",
+          tui,
+        })
+    );
+    if (!selectedExecutor) {
+      return undefined;
+    }
+    const selectedExecutorEffort = await ctx.ui.select(
+      "Select Executor Reasoning/Thinking Level",
+      effortChoices(executorEffort)
+    );
+    if (!selectedExecutorEffort) {
+      return undefined;
+    }
+    executor = selectedExecutor;
+    executorEffort = selectedEffort(selectedExecutorEffort);
+  }
+
+  if (options.selectAdvisor) {
+    const selectedAdvisor = await ctx.ui.custom<string | undefined>(
+      (tui, theme, keybindings, done) =>
+        new SearchableModelSelector({
+          allOptions,
+          currentOption: advisor || undefined,
+          keybindings,
+          onCancel: () => done(undefined),
+          onSelect: done,
+          theme,
+          title: "Select Advisor Model",
+          tui,
+        })
+    );
+    if (!selectedAdvisor) {
+      return undefined;
+    }
+    const selectedAdvisorEffort = await ctx.ui.select(
+      "Select Advisor Reasoning/Thinking Level",
+      effortChoices(advisorEffort)
+    );
+    if (!selectedAdvisorEffort) {
+      return undefined;
+    }
+    advisor = selectedAdvisor;
+    advisorEffort = selectedEffort(selectedAdvisorEffort);
+  }
+
+  if (!(advisor && executor)) {
+    return undefined;
+  }
+  return { advisor, advisorEffort, executor, executorEffort };
+};
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one settings form maps every persisted control.
+const applyAdvisorSettings = (settings: AdvisorSettings) => {
+  setAdvisorEffortRef(
+    settings.effort === "Default (Model Default)" ? undefined : settings.effort
+  );
+  setContextMaxCharsRef(settings.contextMaxChars);
+  setAdvisorPlanGateRef(settings.planGate);
+  setAdvisorFailureGateRef(settings.failureGate);
+  setAdvisorCompletionGateRef(settings.completionGate);
+  setAdvisorCollapseResponsesRef(settings.collapseResponses);
+  setAdvisorCustomInvocationRef(settings.customRule);
+  setAdvisorBlockOnBlockedRef(settings.blockOnBlocked ?? true);
+  setAdvisorAutoLoopGateRef(settings.autoLoopGate ?? true);
+  setAdvisorLoopThresholdRef(settings.loopThreshold ?? 3);
+  setAdvisorMaxCallsPerSessionRef(settings.maxCallsPerSession);
+  setAdvisorSessionSummaryRef(settings.sessionSummary ?? false);
+  setAdvisorScoutEnabledRef(settings.scoutEnabled ?? false);
+  setShowUsageDetailsRef(settings.showUsageDetails ?? true);
+  setShowUsageFooterRef(settings.showUsageFooter ?? false);
+  setSimpleModeRef(settings.simpleMode ?? false);
+  setAlwaysOnRef(settings.alwaysOn ?? false);
+  setAdvisorFailureModeRef(settings.failureMode ?? "block-session");
+  setAdvisorHerdrIntegrationRef(settings.herdrIntegration ?? true);
+  setAdvisorToolResultMaxLinesRef(settings.toolResultMaxLines ?? 2000);
+  setAdvisorToolResultMaxBytesRef(settings.toolResultMaxBytes ?? 50 * 1024);
+  setAdvisorRedactSecretsRef(settings.redactSecrets ?? false);
+  setAdvisorGitContextRef(settings.gitContext ?? "summary");
+  setAdvisorGitContextMaxCharsRef(settings.gitContextMaxChars ?? 20_000);
+  setAdvisorToolPoliciesRef(settings.toolPolicies ?? {});
+  setAdvisorTrackedFileContentRef(settings.trackedFileContent ?? false);
+  setAdvisorUntrackedContentRef(settings.untrackedContent ?? false);
+  setAdvisorOutcomeLoggingRef(settings.outcomeLogging ?? false);
+};
+
+const saveAdvisorSettings = (
+  ctx: ExtensionContext,
+  settings: AdvisorSettings
+) => {
+  applyAdvisorSettings(settings);
+  const persisted = getPersistedModelRefs();
+  saveConfig(ctx, {
+    persistAdvisor: Boolean(persisted.advisor),
+    persistExecutor: Boolean(persisted.executor),
+  });
+  saveGlobalOutcomeLogging(settings.outcomeLogging ?? false);
+};
+
 export const registerCommands = (
   pi: ExtensionAPI,
   dependencies: {
@@ -178,42 +541,70 @@ export const registerCommands = (
 ) => {
   const advisorSessionState =
     dependencies.sessionState ?? defaultAdvisorSessionState;
-  const scoutStatus = dependencies.statusManager ?? new ScoutStatusManager();
+  const scoutStatus =
+    dependencies.statusManager ?? new ScoutStatusManager(false);
   const flowEnabled = () => pi.getActiveTools().includes("ask_advisor");
   const requestAdvisor =
     dependencies.consult ??
-    ((ctx, question, signal, onChunk, onScout) =>
+    ((ctx, question, signal, onChunk, onScout, gitContext) =>
       consultAdvisor(
         ctx,
         question,
         signal,
         onChunk,
         "manual",
-        undefined,
+        gitContext,
         undefined,
         undefined,
         undefined,
         onScout,
         undefined
       ));
+  // Pi's model_select event reports both built-in `/model` changes and direct
+  // pi.setModel() calls. Keep an inactive user selection transiently so
+  // `/advisor` can adopt it without treating every normal model change as a
+  // global default. The suppression flag covers this extension's own restore.
+  let pendingExecutorModelRef: string | undefined;
+  let suppressModelSelectionSync = false;
+  const setExecutorModel = async (
+    model: Parameters<ExtensionAPI["setModel"]>[0]
+  ) => {
+    suppressModelSelectionSync = true;
+    try {
+      return await pi.setModel(model);
+    } finally {
+      suppressModelSelectionSync = false;
+    }
+  };
   const manualConsultations = new Map<AbortController, symbol>();
+  const manualProgressTimers = new Map<
+    AbortController,
+    ReturnType<typeof setInterval>
+  >();
+  const manualProgress = new Map<string, ManualAdvisorProgressState>();
+  let manualProgressSequence = 0;
   const updateAdvisorUsageStatus = (ctx: ExtensionContext) => {
     if (ctx.hasUI) {
-      ctx.ui.setStatus("advisor-usage", advisorSessionState.usageStatus());
+      ctx.ui.setStatus(
+        "advisor-usage",
+        getAdvisorSettings().showUsageFooter
+          ? advisorSessionState.usageStatus()
+          : undefined
+      );
     }
   };
-  const setManualStatus = (
-    ctx: ExtensionContext,
-    controller: AbortController,
-    token: symbol,
-    status: string | undefined
-  ) => {
-    if (
-      ctx.hasUI &&
-      manualConsultations.get(controller) === token &&
-      !controller.signal.aborted
-    ) {
-      ctx.ui.setStatus("advisor-manual", status);
+  const reportManualBudgetExhausted = (ctx: ExtensionContext) => {
+    const message = "Advisor call budget exhausted for this session.";
+    notify(ctx, message, "warning");
+    notifyHerdrAdvisorFailure("Advisor budget exhausted", message);
+  };
+
+  // A status update with an undefined value is an invisible render pulse. The
+  // transcript owns manual progress now, so no consultation text is kept in the
+  // footer while this pulse still drives the live spinner.
+  const requestManualRender = (ctx: ExtensionContext) => {
+    if (ctx.hasUI) {
+      ctx.ui.setStatus("advisor-manual", undefined);
     }
   };
 
@@ -221,10 +612,26 @@ export const registerCommands = (
     ctx: ExtensionContext,
     question: string | undefined,
     controller: AbortController,
-    scoutStatusToken: symbol
+    scoutStatusToken: symbol,
+    progress: ManualAdvisorProgressState,
+    gitContext?: GitContextLevel
   ) => {
     herdrAdvisorActivity.start();
-    setManualStatus(ctx, controller, scoutStatusToken, "Advisor preparing…");
+    progress.phase = "preparing";
+    requestManualRender(ctx);
+    if (ctx.hasUI) {
+      const timer = setInterval(() => {
+        if (
+          controller.signal.aborted ||
+          manualConsultations.get(controller) !== scoutStatusToken
+        ) {
+          clearInterval(timer);
+          return;
+        }
+        requestManualRender(ctx);
+      }, 80);
+      manualProgressTimers.set(controller, timer);
+    }
     let scoutDetails: Parameters<typeof appendScoutLifecycleEntry>[2];
     return requestAdvisor(
       ctx,
@@ -234,41 +641,27 @@ export const registerCommands = (
         if (controller.signal.aborted) {
           return;
         }
-        let status = "Advisor working…";
-        if (thinking.trim()) {
-          status = "Advisor thinking…";
-        }
-        if (text.trim()) {
-          status = "Advisor responding…";
-        }
-        setManualStatus(ctx, controller, scoutStatusToken, status);
+        progress.phase = "active";
+        progress.thinking = thinking;
+        progress.text = text;
+        requestManualRender(ctx);
       },
       (event) => {
         if (!controller.signal.aborted) {
           scoutStatus.update(ctx, scoutStatusToken, event);
-          if (event.type === "call" || event.type === "chunk") {
-            setManualStatus(
-              ctx,
-              controller,
-              scoutStatusToken,
-              "Advisor Scout curating…"
-            );
-          } else if (event.type === "success" || event.type === "fallback") {
-            setManualStatus(
-              ctx,
-              controller,
-              scoutStatusToken,
-              "Advisor working…"
-            );
-          }
           scoutDetails = appendScoutLifecycleEntry(pi, event, scoutDetails);
+          progress.scout = scoutDetails;
+          progress.phase = "active";
+          requestManualRender(ctx);
         }
-      }
+      },
+      gitContext
     )
       .then(({ markdown, usage }) => {
         if (controller.signal.aborted) {
           return;
         }
+        progress.phase = "complete";
         advisorSessionState.recordInvocation({
           cost: advisorUsageCost(usage),
           executionEffect: "continued",
@@ -303,6 +696,7 @@ export const registerCommands = (
         if (controller.signal.aborted) {
           return;
         }
+        progress.phase = "error";
         const message = error instanceof Error ? error.message : String(error);
         advisorSessionState.recordInvocation({
           executionEffect: "continued",
@@ -328,12 +722,15 @@ export const registerCommands = (
         notifyHerdrAdvisorFailure("Advisor consultation failed", message);
       })
       .finally(() => {
-        if (
-          ctx.hasUI &&
-          manualConsultations.get(controller) === scoutStatusToken
-        ) {
-          ctx.ui.setStatus("advisor-manual", undefined);
+        if (controller.signal.aborted) {
+          progress.phase = "cancelled";
+        }
+        const timer = manualProgressTimers.get(controller);
+        if (timer) {
+          clearInterval(timer);
+          manualProgressTimers.delete(controller);
         }
+        requestManualRender(ctx);
         scoutStatus.release(ctx, scoutStatusToken);
         manualConsultations.delete(controller);
         herdrAdvisorActivity.finish();
@@ -344,17 +741,25 @@ export const registerCommands = (
   const resolveActivationModels = async (ctx: ExtensionContext) => {
     const executor = findConfiguredModel(ctx, executorRef);
     if (!executor) {
-      return { error: `Executor model not found: ${executorRef}` };
+      return {
+        error: executorRef
+          ? `Executor model not found: ${executorRef}`
+          : "Executor model not configured",
+      };
     }
     const advisor = findConfiguredModel(ctx, advisorRef);
     if (!advisor) {
-      return { error: `Advisor model not found: ${advisorRef}` };
+      return {
+        error: advisorRef
+          ? `Advisor model not found: ${advisorRef}`
+          : "Advisor model not configured",
+      };
     }
     const advisorAuth = await ctx.modelRegistry.getApiKeyAndHeaders(advisor);
     if (!(advisorAuth.ok && advisorAuth.apiKey)) {
       return { error: `No API key for Advisor ${advisorRef}` };
     }
-    if (!(await pi.setModel(executor))) {
+    if (!(await setExecutorModel(executor))) {
       return { error: `No API key for Executor ${executorRef}` };
     }
     return {};
@@ -375,6 +780,83 @@ export const registerCommands = (
     }
   };
 
+  const prepareActivationModels = async (
+    ctx: ExtensionContext,
+    announce: boolean,
+    executorOverride: boolean,
+    advisorOverride: boolean
+  ): Promise<
+    { pickedModels: boolean; pendingExecutor?: string } | undefined
+  > => {
+    const persisted = getPersistedModelRefs();
+    const availableRefs = getAvailableModelRefs(ctx);
+    const availableRefSet = availableRefs ? new Set(availableRefs) : undefined;
+    const explicitError =
+      getExplicitModelError(
+        ctx,
+        executorRef,
+        "Executor",
+        executorOverride,
+        availableRefSet
+      ) ??
+      getExplicitModelError(
+        ctx,
+        advisorRef,
+        "Advisor",
+        advisorOverride,
+        availableRefSet
+      );
+    if (explicitError) {
+      notify(ctx, explicitError, "error");
+      return;
+    }
+
+    const plan = planActivationModels(
+      ctx,
+      executorRef,
+      advisorRef,
+      pendingExecutorModelRef,
+      persisted,
+      executorOverride,
+      advisorOverride,
+      availableRefSet
+    );
+    setExecutorRef(plan.pendingExecutor ?? executorRef);
+    if (!(plan.selectExecutor || plan.selectAdvisor)) {
+      return { pendingExecutor: plan.pendingExecutor, pickedModels: false };
+    }
+
+    // Always-on startup cannot open an interactive picker, so it leaves the
+    // flow disabled until the user selects both models with `/advisor`.
+    if (!announce) {
+      notify(
+        ctx,
+        "Advisor models are not configured or available. Run /advisor to choose them.",
+        "error"
+      );
+      return;
+    }
+    const selection = await selectAdvisorModels(ctx, {
+      advisor: advisorOverride || persisted.advisor ? advisorRef : "",
+      advisorEffort: advisorEffortRef,
+      executor:
+        executorOverride || plan.pendingExecutor || persisted.executor
+          ? executorRef
+          : "",
+      executorEffort: executorEffortRef,
+      selectAdvisor: plan.selectAdvisor,
+      selectExecutor: plan.selectExecutor,
+    });
+    if (!selection) {
+      return;
+    }
+    setAdvisorRef(selection.advisor);
+    setAdvisorEffortRef(selection.advisorEffort);
+    setExecutorRef(selection.executor);
+    setExecutorEffortRef(selection.executorEffort);
+    return { pendingExecutor: plan.pendingExecutor, pickedModels: true };
+  };
+
   const activateAdvisor = async (
     args: string,
     ctx: ExtensionContext,
@@ -385,32 +867,53 @@ export const registerCommands = (
     }
     const previous = {
       advisor: advisorRef,
+      advisorEffort: advisorEffortRef,
       contextMaxChars: contextMaxCharsRef,
       executor: executorRef,
+      executorEffort: executorEffortRef,
     };
     const restoreRefs = () => {
       setAdvisorRef(previous.advisor);
+      setAdvisorEffortRef(previous.advisorEffort);
       setContextMaxCharsRef(previous.contextMaxChars);
       setExecutorRef(previous.executor);
+      setExecutorEffortRef(previous.executorEffort);
     };
+    const executorOverride = hasExecutorOverride(args);
+    const advisorOverride = hasAdvisorOverride(args);
     const argumentError = parseArgs(args);
     if (argumentError) {
       restoreRefs();
       notify(ctx, argumentError, "error");
       return;
     }
+
+    const prepared = await prepareActivationModels(
+      ctx,
+      announce,
+      executorOverride,
+      advisorOverride
+    );
+    if (!prepared) {
+      restoreRefs();
+      return;
+    }
     const { error } = await resolveActivationModels(ctx);
     if (error) {
       restoreRefs();
       notify(ctx, error, "error");
       return;
     }
-    // parseArgs only mutates in-memory refs, and every later loadConfig resets
-    // them from disk. Persist supplied arguments once they are known to resolve,
+    // parseArgs, model picking, and an inactive `/model` selection only mutate
+    // in-memory refs. Persist them once both models are known and authenticated,
     // so an unusable model reference is never written to the configuration.
-    if (args.trim()) {
-      saveConfig(ctx);
+    if (args.trim() || prepared.pickedModels || prepared.pendingExecutor) {
+      saveConfig(ctx, { persistAdvisor: true, persistExecutor: true });
     }
+    // A successful activation has committed the effective Executor. Do not let
+    // an older inactive selection override an explicit activation argument on a
+    // later attempt.
+    pendingExecutorModelRef = undefined;
     if (executorEffortRef) {
       pi.setThinkingLevel(executorEffortRef as ThinkingLevel);
     }
@@ -424,7 +927,7 @@ export const registerCommands = (
     if (announce) {
       notify(
         ctx,
-        `Advisor flow ready — Executor: ${executorRef} (thinking: ${executorEffortRef || "default"}) · Advisor: ${advisorRef} (thinking: ${advisorEffortRef || "default"})`,
+        `${ADVISOR_ACTIVATION_EXPLANATION}\n\nAdvisor flow ready — Executor: ${executorRef} (thinking: ${executorEffortRef || "default"}) · Advisor: ${advisorRef} (thinking: ${advisorEffortRef || "default"})`,
         "info"
       );
     }
@@ -432,9 +935,20 @@ export const registerCommands = (
 
   pi.registerEntryRenderer?.(
     "advisor-manual-call",
-    (entry, _options, theme) => {
-      const { question } = (entry.data ?? {}) as { question?: string };
-      return renderAdvisorCallBox(question, theme);
+    (entry, { expanded }, theme) => {
+      const { progressId, question } = (entry.data ?? {}) as {
+        progressId?: string;
+        question?: string;
+      };
+      const progress = progressId ? manualProgress.get(progressId) : undefined;
+      return progress
+        ? new ManualAdvisorProgressComponent(
+            question,
+            progress,
+            Boolean(expanded),
+            theme
+          )
+        : renderAdvisorCallBox(question, theme);
     }
   );
 
@@ -461,9 +975,11 @@ export const registerCommands = (
       if (details?.advisor) {
         box.addChild(new Text(theme.fg("dim", `  ${details.advisor}`), 0, 0));
       }
-      const usage = formatAdvisorUsage(details?.usage);
-      if (usage) {
-        box.addChild(new Text(theme.fg("dim", `  Usage: ${usage}`), 0, 0));
+      if (getAdvisorSettings().showUsageDetails) {
+        const usage = formatAdvisorUsage(details?.usage);
+        if (usage) {
+          box.addChild(new Text(theme.fg("dim", `  Usage: ${usage}`), 0, 0));
+        }
       }
       box.addChild(
         new Markdown(
@@ -478,6 +994,7 @@ export const registerCommands = (
   );
 
   pi.on("session_start", async (_event, ctx) => {
+    pendingExecutorModelRef = undefined;
     // A malformed advisor.json or a provider auth failure must not reject a
     // lifecycle handler and break session startup.
     try {
@@ -492,39 +1009,57 @@ export const registerCommands = (
   });
 
   pi.on("model_select", (event, ctx) => {
-    // Only an explicit user selection redefines the Executor. "restore" replays a
-    // stored session model and would otherwise overwrite saved configuration.
-    if (event.source !== "set" || !flowEnabled()) {
+    // "restore" replays a stored session model and "cycle" changes the active
+    // model without an explicit `/model` choice. Neither should redefine the
+    // configured Executor.
+    if (event.source !== "set" || suppressModelSelectionSync) {
       return;
     }
     const selected = `${event.model.provider}/${event.model.id}`;
+    if (!flowEnabled()) {
+      // Defer persistence until `/advisor` succeeds. This keeps ordinary model
+      // selection global defaults untouched when the flow is not enabled.
+      pendingExecutorModelRef = selected;
+      return;
+    }
+    pendingExecutorModelRef = undefined;
     if (selected === executorRef) {
       return;
     }
+    const persisted = getPersistedModelRefs();
     setExecutorRef(selected);
-    saveConfig(ctx);
+    saveConfig(ctx, {
+      persistAdvisor: Boolean(persisted.advisor),
+      persistExecutor: true,
+    });
   });
 
   pi.on("session_shutdown", (_event, ctx) => {
     if (ctx.hasUI) {
-      ctx.ui.setStatus("advisor-manual", undefined);
       ctx.ui.setStatus("advisor-usage", undefined);
     }
     for (const [controller, token] of manualConsultations) {
       controller.abort();
+      const timer = manualProgressTimers.get(controller);
+      if (timer) {
+        clearInterval(timer);
+        manualProgressTimers.delete(controller);
+      }
       scoutStatus.release(ctx, token);
     }
     scoutStatus.clear(ctx);
     manualConsultations.clear();
+    manualProgressTimers.clear();
+    manualProgress.clear();
     herdrAdvisorActivity.clear();
   });
 
   pi.registerCommand("advisor-manual", {
     description:
       "Consult the Advisor in parallel; accepts an optional focused question and fans its response out to the Executor",
-    handler: (args, ctx) => {
+    handler: async (args, ctx) => {
       if (!loadCommandConfig(ctx)) {
-        return Promise.resolve();
+        return;
       }
       if (
         !(
@@ -532,15 +1067,57 @@ export const registerCommands = (
           advisorSessionState.canConsult(getAdvisorMaxCallsPerSession())
         )
       ) {
-        const message = "Advisor call budget exhausted for this session.";
-        notify(ctx, message, "warning");
-        notifyHerdrAdvisorFailure("Advisor budget exhausted", message);
-        return Promise.resolve();
+        reportManualBudgetExhausted(ctx);
+        return;
       }
+
+      let gitContext: GitContextLevel | undefined;
+      let question: string | undefined;
+      if (ctx.mode === "tui") {
+        const request = await ctx.ui.custom<ManualAdvisorRequest | undefined>(
+          (tui, theme, keybindings, done) =>
+            new ManualAdvisorDialog({
+              gitContext: getAdvisorSettings().gitContext,
+              initialMessage: args,
+              keybindings,
+              onCancel: () => done(undefined),
+              onSubmit: done,
+              theme,
+              tui,
+            }),
+          {
+            overlay: true,
+            overlayOptions: {
+              anchor: "center",
+              margin: 2,
+              maxHeight: "80%",
+              minWidth: 56,
+              width: 76,
+            },
+          }
+        );
+        if (!request) {
+          return;
+        }
+        if (
+          !(
+            isSimpleMode() ||
+            advisorSessionState.canConsult(getAdvisorMaxCallsPerSession())
+          )
+        ) {
+          reportManualBudgetExhausted(ctx);
+          return;
+        }
+        const { gitContext: selectedGitContext, message } = request;
+        gitContext = selectedGitContext;
+        question = resolveAdvisorRequest(message);
+      } else {
+        question = resolveAdvisorRequest(args);
+      }
+
       if (!isSimpleMode()) {
         advisorSessionState.consumeCall();
       }
-      const question = resolveAdvisorRequest(args);
       // A single visible progress surface avoids competing consultations overwriting
       // each other's streamed state. A newer manual request replaces the previous one.
       for (const [pending, token] of manualConsultations) {
@@ -550,17 +1127,27 @@ export const registerCommands = (
       manualConsultations.clear();
       const controller = new AbortController();
       const scoutStatusToken = Symbol("manual-scout");
+      manualProgressSequence += 1;
+      const progressId = `manual-${manualProgressSequence}`;
+      const progress: ManualAdvisorProgressState = { phase: "preparing" };
+      manualProgress.set(progressId, progress);
       scoutStatus.register(scoutStatusToken);
       manualConsultations.set(controller, scoutStatusToken);
-      pi.appendEntry?.("advisor-manual-call", { question });
-      startManualConsultation(ctx, question, controller, scoutStatusToken);
-      return Promise.resolve();
+      pi.appendEntry?.("advisor-manual-call", { progressId, question });
+      startManualConsultation(
+        ctx,
+        question,
+        controller,
+        scoutStatusToken,
+        progress,
+        gitContext
+      );
     },
   });
 
   pi.registerCommand("advisor", {
     description:
-      "Enable the Executor/Advisor flow and switch to the configured Executor model; accepts contextMaxChars=N",
+      "Enable the Executor/Advisor flow and switch to the configured or explicitly selected Executor model; accepts contextMaxChars=N",
     handler: (args, ctx) => activateAdvisor(args, ctx),
   });
 
@@ -571,66 +1158,33 @@ export const registerCommands = (
       if (!(loadCommandConfig(ctx) && ctx.hasUI)) {
         return;
       }
-      const refs = ctx.modelRegistry
-        .getAvailable()
-        .map((m) => `${m.provider}/${m.id}`);
-
-      const executor = await ctx.ui.custom<string | undefined>(
-        (tui, theme, keybindings, done) =>
-          new SearchableModelSelector({
-            allOptions: refs,
-            currentOption: executorRef,
-            keybindings,
-            onCancel: () => done(undefined),
-            onSelect: done,
-            theme,
-            title: "Select Executor Model",
-            tui,
-          })
-      );
-      if (!executor) {
-        return;
-      }
-
-      const executorEffort = await ctx.ui.select(
-        "Select Executor Reasoning/Thinking Level",
-        effortChoices(executorEffortRef)
-      );
-      if (!executorEffort) {
-        return;
-      }
-
-      const advisor = await ctx.ui.custom<string | undefined>(
-        (tui, theme, keybindings, done) =>
-          new SearchableModelSelector({
-            allOptions: refs,
-            currentOption: advisorRef,
-            keybindings,
-            onCancel: () => done(undefined),
-            onSelect: done,
-            theme,
-            title: "Select Advisor Model",
-            tui,
-          })
-      );
-      if (!advisor) {
-        return;
-      }
-
-      const advisorEffort = await ctx.ui.select(
-        "Select Advisor Reasoning/Thinking Level",
-        effortChoices(advisorEffortRef)
-      );
-      if (!advisorEffort) {
+      // When `/model` was used before activation, show that session choice as
+      // the Executor's current option instead of making the persisted Executor
+      // look like the active selection.
+      const persisted = getPersistedModelRefs();
+      const selection = await selectAdvisorModels(ctx, {
+        advisor: persisted.advisor ? advisorRef : "",
+        advisorEffort: advisorEffortRef,
+        executor:
+          pendingExecutorModelRef ?? (persisted.executor ? executorRef : ""),
+        executorEffort: executorEffortRef,
+        selectAdvisor: true,
+        selectExecutor: true,
+      });
+      if (!selection) {
         return;
       }
 
-      setExecutorRef(executor);
-      setAdvisorRef(advisor);
-      setExecutorEffortRef(selectedEffort(executorEffort));
-      setAdvisorEffortRef(selectedEffort(advisorEffort));
+      setExecutorRef(selection.executor);
+      setAdvisorRef(selection.advisor);
+      setExecutorEffortRef(selection.executorEffort);
+      setAdvisorEffortRef(selection.advisorEffort);
 
-      const path = saveConfig(ctx);
+      const path = saveConfig(ctx, {
+        persistAdvisor: true,
+        persistExecutor: true,
+      });
+      pendingExecutorModelRef = undefined;
       ctx.ui.notify(
         `Saved Executor + Advisor configurations to ${path}`,
         "info"
@@ -639,68 +1193,37 @@ export const registerCommands = (
   });
 
   pi.registerCommand("advisor-settings", {
-    description: "Configure Advisor context and reasoning effort",
-    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one settings form maps every persisted control.
+    description: "Configure Advisor settings",
     handler: async (_args, ctx) => {
       if (!(loadCommandConfig(ctx) && ctx.hasUI)) {
         return;
       }
 
       const initial: AdvisorSettings = getAdvisorSettings();
-      const settings = await ctx.ui.custom<AdvisorSettings | undefined>(
+      await ctx.ui.custom<void>(
         (tui, theme, _keybindings, done) =>
           new AdvisorSettingsSelector({
             effortLevels: EFFORT_LEVELS,
             initial,
-            onCancel: () => done(undefined),
-            onSave: done,
+            onCancel: () => done(),
+            onChange: (settings) => {
+              try {
+                saveAdvisorSettings(ctx, settings);
+                updateAdvisorUsageStatus(ctx);
+              } catch (error) {
+                const message =
+                  error instanceof Error ? error.message : String(error);
+                ctx.ui.notify(
+                  `Could not save Advisor settings: ${message}`,
+                  "error"
+                );
+              }
+            },
             presets: CONTEXT_PRESETS,
             theme,
             tui,
           })
       );
-      if (!settings) {
-        return;
-      }
-
-      setAdvisorEffortRef(
-        settings.effort === "Default (Model Default)"
-          ? undefined
-          : settings.effort
-      );
-      setContextMaxCharsRef(settings.contextMaxChars);
-      setAdvisorPlanGateRef(settings.planGate);
-      setAdvisorFailureGateRef(settings.failureGate);
-      setAdvisorCompletionGateRef(settings.completionGate);
-      setAdvisorCollapseResponsesRef(settings.collapseResponses);
-      setAdvisorCustomInvocationRef(settings.customRule);
-      setAdvisorBlockOnBlockedRef(settings.blockOnBlocked ?? true);
-      setAdvisorAutoLoopGateRef(settings.autoLoopGate ?? true);
-      setAdvisorLoopThresholdRef(settings.loopThreshold ?? 3);
-      setAdvisorMaxCallsPerSessionRef(settings.maxCallsPerSession);
-      setAdvisorSessionSummaryRef(settings.sessionSummary ?? false);
-      setAdvisorScoutEnabledRef(settings.scoutEnabled ?? false);
-      setSimpleModeRef(settings.simpleMode ?? false);
-      setAlwaysOnRef(settings.alwaysOn ?? false);
-      setAdvisorFailureModeRef(settings.failureMode ?? "block-session");
-      setAdvisorHerdrIntegrationRef(settings.herdrIntegration ?? true);
-      setAdvisorToolResultMaxLinesRef(settings.toolResultMaxLines ?? 2000);
-      setAdvisorToolResultMaxBytesRef(settings.toolResultMaxBytes ?? 50 * 1024);
-      setAdvisorRedactSecretsRef(settings.redactSecrets ?? false);
-      setAdvisorGitContextRef(settings.gitContext ?? "summary");
-      setAdvisorGitContextMaxCharsRef(settings.gitContextMaxChars ?? 20_000);
-      setAdvisorToolPoliciesRef(settings.toolPolicies ?? {});
-      setAdvisorTrackedFileContentRef(settings.trackedFileContent ?? false);
-      setAdvisorUntrackedContentRef(settings.untrackedContent ?? false);
-      setAdvisorOutcomeLoggingRef(settings.outcomeLogging ?? false);
-      const path = saveConfig(ctx);
-      const globalPath = saveGlobalOutcomeLogging(
-        settings.outcomeLogging ?? false
-      );
-      ctx.ui.notify(
-        `Saved Advisor settings to ${path}; outcome logging globally to ${globalPath}`,
-        "info"
-      );
     },
   });
 
@@ -718,8 +1241,12 @@ export const registerCommands = (
       // Leaving alwaysOn set would silently reactivate the flow next session.
       const wasAlwaysOn = alwaysOnRef;
       if (wasAlwaysOn) {
+        const persisted = getPersistedModelRefs();
         setAlwaysOnRef(false);
-        saveConfig(ctx);
+        saveConfig(ctx, {
+          persistAdvisor: Boolean(persisted.advisor),
+          persistExecutor: Boolean(persisted.executor),
+        });
       }
       notify(
         ctx,