infinity-harness 2.6.4 → 2.6.5

package/CHANGELOG.md

@@ -4,6 +4,40 @@ 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.6.5] — 2026-08-27
+
+Routing is honest about handoff, research knows how deep to go, and the human reads the same wiring the runner does.
+
+### Added
+
+- **Research depth tiers.** Wizard asks `How deep should research go?` only when `research` is in the pipeline — `standard` (Deep 3 tasks ≥5 sources ~800), `deep` (Very Deep 5 tasks ≥7 sources ~1800), `comprehensive` (Literature Review 7 tasks ≥15 annotated ~5000). `harness/config.json: researchDepth` persists it, `STARTER_TASKS_BY_DEPTH` feeds `seedPhaseIfEmpty`, `checkResearchDoc` enforces the right floor, and `harness/skills/deep-research.md` codifies the `process` skill per depth. `src/intake.ts` surfaces `Research  <depth>` in the intake summary.
+
+- **`harness/skills/deep-research.md`.** Process skill for the RESEARCH phase — depth-gated task/proof table, prior-art citation mandate, falsification experiment.
+
+- **Dashboard actually shows its URL and the handoff→model contract.** `WidgetState.dashboardUrl` + `WidgetState.handoffModelNote` are populated from the live `remoteServer.url` and from `handoffModelNote(handoff)`; terminal header renders an `OSC 8` clickable `Dashboard: …` line, web dashboard renders `dash-url` + `handoff-note` under the masthead.
+
+### Changed
+
+- **Model routing follows handoff (Option A: hardest wins in the bucket).** `src/scheduler.ts: effectiveDifficultyForTask(task, handoff, list)` — `task/subtask` keeps own difficulty (subtasks inherit parent), `phase/feature/sprint/goal/off` collapses the bucket to its hardest (`easy < moderate < difficult`). `spawnWorkers` and `extensions/infinity-harness:index.ts` (`applyRouting` + `routingSummaryForBrief` + brief line) all read `config.session.handoff` each call; `src/intake.ts: HANDOFF_QUESTION` help text now states `Model per …` per choice. `src/handoff.ts` wording updated to match.
+
+- **Seeding + config defaults.** `src/core/init.ts` writes `researchDepth` (`deep` when research enabled), `src/core/config.ts` defaults it, `src/core/phases.ts` returns the depth-appropriate starter set via `loadConfig` (no raw file read), `src/remote.ts` keeps the read-only dashboard read via `require` deferred import so pack audit stays green (`42` modules reachable).
+
+### Fixed
+
+- **Wizard ate its own answer.** Real-pi `research-first` and `build one` → research handoff paths previously timed out because depth answer matched the question title not option text and consumed the wrong line; e2e now answers depth with regex on option (`/Very Deep/`), research gate fixture length raised to `40×` so `deep = 1800` passes, and both realpi `wizard` + `custom` + `coldstart` `a custom workflow …` are green.
+
+- **Second reuse init lost its saved workflow.** `coldstart-reuse` answered with a bare `Client work \(yours\)` line that no longer matched after research re-enabled depth intake; now answered `Very Deep` so the workflow survives.
+
+- **Gate fixture regression.** `research.md` fixture at `20×` was `1152` chars — short of the new `deep 1800` floor — caused `the whole pipeline …` stall; corrected to `40×` (`2280`) so `research: pass` remains single-shot.
+
+- **`src/intake.ts` CRLF drift.** Full-file rewrite was display-only (line endings); fixed to LF and only the 25-line surgical change retained.
+
+- **Extension ESM require shim.** Prior `require("../../src/scheduler.ts")` in `widgetStateFor` broke ESM and never surfaced `handoffModelNote`; inlined pure map instead.
+
+### Verified
+
+- `tsc --noEmit` clean, `34/34` unit, `15/15` e2e (`coldstart 12/12`, `realpi 10/10`), `42` modules reachable via `package` scenario. `tests/skills.test.ts` bumps shipped skill count `28 → 29`, `tests/intake.test.ts` asserts `How deep …` + `Research deep` summary.
+
 ## [2.6.4] — 2026-08-25
 
 `feature-criteria` now ignores seeded `phase-*` scaffolding so `DEFINE` does not pass on the

package/extensions/infinity-harness/index.ts

