pi-advisor-flow 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -4,6 +4,60 @@ All notable changes to this project are documented here.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.5.2 - 2026-09-05
+
+### Changed
+
+- Reorganized configuration, UI, Advisor tool, and command code into smaller modules behind the existing public facades without changing the extension's public API.
+
+### Fixed
+
+- Kept failed or aborted Advisor streams from treating partial responses as successful advice or automatic gate permission.
+- Made malformed automatic-gate Markdown fences fail closed when their character or delimiter length does not match.
+- Applied optional secret redaction to targeted Advisor questions before sending provider requests while retaining the raw question for local displays.
+- Kept the TUI tab keybinding out of Socket's URL-string heuristic without changing its runtime behavior.
+- Made benchmark extension attestations follow the root `package.json` version instead of a duplicated constant.
+
+## 0.5.1
+
+### Changed
+
+- Updated CI and local validation to Bun 1.4.1 and kept the Pi compatibility packages at 0.84.4; Pi 0.85.0 currently adds an eager `/server` import without declaring the `@earendil-works/pi-server` dependency required by its coding-agent entry point.
+- Kept benchmark tests out of the normal test run; use `bun run test:bench` to run them explicitly.
+- Added Socket security dependency overrides and a `socket` script for `bunx socket optimize`.
+
+### Added
+
+- Added a repository-only failsafe benchmark with an offline replay tier, a
+  24-item decision-point corpus, a fail-closed Pi/Harbor ReactBench adapter,
+  pinned live-tier controls, hard budget limits, and task-level
+  uplift/dominance reporting. See [Benchmarking](docs/benchmark.md).
+- Added bounded local Harbor runtime controls for Apple Container experiments,
+  Docker build-cache cleanup, and a recorded one-hour agent timeout for complex
+  ReactBench tasks.
+- Added a disposable, credential-free GitHub build compatibility layer for
+  pinned ReactBench Dockerfiles whose Git 2.39 transport is rejected by the
+  GitHub endpoint, with bounded pre-agent Harbor infrastructure retries and
+  per-attempt artifacts for transient build and transport failures.
+- Derived the host Harbor command timeout from the bounded agent timeout and
+  made timeout cleanup terminate the full Harbor process group, including the
+  broker and descendants.
+- Ensured configured Advisor reasoning effort reaches the provider-facing
+  request field used by current Pi AI adapters.
+
+### Fixed
+
+- Made `/advisor` open the available-model picker on first use or when either saved model is missing or unavailable; activation never silently selects a model outside the user's available catalog.
+- Added a concise `/advisor` explanation of the Advisor's second-opinion role.
+- Preserved Markdown formatting in visible Scout and nested Advisor thinking previews while retaining their speech-bubble cue. During streaming, incomplete Markdown delimiters display transiently until they close, which is expected behavior when thinking arrives incrementally.
+- Adopted an explicit `/model` selection made before `/advisor` as the Executor on the next successful activation, without persisting ordinary model changes while the flow is off.
+
+## [5.1.0] - 2026-09-04 [YANKED]
+
+### Release status
+
+- Published by mistake instead of `0.5.1`; withdrawn from npm and removed from Git, with `latest` restored to `0.5.0`.
+
 ## 0.5.0
 
 ### Changed

package/README.md

@@ -1,4 +1,4 @@
-# pi-advisor
+# [pi-advisor](https://github.com/philipbrembeck/pi-advisor)
 
 <div align="center">
 
@@ -8,114 +8,80 @@ A configurable second-opinion workflow for <a href="https://github.com/earendil-
 
 </div>
 
