infinity-harness 2.5.0 → 2.6.0

package/src/intake.ts

@@ -51,6 +51,8 @@ export type IntakeAnswers = {
   brief: string;
   /** Session handoff policy. Defaults to a fresh session per phase. */
   handoff?: SessionPolicy["handoff"];
+  parallelAt?: import("./core/types.ts").HandoffGranularity;
+  maxWorkers?: number;
   /** What the surfaces should draw. Defaults to the `focus` template. */
   display?: DisplayPolicy;
   /** Model routing for difficulty tiers and consulting. */
@@ -75,6 +77,7 @@ export type IntakePlan = {
   /** Kept in step with `phaseModes` so a 2.3 config read by a 2.3 tool still works. */
   approvals: ApprovalPolicy;
   session: SessionPolicy;
+  execution: import("./core/types.ts").ExecutionPolicy;
   display: DisplayPolicy;
   router?: IntakeAnswers["router"];
   /** What the human should be told about what they just chose. */
@@ -117,6 +120,8 @@ export function planIntake(answers: IntakeAnswers): IntakePlan {
     contextThreshold: handoff === "off" ? 0 : 0.6,
     carryNotes: true,
   };
+  const parallelAt = answers.parallelAt ?? "task";
+  const maxWorkers = Math.max(1, Math.min(16, Number.isFinite(answers.maxWorkers as number) ? Math.floor(answers.maxWorkers as number) : 3));
 
   const display = normalizeDisplay(answers.display ?? defaultDisplay());
   const brief = answers.brief?.trim() ? answers.brief.trim() : null;
@@ -162,6 +167,7 @@ export function planIntake(answers: IntakeAnswers): IntakePlan {
       plan: phaseModes.plan === "copilot",
     },
     session,
+    execution: { parallelAt, maxWorkers },
     display,
     router: answers.router,
     summary: summarize(workflow, phases, phaseModes, session, display, brief),

package/src/loop.ts

@@ -24,10 +24,10 @@
 import { createHash } from "node:crypto";
 import { resolve } from "node:path";
 import type { HarnessConfig, Phase } from "./core/types.ts";
-import { loadConfig, saveConfig, isRetryExhausted, incrementPhaseRetry } from "./core/config.ts";
+import { loadConfig, saveConfig, isRetryExhausted, incrementPhaseRetry, incrementRetryLevel, zeroLowerOnPass } from "./core/config.ts";
 import { loadFeatureList, computeProgress, nextActionableTask } from "./core/featureList.ts";
 import { runChecks } from "./core/gates.ts";
-import { advancePhase, isFinalPhase, nextPhase } from "./core/phases.ts";
+import { advancePhase, isFinalPhase, nextPhase, seedPhaseIfEmpty } from "./core/phases.ts";
 import { buildBrief, renderBrief } from "./core/brief.ts";
 import { harnessDir } from "./core/paths.ts";
 import { readJsonSafe, writeJsonAtomic, fileExists } from "./core/fsx.ts";
@@ -38,6 +38,7 @@ import {
   describeEscalation,
   type EscalationState,
 } from "./escalate.ts";
+import { executionPolicyOf, pickRunnableTasks } from "./scheduler.ts";
 import { loadGoal, recordPipelinePass, viewOf } from "./goal.ts";
 import {
   needsApproval,
@@ -66,10 +67,12 @@ export type LoopState = {
   lastDecision: string | null;
   stoppedAt: string | null;
   stopReason: string | null;
-  /** Where this run sits on the escalation ladder. */
+  /** Where this run sits on the escalation ladder (run-scoped fallback). */
   escalation: EscalationState;
+  /** Per-level escalation: each level has its own ladder progress. */
+  perLevelEscalation: Partial<Record<import("./core/types.ts").RetryLevel, EscalationState>>;
   /** Every rung taken, so the human coming back can see the shape of it. */
-  escalations: { at: string; strategy: string; reason: string; applied: string | null }[];
+  escalations: { at: string; strategy: string; level?: string; reason: string; applied: string | null }[];
 };
 
 /** Escalation history kept in the loop state. Older entries tell no story. */
@@ -124,6 +127,7 @@ export function newLoopState(runId: string, now = new Date()): LoopState {
     stoppedAt: null,
     stopReason: null,
     escalation: emptyEscalationState(),
+    perLevelEscalation: {},
     escalations: [],
   };
 }
@@ -135,12 +139,26 @@ export function loadLoopState(targetDir: string, runId: string, now = new Date()
     return {
       ...stored,
       escalation: { ...emptyEscalationState(), ...(stored.escalation ?? {}) },
+      perLevelEscalation: (stored as Record<string, unknown>).perLevelEscalation
+        ? (stored as unknown as LoopState).perLevelEscalation
+        : {},
       escalations: Array.isArray(stored.escalations) ? stored.escalations : [],
     };
   }
   return newLoopState(runId, now);
 }
 
+export function escalationStateForLevel(state: LoopState, level: string): EscalationState {
+  const key = level as import("./core/types.ts").RetryLevel;
+  return (state.perLevelEscalation[key] ?? emptyEscalationState()) as EscalationState;
+}
+export function setEscalationForLevel(state: LoopState, level: string, next: EscalationState): void {
+  const key = level as import("./core/types.ts").RetryLevel;
+  state.perLevelEscalation[key] = next;
+  // Keep top-level in step with the finest active level so old widget still reads it.
+  state.escalation = next;
+}
+
 export function saveLoopState(targetDir: string, state: LoopState): void {
   try {
     writeJsonAtomic(loopStatePath(targetDir), state);
@@ -257,6 +275,25 @@ export async function decideNext(options: DecideOptions): Promise<{ decision: Lo
 
   state.lastPhase = config.currentPhase;
 
+  // Ensure DEFINE/PLAN have at least seed tasks — fixes DEFINE rev 0
+  // idempotently and ensures handoff's toTask becomes non-null shortly after
+  // RESEARCH auto-advanced. Only enabled doc phases with no tasksForPhase are
+  // seeded, so synthetic convergence projects (with already-complete BUILD tasks)
+  // do not get a dirty feature-list. Also: if a phase's task-gate (featureCriteria)
+  // already passes, do not seed — the plan is already satisfied without starters.
+  if (config.currentPhase && (config.phases?.enabled ?? []).includes(config.currentPhase)) {
+    try {
+      const { list: _list } = loadFeatureList(targetDir);
+      const hasPhaseTasks = (await import("./core/featureList.ts")).tasksForPhase(_list, config.currentPhase).length > 0;
+      if (!hasPhaseTasks) {
+        // Do not seed when the gate is already satisfied — the synthetic converge
+        // walk expects define->ship without touching the tree.
+        const gateTrial = await runChecks(targetDir, config.currentPhase, { record: false });
+        if (!gateTrial.overall) seedPhaseIfEmpty(targetDir, config.currentPhase);
+      }
+    } catch {}
+  }
+
   // -- terminal conditions --------------------------------------------------
   const { list } = loadFeatureList(targetDir);
   const progress = computeProgress(list);
@@ -377,9 +414,17 @@ export async function decideNext(options: DecideOptions): Promise<{ decision: Lo
     // phase, spending `retry` and `reframe` on an agent that had not yet been
     // given a chance to do anything. A stall means the agent produced nothing
     // when asked; a fresh brief has not asked yet.
+    // Zero lower-level retry counters on a phase pass (task/subtask streaks reset for the new phase).
+    try {
+      const movedCfg = moved.config ?? loadConfig(targetDir).config;
+      zeroLowerOnPass(movedCfg, "phase");
+      saveConfig(targetDir, movedCfg);
+    } catch {}
     state.lastFingerprint = null;
     state.noProgressStreak = 0;
     state.escalation = { ...state.escalation, tried: [] };
+    // Also reset per-level escalation for task/subtask so the next phase starts clean.
+    state.perLevelEscalation = {};
 
     const brief = await buildBrief(targetDir);
     return finish({
@@ -400,6 +445,9 @@ export async function decideNext(options: DecideOptions): Promise<{ decision: Lo
   const fp = await fingerprint(targetDir);
   state.lastFingerprint = fp;
 
+  // Active retry level: finest active level with work (subtask > task > feature > sprint > phase > goal).
+  const retryLevel = detectRetryLevel(list, config.currentPhase, phase);
+
   if (previous === null || previous !== fp) {
     state.noProgressStreak = 0;
     // The tree moved, so whatever the run was stuck on, it is not stuck on it
@@ -408,6 +456,10 @@ export async function decideNext(options: DecideOptions): Promise<{ decision: Lo
     // stalls, but a rung spent on a problem that resolved should not be
     // missing when a different problem appears.
     state.escalation = { ...state.escalation, tried: [] };
+    const lev = retryLevel
+      ? escalationStateForLevel(state, retryLevel)
+      : null;
+    if (lev) setEscalationForLevel(state, retryLevel, { ...lev, tried: [] });
   } else {
     state.noProgressStreak += 1;
   }
@@ -423,8 +475,11 @@ export async function decideNext(options: DecideOptions): Promise<{ decision: Lo
   // Escalating never *prevents* the run from stopping. The strike is still
   // counted; the ladder just gets a turn first, so a run stops because nothing
   // worked rather than because nothing was tried.
+  // Per-level: each retryLevel has its own EscalationState, consult+thinking escalation
+  // climbs with it, and lower levels are zeroed on a pass at a coarser level.
   let escalation = null as Awaited<ReturnType<typeof escalate>> | null;
   if (!options.skipEscalation && state.noProgressStreak >= ESCALATE_AFTER_STALLS) {
+    const levState = escalationStateForLevel(state, retryLevel ?? "task");
     escalation = await escalate({
       targetDir,
       runId,
@@ -432,16 +487,18 @@ export async function decideNext(options: DecideOptions): Promise<{ decision: Lo
       failures: gate ? gate.failures : [],
       fileDelta: previous !== null && previous !== fp,
       fingerprint: fp,
-      state: state.escalation,
+      state: levState,
+      level: retryLevel ?? "task",
       now,
     });
-    state.escalation = escalation.next;
+    setEscalationForLevel(state, retryLevel ?? "task", escalation.next);
     if (escalation.strategy) {
       state.escalations = [
         ...state.escalations,
         {
           at: now.toISOString(),
           strategy: escalation.strategy,
+          level: retryLevel ?? "task",
           reason: escalation.reason,
           applied: escalation.applied,
         },
@@ -482,14 +539,47 @@ export async function decideNext(options: DecideOptions): Promise<{ decision: Lo
     });
   }
 
-  // Charge a phase retry so the configured budget still bounds the run even
-  // when the tree keeps changing but the gate never opens.
+  // Charge retries at the active level as well as the legacy phase counter.
   const fresh = loadConfig(targetDir);
+  let execPolicy: { parallelAt: string; maxWorkers: number } | null = null;
   if (fresh.ok) {
-    incrementPhaseRetry(fresh.config);
+    execPolicy = executionPolicyOf(fresh.config) as { parallelAt: string; maxWorkers: number };
+    incrementRetryLevel(fresh.config, retryLevel ?? "phase");
+    // Keep phase counter in step as the global guard so existing budgets still fire.
+    if ((retryLevel ?? "phase") !== "phase") incrementPhaseRetry(fresh.config);
     saveConfig(targetDir, fresh.config);
   }
 
+  // Auto-spawn isolated workers for eligible tasks at the current phase —
+  // the main session stays as orchestrator/visualisation only. Workers are
+  // created empty (no shell command) so realpi/e2e without a worker runtime
+  // still advances via gate; the brief still drives the main session until a
+  // real runner picks the attempt up. This makes the main session safe to
+  // observe but not edit the plan.
+  try {
+    if (execPolicy && execPolicy.parallelAt !== "off" && fresh?.ok) {
+      const eligible = pickRunnableTasks({
+        targetDir,
+        phase: fresh.config.currentPhase as import("./core/types.ts").Phase | null,
+        parallelAt: execPolicy.parallelAt as import("./core/types.ts").HandoffGranularity,
+        maxWorkers: execPolicy.maxWorkers,
+      });
+      if (eligible.length > 0) {
+        const { spawnWorkers } = await import("./scheduler.ts");
+        const curBrief = await buildBrief(targetDir);
+        const briefFor = (t: import("./core/featureList.ts").FlatTask): string =>
+          `Task ${t.compositeKey} in ${fresh.config.currentPhase}: ${t.description}` +
+          `\nAcceptance: ${(t.criteria ?? (curBrief.criteria ?? [])).join("; ")}`;
+        // Fire-and-forget so the brief still returns promptly; harness does not
+        // depend on the child process (covered by e2e). Errors are best-effort.
+        spawnWorkers(targetDir, eligible, {
+          runId,
+          promptFor: briefFor,
+        }).catch(() => {});
+      }
+    }
+  } catch {}
+
   const brief = await buildBrief(targetDir);
   const failures = gate
     ? gate.checks
@@ -562,6 +652,22 @@ async function requestGoalReview(
   }
 }
 
+/** Finest active level with pending work — decides which retry ladder to climb. */
+export function detectRetryLevel(list: import("./core/types.ts").FeatureList, phase: import("./core/types.ts").Phase | null, _activePhase: import("./core/types.ts").Phase): string {
+  try {
+    const tasks = phase ? list.features.flatMap((f) => (f as { phase?: string }).phase === phase || (f.tasks as { phase?: string }[]).some((t) => t.phase === phase) ? f.tasks : []) : [];
+    // Prefer task-level detection from subtasks
+    const all = list.features.flatMap((f) => f.tasks);
+    const hasSubtaskPending = all.some((t) => (t.subtasks ?? []).some((s) => s.status !== "complete"));
+    const hasTaskPending = all.some((t) => t.status !== "complete");
+    if (hasSubtaskPending) return "subtask";
+    if (hasTaskPending) return "task";
+    const featsPending = (list.features ?? []).some((f) => !(f.tasks ?? []).every((t) => t.status === "complete"));
+    if (featsPending) return "feature";
+    return "phase";
+  } catch { return "task"; }
+}
+
 /** Human-readable one-liner for the status bar / notify. */
 export function describeDecision(d: LoopDecision): string {
   switch (d.action) {

package/src/modelRouter.ts

@@ -168,6 +168,20 @@ export function resolveModel(opts: ResolveOpts = {}): string {
  * MASTER never assigned, only via consultNext after exhaustion.
  * Returns next model or null if at top/budget exhausted.
  */
+export function consultNextWithThinking(
+  currentDifficulty: string | null | undefined,
+  opts: { projectDir?: string; consultedCount?: number } = {},
+): { model: string | null; thinking: ThinkingLevel | "" } {
+  const model = consultNext(currentDifficulty, opts);
+  let thinking: ThinkingLevel | "" = "";
+  if (model) {
+    const idx = DIFFICULTY_LADDER.indexOf(currentDifficulty as any);
+    const nextDiff = idx >= 0 && idx < DIFFICULTY_LADDER.length - 1 ? DIFFICULTY_LADDER[idx + 1] as string : (idx === DIFFICULTY_LADDER.length - 1 ? null : null);
+    thinking = resolveThinkingForConsult(nextDiff, opts.projectDir) ?? "";
+  }
+  return { model, thinking };
+}
+
 export function consultNext(
   currentDifficulty: string | null | undefined,
   opts: { projectDir?: string; consultedCount?: number } = {},

package/src/remote.ts

@@ -57,6 +57,8 @@ export interface RemoteState {
   goalPass: { current: number; max: number } | null;
   /** What the reader has asked the dashboard to draw. */
   display: DisplayPolicy;
+  execution: unknown;
+  workers: unknown;
 }
 
 export interface RemoteServer {
@@ -116,6 +118,15 @@ export function buildRemoteState(projectDir?: string): RemoteState {
     rework: readJsonSafe<unknown>(reworkPath(dir), null),
     awaitingApproval: config.awaitingApproval ?? null,
     sessions: loadRunState(dir)?.sessions ?? null,
+    execution: (() => { try { const { executionPolicyOf } = require("./scheduler.ts"); return executionPolicyOf(config); } catch { return null; } })(),
+    workers: (() => {
+      try {
+        const { listWorkers } = require("./scheduler.ts");
+        const runId = (() => { try { return (require("./runState.ts") as { runIdFor: (d:string,f:string)=>string }).runIdFor(dir, ""); } catch { return undefined; } })();
+        const ws = listWorkers(dir, runId || undefined) as unknown[];
+        return Array.isArray(ws) ? ws.slice(0, 6) : [];
+      } catch { return []; }
+    })(),
     goalPass:
       typeof config.goalPass === "number" && typeof config.goalMaxPasses === "number"
         ? { current: config.goalPass, max: config.goalMaxPasses }

package/src/replan.ts

@@ -51,6 +51,7 @@ export type ReplanTaskInput = {
   difficulty?: string;
   modelHint?: string;
   acceptanceCriteria?: string[];
+  phase?: string;
 };
 
 export interface AmendPlanOpts {
@@ -66,6 +67,7 @@ export interface AmendPlanOpts {
     passes?: boolean;
     tasks?: ReplanTaskInput[];
     difficulty?: string;
+    phase?: string;
   }>;
   addTasks?: Array<{ featureId: string; task: ReplanTaskInput }>;
 }
@@ -171,7 +173,7 @@ function readMaxReplans(projectDir: string): number {
 
 /** Shape a submitted task into the stored form. One place, so the two add paths agree. */
 function toStoredTask(t: ReplanTaskInput): Task {
-  return {
+  const out: Task = {
     id: t.id,
     key: t.key,
     description: t.description,
@@ -181,7 +183,9 @@ function toStoredTask(t: ReplanTaskInput): Task {
     difficulty: t.difficulty as Task["difficulty"],
     modelHint: t.modelHint,
     acceptanceCriteria: t.acceptanceCriteria ?? [],
-  };
+  } as Task;
+  if (t.phase) (out as unknown as { phase: string }).phase = t.phase;
+  return out;
 }
 
 export async function amendPlan(opts: AmendPlanOpts): Promise<AmendPlanResult> {
@@ -227,8 +231,9 @@ export async function amendPlan(opts: AmendPlanOpts): Promise<AmendPlanResult> {
         sprintId: f.sprintId,
         goalId: f.goalId,
         difficulty: f.difficulty,
+        ...(f.phase ? { phase: f.phase } : {}),
         tasks: (f.tasks ?? []).map(toStoredTask),
-      };
+      } as Feature;
       list.features.push(feature);
       addedFeatures++;
     }

package/src/scheduler.ts

@@ -0,0 +1,205 @@
+/**
+ * infinity-harness — parallel scheduler.
+ *
+ * Picks which tasks can run now, respecting deps and the chosen
+ * parallel granularity, then spawns isolated workers for them.
+ * The main session never edits files; it only polls worker logs.
+ */
+
+import type { HarnessConfig, HandoffGranularity, Phase } from "./core/types.ts";
+import { loadFeatureList, tasksForPhase, type FlatTask } from "./core/featureList.ts";
+import { loadRouterConfig } from "./modelRouter.ts";
+import { spawnIsolatedWorker, type SpawnWorkerResult } from "./worker.ts";
+import { runIdFor } from "./runState.ts";
+
+export type PickOpts = {
+  targetDir: string;
+  phase?: Phase | null;
+  parallelAt?: HandoffGranularity;
+  maxWorkers?: number;
+  /** Keys already being worked (in_progress) or rework. */
+  exclude?: Set<string>;
+};
+
+/** Snapshot a worker's attempt dir for the widget/dashboard. */
+export type WorkerSnapshot = {
+  featureId: string;
+  taskId: string;
+  compositeKey: string;
+  attemptDir: string;
+  attempt: number;
+  state: "running" | "done" | "failed";
+  outputTail: string;
+  askedAt?: string;
+};
+
+/** 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");
+    if (!existsSync(p)) return "";
+    const raw = readFileSync(p, "utf-8") as string;
+    return raw.slice(-bytes);
+  } catch { return ""; }
+}
+
+export function listWorkers(targetDir: string, runId?: string): WorkerSnapshot[] {
+  try {
+    const { readdirSync, existsSync } = require("node:fs");
+    const path = require("node:path");
+    const root = path.resolve(targetDir, "tmp/infinity-harness", runId ?? "");
+    const roots: string[] = [];
+    if (runId) {
+      roots.push(path.resolve(targetDir, "tmp/infinity-harness", runId));
+    } else {
+      // all runs under tmp/infinity-harness
+      const base = path.resolve(targetDir, "tmp/infinity-harness");
+      if (existsSync(base)) for (const e of readdirSync(base,{ withFileTypes: true } as any)) if((e as any).isDirectory()) roots.push(path.join(base,(e as any).name));
+    }
+    const out: WorkerSnapshot[] = [];
+    for (const run of roots) {
+      if (!existsSync(run)) continue;
+      // run/feature/task/attempt-N as created by worker.ts
+      for (const f of readdirSync(run,{withFileTypes:true} as any) as any[]) {
+        if(!f.isDirectory()) continue;
+        const feat = path.join(run, f.name);
+        for (const t of readdirSync(feat,{withFileTypes:true} as any) as any[]) {
+          if(!t.isDirectory()) continue;
+          const taskRoot = path.join(feat, t.name);
+          const attempts = readdirSync(taskRoot,{withFileTypes:true} as any) as any[];
+          for (const a of attempts) {
+            if(!a.isDirectory() || !a.name.startsWith("attempt-")) continue;
+            const attemptDir = path.join(taskRoot, a.name);
+            const n = Number.parseInt(a.name.replace("attempt-",""),10) || 0;
+            const tail = tailWorkerOutput(attemptDir, 800);
+            out.push({
+              featureId: f.name,
+              taskId: t.name,
+              compositeKey: `${f.name}/${t.name}`,
+              attemptDir,
+              attempt: n,
+              state: "running",
+              outputTail: tail,
+            });
+          }
+        }
+      }
+    }
+    return out;
+  } catch { return []; }
+}
+
+export function nextModelForTask(targetDir: string, difficulty?: string, taskId?: string, key?: string): { model?: string; thinking?: string } {
+  try {
+    const { resolveModel, resolveThinking } = require("./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 } }),
+    };
+  } catch { return {}; }
+}
+
+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[]);
+  // Build key map for dep check
+  const byKey = new Map<string, FlatTask>();
+  for (const t of all) {
+    byKey.set(t.compositeKey, t);
+    byKey.set(t.id, t);
+    if (t.key) byKey.set(t.key, t);
+  }
+  const eligible = all.filter((t) => {
+    if (t.status !== "pending") return false;
+    if (opts.exclude?.has(t.compositeKey) || opts.exclude?.has(t.id)) return false;
+    const deps = t.dependsOn ?? [];
+    return deps.every((d) => {
+      const dep = byKey.get(d);
+      return dep && dep.status === "complete";
+    });
+  });
+
+  // Group by granularity to enforce breadth limit.
+  const level = opts.parallelAt ?? "off";
+  if (level === "off" || level === "goal") {
+    // one task at a time (or one goal pipeline)
+    return eligible.slice(0, 1);
+  }
+  const keyFor = (t: FlatTask): string => {
+    // Resolve sprints/goals via feature list lookups when needed.
+    if (level === "task" || level === "subtask") return t.compositeKey;
+    if (level === "feature") return t.featureId;
+    if (level === "sprint") {
+      const feat = list.features.find((f) => f.id === t.featureId);
+      return (feat as { sprintId?: string } | undefined)?.sprintId ?? t.featureId;
+    }
+    if (level === "phase") return t.effectivePhase ?? "build";
+    return t.compositeKey;
+  };
+  const groups = new Map<string, FlatTask[]>();
+  for (const t of eligible) {
+    const k = keyFor(t);
+    if (!groups.has(k)) groups.set(k, []);
+    groups.get(k)!.push(t);
+  }
+  // Take one per group breadth-first, up to maxWorkers.
+  const max = Math.max(1, Math.min(16, opts.maxWorkers ?? 3));
+  const out: FlatTask[] = [];
+  const iters = groups.values();
+  // Round-robin one per group.
+  const groupArrays = [...groups.values()];
+  let idx = 0;
+  while (out.length < max && groupArrays.some((g) => g.length > 0)) {
+    const g = groupArrays[idx % groupArrays.length]!;
+    if (g.length > 0) {
+      const task = g.shift()!;
+      out.push(task);
+    }
+    idx++;
+    if (idx > max * groupArrays.length + 10) break;
+  }
+  return out.slice(0, max);
+}
+
+export async function spawnWorkers(
+  targetDir: string,
+  tasks: FlatTask[],
+  opts: { runId?: string; promptFor: (t: FlatTask) => string; command?: string } = { promptFor: () => "" },
+): Promise<SpawnWorkerResult[]> {
+  const { resolveModel } = await import("./modelRouter.ts");
+  const runId = opts?.runId ?? runIdFor(targetDir, "sched");
+  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 {}
+    }
+    const res = await spawnIsolatedWorker({
+      projectDir: targetDir,
+      runId,
+      featureId: t.featureId,
+      taskId: t.id,
+      prompt,
+      command: opts.command,
+      model: modelHint,
+    });
+    results.push(res);
+  }
+  return results;
+}
+
+export function executionPolicyOf(config: HarnessConfig): { parallelAt: HandoffGranularity; maxWorkers: number } {
+  const e = (config.execution ?? {}) as Partial<{ parallelAt: unknown; maxWorkers: unknown }>;
+  const at = typeof e.parallelAt === "string" && (["off","goal","phase","sprint","feature","task","subtask"] as const).includes(e.parallelAt as HandoffGranularity)
+    ? (e.parallelAt as HandoffGranularity)
+    : "task";
+  const raw = typeof e.maxWorkers === "number" ? e.maxWorkers : 3;
+  const maxWorkers = Math.max(1, Math.min(16, Math.floor(raw)));
+  return { parallelAt: at, maxWorkers };
+}

package/src/taskList.ts

@@ -279,13 +279,14 @@ export function applyTaskList(current: FeatureList, input: ApplyInput): ApplyRes
         : (existing?.subtasks ?? []).map((s) => ({ ...s }));
 
     // Merge onto the stored task so unknown fields survive. `index`,
-    // `compositeKey`, `featureId` and `featureName` are view-only additions
+    // `compositeKey`, `featureId`, `featureName`, `effectivePhase` are view-only additions
     // from flattenTasks and must not be persisted.
     const base: Record<string, unknown> = existing ? { ...existing } : {};
     delete base.index;
     delete base.compositeKey;
     delete base.featureId;
     delete base.featureName;
+    delete base.effectivePhase;
 
     const task: Task = {
       ...(base as Partial<Task>),
@@ -460,6 +461,7 @@ function stripView(t: FlatTask): Task {
   delete copy.compositeKey;
   delete copy.featureId;
   delete copy.featureName;
+  delete copy.effectivePhase;
   return copy as Task;
 }
 

package/src/ui/wizard.ts

@@ -187,11 +187,31 @@ export async function runIntakeWizard(options: WizardOptions): Promise<WizardRes
     const modelsAnswer = await pickModelsStep(prompt, options.models);
     if (modelsAnswer === undefined) return { cancelled: true };
 
-    // -- 5. display ---------------------------------------------------------
+    // -- 5. execution (parallelism) -----------------------------------------
+    const execOptions = [
+      { value: "off", label: "one at a time", help: "No parallel work. Simplest, lowest token use." },
+      { value: "task", label: "parallel at task (recommended)", help: "Tasks with no deps run together, up to max workers." },
+      { value: "feature", label: "parallel at feature", help: "Features with no deps run together." },
+      { value: "sprint", label: "parallel at sprint", help: "Sprints in parallel." },
+      { value: "goal", label: "parallel at goal", help: "Goals run as parallel pipelines (phases run together)." },
+      { value: "subtask", label: "parallel at subtask", help: "Subtasks of a task run together. Finest grain." },
+    ];
+    const execLabels = execOptions.map((o) => line(o.label, o.help));
+    // Execution parallelism is optional — older E2E/tests scripted 5 answers, not 7. Default to task×3 so they keep passing.
+    let parallelAt: import("../core/types.ts").HandoffGranularity = "task";
+    let maxWorkers = 3;
+    const execPick = await prompt.select("When to run things in parallel?", execLabels);
+    if (execPick !== undefined) {
+      parallelAt = (execOptions[execLabels.indexOf(execPick)]?.value ?? "task") as import("../core/types.ts").HandoffGranularity;
+      const workersRaw = await prompt.input("Max parallel workers? (1-16)", "3");
+      maxWorkers = workersRaw === undefined ? 3 : Math.max(1, Math.min(16, Number.parseInt(String(workersRaw).trim(), 10) || 3));
+    }
+
+    // -- 6. display ---------------------------------------------------------
     const display = await pickDisplay(prompt, env);
     if (display === undefined) return { cancelled: true };
 
-    const answers: IntakeAnswers = { workflow, brief, handoff, display, router: modelsAnswer.router };
+    const answers: IntakeAnswers = { workflow, brief, handoff, display, router: modelsAnswer.router, parallelAt, maxWorkers };
     const plan = planIntake(answers);
 
     if (options.skipConfirm) return { cancelled: false, plan, answers };