infinity-harness 2.3.1 → 2.5.0

package/src/core/init.ts

@@ -29,6 +29,7 @@ import { DEFAULT_ENABLED_PHASES, PHASE_ORDER, PHASE_ROLE } from "./types.ts";
 import { defaultConfig, saveConfig } from "./config.ts";
 import { emptyFeatureList, saveFeatureList } from "./featureList.ts";
 import * as P from "./paths.ts";
+import { normalizeDisplay } from "../ui/display.ts";
 
 export type StackId = "node" | "python" | "rust" | "go" | "unknown";
 
@@ -149,12 +150,21 @@ export type InitOptions = {
   commands?: Partial<ProjectCommands>;
   /** Re-scaffold missing files in a project that already has a config. */
   force?: boolean;
-  /** Which phases stop for a human signature. See SessionPolicy / ApprovalPolicy. */
+  /** Legacy three-phase approval switch, kept in step with `phaseModes`. */
   approvals?: Partial<HarnessConfig["approvals"]>;
+  /** Mode per phase — which of them stop for a human signature. */
+  phaseModes?: HarnessConfig["phaseModes"];
+  /** Which named workflow those modes came from. */
+  workflow?: HarnessConfig["workflow"];
+  /** What the widget and the dashboard draw. */
+  display?: HarnessConfig["display"];
   /** Session-handoff policy. Defaults to a fresh session per phase. */
   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 = {
@@ -210,6 +220,20 @@ export function initHarness(targetDir: string, options: InitOptions = {}): InitR
   config.commands = { ...stack.commands, ...stripUndefined(options.commands ?? {}) };
   config.approvals = { ...config.approvals, ...stripUndefined(options.approvals ?? {}) };
   config.session = { ...config.session, ...stripUndefined(options.session ?? {}) };
+  // Every enabled phase gets a mode, so a phase list and a mode map cannot
+  // disagree about which phases exist. A caller that still passes the 2.3
+  // `approvals` shape and no modes gets what it asked for rather than silently
+  // getting autopilot — the same rule `loadConfig` applies to an older file.
+  const legacy = (options.approvals ?? {}) as Record<string, unknown>;
+  const hasModes = options.phaseModes && Object.keys(options.phaseModes).length > 0;
+  config.phaseModes = Object.fromEntries(
+    phases.map((p) => [
+      p,
+      (hasModes ? options.phaseModes?.[p] === "copilot" : legacy[p] === true) ? "copilot" : "autopilot",
+    ]),
+  );
+  if (options.workflow) config.workflow = options.workflow;
+  if (options.display) config.display = normalizeDisplay(options.display);
   if (options.brief !== undefined) {
     config.intake = {
       completed: true,
@@ -217,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/paths.ts

@@ -5,10 +5,35 @@
  * Nothing outside this module hardcodes a harness path.
  */
 
+import { homedir } from "node:os";
 import { resolve } from "node:path";
 
 export const HARNESS_DIRNAME = "harness";
 
+/**
+ * Where things that belong to the *person* live, rather than to a project.
+ *
+ * A workflow someone designed and named is worth exactly as much on their next
+ * project as on this one, so it cannot live under `harness/`. This follows
+ * pi's own config directory, honouring the same override pi honours, so a
+ * sandboxed or rebranded install keeps everything in one place.
+ */
+export function userDir(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.PI_CODING_AGENT_DIR;
+  if (override && override.trim()) return resolve(override.trim(), "infinity-harness");
+  return resolve(homedir(), ".pi", "agent", "infinity-harness");
+}
+
+/** The workflows this person has saved, reusable across every project. */
+export function userWorkflowsPath(env?: NodeJS.ProcessEnv): string {
+  return resolve(userDir(env), "workflows.json");
+}
+
+/** The display templates this person has saved. */
+export function userDisplayPath(env?: NodeJS.ProcessEnv): string {
+  return resolve(userDir(env), "displays.json");
+}
+
 export function harnessDir(targetDir: string): string {
   return resolve(targetDir, HARNESS_DIRNAME);
 }

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. */
@@ -49,6 +50,9 @@ export type SettingsGroup = {
 
 // ── The schema ──────────────────────────────────────────────────────────────
 
+/** The two things a phase can do when its gate passes. */
+const PHASE_MODE_CHOICES = ["autopilot", "copilot"] as const;
+
 const DIFFICULTY_HELP =
   "Tasks the planner marked at this difficulty run on this model. Empty means: use whatever model pi is already on.";
 
@@ -72,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",
@@ -79,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",
@@ -86,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",
@@ -93,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",
@@ -100,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",
@@ -152,31 +191,157 @@ export const SETTINGS: SettingsGroup[] = [
     ],
   },
   {
-    id: "approvals",
-    label: "Your approvals",
-    help: "Which phases stop and wait for your signature. These are the three that decide WHAT gets built — after PLAN, a wrong turn fails a gate and retries.",
+    id: "workflow",
+    label: "Workflow",
+    help: "Which phases stop and wait for your signature, one phase at a time. `/infinity:workflow` picks a named one or builds a new one.",
     settings: [
       {
-        path: "approvals.research",
+        path: "phaseModes.research",
         file: "config",
-        label: "Sign off RESEARCH",
-        help: "You read harness/docs/RESEARCH.md and say whether it is looking at the right problem. Only applies when the RESEARCH phase is enabled.",
-        type: { kind: "boolean" },
+        label: "RESEARCH",
+        help: "copilot stops so you can read harness/docs/RESEARCH.md before anything is specified.",
+        type: { kind: "choice", choices: PHASE_MODE_CHOICES },
       },
       {
-        path: "approvals.define",
+        path: "phaseModes.define",
         file: "config",
-        label: "Sign off DEFINE",
+        label: "DEFINE",
         help: "The highest-leverage signature: a wrong definition is a weekend building the wrong thing perfectly.",
+        type: { kind: "choice", choices: PHASE_MODE_CHOICES },
+      },
+      {
+        path: "phaseModes.plan",
+        file: "config",
+        label: "PLAN",
+        help: "copilot shows you the whole task list before a line of it is built.",
+        type: { kind: "choice", choices: PHASE_MODE_CHOICES },
+      },
+      {
+        path: "phaseModes.build",
+        file: "config",
+        label: "BUILD",
+        help: "copilot stops once the code passes its gate, so you can read the diff.",
+        type: { kind: "choice", choices: PHASE_MODE_CHOICES },
+      },
+      {
+        path: "phaseModes.verify",
+        file: "config",
+        label: "VERIFY",
+        help: "copilot asks whether the tests prove the thing works or only that it runs.",
+        type: { kind: "choice", choices: PHASE_MODE_CHOICES },
+      },
+      {
+        path: "phaseModes.simplify",
+        file: "config",
+        label: "SIMPLIFY",
+        help: "copilot shows you what was deleted before it moves on.",
+        type: { kind: "choice", choices: PHASE_MODE_CHOICES },
+      },
+      {
+        path: "phaseModes.review",
+        file: "config",
+        label: "REVIEW",
+        help: "copilot asks whether you would approve this if someone else had written it.",
+        type: { kind: "choice", choices: PHASE_MODE_CHOICES },
+      },
+      {
+        path: "phaseModes.ship",
+        file: "config",
+        label: "SHIP",
+        help: "copilot stops before the tag goes on. The last chance to say no.",
+        type: { kind: "choice", choices: PHASE_MODE_CHOICES },
+      },
+    ],
+  },
+  {
+    id: "display",
+    label: "Display",
+    help: "What the terminal widget and the web dashboard draw. `/infinity:display` picks a template or edits this level by level.",
+    settings: [
+      {
+        path: "display.levels.goal",
+        file: "config",
+        label: "Goals",
+        help: "The outermost level. Off on a plan with one goal costs you nothing.",
         type: { kind: "boolean" },
       },
       {
-        path: "approvals.plan",
+        path: "display.levels.sprint",
         file: "config",
-        label: "Sign off PLAN",
-        help: "You see the whole task list before a line of it is built, and can send it back with a note.",
+        label: "Sprints",
+        help: "Off hides the sprint rows; the features under them still show, one level shallower.",
         type: { kind: "boolean" },
       },
+      {
+        path: "display.levels.feature",
+        file: "config",
+        label: "Features",
+        help: "Off hides the feature rows; their tasks still show.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "display.levels.task",
+        file: "config",
+        label: "Tasks",
+        help: "Off leaves the shape of the run without the work — see the `overview` template.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "display.levels.subtask",
+        file: "config",
+        label: "Subtasks",
+        help: "active shows them only on the task being worked, which is what fits in a widget.",
+        type: { kind: "choice", choices: ["none", "active", "all"] },
+      },
+      {
+        path: "display.counts",
+        file: "config",
+        label: "Counts",
+        help: "The done/total figure on goals, sprints and features.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "display.dependencies",
+        file: "config",
+        label: "Dependency labels",
+        help: "The `← #3` markers that say which task a task is waiting on.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "display.criteria",
+        file: "config",
+        label: "Acceptance criteria",
+        help: "Shown under each feature on the dashboard. No room for them in a terminal widget.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "display.rail",
+        file: "config",
+        label: "Phase rail",
+        help: "The `define ─ plan ─ BUILD ─ …` strip.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "display.progress",
+        file: "config",
+        label: "Progress meter",
+        help: "The bar and the task/feature counts beside it.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "display.alerts",
+        file: "config",
+        label: "Alert strip",
+        help: "Blocked and rework counts, retries, sessions, and any phase waiting for you.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "display.taskWindow",
+        file: "config",
+        label: "Widget rows",
+        help: "How many rows of plan the terminal shows before it starts scrolling.",
+        type: { kind: "number", min: 3, max: 60 },
+      },
     ],
   },
   {
@@ -188,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",
@@ -409,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":
@@ -454,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;
@@ -467,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
@@ -176,13 +181,55 @@ export type SessionPolicy = {
   carryNotes: boolean;
 };
 
-/** Which phases stop and wait for a human signature before the run continues. */
+/**
+ * Which phases stop and wait for a human signature before the run continues.
+ *
+ * Superseded by `HarnessConfig.phaseModes`, which says the same thing for
+ * *every* phase rather than only these three. Kept because configs written by
+ * 2.3 have it, and `loadConfig` migrates them on read.
+ */
 export type ApprovalPolicy = {
   research: boolean;
   define: boolean;
   plan: boolean;
 };
 
+/** What happens when a phase's gate passes: stop for the human, or advance. */
+export type PhaseMode = "copilot" | "autopilot";
+
+/**
+ * Which parts of the plan a surface draws.
+ *
+ * Two people watching the same run want different things on screen: one works
+ * in sprints and never opens a subtask, the next has no sprints at all and
+ * lives in the subtask list. Rather than pick a winner, the levels are a
+ * setting, and the widget and the dashboard read the same one.
+ */
+export type DisplayPolicy = {
+  /** Name of the template this came from, or "custom" once it is edited. */
+  preset: string;
+  levels: {
+    goal: boolean;
+    sprint: boolean;
+    feature: boolean;
+    task: boolean;
+    /** "active" shows them only on the task being worked. */
+    subtask: "none" | "active" | "all";
+  };
+  /** `2/5` counts on the grouping rows. */
+  counts: boolean;
+  /** `← #3` dependency labels on tasks. */
+  dependencies: boolean;
+  /** The phase rail, the progress meter and the alert strip. */
+  rail: boolean;
+  progress: boolean;
+  alerts: boolean;
+  /** Acceptance criteria under each feature. Dashboard only — no room in a widget. */
+  criteria: boolean;
+  /** Rows of plan in the terminal widget before it starts scrolling. */
+  taskWindow: number;
+};
+
 /** What the start-up wizard settled, so it is never asked twice. */
 export type IntakeState = {
   /** True once the wizard has run to completion for this project. */
@@ -227,7 +274,13 @@ export type HarnessConfig = {
   phases: { enabled: Phase[] };
   roles: { strict: boolean };
   session: SessionPolicy;
+  /** Legacy: the three-phase approval switch 2.3 shipped. Migrated to `phaseModes`. */
   approvals: ApprovalPolicy;
+  /** Mode per phase — the setting `approvals` became. */
+  phaseModes: Partial<Record<Phase, PhaseMode>>;
+  /** Which named workflow the modes above came from, before any hand-editing. */
+  workflow: { id: string; name: string } | null;
+  display: DisplayPolicy;
   intake: IntakeState;
   /** Set when a gate passed but the phase needs a human signature first. */
   awaitingApproval: Phase | null;

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.",
   };