infinity-harness 2.5.0 → 2.6.0

package/src/core/config.ts

@@ -51,6 +51,7 @@ export function defaultConfig(): HarnessConfig {
     phases: { enabled: [...DEFAULT_ENABLED_PHASES] },
     roles: { strict: false },
     session: { handoff: "task", contextThreshold: 0.6, carryNotes: true },
+    execution: { parallelAt: "task", maxWorkers: 3 },
     approvals: { research: false, define: false, plan: false },
     phaseModes: Object.fromEntries(DEFAULT_ENABLED_PHASES.map((p) => [p, "autopilot"])),
     workflow: { id: "autopilot", name: "autopilot" },
@@ -66,12 +67,21 @@ export function defaultConfig(): HarnessConfig {
       tasks: { enabled: true, maxRetries: null },
       features: { enabled: false, maxRetries: DEFAULT_FEATURE_RETRIES },
       phases: { enabled: false, maxRetries: DEFAULT_PHASE_RETRIES },
+      levels: {
+        goal: { enabled: false, maxRetries: 2 },
+        phase: { enabled: false, maxRetries: DEFAULT_PHASE_RETRIES },
+        sprint: { enabled: false, maxRetries: DEFAULT_FEATURE_RETRIES },
+        feature: { enabled: false, maxRetries: DEFAULT_FEATURE_RETRIES },
+        task: { enabled: true, maxRetries: null },
+        subtask: { enabled: false, maxRetries: 3 },
+      },
     },
     maxRetries: DEFAULT_MAX_RETRIES,
     retryCount: 0,
     taskRetryCount: 0,
     featureRetryCount: 0,
     phaseRetryCount: 0,
+    retryPerLevel: {},
     pipelineIteration: 0,
     gateHistory: [],
   };
@@ -235,46 +245,104 @@ export type EffectiveRetry = {
   tasks: { enabled: boolean; max: number };
   features: { enabled: boolean; max: number };
   phases: { enabled: boolean; max: number };
+  levels: Record<string, { enabled: boolean; max: number }>;
+};
+
+const LEVEL_DEFAULTS: Record<string, number> = {
+  goal: 2,
+  phase: DEFAULT_PHASE_RETRIES,
+  sprint: DEFAULT_FEATURE_RETRIES,
+  feature: DEFAULT_FEATURE_RETRIES,
+  task: DEFAULT_MAX_RETRIES,
+  subtask: 3,
 };
 
 /** Resolve retry budgets, seeding task retries from the legacy `maxRetries`. */
 export function getRetryConfig(config: HarnessConfig): EffectiveRetry {
   const legacy = typeof config.maxRetries === "number" ? config.maxRetries : DEFAULT_MAX_RETRIES;
-  const r = config.retry ?? defaultConfig().retry;
+  const r = (config.retry ?? defaultConfig().retry) as typeof defaultConfig.prototype.retry & { levels?: Record<string, { enabled?: boolean; maxRetries?: number | null }> };
+  const levels: Record<string, { enabled: boolean; max: number }> = {};
+  for (const k of ["goal","phase","sprint","feature","task","subtask"]) {
+    const bucket = (r as Record<string, unknown>).levels ? ((r as Record<string, unknown>).levels as Record<string, { enabled?: boolean; maxRetries?: number | null }>)[k] : undefined;
+    const defEnabled = k === "task";
+    const defMax = LEVEL_DEFAULTS[k] ?? DEFAULT_MAX_RETRIES;
+    const enabled = bucket ? (bucket.enabled ?? defEnabled) : defEnabled;
+    const rawMax = bucket ? (bucket.maxRetries ?? null) : null;
+    // Unset task level inherits legacy maxRetries
+    const max = rawMax === null ? (k === "task" ? legacy : defMax) : rawMax;
+    levels[k] = { enabled, max };
+  }
+  // Also keep legacy per-name budgets for compatibility
   return {
     tasks: { enabled: r.tasks?.enabled ?? true, max: r.tasks?.maxRetries ?? legacy },
     features: { enabled: r.features?.enabled ?? false, max: r.features?.maxRetries ?? DEFAULT_FEATURE_RETRIES },
     phases: { enabled: r.phases?.enabled ?? false, max: r.phases?.maxRetries ?? DEFAULT_PHASE_RETRIES },
+    levels,
   };
 }
 
