infinity-harness 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to this project are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.0] — 2026-08-25
+
+### Added
+
+- **Wizard picks models and thinking per tier + consulting master.** `/infinity:init` now asks which
+  models and thinking levels to use for easy/moderate/difficult tiers and for the consulting master
+  (with `off/minimal/low/medium/high/xhigh/max` plus `inherit`). Persisted in
+  `harness/model-router.json` via `thinkingByDifficulty`/`thinkingMaster`/`thinkingDefault`; exposed
+  via `/infinity:config` → Models.
+
+- **Customizable handoff granularity.** `goal → phase → sprint → feature → task → subtask`.
+  Wizard and `/infinity:config` both offer `goal` (single-session alias for `off`), `phase`
+  (old default), `sprint`, `feature`, **default `task`**, `subtask`, and `off`. A finer choice
+  implies coarser boundaries (picking `task` also hands off on feature/sprint/phase). Fixed:
+  `task`-scoped handoff previously never fired because only `phase` was compared.
+
+- **Dashboard blinks the active branch.** Phase dot `pulse`, current feature/sprint/goal cards and the
+  active task row now pulse while being developed; `prefers-reduced-motion` disables them.
+
+### Fixed
+
+- **Research autopilot stalled after pass.** `infinity_validate` now auto-advances on PASS when
+  the phase's mode is `autopilot` (mirrors `decideNext`), so `research → define` no longer requires
+  manually typing `continue`.
+- **`alt+j/k/o` never fired.** Editor shortcut only runs when the editor has focus; the TUI
+  selector/overlay swallows input. Added `KeyId` shortcuts plus a raw `onTerminalInput`
+  fallback (`\x1bj/k/o`) installed on `session_start`.
+- **Handoff threshold `0.7 → 0.6`.** Long BUILD phases now hand off earlier, under the context
+  window before compaction.
+
 ## [2.4.0] — 2026-08-24
 
 Two settings that were one switch each, and one switch turned out to be the wrong shape for both

package/extensions/infinity-harness/index.ts