@@ -168,10 +168,24 @@ export default function (pi: ExtensionAPI): void {
 
   // -- widget ---------------------------------------------------------------
 
+  const handoffNoteFor = (h: import("../../src/core/types.ts").HandoffGranularity): string | null => {
+    const map: Record<string, string> = {
+      off: "Model per run (off/goal) — the whole run shares its hardest model; finer per-task routing requires task/subtask handoff",
+      goal: "Model per run (off/goal) — the whole run shares its hardest model; finer per-task routing requires task/subtask handoff",
+      phase: "Model per phase — tasks & subtasks in a phase share the hardest model in that phase",
+      sprint: "Model per sprint — tasks & subtasks in a sprint share the hardest model in that sprint",
+      feature: "Model per feature — tasks & subtasks in a feature share the hardest model in that feature",
+      task: "Model per task — subtasks share their parent task's model",
+      subtask: "Model per subtask — each subtask may use its own model (needs subtask difficulty)",
+    };
+    return map[h] ?? null;
+  };
+
   const widgetStateFor = (dir: string): WidgetState | null => {
     try {
       const { list } = loadFeatureList(dir);
       const { config } = loadConfig(dir);
+      const handoffModelNote: string | null = handoffNoteFor((config.session?.handoff as import("../../src/core/types.ts").HandoffGranularity) ?? "task");
       const spent = escalationSummary(dir);
       const loop = readJsonSafe<{ escalations?: { strategy: string }[] } | null>(
         loopStatePath(dir),
@@ -184,6 +198,8 @@ export default function (pi: ExtensionAPI): void {
       return {
         list,
         view,
+        dashboardUrl: remoteServer?.url ?? null,
+        handoffModelNote,
         sessions: run?.sessions ?? null,
         intake: typeof config.intake?.brief === "string" ? config.intake.brief : null,
         awaitingApproval: config.awaitingApproval ?? null,
@@ -301,10 +317,15 @@ export default function (pi: ExtensionAPI): void {
   const applyRouting = async (ctx: ExtensionContext, dir: string, source: string): Promise<void> => {
     try {
       const { resolveModel, resolveThinking } = await import("../../src/modelRouter.ts");
+      const { effectiveDifficultyForTask } = await import("../../src/scheduler.ts");
       const { nextActionableTask, findFeature } = await import("../../src/core/featureList.ts");
       const { loadFeatureList: loadList } = await import("../../src/core/featureList.ts");
       const list = loadList(dir).list;
       const task = nextActionableTask(list);
+      const cfg = loadConfig(dir).config;
+      const handoff = (cfg.session?.handoff ?? "task") as import("../../src/core/types.ts").HandoffGranularity;
+      // Effective difficulty honors handoff bucket: phase/feature/sprint tasks share hardest in that bucket.
+      const effDiff = task && list ? (effectiveDifficultyForTask(task as import("../../src/core/featureList.ts").FlatTask, handoff, list) ?? (task as { difficulty?: string }).difficulty) : (task as { difficulty?: string } | null)?.difficulty;
       // Resolve against task/parent feature/sprint difficulty; fall through to default when no actionable.
       const feature = task ? findFeature(list, task.featureId) ?? undefined : undefined;
       const sprint = feature?.sprintId ? (list.sprints ?? []).find((s) => s.id === feature.sprintId) ?? undefined : undefined;
@@ -312,7 +333,7 @@ export default function (pi: ExtensionAPI): void {
       type T = NonNullable<ReturnType<typeof nextActionableTask>>;
       const routedModel = resolveModel({
         projectDir: dir,
-        task: (task as T | null | undefined)?.difficulty || feature?.difficulty ? ({ difficulty: (task as T | undefined)?.difficulty, modelHint: (task as T | undefined)?.modelHint, id: task?.id, key: (task as T | undefined)?.compositeKey ?? (task as T | undefined)?.key } as never) : undefined,
+        task: effDiff || (feature as { difficulty?: string } | undefined)?.difficulty ? ({ difficulty: effDiff as string | undefined, modelHint: (task as T | undefined)?.modelHint, id: task?.id, key: (task as T | undefined)?.compositeKey ?? (task as T | undefined)?.key } as never) : undefined,
         feature: feature as never,
         sprint: sprint as never,
         phase: loadConfig(dir).config.currentPhase ?? undefined,
@@ -320,7 +341,7 @@ export default function (pi: ExtensionAPI): void {
       });
       const routedThinking = resolveThinking({
         projectDir: dir,
-        task: (task as T | null | undefined) ? ({ difficulty: (task as T | undefined)?.difficulty, id: task?.id, key: (task as T | undefined)?.compositeKey ?? (task as T | undefined)?.key } as never) : undefined,
+        task: effDiff ? ({ difficulty: effDiff as string } as never) : (task as T | null | undefined) ? ({ difficulty: (task as T | undefined)?.difficulty, id: task?.id, key: (task as T | undefined)?.compositeKey ?? (task as T | undefined)?.key } as never) : undefined,
         feature: feature as never,
         sprint: sprint as never,
       });
@@ -378,15 +399,19 @@ export default function (pi: ExtensionAPI): void {
     try {
       const { nextActionableTask, findFeature } = await import("../../src/core/featureList.ts");
       const { resolveModel, resolveThinking } = await import("../../src/modelRouter.ts");
+      const { effectiveDifficultyForTask } = await import("../../src/scheduler.ts");
       const { list } = loadFeatureList(dir);
       const task = nextActionableTask(list);
       if (!task) return null;
+      const cfg = loadConfig(dir).config;
+      const handoff = (cfg.session?.handoff ?? "task") as import("../../src/core/types.ts").HandoffGranularity;
+      const effDiff = effectiveDifficultyForTask(task as import("../../src/core/featureList.ts").FlatTask, handoff, list) ?? (task as { difficulty?: string }).difficulty;
       const feature = findFeature(list, task.featureId) ?? undefined;
       const sprint = feature?.sprintId ? (list.sprints ?? []).find((s) => s.id === feature.sprintId) ?? undefined : undefined;
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const m = resolveModel({ projectDir: dir, task: ({ difficulty: (task as any).difficulty, modelHint: (task as any).modelHint, id: task.id, key: (task as any).compositeKey ?? (task as any).key } as never), feature: feature as never, sprint: sprint as never, phase: loadConfig(dir).config.currentPhase ?? undefined });
+      const m = resolveModel({ projectDir: dir, task: ({ difficulty: effDiff as string | undefined, modelHint: (task as any).modelHint, id: task.id, key: (task as any).compositeKey ?? (task as any).key } as never), feature: feature as never, sprint: sprint as never, phase: loadConfig(dir).config.currentPhase ?? undefined });
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const th = resolveThinking({ projectDir: dir, task: ({ difficulty: (task as any).difficulty } as never), feature: feature as never, sprint: sprint as never });
+      const th = resolveThinking({ projectDir: dir, task: ({ difficulty: effDiff as string | undefined } as never), feature: feature as never, sprint: sprint as never });
       if (!m || !m.trim()) return null;
       return `Routing: ${task.compositeKey} → ${m}${th ? ` · thinking ${th}` : ""}`;
     } catch { return null; }

package/harness/skills/deep-research.md

@@ -0,0 +1,38 @@
+---
+name: deep-research
+description: Deep prior-art sweep, synthesis and tradeoff analysis — literature-review level when needed
+tags: [research, literature, prior-art, synthesis, constraints, tradeoffs, recommendation, falsification]
+when: research depth is standard/deep/comprehensive and the question needs more than a web search
+phases: [research]
+kind: process
+---
+
+# Deep research
+
+Use when `config.researchDepth` is set — `standard` (Deep), `deep` (Very Deep) or `comprehensive` (Literature Review). The wizard only asks when `research` is in the pipeline.
+
+## Depth — what the harness expects
+
+| Depth | Tasks | Sources | Gate | What you deliver |
+|-------|-------|---------|------|-----------------|
+| `standard` (Deep) | 3 | ≥5 primary, all with URLs | ~800 chars | comparison table, constraints table, ≥3 options |
+| `deep` (Very Deep) | 5 | ≥7 primary + gap analysis | ~1800 chars | above + competitive matrix, cost/risk model, risk register |
+| `comprehensive` (Literature Review) | 7 | ≥15 annotated bibliography | ~5000 chars | above + benchmarks on a toy case, synthesis, gap analysis, ADR |
+
+Deeper = longer `harness/docs/RESEARCH.md`. The gate reads `config.researchDepth` and enforces the char floor.
+
+## Process
+
+1. Collect primary sources only — official docs, specs, first-party APIs, papers with DOIs, postmortems. Every claim needs a URL or citation.
+2. Fill the constraints table `given vs inferred` (inferred = question for DEFINE).
+3. Benchmark or reason about ≥1 approach on a minimal case where possible (comprehensive must).
+4. Lay out genuine options (standard ≥3) with architecture sketch, cost, risk, team & time. A list of one is a decision wearing a disguise.
+5. Write an ADR: recommendation + what would have to be true for it to be wrong (falsification + experiment design).
+6. Risk register: known unknowns vs unknown unknowns, mitigations.
+7. Ranked open questions for DEFINE (standard ≥5, deep ≥8, comprehensive ≥12) + glossary delta for `DOMAIN.md`.
+
+## Anti-patterns
+
+- No open questions — you did not look hard enough.
+- One option presented as inevitable.
+- Findings with no source, stated as confidently as sourced ones.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinity-harness",
-  "version": "2.6.4",
+  "version": "2.6.5",
   "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,6 +50,7 @@ export function defaultConfig(): HarnessConfig {
     },
     phases: { enabled: [...DEFAULT_ENABLED_PHASES] },
     roles: { strict: false },
+    researchDepth: "deep" as import("./types.ts").ResearchDepth,
     session: { handoff: "task", contextThreshold: 0.6, carryNotes: true },
     execution: { parallelAt: "task", maxWorkers: 3 },
     approvals: { research: false, define: false, plan: false },

package/src/core/gates.ts

@@ -231,8 +231,15 @@ async function checkChangelog({ targetDir }: Ctx): Promise<CheckResult> {
  * bar deliberately — the gate judges that work happened, the human judges
  * whether it was any good.
  */
-async function checkResearchDoc({ targetDir }: Ctx): Promise<CheckResult> {
-  return docCheck("research-doc", P.researchPath(targetDir), 400, "harness/docs/RESEARCH.md");
+async function checkResearchDoc({ targetDir, config }: Ctx): Promise<CheckResult> {
+  // Depth-dependent threshold — Literature needs a real review, Standard is the old 400 baseline.
+  const depth = (config as { researchDepth?: string }).researchDepth as string | undefined;
+  const minChars = depth === "comprehensive" ? 5000 : depth === "deep" ? 1800 : 800;
+  // Note: depth="deep" is the default, 800 ≈ old 400 doubled but Standard is a true lite mode.
+  // Comprehensive still passes if Standard doc exists — depth is about work produced, not gate strictness,
+  // but the line below makes the harness actually demand the depth the wizard promised.
+  const effectiveMin = depth ? minChars : 400;
+  return docCheck("research-doc", P.researchPath(targetDir), effectiveMin, "harness/docs/RESEARCH.md");
 }
 
 async function checkArchitectureDoc({ targetDir }: Ctx): Promise<CheckResult> {

package/src/core/init.ts

@@ -146,6 +146,7 @@ function pythonCommands(targetDir: string): ProjectCommands {
 export type InitOptions = {
   stack?: StackId;
   mode?: "copilot" | "autopilot";
+  researchDepth?: import("./types.ts").ResearchDepth;
   phases?: Phase[];
   commands?: Partial<ProjectCommands>;
   /** Re-scaffold missing files in a project that already has a config. */
@@ -213,6 +214,11 @@ export function initHarness(targetDir: string, options: InitOptions = {}): InitR
   const phase = phases[0] ?? "define";
 
   const config = defaultConfig();
+  if (options.researchDepth && (options.researchDepth === "standard" || options.researchDepth === "deep" || options.researchDepth === "comprehensive")) {
+    config.researchDepth = options.researchDepth;
+  } else if (phases.includes("research")) {
+    config.researchDepth = "deep";
+  }
   config.stack = stack.id === "unknown" ? null : stack.id;
   config.mode = options.mode ?? "copilot";
   config.phases = { enabled: phases };

package/src/core/phases.ts

@@ -140,27 +140,37 @@ export type StarterTask = {
   difficulty: "easy" | "moderate" | "difficult";
   subtasks?: string[];
 };
-export const STARTER_TASKS: Record<string, StarterTask[]> = {
-  research: [
-    {
-      id: "research/r1",
-      description: "Collect prior art — 3 sources, what exists, where it stops",
-      difficulty: "moderate",
-      subtasks: ["source 1 + summary", "source 2 + summary", "source 3 + summary"],
-    },
-    {
-      id: "research/r2",
-      description: "Name constraints (given vs inferred) and lay out 2+ options with costs",
-      difficulty: "moderate",
-      subtasks: ["constraints given vs inferred", "option A cost/benefit", "option B cost/benefit"],
-    },
-    {
-      id: "research/r3",
-      description: "Recommend one option, falsification condition, and open questions for DEFINE",
-      difficulty: "moderate",
-      subtasks: ["recommendation + falsification", "open questions list"],
-    },
+/** Depth: Standard(3 tasks/9 subtasks) < Deep(5/15) < Comprehensive(10/30+). Default deep. */
+export type ResearchDepth = "standard" | "deep" | "comprehensive";
+export const STARTER_TASKS_BY_DEPTH: Record<ResearchDepth, StarterTask[]> = {
+  standard: [
+    { id: "research/r1", description: "Collect prior art — 3 primary sources with URLs, what exists, where it stops", difficulty: "moderate", subtasks: ["source 1 + URL + summary", "source 2 + URL + summary", "source 3 + URL + summary"] },
+    { id: "research/r2", description: "Name constraints (given vs inferred) and lay out 2+ options with costs", difficulty: "moderate", subtasks: ["constraints given vs inferred table", "option A cost/benefit", "option B cost/benefit"] },
+    { id: "research/r3", description: "Recommend one option, falsification condition, and open questions for DEFINE", difficulty: "moderate", subtasks: ["recommendation + falsification", "open questions list (≥5)"] },
+  ],
+  deep: [
+    { id: "research/r1", description: "Prior art: ≥5 primary sources with URLs (docs/specs/repos), what each gets right and where it stops", difficulty: "moderate", subtasks: ["sources 1-3 + URLs + summaries", "sources 4-5 + URLs + gap analysis", "comparison table: feature × prior art"] },
+    { id: "research/r2", description: "Constraints & domain model: given vs inferred, glossary terms, actors & data", difficulty: "moderate", subtasks: ["constraints given vs inferred (table)", "domain glossary + actors", "data & platform constraints"] },
+    { id: "research/r3", description: "Options: ≥3 genuine alternatives with architecture, cost, risk and trade-offs", difficulty: "difficult", subtasks: ["option A: arch + cost + risk", "option B: arch + cost + risk", "option C / hybrid + trade-off matrix"] },
+    { id: "research/r4", description: "Recommendation with falsification: what must be true, what would prove it wrong", difficulty: "moderate", subtasks: ["recommendation + rationale", "falsification condition + experiment"] },
+    { id: "research/r5", description: "Open questions for DEFINE: ranked questions only a human can answer", difficulty: "easy", subtasks: ["open questions (≥8) ranked", "DEFINE interview agenda"] },
+  ],
+  comprehensive: [
+    { id: "research/r1", description: "Literature sweep: ≥15 primary sources — papers, RFCs, repos, postmortems — annotated", difficulty: "difficult", subtasks: ["sources 1-5 annotated", "sources 6-10 annotated", "sources 11-15 annotated", "citation map + gaps in literature"] },
+    { id: "research/r2", description: "Domain & constraints synthesis: glossary, actors, data, regulatory & platform limits", difficulty: "difficult", subtasks: ["constraints given vs inferred (full table)", "domain glossary + bounded contexts", "actors, data flows & invariants"] },
+    { id: "research/r3", description: "Benchmark prior work: reproduce or reason about 3+ approaches on a toy case", difficulty: "difficult", subtasks: ["approach A benchmark", "approach B benchmark", "approach C benchmark + comparison matrix"] },
+    { id: "research/r4", description: "Architecture options: ≥3 with diagrams, cost model, risk register, team & time", difficulty: "difficult", subtasks: ["option A: diagram + cost + risk", "option B: diagram + cost + risk", "option C: diagram + cost + risk", "trade-off matrix + decision criteria"] },
+    { id: "research/r5", description: "Recommendation as a decision record + what falsifies it", difficulty: "moderate", subtasks: ["ADR: recommendation + alternatives rejected", "falsification condition + experiment design"] },
+    { id: "research/r6", description: "Risk & unknowns register: known unknowns, unknown unknowns, mitigations", difficulty: "moderate", subtasks: ["risk register", "mitigations + owners", "open unknowns vs knowns"] },
+    { id: "research/r7", description: "DEFINE handoff: ranked open questions (≥12) + interview agenda + glossary delta", difficulty: "easy", subtasks: ["open questions (≥12) ranked", "DEFINE interview agenda", "glossary delta for DOMAIN.md"] },
   ],
+};
+// Back-compat: default deep
+const DEFAULT_RESEARCH_DEPTH: ResearchDepth = "deep";
+export const STARTER_TASKS: Record<string, StarterTask[]> = {
+  get research(): StarterTask[] { return STARTER_TASKS_BY_DEPTH[DEFAULT_RESEARCH_DEPTH]; },
+  set research(v: StarterTask[]) { (STARTER_TASKS_BY_DEPTH as Record<string, StarterTask[]>)[DEFAULT_RESEARCH_DEPTH] = v; },
+
   define: [
     {
       id: "define/d1",
@@ -197,8 +207,18 @@ export function isPhaseDone(dir: string, phase: import("./types.ts").Phase): boo
   return tasks.length > 0 && tasks.every((t) => t.status === "complete");
 }
 
+function startersForPhase(dir: string, phase: string): StarterTask[] {
+  if (phase !== "research") return STARTER_TASKS[phase] ?? [];
+  try {
+    const { config } = loadConfig(dir);
+    const depth = (config as { researchDepth?: ResearchDepth }).researchDepth;
+    if (depth && STARTER_TASKS_BY_DEPTH[depth]) return STARTER_TASKS_BY_DEPTH[depth];
+  } catch {}
+  return STARTER_TASKS_BY_DEPTH[DEFAULT_RESEARCH_DEPTH] ?? [];
+}
+
 export function seedPhaseIfEmpty(dir: string, phase: import("./types.ts").Phase): { seeded: boolean; error: string | null } {
-  const seeded = STARTER_TASKS[phase] ?? [];
+  const seeded = startersForPhase(dir, phase);
   if (seeded.length === 0) return { seeded: false, error: null };
   try {
     const { list } = loadFeatureList(dir);

package/src/core/types.ts

@@ -244,6 +244,10 @@ export type DisplayPolicy = {
   taskWindow: number;
 };
 
+/** How deep the research phase goes, when enabled. Only asked when research is in the pipeline. */
+export type ResearchDepth = "standard" | "deep" | "comprehensive";
+export const RESEARCH_DEPTHS: readonly ResearchDepth[] = ["standard", "deep", "comprehensive"] as const;
+
 /** 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. */
@@ -257,6 +261,8 @@ export type IntakeState = {
 export type HarnessConfig = {
   version: string;
   stack: string | null;
+  /** Research depth — only meaningful when research is in phases.enabled. */
+  researchDepth?: ResearchDepth;
   mode: "copilot" | "autopilot";
   currentPhase: Phase | null;
   currentRole: Role | null;

package/src/intake.ts

@@ -44,9 +44,13 @@ export type Mode = "copilot" | "autopilot";
 export const INTAKE_STEPS = ["workflow", "brief", "handoff", "display"] as const;
 export type IntakeStep = (typeof INTAKE_STEPS)[number];
 
+export type ResearchDepth = import("./core/types.ts").ResearchDepth;
+
 export type IntakeAnswers = {
   /** The chosen workflow: a built-in, one they saved, or one they just built. */
   workflow: Workflow;
+  /** Research depth — only when research is in the pipeline. */
+  researchDepth?: ResearchDepth;
   /** What the human wants built, in their words. Empty is allowed but warned about. */
   brief: string;
   /** Session handoff policy. Defaults to a fresh session per phase. */
@@ -71,6 +75,7 @@ export type IntakePlan = {
   /** Derived: "copilot" when the run stops for the human anywhere, else "autopilot". */
   mode: Mode;
   workflow: { id: string; name: string };
+  researchDepth?: ResearchDepth;
   brief: string | null;
   phases: Phase[];
   phaseModes: PhaseModes;
@@ -155,9 +160,11 @@ export function planIntake(answers: IntakeAnswers): IntakePlan {
     );
   }
 
+  const _researchDepth: ResearchDepth | undefined = (phases.includes("research" as Phase) ? ((answers.researchDepth as ResearchDepth) ?? "deep") : undefined) as ResearchDepth | undefined;
   return {
     mode,
     workflow: { id: workflow.id, name: workflow.name },
+    researchDepth: _researchDepth,
     brief,
     phases,
     phaseModes,
@@ -170,7 +177,7 @@ export function planIntake(answers: IntakeAnswers): IntakePlan {
     execution: { parallelAt, maxWorkers },
     display,
     router: answers.router,
-    summary: summarize(workflow, phases, phaseModes, session, display, brief),
+    summary: summarize(workflow, phases, phaseModes, session, display, brief, _researchDepth),
     warnings,
   };
 }
@@ -182,6 +189,7 @@ function summarize(
   session: SessionPolicy,
   display: DisplayPolicy,
   brief: string | null,
+  researchDepth?: ResearchDepth | undefined,
 ): string {
   const signed = phases.filter((p) => modes[p] === "copilot");
   const L: string[] = [];
@@ -200,6 +208,7 @@ function summarize(
     }`,
   );
   L.push(`Display   ${display.preset}`);
+  if (researchDepth) L.push(`Research  ${researchDepth}`);
   L.push(`Goal      ${brief ?? "(none yet — you will be asked first thing)"}`);
   return L.join("\n");
 }
@@ -237,37 +246,37 @@ export const HANDOFF_QUESTION: Question = {
     {
       value: "goal",
       label: "per goal — one session for the whole run",
-      help: "The old single-session run. Every task accumulates context until compaction.",
+      help: "The old single-session run. Model per run (off/goal) — whole run shares its hardest model. For true per-task models use task/subtask.",
     },
     {
       value: "phase",
       label: "every phase",
-      help: "Old default. Each phase starts clean from the brief.",
+      help: "Model per phase — tasks & subtasks in a phase share the hardest model in that phase. Old default. Each phase starts clean from the brief.",
     },
     {
       value: "sprint",
       label: "every sprint",
-      help: "New session whenever the active sprint changes (or phase).",
+      help: "Model per sprint — tasks & subtasks in a sprint share the hardest model in that sprint. New session whenever the sprint changes (or phase).",
     },
     {
       value: "feature",
       label: "every feature",
-      help: "New session on each feature boundary (and sprint/phase).",
+      help: "Model per feature — tasks & subtasks in a feature share the hardest model in that feature. New session on each feature boundary (and sprint/phase).",
     },
     {
       value: "task",
       label: "every task (recommended)",
-      help: "Each task gets a clean session. Best isolation; one extra brief per task.",
+      help: "Model per task — subtasks share their parent task's model. 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.",
+      help: "Model per subtask — each subtask may use its own model (needs subtask difficulty). Finest grain. Most isolation, most churn.",
     },
     {
       value: "off",
       label: "never — alias for per goal",
-      help: "Same as per goal — one long session without fresh starts.",
+      help: "Model per run — same as per goal, one long session.",
     },
   ],
 };

package/src/scheduler.ts

@@ -7,10 +7,107 @@
  */
 
 import type { HarnessConfig, HandoffGranularity, Phase } from "./core/types.ts";
-import { loadFeatureList, tasksForPhase, type FlatTask } from "./core/featureList.ts";
+import { loadFeatureList, tasksForPhase, type FlatTask, flattenTasks } from "./core/featureList.ts";
 import { loadRouterConfig } from "./modelRouter.ts";
 import { spawnIsolatedWorker, type SpawnWorkerResult } from "./worker.ts";
 import { runIdFor } from "./runState.ts";
+import { loadConfig } from "./core/config.ts";
+
+/** Difficulty ranking — higher wins when collapsing a bucket to its hardest. */
+const DIFFICULTY_RANK: Record<string, number> = { easy: 1, moderate: 2, difficult: 3 };
+
+function hardestDifficulty(tasks: Array<{ difficulty?: string }>): string | undefined {
+  let best: string | undefined;
+  let bestRank = -1;
+  for (const t of tasks) {
+    const d = (t as { difficulty?: string }).difficulty;
+    if (!d) continue;
+    const r = DIFFICULTY_RANK[d] ?? -1;
+    if (r > bestRank) { bestRank = r; best = d; }
+  }
+  return best;
+}
+
+function goalIdForTask(task: FlatTask, list: import("./core/types.ts").FeatureList): string | null {
+  const feat = list.features.find((f) => f.id === task.featureId) as { goalId?: string; sprintId?: string } | undefined;
+  if (!feat) return (list.goals?.[0]?.id ?? null) as string | null;
+  if (feat.goalId) return feat.goalId;
+  if (feat.sprintId) {
+    const spr = (list.sprints ?? []).find((s) => s.id === feat.sprintId) as { goalId?: string } | undefined;
+    if (spr?.goalId) return spr.goalId;
+  }
+  return (list.goals?.[0]?.id ?? null) as string | null;
+}
+
+/**
+ * Effective difficulty for a task given the session handoff granularity.
+ *
+ * Design choice (Option A): the handoff bucket is the model bucket.
+ * Everything finer than the handoff shares the hardest model in that bucket:
+ *   - handoff phase  → all tasks in that phase share one model (hardest in phase)
+ *   - handoff feature → tasks in feature share hardest in feature
+ *   - handoff task   → subtasks share their parent task's model
+ * Shown in wizard + dashboard so the user knows the trade-off.
+ */
+export function effectiveDifficultyForTask(
+  task: FlatTask,
+  handoff: HandoffGranularity,
+  list: import("./core/types.ts").FeatureList,
+): string | undefined {
+  const own = (task as { difficulty?: string }).difficulty;
+  if (handoff === "task" || handoff === "subtask" || handoff === "off") {
+    // task/subtask: subtasks are not separate tasks, so they inherit the task
+    // off: one session for whole run — hardest in whole plan (most conservative)
+    if (handoff === "off") {
+      const globalHardest = hardestDifficulty(flattenTasks(list) as unknown as Array<{ difficulty?: string }>);
+      return globalHardest ?? own;
+    }
+    return own;
+  }
+  let bucket: FlatTask[] = [];
+  const all = flattenTasks(list);
+  if (handoff === "phase") {
+    const phase = (task as { effectivePhase?: string }).effectivePhase ?? "build";
+    bucket = all.filter((t) => (t as { effectivePhase?: string }).effectivePhase === phase);
+  } else if (handoff === "feature") {
+    bucket = all.filter((t) => t.featureId === task.featureId);
+  } else if (handoff === "sprint") {
+    const feat = list.features.find((f) => f.id === task.featureId) as { sprintId?: string } | undefined;
+    const sid = feat?.sprintId;
+    if (!sid) return own;
+    bucket = all.filter((t) => {
+      const f = list.features.find((ff) => ff.id === t.featureId) as { sprintId?: string } | undefined;
+      return f?.sprintId === sid;
+    });
+  } else if (handoff === "goal") {
+    const gid = goalIdForTask(task, list);
+    if (!gid) return own;
+    bucket = all.filter((t) => goalIdForTask(t, list) === gid);
+  } else {
+    return own;
+  }
+  return hardestDifficulty(bucket as unknown as Array<{ difficulty?: string }>) ?? own;
+}
+
+export function handoffModelNote(handoff: HandoffGranularity): string {
+  switch (handoff) {
+    case "off":
+    case "goal":
+      return "Model per run (off/goal) — the whole run shares its hardest model; finer per-task routing requires task/subtask handoff";
+    case "phase":
+      return "Model per phase — tasks & subtasks in a phase share the hardest model in that phase";
+    case "sprint":
+      return "Model per sprint — tasks & subtasks in a sprint share the hardest model in that sprint";
+    case "feature":
+      return "Model per feature — tasks & subtasks in a feature share the hardest model in that feature";
+    case "task":
+      return "Model per task — subtasks share their parent task's model";
+    case "subtask":
+      return "Model per subtask — each subtask may use its own model (needs subtask difficulty)";
+    default:
+      return "";
+  }
+}
 
 export type PickOpts = {
   targetDir: string;
@@ -36,8 +133,8 @@ export type WorkerSnapshot = {
 /** Tail a worker attempt's output.log (best-effort, never throws). */
 export function tailWorkerOutput(attemptDir: string, bytes = 3000): string {
   try {
-    const { readFileSync, existsSync } = require("node:fs");
-    const p = require("node:path").join(attemptDir, "output.log");
+    const { readFileSync, existsSync } = require("node:fs") as typeof import("node:fs");
+    const p = (require("node:path") as typeof import("node:path")).join(attemptDir, "output.log");
     if (!existsSync(p)) return "";
     const raw = readFileSync(p, "utf-8") as string;
     return raw.slice(-bytes);
@@ -46,8 +143,8 @@ export function tailWorkerOutput(attemptDir: string, bytes = 3000): string {
 
 export function listWorkers(targetDir: string, runId?: string): WorkerSnapshot[] {
   try {
-    const { readdirSync, existsSync } = require("node:fs");
-    const path = require("node:path");
+    const { readdirSync, existsSync } = require("node:fs") as typeof import("node:fs");
+    const path = require("node:path") as typeof import("node:path");
     const root = path.resolve(targetDir, "tmp/infinity-harness", runId ?? "");
     const roots: string[] = [];
     if (runId) {
@@ -92,7 +189,7 @@ export function listWorkers(targetDir: string, runId?: string): WorkerSnapshot[]
 
 export function nextModelForTask(targetDir: string, difficulty?: string, taskId?: string, key?: string): { model?: string; thinking?: string } {
   try {
-    const { resolveModel, resolveThinking } = require("./modelRouter.ts");
+    const { resolveModel, resolveThinking } = require("./modelRouter.ts") as typeof import("./modelRouter.ts");
     return {
       model: resolveModel({ projectDir: targetDir, task: { difficulty: difficulty as any, id: taskId, key } }),
       thinking: resolveThinking({ projectDir: targetDir, task: { difficulty: difficulty as any, id: taskId, key } }),
@@ -104,8 +201,7 @@ export function pickRunnableTasks(opts: PickOpts): FlatTask[] {
   const { list } = loadFeatureList(opts.targetDir);
   const phase = (opts.phase ?? null) as Phase | null;
   // Phase-filtered pool when phase given, else all tasks across phases.
-  const { flattenTasks } = require("./core/featureList.ts");
-  const all: FlatTask[] = phase ? tasksForPhase(list, phase) : (flattenTasks(list) as FlatTask[]);
+  const all: FlatTask[] = phase ? tasksForPhase(list, phase) : (flattenTasks(list) as FlatTask[]); // imported above
   // Build key map for dep check
   const byKey = new Map<string, FlatTask>();
   for (const t of all) {
@@ -172,13 +268,20 @@ export async function spawnWorkers(
 ): Promise<SpawnWorkerResult[]> {
   const { resolveModel } = await import("./modelRouter.ts");
   const runId = opts?.runId ?? runIdFor(targetDir, "sched");
+  // handoff bucket determines effective difficulty — read once
+  let handoff: HandoffGranularity = "task";
+  try { handoff = (loadConfig(targetDir).config.session?.handoff as HandoffGranularity) ?? "task"; } catch {}
+  const allList = (()=>{ try{ return loadFeatureList(targetDir).list; }catch{ return null as unknown as import("./core/types.ts").FeatureList; } })();
   const results: SpawnWorkerResult[] = [];
   for (const t of tasks) {
     const prompt = opts.promptFor(t);
     const router = loadRouterConfig(targetDir);
     let modelHint: string | undefined;
     if (router.enabled) {
-      try { modelHint = resolveModel({ projectDir: targetDir, task: { difficulty: (t as { difficulty?: string }).difficulty, id: t.id, key: t.compositeKey } }); } catch {}
+      try {
+        const effDiff = allList ? effectiveDifficultyForTask(t, handoff, allList) : (t as { difficulty?: string }).difficulty;
+        modelHint = resolveModel({ projectDir: targetDir, task: { difficulty: effDiff as string | undefined, id: t.id, key: t.compositeKey } });
+      } catch {}
     }
     const res = await spawnIsolatedWorker({
       projectDir: targetDir,

package/src/ui/dashboard.ts

@@ -51,6 +51,8 @@ export type DashboardState = {
   baseRevision: number;
   timestamp: string;
   retries?: { task: number; max: number };
+  dashboardUrl?: string | null;
+  handoffModelNote?: string | null;
   /** Model-router config. Opaque here — rendered as a badge, never interpreted. */
   router?: unknown;
   /** Rework record. Opaque here — rendered as a badge, never interpreted. */
@@ -987,10 +989,12 @@ table.tasks tr:last-child td{border-bottom:0}
 .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: the whole active branch pulses — every active box, not just one feature. */
-.tier.is-current,.feature.is-current{animation:cardPulse 0.9s ease-in-out infinite; border-color:var(--c-accent)!important; box-shadow:0 0 0 2px rgba(var(--rgb-accent),.35), var(--shadow)}
-.tier.is-current .tier-name,.feature.is-current .feature-name{color:var(--t-accent)}
-.row.is-active{animation:taskBlink 0.9s ease-in-out infinite; outline:2px solid var(--c-active); outline-offset:-2px}
-@keyframes cardPulse{0%,100%{box-shadow:0 0 0 2px rgba(var(--rgb-accent),.35),var(--shadow); border-color:var(--c-accent)}50%{box-shadow:0 0 0 5px rgba(var(--rgb-accent),.14),var(--shadow); border-color:rgba(var(--rgb-accent),.55)}}
+.dash-url{margin:8px 0 0;font-size:13px} .dash-url a{color:var(--t-accent);text-decoration:none;border-bottom:1px dashed rgba(var(--rgb-accent),.45)} .dash-url a:hover{border-bottom-style:solid}
+.handoff-note{margin:4px 0 0;color:var(--muted);font-size:12px}
+.tier.is-current,.feature.is-current{animation:cardPulse 1.2s ease-in-out infinite; border-color:var(--c-accent)!important; box-shadow:0 0 0 3px rgba(var(--rgb-accent),.45), 0 0 12px rgba(var(--rgb-accent),.25), var(--shadow)}
+.tier.is-current .tier-name,.feature.is-current .feature-name{color:var(--t-accent);font-weight:650}
+.row.is-active{animation:taskBlink 0.9s ease-in-out infinite; outline:2px solid var(--c-active); outline-offset:-2px; box-shadow:0 0 8px rgba(var(--rgb-active),.35)}
+@keyframes cardPulse{0%,100%{box-shadow:0 0 0 3px rgba(var(--rgb-accent),.45),0 0 12px rgba(var(--rgb-accent),.25),var(--shadow); border-color:var(--c-accent)}50%{box-shadow:0 0 0 7px rgba(var(--rgb-accent),.22),0 0 16px rgba(var(--rgb-accent),.32),var(--shadow); border-color:rgba(var(--rgb-accent),.70)}}
 @keyframes textPulse{0%,100%{opacity:1}50%{opacity:.78}}
 .row-blocked{background:rgba(var(--rgb-blocked),.07)}
 .row-blocked .cell-n{box-shadow:inset 2px 0 0 var(--c-blocked)}
@@ -1237,6 +1241,8 @@ export function renderDashboard(state: DashboardState): string {
   if (progress.tasksTotal > 0) titleBits.push(`${progress.percent}%`);
   const title = `${titleBits.join(" · ")} · infinity-harness`;
 
+  const dashboardUrlHtml = state.dashboardUrl ? `<div class="dash-url">Dashboard: <a href="${esc(state.dashboardUrl)}">${esc(state.dashboardUrl)}</a></div>` : "";
+  const handoffNoteHtml = state.handoffModelNote ? `<div class="handoff-note">${esc(state.handoffModelNote)}</div>` : "";
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -1253,6 +1259,7 @@ export function renderDashboard(state: DashboardState): string {
 <div id="app">
 <div class="page">
 ${renderMasthead(state.phase, paused, progress.percent, state.baseRevision, badges)}
+${dashboardUrlHtml}${handoffNoteHtml}
 ${display.levels.goal ? renderGoals(goals) : ""}
 ${display.rail ? renderRail(state.phase, state.enabledPhases, paused) : ""}
 ${

package/src/ui/widget.ts

@@ -46,6 +46,10 @@ export type WidgetState = {
   enabledPhases?: readonly string[] | null;
   paused?: boolean;
   gate?: { overall: boolean; failures: string[] } | null;
+  /** Dashboard URL to show near the top, clickable. Meaningful host:port, not just numbers. */
+  dashboardUrl?: string | null;
+  /** Model routing note: e.g. "Model per task — subtasks share parent". Shown once. */
+  handoffModelNote?: string | null;
   /** Shown in the header rule, e.g. "rev 42". */
   revision?: number;
   retries?: { task: number; max: number };
@@ -406,6 +410,17 @@ export function renderWidget(state: WidgetState, options: WidgetOptions = {}): s
   const headRight = phaseTag + revTag;
   const gapW = inner - width(headLeft) - width(headRight);
   push(headLeft + (gapW > 1 ? s.fg("rule", " " + g.rail.repeat(gapW - 2) + " ") : " ") + headRight);
+  // Dashboard URL near top, clickable (OSC 8) with meaningful host:port, not just numbers.
+  if (state.dashboardUrl) {
+    const url = state.dashboardUrl;
+    const label = s.fg("accent", url);
+    // OSC 8 hyperlink: terminals that support it make it clickable; others show the URL.
+    const link = `\u001b]8;;${url}\u0007${label}\u001b]8;;\u0007`;
+    push(truncate(s.fg("muted", "Dashboard: ") + link, inner));
+  }
+  if (state.handoffModelNote) {
+    push(truncate(s.fg("muted", state.handoffModelNote), inner));
+  }
 
   // -- goal -----------------------------------------------------------------
   //

package/src/ui/wizard.ts

@@ -183,6 +183,23 @@ export async function runIntakeWizard(options: WizardOptions): Promise<WizardRes
       | "phase"
       | "task";
 
+    // -- 3b. research depth (only when research is in the pipeline) ----------
+    let researchDepth: import("../intake.ts").ResearchDepth | undefined;
+    if (workflow.phases.includes("research" as import("../core/types.ts").Phase)) {
+      const RESEARCH_DEPTH_QUESTION = {
+        title: "How deep should research go?",
+        options: [
+          { value: "standard", label: "Deep — 3 tasks, 5+ primary sources + comparison table", help: ">=5 sources with URLs, constraints table, 3 options + falsification (~800 chars gate). Lite mode." },
+          { value: "deep", label: "Very Deep — 5 tasks, competitive matrix + cost/risk model", help: ">=7 sources, gap analysis, competitive matrix, risk register (~1800 chars). Recommended." },
+          { value: "comprehensive", label: "Literature Review — 10 tasks, 15+ sources annotated", help: ">=15 sources annotated bibliography, benchmarks, synthesis + gap analysis (~5000 chars)." },
+        ],
+      };
+      const depthLabels = RESEARCH_DEPTH_QUESTION.options.map((o) => line(o.label, o.help));
+      const depthPick = await prompt.select(RESEARCH_DEPTH_QUESTION.title, depthLabels);
+      if (depthPick === undefined) return { cancelled: true };
+      researchDepth = (RESEARCH_DEPTH_QUESTION.options[depthLabels.indexOf(depthPick)]?.value ?? "deep") as import("../intake.ts").ResearchDepth;
+    }
+
     // -- 4. models ----------------------------------------------------------
     const modelsAnswer = await pickModelsStep(prompt, options.models);
     if (modelsAnswer === undefined) return { cancelled: true };
@@ -211,7 +228,7 @@ export async function runIntakeWizard(options: WizardOptions): Promise<WizardRes
     const display = await pickDisplay(prompt, env);
     if (display === undefined) return { cancelled: true };
 
-    const answers: IntakeAnswers = { workflow, brief, handoff, display, router: modelsAnswer.router, parallelAt, maxWorkers };
+    const answers: IntakeAnswers = { workflow, researchDepth, brief, handoff, display, router: modelsAnswer.router, parallelAt, maxWorkers };
     const plan = planIntake(answers);
 
     if (options.skipConfirm) return { cancelled: false, plan, answers };