+![d18m Downloads](https://img.shields.io/npm/d18m/pi-advisor-flow?style=flat) ![NPM Version](https://img.shields.io/npm/v/pi-advisor-flow?style=flat) ![Pi Advisor Flow badge](https://img.shields.io/badge/advisor%20flow-fff?logo=pi&logoColor=000)
 
-![d18m Downloads](https://img.shields.io/npm/d18m/pi-advisor-flow?style=flat) ![NPM Version](https://img.shields.io/npm/v/pi-advisor-flow?style=flat)
 
 `pi-advisor-flow` keeps one model focused on execution and makes a second, smarter model available for consequential decisions, stalled work, and final reviews. The Executor still owns the work. The Advisor challenges assumptions, exposes risks, and suggests verification steps without taking over or running tools.
 
-The idea is simple: keep implementation on a fast model and borrow frontier reasoning only when decisions matter. [Read why this workflow is useful](https://philipbrembeck.com/writings/2026/07/only-as-much-intelligence-as-you-need).
+Keep implementation on a fast model and borrow frontier reasoning only when decisions matter. [Read why this workflow is useful](https://philipbrembeck.com/writings/2026/07/only-as-much-intelligence-as-you-need).
 
-## Features
+## How it works
+
+1. The Executor works on your task as usual.
+2. It calls `ask_advisor`, or an enabled gate starts a review.
+3. pi-advisor reconstructs the relevant conversation and allowed repository context.
+4. The Advisor returns an opinion. The Executor decides what to adopt, changes the code, and validates it.
 
-- **On-demand second opinions** through the `ask_advisor` tool or `/advisor-manual`.
-- **Configurable review gates** before plans, after repeated failures, and before declaring completion.
-- **Automatic loop detection** for repeated tool calls, with explicit proceed, revise, or blocked decisions.
-- **Separate model and reasoning controls** for the Executor and Advisor.
-- **Advisor usage accounting** with per-response token/cost details and optional cumulative direct usage in the Pi footer and session summary. Per-response usage and cost details are shown by default and can be hidden independently from the footer in `/advisor-settings`.
-- **Privacy controls** for conversation history, repository context, explicit tracked/untracked file handoff, tool results, secret redaction, and outcome logging.
-- **Optional persistent activation, Simple mode, session summaries, and Herdr integration.**
-- **Compact searchable `/advisor-settings` controls** that match Pi's settings list and save changes immediately.
-- **EXPERIMENTAL Advisor Scout** that uses the configured Executor model to curate conversation evidence before every Advisor call.
+Regular consultations do not block execution. Automatic loop gates are different: they can stop a repeated tool action or session based on your configured failure policy.
 
 ## Install
 
-Requires Pi 0.84.1 or later and is compatible with Herdr 0.8.0.
+Requires Pi 0.84.1 or later.
 
 ```bash
-# npm
 pi install npm:pi-advisor-flow
+```
 
-# GitHub
-pi install git:github.com/philipbrembeck/pi-advisor.git
+You can also install from GitHub:
 
-# local checkout
-pi install /path/to/pi-advisor
+```bash
+pi install git:github.com/philipbrembeck/pi-advisor.git
 ```
 
-Restart or reload Pi after installation.
+Reload Pi after installing.
 
 ## Quick start
 
-1. Run `/advisor` to enable the flow and register `ask_advisor`.
-2. Run `/advisor-models` to choose the Executor and Advisor models. Current model and thinking-level selections appear first and ticked, so pressing Enter keeps them.
-3. Run `/advisor-settings` to configure review gates, context, privacy, and limits. Type to fuzzy-search settings; changes save immediately.
-
-![Advisor Settings](https://raw.githubusercontent.com/philipbrembeck/pi-advisor/refs/heads/main/assets/settings.png)
-
-Unknown fields in `advisor.json` are preserved for forward compatibility and reported as non-blocking warnings. Invalid recognized values remain errors, and Advisor commands show the configuration problem without crashing their handlers.
-
-You can also enable the flow and select both models at once:
-
 ```text
-/advisor executor=openai-codex/gpt-5.6-luna advisor=openai-codex/gpt-5.6-sol
+/advisor            # Enable the Advisor Flow
+/advisor-models     # Choose the Executor and Advisor models
+/advisor-settings   # Configure behavior, modes, etc.
 ```
 
-## How it works
-
-1. The Executor investigates the task and forms its own candidate direction.
-2. For a consequential decision, stalled attempt, or final review, it calls `ask_advisor` with the reconstructed conversation and allowed repository context.
-3. When Experimental Advisor Scout is enabled, the configured Executor model selects relevant conversation groups and writes a short, explicitly untrusted synthesis.
-4. The Advisor receives selected verbatim evidence, required current-request context, and the unchanged deterministic repository, preference, draft, and attachment regions.
-5. The Executor decides what to adopt, performs the work, and validates the result.
-
-A normal consultation never blocks execution. The optional automatic loop gate is different: it evaluates repeated tool calls and applies the configured failure policy when the Advisor says to revise, reports a block, is unavailable, or returns an invalid decision.
+On first use, or whenever a saved model is unavailable, `/advisor` opens the same available-model picker as `/advisor-models`; it never silently chooses an unconfigured model. After activation, `/advisor` explains that the Advisor reviews the Executor's context without changing files or running tools.
 
-Advisor responses show provider-reported input, output, cache, and cost details when available. Successful `ask_advisor` tool results also carry normalized usage into Pi's built-in `Tools/summaries` and `/cost` totals. Manual consultations and automatic gates remain in the separate session-local direct Advisor accounting because they are custom messages, so they are not double-counted in Pi's Executor totals. Missing or partial provider usage is shown as unavailable rather than fabricated as zero usage. `/advisor-settings` independently controls per-response usage details and the cumulative Advisor footer without disabling this accounting; the footer is off by default.
+From the Executor, `ask_advisor({})` requests a general review. A targeted `question` or concise `draft` can focus the review on a particular decision.
 
-Successful calls return an opaque `adviceId`. If global outcome logging is enabled, the Executor can call `record_advisor_outcome` once to record whether the advice was adopted and whether final validation passed.
-
-### Experimental Advisor Scout
-
-Experimental Advisor Scout is off by default. Enable `Experimental Advisor Scout` in the advanced `/advisor-settings` screen or set `"advisorScoutEnabled": true` in the global `advisor.json`.
-
-Scout runs before `ask_advisor`, `/advisor-manual`, and automatic Advisor gates. It uses the configured Executor model and Executor reasoning effort in a separate model call. This adds cost and latency, but can reduce cost in the Advisor call. The compact result shows the model, selection counts, elapsed time, and usage/cost details; `Ctrl+O` shows bounded selected labels and the synthesis. Usage and cost details can be hidden in `/advisor-settings`.
-
-Scout receives a bounded manifest of conversation and tool-history groups after the normal tool disclosure, result-cap, and redaction policies are applied. The Scout manifest has its own fixed transport limit, while the reconstructed conversation remains bounded by the Advisor's remaining context budget after repository context; manifest metadata no longer consumes that Advisor conversation budget. A zero remaining budget produces no history groups. For a pending `ask_advisor` call, Scout receives only the allowlisted question and Git-context preference, never the draft or explicit attachment paths. Scout does not receive the deterministic Git context, draft, project preferences, or explicit tracked and untracked attachments. Those regions are appended later through their existing consent and cap rules.
-
-This experiment adapts the context-boundary idea from Zhang et al., ["FastContext: Training Efficient Repository Explorer for Coding Agents"](https://arxiv.org/html/2606.14066v1). It is not a reproduction of FastContext. pi-advisor Scout curates conversation history only.
+In the Settings, enable the Simple Mode for a quick start.
+![Pi Advisor Settings Panel](https://raw.githubusercontent.com/philipbrembeck/pi-advisor/refs/heads/main/assets/settings.png)
 
 ## Commands
 
-| Command | Purpose |
-| --- | --- |
-| `/advisor` | Enable the flow and optionally override the Executor, Advisor, or context limit. |
-| `/advisor-manual [focus]` | Open a TUI form for a parallel consultation, or consult immediately in non-TUI modes; shows progress in the footer. |
-| `/advisor-models` | Choose both models and their reasoning effort; current models are preselected. |
-| `/advisor-settings` | Configure behavior, context, gates, privacy, and output limits. |
-| `/advisor-off` | Disable the flow and turn off persistent activation. |
+| Command                   | What it does                                      |
+| ------------------------- | ------------------------------------------------- |
+| `/advisor`                | Enable the flow; choose available models when needed. |
+| `/advisor-manual [focus]` | Ask for an immediate second opinion.              |
+| `/advisor-models`         | Choose the Executor and Advisor models.           |
+| `/advisor-settings`       | Configure behavior, context, privacy, and limits. |
+| `/advisor-off`            | Disable the flow and persistent activation.       |
 
-In the interactive TUI, `/advisor-manual [focus]` opens a centered overlay. The optional focus text is prefilled and editable; Enter submits, Shift+Enter inserts a newline, Tab/Shift+Tab moves focus, and Escape cancels. The form lets you choose the permitted Git context level, with choices above the configured ceiling hidden. `None` withholds Git data only; it does not remove configured conversation history. After submission, the call, Scout, and Advisor streaming progress appear immediately in the transcript. Canceling has no consultation side effects. RPC, print, and JSON invocations retain their immediate argument-driven behavior.
-
-The Executor calls `ask_advisor({})` for a general review. It can pass a targeted `question` or a concise `draft` describing proposed work, validation, and remaining risks. If the Advisor explicitly says it cannot review a specifically named file, the Executor may make a sequential follow-up call with `includeTrackedFiles` when global consent is enabled and the file is relevant. Draft claims give the Advisor review context; they are not verification evidence.
+### Experimental Advisor Scout
 
-## What gets sent to the Advisor
+Advisor Scout is off by default. When enabled, the Executor model first selects relevant conversation history before the Advisor sees it. This adds a model call, latency, and cost. See the [configuration guide](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/configuration.md) for details.
 
-Advisor context can include user messages, tool calls, tool results, and repository information. Secret redaction is off by default, and tools without an explicit disclosure policy default to full context. Review the privacy settings before using the extension with sensitive work.
+## Privacy
 
-When Experimental Advisor Scout is enabled, the Executor model provider also receives bounded Advisor-eligible conversation history. Scout does not receive the deterministic repository, draft, preference, or explicit-file regions described below.
+Advisor requests can include user messages, tool calls, tool results, targeted questions, and repository information. `/advisor-settings` controls context, tool disclosure, redaction, and explicit file handoff. Secret redaction is off by default; when enabled, credential-shaped values in targeted questions are redacted before the provider request. Tools without an explicit policy use full context. Settings are global, so a project cannot silently change them.
 
-Repository context is configurable from no access through changed-file summaries to a capped patch. When context is disabled or its budget is zero, the Advisor is told it was withheld rather than shown an apparently clean tree. Explicit tracked and untracked file contents require separate global opt-ins; attachments are capped, redacted when configured, and sent as untrusted data.
+Read [Privacy and data handling](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/privacy.md) before using pi-advisor with sensitive work.
 
 ## Documentation
 
 - [Configuration and automatic loop gates](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/configuration.md)
 - [Privacy and data handling](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/privacy.md)
 - [Development](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/development.md)
-- [Documentation index](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/README.md)
-
-## Links
-
-- [MIT License](LICENSE)
+- [Benchmarking](docs/benchmark.md)
 - [Changelog](CHANGELOG.md)
+- [MIT License](LICENSE)
 - [npm package](https://www.npmjs.com/package/pi-advisor-flow)
 - [Why use an Advisor flow?](https://philipbrembeck.com/writings/2026/07/only-as-much-intelligence-as-you-need)

package/extensions/index.ts

@@ -1,16 +1,16 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { registerCommands } from "../src/commands.js";
+import { registerCommands } from "../src/commands/registration.js";
 import { setHerdrBlockedEmitter } from "../src/herdr.js";
 import { AdvisorSessionState } from "../src/session-state.js";
 import {
   consultAdvisor as consultAdvisorImplementation,
-  parseAutomaticDecision as parseAutomaticDecisionImplementation,
-  registerAdvisorTool,
   runAdvisorGate as runAdvisorGateImplementation,
-  ScoutStatusManager,
-} from "../src/tools.js";
+} from "../src/tools/consultation.js";
+import { parseAutomaticDecision as parseAutomaticDecisionImplementation } from "../src/tools/gate-protocol.js";
+import { registerAdvisorTool } from "../src/tools/registration.js";
+import { ScoutStatusManager } from "../src/tools/scout-status.js";
 
-export type { AdvisorConfig, GateFailureMode } from "../src/config.js";
+export type { AdvisorConfig, GateFailureMode } from "../src/config/types.js";
 export type {
   AdvisorConsultationResult,
   AdvisorGateFailure,
@@ -19,7 +19,7 @@ export type {
   ConsultationTrigger,
   GateDecision,
   GateTrigger,
-} from "../src/tools.js";
+} from "../src/tools/types.js";
 export const consultAdvisor = (
   ...args: Parameters<typeof consultAdvisorImplementation>
 ) => consultAdvisorImplementation(...args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-advisor-flow",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Advanced Executor/Advisor flow for Pi, fully configurable and extendable.",
   "keywords": [
     "pi-package",
@@ -28,33 +28,46 @@
     "README.md"
   ],
   "scripts": {
+    "bench:decisions": "bun bench/src/cli.ts decisions",
+    "bench:evaluate": "bun bench/src/cli.ts evaluate",
+    "bench:replay": "bun bench/src/cli.ts replay",
+    "bench:screen": "bun bench/src/cli.ts screen",
+    "check:boundaries": "node scripts/check-module-boundaries.mjs",
     "format": "bunx ultracite fix --linter-enabled=false",
     "lint": "bunx ultracite check",
     "lint:fix": "bunx ultracite fix",
     "package:check": "node scripts/check-package.mjs",
     "prepare": "husky",
+    "socket": "bunx socket optimize",
     "test": "bun test",
+    "test:bench": "bun --config=./bunfig.bench.toml test ./bench/test/",
     "typecheck": "tsc --noEmit"
   },
   "lint-staged": {
     "*.{json,jsonc,ts}": "bun run lint:fix --"
   },
+  "resolutions": {
+    "is-unicode-supported": "npm:@socketregistry/is-unicode-supported@^1",
+    "safe-buffer": "npm:@socketregistry/safe-buffer@^1"
+  },
   "overrides": {
     "brace-expansion": "5.0.9",
+    "is-unicode-supported": "npm:@socketregistry/is-unicode-supported@^1",
+    "safe-buffer": "npm:@socketregistry/safe-buffer@^1",
     "undici": "8.9.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.11",
+    "@biomejs/biome": "2.5.12",
     "@earendil-works/pi-ai": "^0.84.4",
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "@earendil-works/pi-tui": "^0.84.4",
-    "@types/node": "^26.4.0",
-    "bun-types": "1.3.14",
+    "@types/node": "^26.4.1",
+    "bun-types": "1.4.1",
     "husky": "^9.1.7",
     "lint-staged": "^17.4.1",
-    "typebox": "^1.3.21",
+    "typebox": "^1.3.25",
     "typescript": "^7.0.2",
-    "ultracite": "7.10.7"
+    "ultracite": "7.10.8"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.1",

package/src/commands/activation-preparation.ts

@@ -0,0 +1,117 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  advisorEffortRef,
+  advisorRef,
+  executorEffortRef,
+  executorRef,
+  getPersistedModelRefs,
+  setAdvisorEffortRef,
+  setAdvisorRef,
+  setExecutorEffortRef,
+  setExecutorRef,
+} from "../config/state.js";
+import { loadConfig } from "../config/storage.js";
+import {
+  getAvailableModelRefs,
+  getExplicitModelError,
+  planActivationModels,
+} from "./model-options.js";
+import { selectAdvisorModels } from "./model-picker.js";
+import { notify } from "./runtime.js";
+import type { CommandRuntime } from "./types.js";
+
+export interface PreparedActivationModels {
+  pendingExecutor?: string;
+  pickedModels: boolean;
+}
+
+export const loadCommandConfig = (ctx: ExtensionContext) => {
+  try {
+    loadConfig(ctx);
+    return true;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    notify(
+      ctx,
+      `Advisor command could not load configuration: ${message} Fix advisor.json and retry.`,
+      "error"
+    );
+    return false;
+  }
+};
+
+export const prepareActivationModels = async (
+  runtime: CommandRuntime,
+  ctx: ExtensionContext,
+  announce: boolean,
+  executorOverride: boolean,
+  advisorOverride: boolean
+): Promise<PreparedActivationModels | 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,
+    runtime.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 };
+};

package/src/commands/activation.ts

@@ -0,0 +1,135 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { parseArgs } from "../config/args.js";
+import {
+  advisorEffortRef,
+  advisorRef,
+  contextMaxCharsRef,
+  executorEffortRef,
+  executorRef,
+  setAdvisorEffortRef,
+  setAdvisorRef,
+  setContextMaxCharsRef,
+  setExecutorEffortRef,
+  setExecutorRef,
+} from "../config/state.js";
+import { saveConfig } from "../config/storage.js";
+import {
+  loadCommandConfig,
+  prepareActivationModels,
+} from "./activation-preparation.js";
+import {
+  ADVISOR_ACTIVATION_EXPLANATION,
+  findConfiguredModel,
+  hasAdvisorOverride,
+  hasExecutorOverride,
+} from "./model-options.js";
+import { notify } from "./runtime.js";
+import type { CommandRuntime, ThinkingLevel } from "./types.js";
+
+const resolveActivationModels = async (
+  runtime: CommandRuntime,
+  ctx: ExtensionContext
+) => {
+  const executor = findConfiguredModel(ctx, executorRef);
+  if (!executor) {
+    return {
+      error: executorRef
+        ? `Executor model not found: ${executorRef}`
+        : "Executor model not configured",
+    };
+  }
+  const advisor = findConfiguredModel(ctx, advisorRef);
+  if (!advisor) {
+    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 runtime.setExecutorModel(executor))) {
+    return { error: `No API key for Executor ${executorRef}` };
+  }
+  return {};
+};
+
+export const activateAdvisor = async (
+  runtime: CommandRuntime,
+  args: string,
+  ctx: ExtensionContext,
+  announce = true
+) => {
+  if (!loadCommandConfig(ctx)) {
+    return;
+  }
+  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(
+    runtime,
+    ctx,
+    announce,
+    executorOverride,
+    advisorOverride
+  );
+  if (!prepared) {
+    restoreRefs();
+    return;
+  }
+  const { error } = await resolveActivationModels(runtime, ctx);
+  if (error) {
+    restoreRefs();
+    notify(ctx, error, "error");
+    return;
+  }
+  // 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() || 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.
+  runtime.pendingExecutorModelRef = undefined;
+  if (executorEffortRef) {
+    runtime.pi.setThinkingLevel(executorEffortRef as ThinkingLevel);
+  }
+  if (!runtime.flowEnabled()) {
+    runtime.pi.setActiveTools([
+      ...runtime.pi.getActiveTools(),
+      "ask_advisor",
+      "record_advisor_outcome",
+    ]);
+  }
+  if (announce) {
+    notify(
+      ctx,
+      `${ADVISOR_ACTIVATION_EXPLANATION}\n\nAdvisor flow ready — Executor: ${executorRef} (thinking: ${executorEffortRef || "default"}) · Advisor: ${advisorRef} (thinking: ${advisorEffortRef || "default"})`,
+      "info"
+    );
+  }
+};

package/src/commands/lifecycle.ts

@@ -0,0 +1,83 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  alwaysOnRef,
+  executorRef,
+  getPersistedModelRefs,
+  setExecutorRef,
+} from "../config/state.js";
+import { loadConfig, saveConfig } from "../config/storage.js";
+import { herdrAdvisorActivity } from "../herdr.js";
+import { notify } from "./runtime.js";
+import type { CommandRuntime } from "./types.js";
+
+export type ActivateAdvisor = (
+  args: string,
+  ctx: ExtensionContext,
+  announce?: boolean
+) => Promise<void>;
+
+export const registerCommandLifecycle = (
+  runtime: CommandRuntime,
+  activateAdvisor: ActivateAdvisor
+) => {
+  runtime.pi.on("session_start", async (_event, ctx) => {
+    runtime.pendingExecutorModelRef = undefined;
+    // A malformed advisor.json or a provider auth failure must not reject a
+    // lifecycle handler and break session startup.
+    try {
+      loadConfig(ctx);
+      if (alwaysOnRef) {
+        await activateAdvisor("", ctx, false);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      notify(ctx, `Advisor activation failed: ${message}`, "error");
+    }
+  });
+
+  runtime.pi.on("model_select", (event, ctx) => {
+    // "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" || runtime.suppressModelSelectionSync) {
+      return;
+    }
+    const selected = `${event.model.provider}/${event.model.id}`;
+    if (!runtime.flowEnabled()) {
+      // Defer persistence until `/advisor` succeeds. This keeps ordinary model
+      // selection global defaults untouched when the flow is not enabled.
+      runtime.pendingExecutorModelRef = selected;
+      return;
+    }
+    runtime.pendingExecutorModelRef = undefined;
+    if (selected === executorRef) {
+      return;
+    }
+    const persisted = getPersistedModelRefs();
+    setExecutorRef(selected);
+    saveConfig(ctx, {
+      persistAdvisor: Boolean(persisted.advisor),
+      persistExecutor: true,
+    });
+  });
+
+  runtime.pi.on("session_shutdown", (_event, ctx) => {
+    if (ctx.hasUI) {
+      ctx.ui.setStatus("advisor-usage", undefined);
+    }
+    for (const [controller, token] of runtime.manualConsultations) {
+      controller.abort();
+      const timer = runtime.manualProgressTimers.get(controller);
+      if (timer) {
+        clearInterval(timer);
+        runtime.manualProgressTimers.delete(controller);
+      }
+      runtime.scoutStatus.release(ctx, token);
+    }
+    runtime.scoutStatus.clear(ctx);
+    runtime.manualConsultations.clear();
+    runtime.manualProgressTimers.clear();
+    runtime.manualProgress.clear();
+    herdrAdvisorActivity.clear();
+  });
+};