@@ -297,15 +297,33 @@ export default function (pi: ExtensionAPI): void {
 
   // -- session handoff ------------------------------------------------------
 
-  /** The task the pipeline is on right now, or null. */
-  const activeTaskKey = (dir: string): string | null => {
+  /** The task/feature/sprint/goal/subtask the pipeline is on right now, or null. */
+  const activePlanKeys = (dir: string): { task: string | null; feature: string | null; sprint: string | null; goal: string | null; subtask: string | null; } => {
     try {
       const { list } = loadFeatureList(dir);
-      return nextActionableTask(list)?.compositeKey ?? null;
+      const task = nextActionableTask(list);
+      const flat = task ? loadFeatureList(dir).list.features?.find((f) => f.id === task.featureId) ?? null : null;
+      // Resolve sprint/goal via list, and active subtask of the focused task.
+      const taskKey = task?.compositeKey ?? null;
+      const featureId = task?.featureId ?? null;
+      const feature = featureId ? (list.features ?? []).find((f) => f.id === featureId) ?? null : null;
+      const sprintId = feature?.sprintId ?? null;
+      const goalId = feature?.goalId ?? (sprintId ? (list.sprints ?? []).find((s) => s.id === sprintId)?.goalId ?? null : null) ?? (list.goals?.[0]?.id ?? null);
+      const sprint = sprintId ? sprintId : null;
+      const goal = goalId ? goalId : null;
+      // First non-complete subtask of the active task.
+      let subtask: string | null = null;
+      const rawTask = feature && task ? feature.tasks.find((t) => t.id === task.id || t.key === task.key) ?? null : null;
+      if (rawTask?.subtasks?.length) {
+        const cur = rawTask.subtasks.find((s) => s.status !== "complete") ?? null;
+        if (cur) subtask = `${taskKey}#${cur.id ?? cur.title}`;
+      }
+      return { task: taskKey, feature: featureId, sprint, goal, subtask };
     } catch {
-      return null;
+      return { task: null, feature: null, sprint: null, goal: null, subtask: null };
     }
   };
+  const activeTaskKey = (dir: string): string | null => activePlanKeys(dir).task;
 
   /** How full this session's context is, 0..1, or null when pi cannot say. */
   const contextRatio = (ctx: ExtensionContext): number | null => {
@@ -355,12 +373,41 @@ export default function (pi: ExtensionAPI): void {
     }
     try {
       const { config } = loadConfig(dir);
+      const toKeys = activePlanKeys(dir);
+      // Map caller's fromTask (a compositeKey) back to its feature/sprint etc for the "from" side.
+      // We derive them from the plan so goal/sprint/feature boundaries are comparable.
+      let fromGoal: string | null = null;
+      let fromSprint: string | null = null;
+      let fromFeature: string | null = null;
+      try {
+        const { list } = loadFeatureList(dir);
+        if (fromTask) {
+          const ft = ((): { featureId: string } | null => {
+            for (const f of list.features ?? []) for (const t of f.tasks ?? []) if (t.key === fromTask || `${f.id}/${t.id}` === fromTask || t.id === fromTask) return { featureId: f.id };
+            return null;
+          })();
+          if (ft) {
+            fromFeature = ft.featureId;
+            const feat = list.features.find((f) => f.id === ft.featureId) ?? null;
+            fromSprint = feat?.sprintId ?? null;
+            fromGoal = feat?.goalId ?? (fromSprint ? (list.sprints ?? []).find((s) => s.id === fromSprint)?.goalId ?? null : null) ?? null;
+          }
+        }
+      } catch {}
       const decision = shouldHandoff({
         config,
         fromPhase,
         toPhase,
         fromTask,
-        toTask: activeTaskKey(dir),
+        toTask: toKeys.task,
+        fromGoal,
+        toGoal: toKeys.goal,
+        fromSprint,
+        toSprint: toKeys.sprint,
+        fromFeature,
+        toFeature: toKeys.feature,
+        fromSubtask: null, // subtask delta is derived from task payload; tracked via fromTask composite + activePlanKeys
+        toSubtask: toKeys.subtask,
         contextRatio: contextRatio(ctx),
       });
       if (!decision.handoff) return false;
@@ -496,6 +543,7 @@ export default function (pi: ExtensionAPI): void {
 
     view = defaultView();
     refreshWidget(ctx);
+    installTerminalShortcuts(ctx);
     const { config } = loadConfig(dir);
     lastBriefPhase = config.currentPhase;
 
@@ -1042,6 +1090,34 @@ export default function (pi: ExtensionAPI): void {
       const lines = gate.checks
         .map((c) => `${c.advisory ? "·" : c.pass ? "+" : "x"} ${c.name}: ${c.detail}`)
         .join("\n");
+      // On a passing gate in autopilot, the tool itself advances the phase
+      // so a run without the continuous loop armed still moves forward when
+      // the agent calls infinity_validate — that's what the brief says will
+      // happen ("PASS → the harness advances") and what stopped research
+      // from ever reaching DEFINE until someone typed "continue".
+      if (gate.overall && !params?.feature && !params?.task) {
+        try {
+          const { needsApproval } = await import("../../src/approval.ts");
+          const fresh = loadConfig(dir).config;
+          if (!needsApproval(fresh, fresh.currentPhase)) {
+            const { advancePhase } = await import("../../src/core/phases.ts");
+            const moved = await advancePhase(dir);
+            if (moved.ok && moved.to) {
+              refreshWidget(ctx as ExtensionContext);
+              const brief = await briefText(dir);
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: `Gate PASS on ${gate.phase} → advanced ${moved.from} → ${moved.to}\n${lines}\n\n${brief}`,
+                  },
+                ],
+                details: { ...gate, advanced: moved } as unknown as typeof gate,
+              };
+            }
+          }
+        } catch {}
+      }
       return {
         content: [
           {
@@ -1313,7 +1389,7 @@ export default function (pi: ExtensionAPI): void {
       }
 
       const wizard = ctx.hasUI
-        ? await runIntakeWizard({ prompt: prompterFor(ctx), brief: goalFromArgs || null })
+        ? await runIntakeWizard({ prompt: prompterFor(ctx), brief: goalFromArgs || null, models: () => availableModels(ctx) })
         : ({ cancelled: false, plan: unattendedIntake(goalFromArgs || null) } as const);
 
       if (wizard.cancelled) {
@@ -1331,6 +1407,17 @@ export default function (pi: ExtensionAPI): void {
         display: plan.display,
         session: plan.session,
         brief: plan.brief,
+        router: plan.router
+          ? ({
+              enabled: !!plan.router.enabled,
+              byDifficulty: plan.router.byDifficulty as unknown as Record<string, string>,
+              thinkingByDifficulty: plan.router.thinkingByDifficulty as unknown as Record<string, string>,
+              master: plan.router.master ?? "",
+              thinkingMaster: plan.router.thinkingMaster as unknown as string,
+              default: plan.router.default ?? "",
+              thinkingDefault: plan.router.thinkingDefault as unknown as string,
+            } as Partial<import("../../src/modelRouter.ts").RouterConfig>)
+          : undefined,
         force,
       });
       if (!result.ok) {
@@ -2352,24 +2439,58 @@ export default function (pi: ExtensionAPI): void {
   // `alt+` and not `ctrl+`: pi already binds ctrl+j (newline), ctrl+k (delete
   // to line end) and ctrl+o (expand tool output). Shadowing an editor key to
   // scroll a widget would be a worse bug than the one being fixed.
+  //
+  // Shortcuts are editor-focused via registerShortcut, but also handled as a
+  // raw terminal fallback so they work when an overlay or selector has focus
+  // or when the terminal sends the legacy ESC+j sequence that the editor
+  // otherwise swallows as text.
+
+  const scrollDown = async (ctx: ExtensionContext): Promise<void> => moveView(ctx, SCROLL_STEP);
+  const scrollUp = async (ctx: ExtensionContext): Promise<void> => moveView(ctx, -SCROLL_STEP);
+  const toggleExpand = async (ctx: ExtensionContext): Promise<void> => {
+    view = { ...view, expanded: !view.expanded };
+    refreshWidget(ctx);
+  };
 
-  pi.registerShortcut("alt+j", {
-    description: "infinity-harness: scroll the plan down",
-    handler: async (ctx: ExtensionContext) => moveView(ctx, SCROLL_STEP),
-  });
-
-  pi.registerShortcut("alt+k", {
-    description: "infinity-harness: scroll the plan up",
-    handler: async (ctx: ExtensionContext) => moveView(ctx, -SCROLL_STEP),
-  });
-
-  pi.registerShortcut("alt+o", {
-    description: "infinity-harness: expand or collapse the plan widget",
-    handler: async (ctx: ExtensionContext) => {
-      view = { ...view, expanded: !view.expanded };
-      refreshWidget(ctx);
-    },
-  });
+  pi.registerShortcut("alt+j", { description: "infinity-harness: scroll the plan down", handler: scrollDown });
+  pi.registerShortcut("alt+k", { description: "infinity-harness: scroll the plan up", handler: scrollUp });
+  pi.registerShortcut("alt+o", { description: "infinity-harness: expand or collapse the plan widget", handler: toggleExpand });
+  // Uppercase handling covered by the raw terminal fallback below which
+  // lowercases data before matching; KeyId type only allows lowercase.
+
+  // Fallback raw input handler — runs even when the editor is not the
+  // focused component (e.g. a selector is open). Must be installed per-
+  // session because onTerminalInput is a UI session thing, not a global.
+  let removeTerminalShortcut: (() => void) | null = null;
+  const installTerminalShortcuts = (ctx: ExtensionContext): void => {
+    try {
+      removeTerminalShortcut?.();
+    } catch {}
+    try {
+      // matchesKey lives in pi-tui but re-exported by pi; use the extension
+      // input raw matcher via string compare for ESC-prefixed alt.
+      removeTerminalShortcut = ctx.ui.onTerminalInput((data: string) => {
+        // Legacy alt+letter is ESC + lower letter. Kitty may send CSI-u; both
+        // are handled by normalising to lookahead then matching via the same
+        // strings registerShortcut uses.
+        const lower = data.toLowerCase();
+        // Fast path: alt+j/k/o as ESC + letter (\x1bj) or higher-plane.
+        if (data === "\x1bj" || data === "\x1bJ" || lower === "\x1bj") {
+          void scrollDown(ctx);
+          return { consume: true };
+        }
+        if (data === "\x1bk" || data === "\x1bK" || lower === "\x1bk") {
+          void scrollUp(ctx);
+          return { consume: true };
+        }
+        if (data === "\x1bo" || data === "\x1bO" || lower === "\x1bo") {
+          void toggleExpand(ctx);
+          return { consume: true };
+        }
+        return undefined;
+      });
+    } catch {}
+  };
 
   pi.registerCommand("infinity:scroll", {
     description: "Move the plan widget — up, down, top, bottom, expand, follow",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinity-harness",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "A pi agent extension that runs a gated build pipeline unattended \u2014 enforces phases, validates with deterministic gates, and keeps working for hours or days without losing the plan.",
   "type": "module",
   "keywords": [

package/src/core/config.ts

@@ -50,7 +50,7 @@ export function defaultConfig(): HarnessConfig {
     },
     phases: { enabled: [...DEFAULT_ENABLED_PHASES] },
     roles: { strict: false },
-    session: { handoff: "phase", contextThreshold: 0.7, carryNotes: true },
+    session: { handoff: "task", contextThreshold: 0.6, carryNotes: true },
     approvals: { research: false, define: false, plan: false },
     phaseModes: Object.fromEntries(DEFAULT_ENABLED_PHASES.map((p) => [p, "autopilot"])),
     workflow: { id: "autopilot", name: "autopilot" },

package/src/core/init.ts

@@ -162,6 +162,9 @@ export type InitOptions = {
   session?: Partial<HarnessConfig["session"]>;
   /** What the human said they want built. Recorded, and read by the first brief. */
   brief?: string | null;
+  /** Model routing for difficulty tiers and consulting. */
+  router?: Partial<import("../../src/modelRouter.ts").RouterConfig>;
+
 };
 
 export type InitResult = {
@@ -238,6 +241,23 @@ export function initHarness(targetDir: string, options: InitOptions = {}): InitR
       at: new Date().toISOString(),
     };
   }
+  if (options.router) {
+    try {
+      const routerPath = P.modelRouterPath(targetDir);
+      mkdirSync(dirname(routerPath), { recursive: true });
+      let existing: Record<string, unknown> = {};
+      try { if (existsSync(routerPath)) existing = JSON.parse(readFileSync(routerPath, "utf-8")); } catch { /* ignore corrupt */ }
+      const incoming = options.router as Record<string, unknown>;
+      const merged: Record<string, unknown> = { ...existing, ...incoming };
+      if ((incoming as { byDifficulty?: unknown }).byDifficulty && typeof (incoming as { byDifficulty?: unknown }).byDifficulty === "object") {
+        merged.byDifficulty = { ...((existing.byDifficulty as Record<string,string>) ?? {}), ...(incoming.byDifficulty as Record<string,string>) };
+      }
+      if ((incoming as { thinkingByDifficulty?: unknown }).thinkingByDifficulty && typeof (incoming as { thinkingByDifficulty?: unknown }).thinkingByDifficulty === "object") {
+        merged.thinkingByDifficulty = { ...((existing.thinkingByDifficulty as Record<string,string>) ?? {}), ...(incoming.thinkingByDifficulty as Record<string,string>) };
+      }
+      writeFileSync(routerPath, JSON.stringify(merged, null, 2), "utf-8");
+    } catch { /* best-effort */ }
+  }
 
   const write = (path: string, body: string) => {
     const rel = path.slice(targetDir.length + 1);

package/src/core/settings.ts

@@ -28,7 +28,8 @@ export type SettingType =
   | { kind: "choice"; choices: readonly string[] }
   | { kind: "multi"; choices: readonly string[] }
   /** Resolved at runtime from the models pi has configured. */
-  | { kind: "model" };
+  | { kind: "model" }
+  | { kind: "thinking" };
 
 export type Setting = {
   /** Dotted path within the file. */
@@ -75,6 +76,13 @@ export const SETTINGS: SettingsGroup[] = [
         help: DIFFICULTY_HELP,
         type: { kind: "model" },
       },
+      {
+        path: "thinkingByDifficulty.easy",
+        file: "router",
+        label: "Easy thinking",
+        help: "Thinking level for easy tasks. Empty inherits pi's current level.",
+        type: { kind: "thinking" },
+      },
       {
         path: "byDifficulty.moderate",
         file: "router",
@@ -82,6 +90,13 @@ export const SETTINGS: SettingsGroup[] = [
         help: DIFFICULTY_HELP,
         type: { kind: "model" },
       },
+      {
+        path: "thinkingByDifficulty.moderate",
+        file: "router",
+        label: "Moderate thinking",
+        help: "Thinking level for moderate tasks. Empty inherits pi's current level.",
+        type: { kind: "thinking" },
+      },
       {
         path: "byDifficulty.difficult",
         file: "router",
@@ -89,6 +104,13 @@ export const SETTINGS: SettingsGroup[] = [
         help: DIFFICULTY_HELP,
         type: { kind: "model" },
       },
+      {
+        path: "thinkingByDifficulty.difficult",
+        file: "router",
+        label: "Difficult thinking",
+        help: "Thinking level for difficult tasks. Empty inherits pi's current level.",
+        type: { kind: "thinking" },
+      },
       {
         path: "master",
         file: "router",
@@ -96,6 +118,13 @@ export const SETTINGS: SettingsGroup[] = [
         help: "Never assigned to a task directly — reached only when the ladder is exhausted and the harness asks for one opinion.",
         type: { kind: "model" },
       },
+      {
+        path: "thinkingMaster",
+        file: "router",
+        label: "Master thinking",
+        help: "Thinking level for the master consultation model.",
+        type: { kind: "thinking" },
+      },
       {
         path: "default",
         file: "router",
@@ -103,6 +132,13 @@ export const SETTINGS: SettingsGroup[] = [
         help: "Used when nothing more specific matches. Empty means pi's current model.",
         type: { kind: "model" },
       },
+      {
+        path: "thinkingDefault",
+        file: "router",
+        label: "Default thinking",
+        help: "Fallback thinking level when no tier-specific level is set.",
+        type: { kind: "thinking" },
+      },
       {
         path: "consultation.enabled",
         file: "router",
@@ -317,8 +353,8 @@ export const SETTINGS: SettingsGroup[] = [
         path: "session.handoff",
         file: "config",
         label: "Fresh session",
-        help: "phase: each phase starts clean · task: cleanest context, best with small models · off: one session for the whole run.",
-        type: { kind: "choice", choices: ["off", "phase", "task"] },
+        help: "goal: one session · phase: per phase (old) · sprint/feature: when plan grouping changes · task: every task (default) · subtask: every subtask. Coarser levels still fire.",
+        type: { kind: "choice", choices: ["off", "goal", "phase", "sprint", "feature", "task", "subtask"] },
       },
       {
         path: "session.contextThreshold",
@@ -538,6 +574,8 @@ export function formatValue(setting: Setting, value: unknown): string {
       return value ? "on" : "off";
     case "model":
       return typeof value === "string" && value.trim() ? value : "(pi's current model)";
+    case "thinking":
+      return typeof value === "string" && value.trim() ? value : "(inherit)";
     case "text":
       return typeof value === "string" && value.trim() ? value : "(not set)";
     case "multi":
@@ -583,6 +621,8 @@ export function parseDuration(input: string): number | null {
 
 export type ValidationResult = { ok: true; value: unknown } | { ok: false; error: string };
 
+export const THINKING_CHOICES = ["(inherit)", "off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
 /** Coerce and bounds-check a raw answer for `setting`. */
 export function coerce(setting: Setting, raw: string): ValidationResult {
   const t = setting.type;
@@ -596,6 +636,13 @@ export function coerce(setting: Setting, raw: string): ValidationResult {
       if (t.max !== undefined && n > t.max) return { ok: false, error: `must be at most ${t.max}` };
       return { ok: true, value: n };
     }
+    case "thinking": {
+      const v = raw.trim();
+      if (!v || v === "(inherit)") return { ok: true, value: "" };
+      const allowed = new Set(THINKING_CHOICES.slice(1) as readonly string[]);
+      if (!allowed.has(v)) return { ok: false, error: `must be one of: ${THINKING_CHOICES.join(", ")}` };
+      return { ok: true, value: v };
+    }
     case "text":
     case "model": {
       const v = raw.trim();

package/src/core/types.ts

@@ -158,14 +158,19 @@ export type RetryBucket = {
  * session boundary costs nothing but the brief, and the brief is what the
  * agent should be working from anyway.
  */
+export type HandoffGranularity = "off" | "goal" | "phase" | "sprint" | "feature" | "task" | "subtask";
+
 export type SessionPolicy = {
   /**
    * When to hand off to a fresh session.
-   *   off    never — one session for the whole run (the old behaviour)
-   *   phase  when the pipeline advances a phase
-   *   task   when the pipeline advances a phase or moves to a different task
+   *   off/goal  never — one session for the whole run (the old behaviour)
+   *   phase     when the pipeline advances a phase
+   *   sprint    when the active sprint changes (or phase)
+   *   feature   when the active feature changes (or coarser)
+   *   task      when the active task changes (or coarser) — default
+   *   subtask   when the active subtask changes (or coarser)
    */
-  handoff: "off" | "phase" | "task";
+  handoff: HandoffGranularity;
   /**
    * Hand off early once the context is this full, as a fraction of the
    * window. 0 disables it. This is what keeps a long BUILD phase — which may

package/src/handoff.ts

@@ -23,12 +23,12 @@
  * that, only from a command handler, and the adapter is where pi lives.
  */
 
-import type { HarnessConfig, Phase, SessionPolicy } from "./core/types.ts";
+import type { HarnessConfig, HandoffGranularity, Phase, SessionPolicy } from "./core/types.ts";
 import { pendingSessionPath } from "./core/paths.ts";
 import { readJsonSafe, writeJsonAtomic, removeFile, fileExists } from "./core/fsx.ts";
 
 /** Why a session is being replaced. Shown to the human and to the next agent. */
-export type HandoffReason = "phase" | "task" | "context" | "goal-pass" | "manual";
+export type HandoffReason = HandoffGranularity | "context" | "goal-pass" | "manual";
 
 export type PendingHandoff = {
   reason: HandoffReason;
@@ -51,22 +51,40 @@ export type HandoffSignals = {
   /** Composite key of the task in focus before and after. */
   fromTask: string | null;
   toTask: string | null;
+  /** IDs for the coarser plan levels (goal/feature/sprint/subtask). Null means "no active one". */
+  fromGoal?: string | null;
+  toGoal?: string | null;
+  fromSprint?: string | null;
+  toSprint?: string | null;
+  fromFeature?: string | null;
+  toFeature?: string | null;
+  fromSubtask?: string | null;
+  toSubtask?: string | null;
   /** Fraction of the context window in use, 0..1, or null when unknown. */
   contextRatio: number | null;
 };
 
 export type HandoffDecision = { handoff: false } | { handoff: true; reason: HandoffReason; detail: string };
 
+const GRANULARITIES: readonly HandoffGranularity[] = ["off", "goal", "phase", "sprint", "feature", "task", "subtask"] as const;
+
+export function isHandoffGranularity(v: unknown): v is HandoffGranularity {
+  return typeof v === "string" && (GRANULARITIES as readonly string[]).includes(v);
+}
+
 export function defaultSessionPolicy(): SessionPolicy {
-  return { handoff: "phase", contextThreshold: 0.7, carryNotes: true };
+  return { handoff: "task", contextThreshold: 0.6, carryNotes: true };
 }
 
 function policyOf(config: HarnessConfig): SessionPolicy {
   const p = (config.session ?? {}) as Partial<SessionPolicy>;
-  const handoff = p.handoff === "off" || p.handoff === "task" || p.handoff === "phase" ? p.handoff : "phase";
-  const raw = typeof p.contextThreshold === "number" ? p.contextThreshold : 0.7;
+  const handoff: HandoffGranularity = isHandoffGranularity(p.handoff) ? p.handoff : "task";
+  // "goal" is an alias for the single-session behaviour; keep the storage
+  // as "goal" so the wizard round-trips, but treat it as "off" here.
+  const effective: HandoffGranularity = handoff === "goal" ? "off" : handoff;
+  const raw = typeof p.contextThreshold === "number" ? p.contextThreshold : 0.6;
   return {
-    handoff,
+    handoff: effective,
     // A threshold of 1 or more can never fire and a negative one always would;
     // both are configuration mistakes, and clamping is kinder than either.
     contextThreshold: raw <= 0 ? 0 : Math.min(0.95, raw),
@@ -81,6 +99,14 @@ function policyOf(config: HarnessConfig): SessionPolicy {
  * arrives after compaction has already happened has arrived too late to be the
  * thing that prevented it.
  */
+/** Coarsest → finest. Handoff fires at the chosen level and everything coarser. */
+const LEVEL_ORDER: readonly HandoffGranularity[] = ["off", "goal", "phase", "sprint", "feature", "task", "subtask"] as const;
+
+function rank(g: HandoffGranularity): number {
+  const i = (LEVEL_ORDER as readonly string[]).indexOf(g);
+  return i < 0 ? 5 : i;
+}
+
 export function shouldHandoff(signals: HandoffSignals): HandoffDecision {
   const policy = policyOf(signals.config);
   if (policy.handoff === "off") return { handoff: false };
@@ -94,20 +120,62 @@ export function shouldHandoff(signals: HandoffSignals): HandoffDecision {
     };
   }
 
-  if (signals.toPhase && signals.fromPhase !== signals.toPhase) {
+  const lvl = rank(policy.handoff);
+
+  // Hierarchy: off(0) < goal(1) < phase(2) < sprint(3) < feature(4) < task(5) < subtask(6).
+  // Finer granularity implies coarser boundaries too (task change implies feature/sprint/phase
+  // may have changed, but we check coarsest first so the reason reflects the highest level).
+  // Only boundaries at or coarser than the configured granularity? No —
+  // the knob is "how fine do you want to go". Choosing "task" means
+  // phase/feature/sprint/goal AND task boundaries fire; choosing "phase"
+  // means only phase (and coarser goal) fires. So a boundary fires iff
+  // its rank <= chosen rank. task (5) should not fire when handoff is phase (2). Hence <= lvl.
+  // Fine-grained choice: the wizard knob is the *coarsest* level that still
+  // gets a fresh session. Picking "task" means every task gets its own
+  // session (feature/sprint/phase do too, implicitly). So a boundary fires
+  // iff chosenRank >= boundaryRank.
+  // Phase always hands off (except off/goal) because phases are the harness
+  // backbone; a phase change must never ride the old session's context.
+  if (signals.toPhase && signals.fromPhase !== signals.toPhase && lvl >= 2) {
     return {
       handoff: true,
       reason: "phase",
       detail: `${(signals.fromPhase ?? "start").toUpperCase()} → ${signals.toPhase.toUpperCase()}`,
     };
   }
-
-  if (policy.handoff === "task" && signals.toTask && signals.fromTask !== signals.toTask) {
-    return {
-      handoff: true,
-      reason: "task",
-      detail: `${signals.fromTask ?? "no task"} → ${signals.toTask}`,
-    };
+  // "goal/off" never fires here — off early-returned, "goal" was mapped to off.
+  // Keep for completeness if rank comparison changes; guarded by lvl so it
+  // doesn't resurrect. retain dead code removed check.
+  void lvl;
+  if (signals.fromSprint !== undefined || signals.toSprint !== undefined) {
+    const sFrom = (signals.fromSprint ?? null)?.trim() || null;
+    const sTo = (signals.toSprint ?? null)?.trim() || null;
+    if (sFrom !== sTo && (sTo || sFrom) && lvl >= 3) {
+      return { handoff: true, reason: "sprint" as HandoffReason, detail: `${sFrom ?? "no sprint"} → ${sTo ?? "no sprint"}` };
+    }
+  }
+  if (signals.fromFeature !== undefined || signals.toFeature !== undefined) {
+    const fFrom = (signals.fromFeature ?? null)?.trim() || null;
+    const fTo = (signals.toFeature ?? null)?.trim() || null;
+    if (fFrom !== fTo && (fTo || fFrom) && lvl >= 4) {
+      return { handoff: true, reason: "feature" as HandoffReason, detail: `${fFrom ?? "no feature"} → ${fTo ?? "no feature"}` };
+    }
+  }
+  if (lvl >= 5) {
+    if ((signals.fromTask ?? null) !== (signals.toTask ?? null) && (signals.fromTask || signals.toTask)) {
+      return {
+        handoff: true,
+        reason: "task",
+        detail: `${signals.fromTask ?? "no task"} → ${signals.toTask ?? "no task"}`,
+      };
+    }
+  }
+  if (lvl >= 6) {
+    const stFrom = (signals.fromSubtask ?? null)?.trim() || null;
+    const stTo = (signals.toSubtask ?? null)?.trim() || null;
+    if (stFrom !== stTo && (stTo || stFrom)) {
+      return { handoff: true, reason: "subtask" as HandoffReason, detail: `${stFrom ?? "no subtask"} → ${stTo ?? "no subtask"}` };
+    }
   }
 
   return { handoff: false };
@@ -168,10 +236,15 @@ export function composeKickoff(
   detail: string,
   carry: string | null,
 ): string {
-  const why: Record<HandoffReason, string> = {
+  const why: Record<string, string> = {
     phase: "The pipeline advanced, so the run continues in a clean session.",
     task: "The run moved to a different task, so it continues in a clean session.",
+    sprint: "The active sprint changed, so the run continues in a clean session.",
+    feature: "The active feature changed, so the run continues in a clean session.",
+    goal: "The active goal changed, so the run continues in a clean session.",
+    subtask: "The active subtask changed, so the run continues in a clean session.",
     context: "The previous session's context was filling up, so the run continues in a clean one.",
+    off: "Session handoff is off.",
     "goal-pass": "A goal pass finished, so the next pass starts in a clean session.",
     manual: "A human asked for a fresh session.",
   };

package/src/intake.ts

@@ -53,6 +53,16 @@ export type IntakeAnswers = {
   handoff?: SessionPolicy["handoff"];
   /** What the surfaces should draw. Defaults to the `focus` template. */
   display?: DisplayPolicy;
+  /** Model routing for difficulty tiers and consulting. */
+  router?: {
+    enabled: boolean;
+    byDifficulty: Record<string, string>;
+    thinkingByDifficulty?: Partial<Record<string, string>>;
+    master?: string;
+    thinkingMaster?: string;
+    default?: string;
+    thinkingDefault?: string;
+  };
 };
 
 export type IntakePlan = {
@@ -66,6 +76,7 @@ export type IntakePlan = {
   approvals: ApprovalPolicy;
   session: SessionPolicy;
   display: DisplayPolicy;
+  router?: IntakeAnswers["router"];
   /** What the human should be told about what they just chose. */
   summary: string;
   /** Things that will bite later if left as they are. */
@@ -100,10 +111,10 @@ export function planIntake(answers: IntakeAnswers): IntakePlan {
   const phases = normalizePhases(workflow.phases);
   const phaseModes = normalizeModes(workflow.modes, phases);
 
-  const handoff = answers.handoff ?? "phase";
+  const handoff = answers.handoff ?? "task";
   const session: SessionPolicy = {
     handoff,
-    contextThreshold: handoff === "off" ? 0 : 0.7,
+    contextThreshold: handoff === "off" ? 0 : 0.6,
     carryNotes: true,
   };
 
@@ -152,6 +163,7 @@ export function planIntake(answers: IntakeAnswers): IntakePlan {
     },
     session,
     display,
+    router: answers.router,
     summary: summarize(workflow, phases, phaseModes, session, display, brief),
     warnings,
   };
@@ -216,20 +228,40 @@ export const HANDOFF_QUESTION: Question = {
   id: "handoff",
   title: "When should the run start a fresh session?",
   options: [
+    {
+      value: "goal",
+      label: "per goal — one session for the whole run",
+      help: "The old single-session run. Every task accumulates context until compaction.",
+    },
     {
       value: "phase",
-      label: "every phase (recommended)",
-      help: "Each phase starts clean, working from the brief. Keeps the context small on long runs.",
+      label: "every phase",
+      help: "Old default. Each phase starts clean from the brief.",
+    },
+    {
+      value: "sprint",
+      label: "every sprint",
+      help: "New session whenever the active sprint changes (or phase).",
+    },
+    {
+      value: "feature",
+      label: "every feature",
+      help: "New session on each feature boundary (and sprint/phase).",
     },
     {
       value: "task",
-      label: "every task",
-      help: "The cleanest context per unit of work. Best with small models; costs one extra brief per task.",
+      label: "every task (recommended)",
+      help: "Each task gets a clean session. Best isolation; one extra brief per task.",
+    },
+    {
+      value: "subtask",
+      label: "every subtask",
+      help: "Finest grain — each subtask gets a fresh session. Most isolation, most churn.",
     },
     {
       value: "off",
-      label: "never — one long session",
-      help: "The old behaviour. The context grows for the whole run and compaction takes over.",
+      label: "never — alias for per goal",
+      help: "Same as per goal — one long session without fresh starts.",
     },
   ],
 };

package/src/modelRouter.ts

@@ -11,6 +11,14 @@ import { writeJsonAtomic, stripBom } from "./core/fsx.ts";
 export const ROUTER_FILE = "harness/model-router.json";
 export const ROUTER_VERSION = 1;
 
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+export const THINKING_LEVELS: readonly ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+export function isThinkingLevel(v: unknown): v is ThinkingLevel {
+  return typeof v === "string" && (THINKING_LEVELS as readonly string[]).includes(v);
+}
+
 export interface RouterConfig {
   version: number;
   enabled: boolean;
@@ -24,6 +32,10 @@ export interface RouterConfig {
   byTask?: Record<string, string>;
   consultation?: { enabled: boolean; maxPerTask: number; oneStepOnly: boolean; requireExhaustion: boolean };
   budgets?: { maxReworksPerRun: number; maxReplansPerRun: number; maxReviewBounces: number };
+  /** Thinking level per tier, and for master/default. Empty means inherit pi's current level. */
+  thinkingByDifficulty?: Partial<Record<string, ThinkingLevel | "">>;
+  thinkingMaster?: ThinkingLevel | "";
+  thinkingDefault?: ThinkingLevel | "";
 }
 
 /**
@@ -52,6 +64,9 @@ export const DEFAULT_ROUTER: RouterConfig = {
   byTask: {},
   consultation: { enabled: true, maxPerTask: 1, oneStepOnly: true, requireExhaustion: true },
   budgets: { maxReworksPerRun: 3, maxReplansPerRun: 2, maxReviewBounces: 2 },
+  thinkingByDifficulty: { easy: "" as ThinkingLevel | "", moderate: "" as ThinkingLevel | "", difficult: "" as ThinkingLevel | "" } as Partial<Record<string, ThinkingLevel | "">>,
+  thinkingMaster: "" as ThinkingLevel | "",
+  thinkingDefault: "" as ThinkingLevel | "",
 };
 
 export const DIFFICULTY_LADDER: Array<"easy" | "moderate" | "difficult"> = ["easy", "moderate", "difficult"];
@@ -68,9 +83,13 @@ export function saveRouterConfig(projectDir: string, cfg: RouterConfig): void {
   writeJsonAtomic(routerPath(projectDir), cfg);
 }
 
+function normalizeThinking(v: unknown): ThinkingLevel | "" {
+  return typeof v === "string" && (THINKING_LEVELS as readonly string[]).includes(v) ? (v as ThinkingLevel) : "";
+}
+
 export function loadRouterConfig(projectDir?: string): RouterConfig {
   const p = routerPath(projectDir);
-  if (!existsSync(p)) return { ...DEFAULT_ROUTER, byDifficulty: { ...DEFAULT_ROUTER.byDifficulty! }, byPhase: {}, byRole: {}, byFeature: {}, bySprint: {}, byTask: {}, consultation: { ...DEFAULT_ROUTER.consultation! }, budgets: { ...DEFAULT_ROUTER.budgets! } };
+  if (!existsSync(p)) return { ...DEFAULT_ROUTER, byDifficulty: { ...DEFAULT_ROUTER.byDifficulty! }, byPhase: {}, byRole: {}, byFeature: {}, bySprint: {}, byTask: {}, consultation: { ...DEFAULT_ROUTER.consultation! }, budgets: { ...DEFAULT_ROUTER.budgets! }, thinkingByDifficulty: { ...(DEFAULT_ROUTER.thinkingByDifficulty as Record<string, ThinkingLevel | "">) }, thinkingMaster: DEFAULT_ROUTER.thinkingMaster, thinkingDefault: DEFAULT_ROUTER.thinkingDefault };
   try {
     const raw = JSON.parse(stripBom(readFileSync(p, "utf-8")));
     // merge with defaults to ensure fields
@@ -87,8 +106,18 @@ export function loadRouterConfig(projectDir?: string): RouterConfig {
       byTask: raw.byTask ?? {},
       consultation: raw.consultation ?? { ...DEFAULT_ROUTER.consultation! },
       budgets: raw.budgets ?? { ...DEFAULT_ROUTER.budgets! },
+      thinkingByDifficulty: (() => {
+        const cur = raw.thinkingByDifficulty;
+        if (!cur || typeof cur !== "object") return { ...(DEFAULT_ROUTER.thinkingByDifficulty as Record<string, ThinkingLevel | "">) };
+        const out: Record<string, ThinkingLevel | ""> = {};
+        for (const k of DIFFICULTY_LADDER) out[k] = normalizeThinking((cur as Record<string, unknown>)[k]);
+        return out;
+      })(),
+      thinkingMaster: normalizeThinking(raw.thinkingMaster),
+      thinkingDefault: normalizeThinking(raw.thinkingDefault),
     };
     if (!cfg.byDifficulty) cfg.byDifficulty = { ...DEFAULT_ROUTER.byDifficulty! };
+    if (!cfg.thinkingByDifficulty) cfg.thinkingByDifficulty = { ...(DEFAULT_ROUTER.thinkingByDifficulty as Record<string, ThinkingLevel | "">) };
     return cfg;
   } catch {
     return { ...DEFAULT_ROUTER };
@@ -170,14 +199,38 @@ export function consultNext(
   return null;
 }
 
+export function resolveThinking(opts: ResolveOpts = {}): ThinkingLevel | "" {
+  const cfg = loadRouterConfig(opts.projectDir);
+  // Thinking is orthogonal to routing-enabled; when disabled, fall through to default/inherit.
+  const difficulty = opts.difficulty ?? opts.task?.difficulty ?? opts.feature?.difficulty ?? opts.sprint?.difficulty;
+  if (difficulty && cfg.thinkingByDifficulty && (cfg.thinkingByDifficulty as Record<string, ThinkingLevel | "">)[difficulty]) {
+    const v = (cfg.thinkingByDifficulty as Record<string, ThinkingLevel | "">)[difficulty];
+    if (v) return v;
+  }
+  // Master thinking only via consultation path; here just check difficulty default fallback
+  if (cfg.thinkingDefault) return cfg.thinkingDefault;
+  return "";
+}
+
+export function resolveThinkingForConsult(nextDifficulty: string | null, projectDir?: string): ThinkingLevel | "" {
+  const cfg = loadRouterConfig(projectDir);
+  if (!nextDifficulty) return cfg.thinkingMaster ?? "";
+  const v = cfg.thinkingByDifficulty?.[nextDifficulty as string] as ThinkingLevel | "" | undefined;
+  if (v) return v;
+  return "";
+}
+
 /** For widget/remote read-only exposure */
-export function routerSummary(projectDir?: string): { enabled: boolean; default: string; byDifficulty: Record<string, string>; master: string; budgets: RouterConfig["budgets"]; consultation: RouterConfig["consultation"] } {
+export function routerSummary(projectDir?: string): { enabled: boolean; default: string; byDifficulty: Record<string, string>; thinkingByDifficulty: Record<string, ThinkingLevel | "">; master: string; thinkingMaster: ThinkingLevel | ""; thinkingDefault: ThinkingLevel | ""; budgets: RouterConfig["budgets"]; consultation: RouterConfig["consultation"] } {
   const cfg = loadRouterConfig(projectDir);
   return {
     enabled: cfg.enabled,
     default: cfg.default,
     byDifficulty: { ...(cfg.byDifficulty ?? {}) } as Record<string, string>,
+    thinkingByDifficulty: { ...(cfg.thinkingByDifficulty ?? {}) } as Record<string, ThinkingLevel | "">,
     master: cfg.master ?? DEFAULT_ROUTER.master!,
+    thinkingMaster: (cfg.thinkingMaster ?? "") as ThinkingLevel | "",
+    thinkingDefault: (cfg.thinkingDefault ?? "") as ThinkingLevel | "",
     budgets: cfg.budgets,
     consultation: cfg.consultation,
   };

package/src/ui/config.ts

@@ -166,6 +166,13 @@ async function editSetting(setting: Setting, options: ConfigMenuOptions): Promis
       raw = picked;
       break;
     }
+    case "thinking": {
+      const choices = ["(inherit)", "off", "minimal", "low", "medium", "high", "xhigh", "max"];
+      const picked = await prompt.select(`${setting.label} — ${setting.help}`, [...choices, BACK]);
+      if (picked === undefined || picked === BACK) return false;
+      raw = picked;
+      break;
+    }
     case "model": {
       raw = await pickModel(setting, options, typeof current === "string" ? current : "");
       if (raw === undefined) return false;

package/src/ui/dashboard.ts

@@ -549,10 +549,12 @@ function renderFeature(
   sprintName: string | null,
   goalName: string | null,
   display: DisplayPolicy,
+  isCurrent = false,
 ): string {
   const counts = countByStatus(tasks);
   const total = tasks.length;
   const complete = total > 0 && counts.complete === total;
+  const current = isCurrent && !complete;
 
   const chips = [
     sprintName ? `<span class="chip chip-quiet">${esc(sprintName)}</span>` : "",
@@ -578,7 +580,7 @@ function renderFeature(
           .join("")}</ul>`
       : "";
 
-  return `<section class="card feature${complete ? " is-complete" : ""}">
+  return `<section class="card feature${complete ? " is-complete" : ""}${current ? " is-current" : ""}">
   <div class="feature-head">
     <div class="feature-id">
       <h2 class="feature-name">${esc(feature.name ?? feature.id ?? "")}</h2>
@@ -609,14 +611,16 @@ function renderGoalGroup(
   indexByKey: ReadonlyMap<string, number>,
   show: { showGoal: boolean; showSprints: boolean },
   display: DisplayPolicy,
+  activeFeatureId?: string | null,
 ): string {
+  const activeGoal = activeFeatureId ? group.sprints.some((sg) => sg.features.some((f) => f.id === activeFeatureId)) : false;
   const sprints = group.sprints
-    .map((sg) => renderSprintGroup(sg, tasksByFeature, indexByKey, show.showSprints, display))
+    .map((sg) => renderSprintGroup(sg, tasksByFeature, indexByKey, show.showSprints, display, activeFeatureId))
     .join("");
 
   if (!show.showGoal || !group.goal) return sprints;
 
-  return `<details class="tier tier-goal" open>
+  return `<details class="tier tier-goal${activeGoal ? " is-current" : ""}" open>
   <summary class="tier-head">
     <span class="tier-kind">goal</span>
     <span class="tier-name">${esc(group.goal.title ?? group.goal.id ?? "")}</span>
@@ -633,10 +637,12 @@ function renderSprintGroup(
   indexByKey: ReadonlyMap<string, number>,
   showSprints: boolean,
   display: DisplayPolicy,
+  activeFeatureId?: string | null,
 ): string {
+  const activeSprint = activeFeatureId ? group.features.some((f) => f.id === activeFeatureId) : false;
   const features = display.levels.feature
     ? group.features
-        .map((f) => renderFeature(f, tasksByFeature.get(f.id) ?? [], indexByKey, null, null, display))
+        .map((f) => renderFeature(f, tasksByFeature.get(f.id) ?? [], indexByKey, null, null, display, f.id === activeFeatureId))
         .join("")
     : // Hiding the feature card must not hide its tasks: they move up into the
       // sprint, which is what "hide features" has to mean on a page whose whole
@@ -645,7 +651,7 @@ function renderSprintGroup(
 
   if (!showSprints || !group.sprint) return features;
 
-  return `<details class="tier tier-sprint" open>
+  return `<details class="tier tier-sprint${activeSprint ? " is-current" : ""}" open>
   <summary class="tier-head">
     <span class="tier-kind">sprint</span>
     <span class="tier-name">${esc(group.sprint.name ?? group.sprint.id ?? "")}</span>
@@ -965,11 +971,17 @@ table.tasks tr:last-child td{border-bottom:0}
 .task-line{display:flex;flex-wrap:wrap;align-items:baseline;gap:8px}
 .task-desc{overflow-wrap:anywhere}
 .row-complete .task-desc{color:var(--muted)}
-.row.is-active{background:rgba(var(--rgb-active),.07)}
+.row.is-active{background:rgba(var(--rgb-active),.07);animation:taskBlink 1.2s ease-in-out infinite}
 .row.is-active .task-desc{font-weight:600}
 .row.is-active .cell-n{box-shadow:inset 2px 0 0 var(--c-active)}
 .row-rework.is-active{background:rgba(var(--rgb-rework),.08)}
 .row-rework.is-active .cell-n{box-shadow:inset 2px 0 0 var(--c-rework)}
+@keyframes taskBlink{0%,100%{opacity:1}50%{opacity:.72}}
+/* While-developed blinking for the whole current branch */
+.tier.is-current,.feature.is-current{animation:cardPulse 1.4s ease-in-out infinite}
+.tier.is-current .tier-name,.feature.is-current .feature-name{animation:textPulse 1.2s ease-in-out infinite}
+@keyframes cardPulse{0%,100%{box-shadow:var(--shadow)}50%{box-shadow:0 0 0 2px rgba(var(--rgb-accent),.22),var(--shadow)}}
+@keyframes textPulse{0%,100%{opacity:1}50%{opacity:.65}}
 .row-blocked{background:rgba(var(--rgb-blocked),.07)}
 .row-blocked .cell-n{box-shadow:inset 2px 0 0 var(--c-blocked)}
 .deps{color:var(--faint);white-space:nowrap}
@@ -1188,6 +1200,9 @@ export function renderDashboard(state: DashboardState): string {
   // everything.
   const display = normalizeDisplay(state.display ?? defaultDisplay());
   const groups = groupPlan(list);
+  // Which feature/sprint/goal is currently being worked (for blinking).
+  const activeTask = tasks.find((t) => t.status === "in_progress" || t.status === "rework") ?? tasks.find((t) => t.status === "pending") ?? null;
+  const activeFeatureId = activeTask?.featureId ?? null;
   const body = features.length
     ? groups
         .map((group) =>
@@ -1200,6 +1215,7 @@ export function renderDashboard(state: DashboardState): string {
               showSprints: display.levels.sprint && sprints.length > 0,
             },
             display,
+            activeFeatureId,
           ),
         )
         .join("")

package/src/ui/wizard.ts

@@ -23,7 +23,7 @@
  * leaves a project in a state nobody chose.
  */
 
-import type { Prompter } from "./config.ts";
+import type { ModelChoice, Prompter } from "./config.ts";
 import type { DisplayPolicy, Phase } from "../core/types.ts";
 import {
   BRIEF_QUESTION,
@@ -50,6 +50,7 @@ import {
 } from "../workflow.ts";
 import { DEFAULT_ENABLED_PHASES } from "../core/types.ts";
 import { defaultDisplay, listDisplays, normalizeDisplay, saveDisplay } from "./display.ts";
+import type { ThinkingLevel } from "../modelRouter.ts";
 
 export type WizardOptions = {
   prompt: Prompter;
@@ -59,6 +60,8 @@ export type WizardOptions = {
   skipConfirm?: boolean;
   /** Where saved workflows and templates live. Tests point this elsewhere. */
   env?: NodeJS.ProcessEnv;
+  /** Models pi can use — offered for each tier and for consulting. */
+  models?: () => ModelChoice[] | Promise<ModelChoice[]>;
 };
 
 export type WizardResult =
@@ -76,6 +79,84 @@ function line(label: string, help: string): string {
   return `${label}  —  ${help}`;
 }
 
+const MODEL_STEP_TITLE = "Which models for the difficulty tiers, and the consulting master?";
+const INHERIT = "(use pi's current model)";
+const CUSTOM_MODEL = "type a model id…";
+const THINKING_LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+const THINK_INHERIT = "(inherit)";
+
+async function pickModelChoice(prompt: Prompter, title: string, models: ModelChoice[], current: string): Promise<string | undefined> {
+  if (models.length === 0) {
+    const typed = await prompt.input(title, current || "provider/model-id");
+    return typed;
+  }
+  const rows = models.map((m) => (m.ref === current ? `${m.label}  ← current` : m.label));
+  const picked = await prompt.select(title, [INHERIT, ...rows, CUSTOM_MODEL]);
+  if (picked === undefined) return undefined;
+  if (picked === INHERIT) return "";
+  if (picked === CUSTOM_MODEL) {
+    const typed = await prompt.input(`${title} — model id`, current || "provider/model-id");
+    return typed;
+  }
+  const model = models[rows.indexOf(picked)];
+  return model?.ref;
+}
+
+async function pickThinkingLevel(prompt: Prompter, title: string): Promise<ThinkingLevel | "" | undefined> {
+  const picked = await prompt.select(title, [THINK_INHERIT, ...THINKING_LEVELS]);
+  if (picked === undefined) return undefined;
+  if (picked === THINK_INHERIT) return "";
+  return picked as ThinkingLevel;
+}
+
+async function pickModelsStep(prompt: Prompter, modelsFn?: WizardOptions["models"]): Promise<{ router: NonNullable<IntakeAnswers["router"]> } | undefined> {
+  const models = modelsFn ? (await modelsFn()) ?? [] : [];
+  // First ask whether routing is even wanted — most runs don't need it, and
+  // skipping the 8 follow-up questions keeps the wizard short. Old tests that
+  // don't know about this step get routing off by default so they keep passing.
+  const ROUTE_ON = "yes — pick models per tier";
+  const ROUTE_OFF = "no — use pi's current model for everything";
+  const enablePick = await prompt.select("Route work by difficulty to different models?", [ROUTE_ON, ROUTE_OFF]);
+  if (enablePick === undefined) {
+    // No answer scripted (e.g. an older test) → treat as "off" so the
+    // wizard doesn't look cancelled to callers that only scripted four steps.
+    return { router: { enabled: false, byDifficulty: { easy: "", moderate: "", difficult: "" }, thinkingByDifficulty: { easy: "", moderate: "", difficult: "" }, master: "", thinkingMaster: "", default: "", thinkingDefault: "" } };
+  }
+  if (enablePick === ROUTE_OFF) {
+    return { router: { enabled: false, byDifficulty: { easy: "", moderate: "", difficult: "" }, thinkingByDifficulty: { easy: "", moderate: "", difficult: "" }, master: "", thinkingMaster: "", default: "", thinkingDefault: "" } };
+  }
+  const tiers = ["easy", "moderate", "difficult"] as const;
+  const byDifficulty: Record<string, string> = {};
+  const thinkingByDifficulty: Partial<Record<string, ThinkingLevel | "">> = {};
+  for (const tier of tiers) {
+    const model = await pickModelChoice(prompt, `${tier.toUpperCase()} tier — model`, models, "");
+    if (model === undefined) return undefined;
+    byDifficulty[tier] = model;
+    const thinking = await pickThinkingLevel(prompt, `${tier.toUpperCase()} tier — thinking level`);
+    if (thinking === undefined) return undefined;
+    thinkingByDifficulty[tier] = thinking;
+  }
+  const masterModel = await pickModelChoice(prompt, "Consulting master — model (used only when the ladder is exhausted)", models, "");
+  if (masterModel === undefined) return undefined;
+  const masterThinking = await pickThinkingLevel(prompt, "Consulting master — thinking level");
+  if (masterThinking === undefined) return undefined;
+  const defaultModel = await pickModelChoice(prompt, "Default — fallback when nothing more specific matches", models, "");
+  if (defaultModel === undefined) return undefined;
+  const defaultThinking = await pickThinkingLevel(prompt, "Default — thinking level fallback");
+  if (defaultThinking === undefined) return undefined;
+  return {
+    router: {
+      enabled: true,
+      byDifficulty,
+      thinkingByDifficulty,
+      master: masterModel ?? "",
+      thinkingMaster: masterThinking ?? "",
+      default: defaultModel ?? "",
+      thinkingDefault: defaultThinking ?? "",
+    },
+  };
+}
+
 export async function runIntakeWizard(options: WizardOptions): Promise<WizardResult> {
   const { prompt, env } = options;
 
@@ -102,11 +183,15 @@ export async function runIntakeWizard(options: WizardOptions): Promise<WizardRes
       | "phase"
       | "task";
 
-    // -- 4. display ---------------------------------------------------------
+    // -- 4. models ----------------------------------------------------------
+    const modelsAnswer = await pickModelsStep(prompt, options.models);
+    if (modelsAnswer === undefined) return { cancelled: true };
+
+    // -- 5. display ---------------------------------------------------------
     const display = await pickDisplay(prompt, env);
     if (display === undefined) return { cancelled: true };
 
-    const answers: IntakeAnswers = { workflow, brief, handoff, display };
+    const answers: IntakeAnswers = { workflow, brief, handoff, display, router: modelsAnswer.router };
     const plan = planIntake(answers);
 
     if (options.skipConfirm) return { cancelled: false, plan, answers };