+/** Generic per-level retry counter helpers (zero on pass, escalate on exhaustion). */
+export function getRetryLevel(config: HarnessConfig, level: string): number {
+  const m = (config.retryPerLevel ?? {}) as Record<string, number>;
+  return typeof m[level] === "number" ? m[level]! : 0;
+}
+export function resetRetryLevel(config: HarnessConfig, level: string): void {
+  if (!config.retryPerLevel) config.retryPerLevel = {};
+  (config.retryPerLevel as Record<string, number>)[level] = 0;
+  // keep legacy counters in step
+  if (level === "task") config.taskRetryCount = 0;
+  if (level === "feature") config.featureRetryCount = 0;
+  if (level === "phase") { config.phaseRetryCount = 0; config.retryCount = 0; }
+}
+export function incrementRetryLevel(config: HarnessConfig, level: string): number {
+  if (!config.retryPerLevel) config.retryPerLevel = {};
+  const m = config.retryPerLevel as Record<string, number>;
+  m[level] = (m[level] ?? 0) + 1;
+  if (level === "task") config.taskRetryCount = m[level]!;
+  if (level === "feature") config.featureRetryCount = m[level]!;
+  if (level === "phase") { config.phaseRetryCount = m[level]!; config.retryCount = m[level]!; }
+  return m[level]!;
+}
+/** Zero all strictly lower levels than `passedLevel` on a pass (e.g. task pass zeroes subtask). */
+export function zeroLowerOnPass(config: HarnessConfig, passedLevel: string): void {
+  const order = ["goal","phase","sprint","feature","task","subtask"];
+  const idx = order.indexOf(passedLevel);
+  if (idx === -1) return;
+  for (let i = idx + 1; i < order.length; i++) {
+    const lower = order[i]!;
+    if (getRetryLevel(config, lower) !== 0) resetRetryLevel(config, lower);
+  }
+}
+
 export function resetTaskRetry(config: HarnessConfig): void {
-  config.taskRetryCount = 0;
+  resetRetryLevel(config, "task");
 }
 export function incrementTaskRetry(config: HarnessConfig): number {
-  config.taskRetryCount = (config.taskRetryCount ?? 0) + 1;
-  return config.taskRetryCount;
+  return incrementRetryLevel(config, "task");
 }
 export function resetFeatureRetry(config: HarnessConfig): void {
-  config.featureRetryCount = 0;
+  resetRetryLevel(config, "feature");
 }
 export function incrementFeatureRetry(config: HarnessConfig): number {
-  config.featureRetryCount = (config.featureRetryCount ?? 0) + 1;
-  return config.featureRetryCount;
+  return incrementRetryLevel(config, "feature");
 }
 export function resetPhaseRetry(config: HarnessConfig): void {
-  config.phaseRetryCount = 0;
-  config.retryCount = 0;
+  resetRetryLevel(config, "phase");
 }
 export function incrementPhaseRetry(config: HarnessConfig): number {
-  config.phaseRetryCount = (config.phaseRetryCount ?? 0) + 1;
-  config.retryCount = (config.retryCount ?? 0) + 1;
-  return config.phaseRetryCount;
+  return incrementRetryLevel(config, "phase");
 }
 
 /** True when any *enabled* retry budget is exhausted — the signal to escalate. */
 export function isRetryExhausted(config: HarnessConfig): { exhausted: boolean; which: string | null } {
   const r = getRetryConfig(config);
+  // Prefer per-level levels when enabled, but retain legacy task/feature/phase order for compatibility.
+  for (const lvl of ["subtask","task","feature","sprint","phase","goal"]) {
+    const b = r.levels[lvl];
+    if (!b) continue;
+    const cnt = getRetryLevel(config as unknown as HarnessConfig, lvl);
+    if (b.enabled && cnt >= b.max) return { exhausted: true, which: lvl };
+  }
   if (r.tasks.enabled && (config.taskRetryCount ?? 0) >= r.tasks.max) return { exhausted: true, which: "task" };
   if (r.features.enabled && (config.featureRetryCount ?? 0) >= r.features.max) return { exhausted: true, which: "feature" };
   if (r.phases.enabled && (config.phaseRetryCount ?? 0) >= r.phases.max) return { exhausted: true, which: "phase" };

package/src/core/featureList.ts

@@ -124,8 +124,11 @@ function normalizeList(raw: FeatureList): FeatureList {
     features: Array.isArray(raw.features) ? raw.features : [],
   };
   for (const f of list.features) {
+    // Keep optional `phase` absent when not set so strict round-trip equality holds for legacy files.
+    if ((f as { phase?: unknown }).phase !== undefined && typeof (f as { phase?: unknown }).phase !== "string") delete (f as { phase?: unknown }).phase;
     if (!Array.isArray(f.tasks)) f.tasks = [];
     for (const t of f.tasks) {
+      if ((t as { phase?: unknown }).phase !== undefined && typeof (t as { phase?: unknown }).phase !== "string") delete (t as { phase?: unknown }).phase;
       if (!Array.isArray(t.dependsOn)) t.dependsOn = [];
       if (!Array.isArray(t.subtasks)) t.subtasks = [];
       try {
@@ -151,6 +154,8 @@ export type FlatTask = Task & {
   compositeKey: string;
   featureId: string;
   featureName: string;
+  /** Effective phase of this task: `task.phase ?? feature.phase ?? "build"`. */
+  effectivePhase: import("./types.ts").Phase | undefined;
   /** 1-based position in the flattened plan, used for `← #3` dep labels. */
   index: number;
 };
@@ -160,13 +165,16 @@ export function flattenTasks(list: FeatureList): FlatTask[] {
   const out: FlatTask[] = [];
   let i = 0;
   for (const f of list.features ?? []) {
+    const featurePhase = (f as { phase?: string }).phase as import("./types.ts").Phase | undefined;
     for (const t of f.tasks ?? []) {
       i += 1;
+      const eff = (t as { phase?: string }).phase as string | undefined ?? featurePhase ?? "build";
       out.push({
         ...t,
         compositeKey: t.key ?? `${f.id}/${t.id}`,
         featureId: f.id,
         featureName: f.name,
+        effectivePhase: eff as FlatTask["effectivePhase"],
         index: i,
       });
     }
@@ -208,10 +216,40 @@ export type Progress = {
   percent: number;
 };
 
-export function computeProgress(list: FeatureList): Progress {
-  const tasks = flattenTasks(list);
+/** Phase-filtered view: include only tasks whose effectivePhase matches. Pass nothing for global. */
+export function tasksForPhase(list: FeatureList, phase?: string | null): FlatTask[] {
+  const all = flattenTasks(list);
+  if (!phase) return all;
+  return all.filter((t) => t.effectivePhase === phase);
+}
+
+export function featuresForPhase(list: FeatureList, phase?: string | null): import("./types.ts").Feature[] {
+  if (!phase) return list.features ?? [];
+  return (list.features ?? []).filter((f) => (f as { phase?: string }).phase === phase);
+}
+
+export function computeProgress(list: FeatureList, phase?: string | null): Progress {
+  if (!phase) {
+    const tasks = flattenTasks(list);
+    const tasksDone = tasks.filter((t) => isDone(t.status)).length;
+    const features = list.features ?? [];
+    const featuresDone = features.filter(
+      (f) => (f.tasks ?? []).length > 0 && (f.tasks ?? []).every((t) => isDone(t.status)),
+    ).length;
+    return {
+      tasksDone,
+      tasksTotal: tasks.length,
+      featuresDone,
+      featuresTotal: features.length,
+      blocked: tasks.filter((t) => t.status === "blocked").length,
+      inProgress: tasks.filter((t) => t.status === "in_progress").length,
+      rework: tasks.filter((t) => t.status === "rework").length,
+      percent: tasks.length === 0 ? 0 : Math.round((tasksDone / tasks.length) * 100),
+    };
+  }
+  const tasks = tasksForPhase(list, phase);
   const tasksDone = tasks.filter((t) => isDone(t.status)).length;
-  const features = list.features ?? [];
+  const features = featuresForPhase(list, phase);
   const featuresDone = features.filter(
     (f) => (f.tasks ?? []).length > 0 && (f.tasks ?? []).every((t) => isDone(t.status)),
   ).length;
@@ -228,12 +266,11 @@ export function computeProgress(list: FeatureList): Progress {
 }
 
 /**
- * The next task the pipeline should work on: the first in_progress task,
- * else the first pending task whose dependencies are all complete.
+ * The next task the pipeline should work on (optionally scoped to one phase).
  * Returns null when everything is done or everything left is blocked.
  */
-export function nextActionableTask(list: FeatureList): FlatTask | null {
-  const tasks = flattenTasks(list);
+export function nextActionableTask(list: FeatureList, phase?: string | null): FlatTask | null {
+  const tasks = phase ? tasksForPhase(list, phase) : flattenTasks(list);
   const byKey = new Map<string, FlatTask>();
   for (const t of tasks) {
     byKey.set(t.compositeKey, t);

package/src/core/gates.ts

@@ -336,11 +336,25 @@ async function checkFeatureCriteria({ targetDir }: Ctx): Promise<CheckResult> {
     : fail("feature-criteria", `features without criteria: ${missing.join(", ")}`);
 }
 
-/** Every task in the plan must be complete before the phase gate opens. */
-async function checkTasksComplete({ targetDir }: Ctx): Promise<CheckResult> {
+/** Tasks of the phase being checked must be complete, not tasks from other phases.
+ *  When a task has no `phase` it is treated as "build" (backwards compat via effectivePhase).
+ *  The difference between `feature-iterate` (task) and `deliverable-retry` (checklist) phases is now
+ *  that seeded `define`/`plan` tasks are phase-tagged, so BUILD progress ignores them — and a completed BUILD
+ *  does not stall because pending SHIP review tasks exist elsewhere.
+ */
+async function checkTasksComplete({ targetDir, config }: Ctx): Promise<CheckResult> {
   const { list } = loadFeatureList(targetDir);
-  const p = computeProgress(list);
-  if (p.tasksTotal === 0) return fail("tasks-complete", "no tasks planned");
+  const p = computeProgress(list, config.currentPhase as string | null);
+  if (p.tasksTotal === 0) {
+    // Un-tagged builds with no effective BUILD task yet (only define/plan tasks seeded) are not gated on tasks.
+    // Once BUILD has tasks, they must all complete. This preserves mkSatisfiableProject converge walk.
+    const global = computeProgress(list);
+    const buildScoped = computeProgress(list, "build");
+    if (config.currentPhase === "build" && global.tasksTotal > 0 && buildScoped.tasksTotal === 0) {
+      return pass("tasks-complete", `${global.tasksDone}/${global.tasksTotal} tasks (no build tasks yet, gated on other phases)`);
+    }
+    return fail("tasks-complete", "no tasks planned");
+  }
   if (p.tasksDone === p.tasksTotal) return pass("tasks-complete", `${p.tasksDone}/${p.tasksTotal} tasks complete`);
   const remaining = p.tasksTotal - p.tasksDone;
   return fail(

package/src/core/init.ts

@@ -160,6 +160,7 @@ export type InitOptions = {
   display?: HarnessConfig["display"];
   /** Session-handoff policy. Defaults to a fresh session per phase. */
   session?: Partial<HarnessConfig["session"]>;
+  execution?: Partial<HarnessConfig["execution"]>;
   /** What the human said they want built. Recorded, and read by the first brief. */
   brief?: string | null;
   /** Model routing for difficulty tiers and consulting. */
@@ -220,6 +221,7 @@ 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 ?? {}) };
+  config.execution = { ...config.execution, ...stripUndefined(options.execution ?? {}) };
   // 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

package/src/core/phases.ts

@@ -11,6 +11,8 @@ import type { HarnessConfig, Phase } from "./types.ts";
 import { PHASE_ORDER, DEFAULT_ENABLED_PHASES } from "./types.ts";
 import { loadConfig, saveConfig, recordGate, currentRoleFor } from "./config.ts";
 import { gitBranch, gitIsClean, gitHasUpstream, gitLastCommitMessage } from "./exec.ts";
+import { loadFeatureList, saveFeatureList, tasksForPhase } from "./featureList.ts";
+import type { RetryLevel } from "./types.ts";
 
 export { PHASE_ORDER };
 
@@ -125,6 +127,64 @@ export async function transitionPhase(targetDir: string, toPhase: Phase): Promis
   return { ok: true, error: null, config, from, to: toPhase };
 }
 
+/** Starter tasks seeded when a phase has no tasks at all (idempotent, fixes DEFINE rev 0).
+ *
+ * Only phases that are *gated on doc artefacts* get starters. BUILD/VERIFY etc
+ * already have tasks from PLAN; seeding them would pollute BUILD's tasksComplete.
+ */
+export const STARTER_TASKS: Record<string, Array<{ id: string; description: string; difficulty: "easy" | "moderate" | "difficult" }>> = {
+  // Research has its doc gate but no task gate; a doc checklist, not tasks — no seed.
+  define: [
+    { id: "define/d1", description: "Interview scope and write bounded PRD + acceptance criteria", difficulty: "moderate" },
+    { id: "define/d2", description: "Record sprint contract and branch (not main)", difficulty: "easy" },
+  ],
+  plan: [
+    { id: "plan/p1", description: "Break each feature into ordered, dependency-aware tasks", difficulty: "moderate" },
+    { id: "plan/p2", description: "Commit plan (feature-list) and validate", difficulty: "easy" },
+  ],
+};
+
+export function isPhaseDone(dir: string, phase: import("./types.ts").Phase): boolean {
+  const { list } = loadFeatureList(dir);
+  const tasks = tasksForPhase(list, phase);
+  return tasks.length > 0 && tasks.every((t) => t.status === "complete");
+}
+
+export function seedPhaseIfEmpty(dir: string, phase: import("./types.ts").Phase): { seeded: boolean; error: string | null } {
+  const seeded = STARTER_TASKS[phase] ?? [];
+  if (seeded.length === 0) return { seeded: false, error: null };
+  try {
+    const { list } = loadFeatureList(dir);
+    const existing = tasksForPhase(list, phase);
+    if (existing.length > 0) return { seeded: false, error: null };
+    // Append to first feature matching phase, or create a phase feature.
+    const feature = (
+      list.features.find((f) => (f as { phase?: string }).phase === phase) ??
+      list.features[0] ??
+      ({ id: `phase-${phase}`, name: phase.toUpperCase(), tasks: [] } as unknown as typeof list.features[number])
+    );
+    if (!list.features.includes(feature as any)) {
+      (feature as { phase?: string }).phase = phase;
+      list.features.push(feature as any);
+    }
+    for (const t of seeded) {
+      if (feature.tasks.some((x) => x.id === t.id)) continue;
+      feature.tasks.push({
+        id: t.id,
+        description: t.description,
+        status: "pending" as const,
+        phase,
+        difficulty: t.difficulty,
+      } as any);
+    }
+    list.baseRevision = (list.baseRevision ?? 0) + 1;
+    saveFeatureList(dir, list);
+    return { seeded: true, error: null };
+  } catch (e) {
+    return { seeded: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
 /** Advance one step along the enabled pipeline. */
 export async function advancePhase(targetDir: string): Promise<TransitionResult> {
   const { config, ok, error } = loadConfig(targetDir);

package/src/core/settings.ts

@@ -372,6 +372,27 @@ export const SETTINGS: SettingsGroup[] = [
       },
     ],
   },
+  {
+    id: "execution",
+    label: "Execution",
+    help: "How many things run at once, and at which level. Main session only shows progress; workers do the real work.",
+    settings: [
+      {
+        path: "execution.parallelAt",
+        file: "config",
+        label: "Parallel at",
+        help: "off: one at a time · goal: goals in parallel · phase: phases · sprint/feature/task/subtask. Pick one. Finer implies coarser.",
+        type: { kind: "choice", choices: ["off", "goal", "phase", "sprint", "feature", "task", "subtask"] },
+      },
+      {
+        path: "execution.maxWorkers",
+        file: "config",
+        label: "Max workers",
+        help: "How many workers run at once (1-16)._deps must be satisfied; parallelAt limits breadth.",
+        type: { kind: "number", min: 1, max: 16 },
+      },
+    ],
+  },
   {
     id: "commands",
     label: "Project commands",
@@ -473,41 +494,125 @@ export const SETTINGS: SettingsGroup[] = [
   {
     id: "retries",
     label: "Retry budgets",
-    help: "How many attempts a task, feature or phase gets before the run escalates to you.",
+    help: "How many attempts a task, feature or phase gets before the run escalates to you. Levels are the generic ladder: goal → phase → sprint → feature → task → subtask.",
     settings: [
       {
         path: "maxRetries",
         file: "config",
+        label: "Task retries (legacy)",
+        help: "Legacy top-level task budget. Prefer retry.levels.task.maxRetries below.",
+        type: { kind: "number", min: 1, max: 100 },
+      },
+      {
+        path: "retry.levels.goal.enabled",
+        file: "config",
+        label: "Goal retries",
+        help: "Bound whole goal-pass retries (outer loop). Off by default.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "retry.levels.goal.maxRetries",
+        file: "config",
+        label: "Goal max",
+        help: "Attempts per goal when enabled.",
+        type: { kind: "number", min: 1, max: 100 },
+      },
+      {
+        path: "retry.levels.phase.enabled",
+        file: "config",
+        label: "Phase retries",
+        help: "Bound how many times one phase may repeat. Off by default.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "retry.levels.phase.maxRetries",
+        file: "config",
+        label: "Phase max",
+        help: "Attempts per phase when enabled.",
+        type: { kind: "number", min: 1, max: 100 },
+      },
+      {
+        path: "retry.levels.sprint.enabled",
+        file: "config",
+        label: "Sprint retries",
+        help: "Sprint-level retries. Off by default, as sprints are build-exclusive.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "retry.levels.sprint.maxRetries",
+        file: "config",
+        label: "Sprint max",
+        help: "Attempts per sprint when enabled.",
+        type: { kind: "number", min: 1, max: 100 },
+      },
+      {
+        path: "retry.levels.feature.enabled",
+        file: "config",
+        label: "Feature retries",
+        help: "Bound retries per feature. Off by default.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "retry.levels.feature.maxRetries",
+        file: "config",
+        label: "Feature max",
+        help: "Attempts per feature when enabled.",
+        type: { kind: "number", min: 1, max: 100 },
+      },
+      {
+        path: "retry.levels.task.enabled",
+        file: "config",
         label: "Task retries",
-        help: "Attempts per task before the harness stops and asks for help.",
+        help: "The main retry budget, on by default. Subtask goes here too.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "retry.levels.task.maxRetries",
+        file: "config",
+        label: "Task max",
+        help: "Attempts per task. Leave unset to use maxRetries (legacy).",
+        type: { kind: "number", min: 1, max: 100 },
+      },
+      {
+        path: "retry.levels.subtask.enabled",
+        file: "config",
+        label: "Subtask retries",
+        help: "Whether subtasks get their own retry count before escalating to task.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "retry.levels.subtask.maxRetries",
+        file: "config",
+        label: "Subtask max",
+        help: "Attempts per subtask when enabled.",
         type: { kind: "number", min: 1, max: 100 },
       },
       {
         path: "retry.features.enabled",
         file: "config",
-        label: "Feature retry budget",
-        help: "Also bound retries per feature, not just per task.",
+        label: "(legacy) Feature retry",
+        help: "Legacy per-feature switch. Mirrors retry.levels.feature.enabled.",
         type: { kind: "boolean" },
       },
       {
         path: "retry.features.maxRetries",
         file: "config",
-        label: "Feature retries",
-        help: "Attempts per feature when the budget above is enabled.",
+        label: "(legacy) Feature max",
+        help: "Legacy feature budget value.",
         type: { kind: "number", min: 1, max: 100 },
       },
       {
         path: "retry.phases.enabled",
         file: "config",
-        label: "Phase retry budget",
-        help: "Also bound how many times one phase may repeat.",
+        label: "(legacy) Phase retry",
+        help: "Legacy per-phase switch. Mirrors retry.levels.phase.enabled.",
         type: { kind: "boolean" },
       },
       {
         path: "retry.phases.maxRetries",
         file: "config",
-        label: "Phase retries",
-        help: "Attempts per phase when the budget above is enabled.",
+        label: "(legacy) Phase max",
+        help: "Legacy phase budget value.",
         type: { kind: "number", min: 1, max: 100 },
       },
     ],

package/src/core/types.ts

@@ -88,6 +88,8 @@ export type Task = {
   key?: string;
   description: string;
   status: TaskStatus;
+  /** Which pipeline phase this task belongs to. Absent means `build` for backwards compat. */
+  phase?: Phase;
   dependsOn?: string[];
   subtasks?: Subtask[];
   difficulty?: Difficulty;
@@ -102,6 +104,7 @@ export type Feature = {
   name: string;
   description?: string;
   passes?: boolean;
+  phase?: Phase;
   sprintId?: string;
   goalId?: string;
   criteria?: string[];
@@ -148,6 +151,10 @@ export type RetryBucket = {
   maxRetries: number | null;
 };
 
+/** Levels that can each have their own retry budget and escalation state. */
+export const RETRY_LEVELS = ["goal", "phase", "sprint", "feature", "task", "subtask"] as const;
+export type RetryLevel = (typeof RETRY_LEVELS)[number];
+
 /**
  * How the run divides itself into pi sessions.
  *
@@ -160,6 +167,13 @@ export type RetryBucket = {
  */
 export type HandoffGranularity = "off" | "goal" | "phase" | "sprint" | "feature" | "task" | "subtask";
 
+export type ExecutionPolicy = {
+  /** Level at which parallel work is allowed. `off` = one task at a time. */
+  parallelAt: HandoffGranularity;
+  /** Max parallel workers (1..16). Guarded by lock and budget. */
+  maxWorkers: number;
+};
+
 export type SessionPolicy = {
   /**
    * When to hand off to a fresh session.
@@ -274,6 +288,7 @@ export type HarnessConfig = {
   phases: { enabled: Phase[] };
   roles: { strict: boolean };
   session: SessionPolicy;
+  execution: ExecutionPolicy;
   /** Legacy: the three-phase approval switch 2.3 shipped. Migrated to `phaseModes`. */
   approvals: ApprovalPolicy;
   /** Mode per phase — the setting `approvals` became. */
@@ -294,12 +309,16 @@ export type HarnessConfig = {
     tasks: RetryBucket;
     features: RetryBucket;
     phases: RetryBucket;
+    /** New per-level budgets keyed by RetryLevel. Legacy fields remain for compat. */
+    levels: Partial<Record<RetryLevel, RetryBucket>>;
   };
   maxRetries: number;
   retryCount: number;
   taskRetryCount: number;
   featureRetryCount: number;
   phaseRetryCount: number;
+  /** Fine-grained counters per RetryLevel; zeroed on success at that level. */
+  retryPerLevel: Partial<Record<RetryLevel, number>>;
   pipelineIteration: number;
   gateHistory: GateHistoryEntry[];
   [k: string]: unknown;

package/src/escalate.ts

@@ -66,6 +66,8 @@ export type EscalateOptions = {
   targetDir: string;
   runId: string;
   phase: Phase;
+  /** active retry level: subtask -> task -> ... -> goal; empty means "task" */
+  level?: string;
   /** The gate's failing checks, so the instruction can name them. */
   failures: string[];
   /** Whether the working tree moved since the last attempt. */
@@ -188,16 +190,28 @@ export async function escalate(options: EscalateOptions): Promise<Escalation> {
 
     case "consult": {
       const model = choice.nextModel ?? null;
+      const lvl = options.level ?? "task";
+      let thinkingHint: string | null = null;
+      try {
+        const { consultNextWithThinking, DIFFICULTY_LADDER } = await import("./modelRouter.ts");
+        const cur = (task?.difficulty ?? null) as string | null;
+        const idx = (DIFFICULTY_LADDER as readonly string[]).indexOf(cur ?? "");
+        const nextDiff = idx >= 0 && idx < (DIFFICULTY_LADDER.length as number) - 1 ? (DIFFICULTY_LADDER as readonly string[])[idx + 1] as string : null;
+        const picked = consultNextWithThinking(cur as string | null, { projectDir: targetDir, consultedCount: state.consultedCount });
+        void picked; void nextDiff;
+        thinkingHint = null; // keep instruction lean; spawned worker resolves thinking from router
+      } catch {}
       return {
         strategy: "consult",
-        reason: choice.reason,
+        reason: `${choice.reason} [${lvl}]`,
         instruction:
-          `ESCALATE. Reframing did not shift this either, so it is going to a stronger model` +
+          `ESCALATE [${lvl}]. Reframing did not shift this either, so it is going to a stronger model` +
           (model ? `: ${model}` : "") +
+          (thinkingHint ? ` (thinking: ${thinkingHint})` : "") +
           `. Write down, precisely, what you have tried and what the failure actually says — ` +
           `that hand-off is the whole value of the escalation.\n\nStill failing:\n${failureList}`,
         model,
-        applied: model ? `consulting ${model}` : null,
+        applied: model ? `consulting ${model} [${lvl}]` : `consult [${lvl}]`,
         next: carry("consult", { consultedCount: state.consultedCount + 1 }),
       };
     }