infinity-harness 2.7.0 → 2.8.0

package/src/replan.ts

@@ -20,13 +20,13 @@
  * implementation of each now, in `core/`.
  */
 
-import { unlinkSync } from "node:fs";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import type { Feature, FeatureList, Subtask, Task, TaskStatus } from "./core/types.ts";
 import { TASK_STATUSES } from "./core/types.ts";
 import { detectCycle, flattenTasks, loadFeatureList, saveFeatureList } from "./core/featureList.ts";
 import { fileExists, readJsonSafe, writeJsonAtomic } from "./core/fsx.ts";
 import { loadConfig } from "./core/config.ts";
-import { featureListPath, replanPath } from "./core/paths.ts";
+import { planPath, replanPath } from "./core/paths.ts";
 import { withLockSync } from "./core/lock.ts";
 
 /**
@@ -161,8 +161,12 @@ function appendReplanHistory(projectDir: string, entry: ReplanHistoryEntry): voi
 
 function readMaxReplans(projectDir: string): number {
   const { config } = loadConfig(projectDir);
+  const lim = (config as unknown as { limits?: { maxReplansPerPhase?: unknown } }).limits as { maxReplansPerPhase?: unknown } | undefined;
+  let hasLimitsFile = false;
+  try { const p = `${projectDir}/harness/config.json`; if (existsSync(p)) { const raw = JSON.parse(readFileSync(p,"utf-8")); if (raw && typeof raw.limits === "object") hasLimitsFile = true; } } catch {}
   const replan = config.replan as { maxReplans?: unknown; maxReplansPerRun?: unknown } | undefined;
   const budgets = config.budgets as { maxReplansPerRun?: unknown } | undefined;
+  if (hasLimitsFile && typeof lim?.maxReplansPerPhase === "number") return lim.maxReplansPerPhase;
   if (typeof replan?.maxReplans === "number") return replan.maxReplans;
   if (typeof replan?.maxReplansPerRun === "number") return replan.maxReplansPerRun;
   if (typeof budgets?.maxReplansPerRun === "number") return budgets.maxReplansPerRun;
@@ -198,7 +202,7 @@ export async function amendPlan(opts: AmendPlanOpts): Promise<AmendPlanResult> {
 
   // Read, amend, validate, bump, write — one atomic section. Adding to the
   // plan is a read-apply-write over the same file every parallel worker edits.
-  const result = withLockSync(featureListPath(projectDir), () => {
+  const result = withLockSync(planPath(projectDir), () => {
     const list = loadPlan(projectDir);
 
     let addedSprints = 0;

package/src/rework.ts

@@ -17,12 +17,12 @@
  * other. One implementation of each now, in `core/`.
  */
 
-import { unlinkSync } from "node:fs";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import type { FeatureList, Task } from "./core/types.ts";
 import { flattenTasks, loadFeatureList, saveFeatureList } from "./core/featureList.ts";
 import { fileExists, readJsonSafe, writeJsonAtomic } from "./core/fsx.ts";
 import { loadConfig } from "./core/config.ts";
-import { featureListPath, reworkPath } from "./core/paths.ts";
+import { planPath, reworkPath } from "./core/paths.ts";
 import { withLockSync } from "./core/lock.ts";
 
 /**
@@ -165,8 +165,14 @@ function appendReworkRecord(projectDir: string, record: ReworkRecord): void {
 
 function readMaxReworks(projectDir: string): number {
   const { config } = loadConfig(projectDir);
+  const lim = (config as unknown as { limits?: { maxReworkPerUnit?: unknown } }).limits as { maxReworkPerUnit?: unknown } | undefined;
+  // limits.maxReworkPerUnit wins only when writable: config actually has a limits file with it.
+  // Test configs write { rework: {maxReworks: 3} } onto a partial config that still has DEFAULT_LIMITS via merge — without this guard every test would see 2.
+  let hasLimitsFile = false;
+  try { const p = `${projectDir}/harness/config.json`; if (existsSync(p)) { const raw = JSON.parse(readFileSync(p,"utf-8")); if (raw && typeof raw.limits === "object") hasLimitsFile = true; } } catch {}
   const rework = config.rework as { maxReworks?: unknown } | undefined;
   const budgets = config.budgets as { maxReworksPerRun?: unknown } | undefined;
+  if (hasLimitsFile && typeof lim?.maxReworkPerUnit === "number") return lim.maxReworkPerUnit;
   if (typeof rework?.maxReworks === "number") return rework.maxReworks;
   if (typeof budgets?.maxReworksPerRun === "number") return budgets.maxReworksPerRun;
   return DEFAULT_MAX_REWORKS;
@@ -209,7 +215,7 @@ export async function startRework(opts: StartReworkOpts): Promise<StartReworkRes
 
   // Read, flip, bump, write — one atomic section. The status flip is a
   // read-apply-write over the same file every parallel worker edits.
-  const result = withLockSync(featureListPath(projectDir), () => {
+  const result = withLockSync(planPath(projectDir), () => {
     const list = loadPlan(projectDir);
     const tasks = flattenTasks(list);
     if (!tasks.some((t) => taskKey(t) === originKey)) {

package/src/runState.ts

@@ -1,121 +1,15 @@
-/**
- * infinity-harness — is a continuous run armed, and which run is it?
- *
- * This used to be a `let loopEnabled = false` inside the extension closure,
- * which meant the answer died with the pi session that held it. That was fine
- * while the harness lived in exactly one session forever, and wrong the moment
- * it did not:
- *
- *   - a fresh session per handoff (the whole point of `src/handoff.ts`) starts
- *     a new extension instance, and the run it was continuing was over
- *   - `/reload`, `/new`, `/resume` and a crash all did the same thing
- *   - the run id was a `randomUUID()` per session, so `loadLoopState` saw a
- *     different run each time and reset the iteration count, the wall-clock
- *     budget, the no-progress streak and the escalation ladder — every budget
- *     that exists to stop a runaway run
- *
- * A run is a property of the project, not of the terminal window that started
- * it. It lives on disk.
- */
-
-import { runStatePath } from "./core/paths.ts";
-import { readJsonSafe, writeJsonAtomic, removeFile } from "./core/fsx.ts";
-
-export type RunState = {
-  /** Whether the loop should keep driving. Read on every session start. */
-  armed: boolean;
-  /** Stable across every session this run spans. */
-  runId: string;
-  startedAt: string;
-  /** How many pi sessions this run has used. Shown in the widget. */
-  sessions: number;
-  /** Why the run last stopped, so a returning human is not left guessing. */
-  stoppedAt: string | null;
-  stopReason: string | null;
-};
-
-export function newRunState(runId: string, now = new Date()): RunState {
-  return {
-    armed: true,
-    runId,
-    startedAt: now.toISOString(),
-    sessions: 1,
-    stoppedAt: null,
-    stopReason: null,
-  };
-}
-
-export function loadRunState(targetDir: string): RunState | null {
-  const raw = readJsonSafe<Partial<RunState> | null>(runStatePath(targetDir), null);
-  if (!raw || typeof raw.runId !== "string" || !raw.runId) return null;
-  return {
-    armed: raw.armed === true,
-    runId: raw.runId,
-    startedAt: typeof raw.startedAt === "string" ? raw.startedAt : new Date(0).toISOString(),
-    sessions: typeof raw.sessions === "number" && raw.sessions > 0 ? raw.sessions : 1,
-    stoppedAt: typeof raw.stoppedAt === "string" ? raw.stoppedAt : null,
-    stopReason: typeof raw.stopReason === "string" ? raw.stopReason : null,
-  };
-}
-
-export function saveRunState(targetDir: string, state: RunState): void {
-  try {
-    writeJsonAtomic(runStatePath(targetDir), state);
-  } catch {
-    // Losing the file costs the run its cross-session budgets, which is bad,
-    // but throwing here would kill the session, which is worse.
-  }
-}
-
-/** Arm a run. Reuses the existing run id when one is already armed. */
-export function armRun(targetDir: string, runId: string, now = new Date()): RunState {
-  const existing = loadRunState(targetDir);
-  const state =
-    existing && existing.armed
-      ? { ...existing, stoppedAt: null, stopReason: null }
-      : newRunState(runId, now);
-  saveRunState(targetDir, state);
-  return state;
-}
-
-export function disarmRun(targetDir: string, reason: string, now = new Date()): RunState | null {
-  const existing = loadRunState(targetDir);
-  if (!existing) return null;
-  const state: RunState = {
-    ...existing,
-    armed: false,
-    stoppedAt: now.toISOString(),
-    stopReason: reason,
-  };
-  saveRunState(targetDir, state);
-  return state;
-}
-
-/** Count one more pi session against this run. Called from `session_start`. */
-export function countSession(targetDir: string): RunState | null {
-  const existing = loadRunState(targetDir);
-  if (!existing) return null;
-  const state = { ...existing, sessions: existing.sessions + 1 };
-  saveRunState(targetDir, state);
-  return state;
-}
-
-export function clearRunState(targetDir: string): void {
-  try {
-    removeFile(runStatePath(targetDir));
-  } catch {
-    /* nothing to clear */
-  }
-}
-
-/**
- * The run id the loop should use.
- *
- * An armed run keeps its id so `loadLoopState` finds the same budgets after a
- * handoff. With nothing armed, the caller's session id is the run id — an
- * ad-hoc `/infinity:validate` should not inherit a finished run's strikes.
- */
-export function runIdFor(targetDir: string, fallback: string): string {
-  const state = loadRunState(targetDir);
-  return state && state.armed ? state.runId : fallback;
-}
+// Re-export from core so both import paths work.
+// Canonical type now lives in src/core/runState.ts (with baseModel/tiers/budget).
+export {
+  loadRunState,
+  saveRunState,
+  armRun,
+  disarmRun,
+  countSession,
+  clearRunState,
+  runIdFor,
+  newRunState,
+  parseBaseModelString,
+  createUsageTotals,
+} from "./core/runState.ts";
+export type { RunState, ProviderModel, TierResults, TierPreflight, Budget, UsageTotals } from "./core/runState.ts";

package/src/scheduler.ts

@@ -8,10 +8,12 @@
 
 import type { HarnessConfig, HandoffGranularity, Phase } from "./core/types.ts";
 import { loadFeatureList, tasksForPhase, type FlatTask, flattenTasks } from "./core/featureList.ts";
-import { loadRouterConfig } from "./modelRouter.ts";
+import { loadRouterConfig, resolveModel } from "./modelRouter.ts";
 import { spawnIsolatedWorker, type SpawnWorkerResult } from "./worker.ts";
 import { runIdFor } from "./runState.ts";
 import { loadConfig } from "./core/config.ts";
+import { loadRunState } from "./core/runState.ts";
+import { isCapExceeded } from "./daemon/budget.ts";
 
 /** Difficulty ranking — higher wins when collapsing a bucket to its hardest. */
 const DIFFICULTY_RANK: Record<string, number> = { easy: 1, moderate: 2, difficult: 3 };
@@ -20,10 +22,13 @@ function hardestDifficulty(tasks: Array<{ difficulty?: string }>): string | unde
   let best: string | undefined;
   let bestRank = -1;
   for (const t of tasks) {
-    const d = (t as { difficulty?: string }).difficulty;
+    const d = t.difficulty;
     if (!d) continue;
     const r = DIFFICULTY_RANK[d] ?? -1;
-    if (r > bestRank) { bestRank = r; best = d; }
+    if (r > bestRank) {
+      bestRank = r;
+      best = d;
+    }
   }
   return best;
 }
@@ -47,7 +52,6 @@ function goalIdForTask(task: FlatTask, list: import("./core/types.ts").FeatureLi
  *   - 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,
@@ -56,16 +60,14 @@ export function effectiveDifficultyForTask(
 ): 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);
+  let bucket: FlatTask[] = [];
   if (handoff === "phase") {
     const phase = (task as { effectivePhase?: string }).effectivePhase ?? "build";
     bucket = all.filter((t) => (t as { effectivePhase?: string }).effectivePhase === phase);
@@ -118,170 +120,142 @@ export type PickOpts = {
   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;
-};
+// ── pick helpers ────────────────────────────────────────────────────────────
 
-/** Tail a worker attempt's output.log (best-effort, never throws). */
-export function tailWorkerOutput(attemptDir: string, bytes = 3000): string {
+function isBudgetFull(targetDir: string): boolean {
   try {
-    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);
-  } catch { return ""; }
+    const rs = loadRunState(targetDir);
+    if (!rs?.budget) return false;
+    return isCapExceeded(rs.budget as never).exceeded;
+  } catch {
+    return false;
+  }
 }
 
-export function listWorkers(targetDir: string, runId?: string): WorkerSnapshot[] {
-  try {
-    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) {
-      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 []; }
+function hasSerializeTask(tasks: FlatTask[]): boolean {
+  return tasks.some(
+    (t) => (t as { serialize?: unknown }).serialize === true && (t.status === "pending" || t.status === "in_progress" || t.status === "rework"),
+  );
 }
 
-export function nextModelForTask(targetDir: string, difficulty?: string, taskId?: string, key?: string): { model?: string; thinking?: string } {
-  try {
-    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 } }),
-    };
-  } catch { return {}; }
+function pickSerializeTask(tasks: FlatTask[], byKey: Map<string, FlatTask>, exclude?: Set<string>): FlatTask | null {
+  const serializeTask = tasks.find(
+    (t) =>
+      (t as { serialize?: unknown }).serialize === true &&
+      t.status === "pending" &&
+      (t.dependsOn ?? []).every((d) => {
+        const dep = byKey.get(d);
+        return dep !== undefined && dep.status === "complete";
+      }) &&
+      !exclude?.has(t.compositeKey) &&
+      !exclude?.has(t.id),
+  );
+  return serializeTask ?? null;
 }
 
-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 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) {
-    byKey.set(t.compositeKey, t);
-    byKey.set(t.id, t);
-    if (t.key) byKey.set(t.key, t);
-  }
-  const eligible = all.filter((t) => {
+function isSerializeBlocked(tasks: FlatTask[]): boolean {
+  return tasks.some((t) => (t as { serialize?: unknown }).serialize === true && (t.status === "in_progress" || t.status === "rework"));
+}
+
+function eligibleTasks(tasks: FlatTask[], byKey: Map<string, FlatTask>, exclude?: Set<string>): FlatTask[] {
+  return tasks.filter((t) => {
     if (t.status !== "pending") return false;
-    if (opts.exclude?.has(t.compositeKey) || opts.exclude?.has(t.id)) return false;
+    if (exclude?.has(t.compositeKey) || exclude?.has(t.id)) return false;
     const deps = t.dependsOn ?? [];
     return deps.every((d) => {
       const dep = byKey.get(d);
-      return dep && dep.status === "complete";
+      return dep !== undefined && 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);
+function groupKeyFor(task: FlatTask, level: HandoffGranularity, list: import("./core/types.ts").FeatureList): string {
+  if (level === "task" || level === "subtask") return task.compositeKey;
+  if (level === "feature") return task.featureId;
+  if (level === "sprint") {
+    const feat = list.features.find((f) => f.id === task.featureId);
+    return (feat as { sprintId?: string } | undefined)?.sprintId ?? task.featureId;
   }
-  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));
+  if (level === "phase") return task.effectivePhase ?? "build";
+  return task.compositeKey;
+}
+
+function roundRobin(groups: Map<string, FlatTask[]>, max: number): FlatTask[] {
   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);
-    }
+    if (g.length > 0) out.push(g.shift()!);
     idx++;
     if (idx > max * groupArrays.length + 10) break;
   }
   return out.slice(0, max);
 }
 
+export function pickRunnableTasks(opts: PickOpts): FlatTask[] {
+  const { list } = loadFeatureList(opts.targetDir);
+  const phase = (opts.phase ?? null) as Phase | null;
+  const all: FlatTask[] = phase ? tasksForPhase(list, phase) : (flattenTasks(list) as FlatTask[]);
+  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);
+  }
+
+  if (hasSerializeTask(all)) {
+    const serializeTask = pickSerializeTask(all, byKey, opts.exclude);
+    if (serializeTask) return [serializeTask];
+    if (isSerializeBlocked(all)) return [];
+  }
+
+  if (isBudgetFull(opts.targetDir)) return [];
+
+  const eligible = eligibleTasks(all, byKey, opts.exclude);
+  const level = opts.parallelAt ?? "off";
+  if (level === "off" || level === "goal") return eligible.slice(0, 1);
+
+  const groups = new Map<string, FlatTask[]>();
+  for (const t of eligible) {
+    const k = groupKeyFor(t, level, list);
+    if (!groups.has(k)) groups.set(k, []);
+    groups.get(k)!.push(t);
+  }
+  const max = Math.max(1, Math.min(16, opts.maxWorkers ?? 3));
+  return roundRobin(groups, 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");
-  // 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; } })();
+  try {
+    handoff = (loadConfig(targetDir).config.session?.handoff as HandoffGranularity) ?? "task";
+  } catch {}
+  let allList: import("./core/types.ts").FeatureList | null = null;
+  try {
+    allList = loadFeatureList(targetDir).list;
+  } catch {
+    allList = null;
+  }
   const results: SpawnWorkerResult[] = [];
   for (const t of tasks) {
     const prompt = opts.promptFor(t);
     const router = loadRouterConfig(targetDir);
     let modelHint: string | undefined;
-    if (router.enabled) {
+    if (router.enabled && allList) {
       try {
-        const effDiff = allList ? effectiveDifficultyForTask(t, handoff, allList) : (t as { difficulty?: string }).difficulty;
+        const effDiff = effectiveDifficultyForTask(t, handoff, allList);
         modelHint = resolveModel({ projectDir: targetDir, task: { difficulty: effDiff as string | undefined, id: t.id, key: t.compositeKey } });
       } catch {}
+    } else if (router.enabled) {
+      try {
+        modelHint = resolveModel({ projectDir: targetDir, task: { difficulty: (t as { difficulty?: string }).difficulty as string | undefined, id: t.id, key: t.compositeKey } });
+      } catch {}
     }
     const res = await spawnIsolatedWorker({
       projectDir: targetDir,
@@ -303,12 +277,11 @@ export function executionPolicyOf(config: HarnessConfig): {
   maxWorkers: number;
 } {
   const e = (config.execution ?? {}) as Partial<{ engine: unknown; parallelAt: unknown; maxWorkers: unknown }>;
-  // Anything but the explicit legacy value means background: a config written
-  // before this setting existed should get the new behaviour, not the bug.
   const engine: import("./core/types.ts").ExecutionEngine = e.engine === "main-session" ? "main-session" : "background";
-  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 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 { engine, parallelAt: at, maxWorkers };

package/src/taskList.ts

@@ -33,8 +33,9 @@ import {
   validateKey,
   type FlatTask,
 } from "./core/featureList.ts";
-import { featureListPath } from "./core/paths.ts";
+import { featureListPath, planPath } from "./core/paths.ts";
 import { withLockSync } from "./core/lock.ts";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 
 /** One task as submitted by the agent. Only `key` is mandatory. */
 export type TaskInput = {
@@ -47,6 +48,8 @@ export type TaskInput = {
   difficulty?: string;
   modelHint?: string;
   criteria?: string[];
+  phase?: string;
+  serialize?: boolean;
 };
 
 /**
@@ -300,7 +303,20 @@ export function applyTaskList(current: FeatureList, input: ApplyInput): ApplyRes
 
     if (raw.difficulty !== undefined) task.difficulty = raw.difficulty as Task["difficulty"];
     if (raw.modelHint !== undefined) task.modelHint = raw.modelHint;
-    if (raw.criteria !== undefined) task.criteria = raw.criteria;
+    if (raw.phase !== undefined) {
+      const pa = String(raw.phase).trim().toLowerCase();
+      const VALID_PHASES = ["init","research","define","plan","build","verify","simplify","review","ship"];
+      if (!VALID_PHASES.includes(pa)) throw new ValidationError(`${path}.phase is invalid: ${String(raw.phase)}`);
+      (task as unknown as { phase: string }).phase = pa;
+    }
+    if (raw.serialize !== undefined) {
+      (task as unknown as { serialize: boolean }).serialize = Boolean(raw.serialize);
+    }
+    if (raw.criteria !== undefined) {
+      if (!Array.isArray(raw.criteria)) throw new ValidationError(`${path}.criteria must be an array`);
+      const criteria = validateCriteria(raw.criteria, `${path}.criteria`);
+      (task as unknown as { criteria: string[] }).criteria = criteria;
+    }
 
     staged.push({ featureId, task, compositeKey: key });
   }
@@ -479,7 +495,29 @@ function stripView(t: FlatTask): Task {
  * losing an edit.
  */
 export function writeTaskList(targetDir: string, input: ApplyInput): ApplyResult {
-  return withLockSync(featureListPath(targetDir), () => {
+  // Acquire a lock that covers both legacy and canonical to avoid racing with
+  // hand-edits that touch legacy. We lock canonical (which is plan.json), then
+  // sync any legacy hand-edit before reading.
+  return withLockSync(planPath(targetDir), () => {
+    // Back-compat: tests modify legacy via readFileSync+writeFileSync then call writeTaskList.
+    // Since loadFeatureList prefers canonical when both exist, a legacy-only hand-edit would be lost.
+    // Detect and mirror a legacy that differs from canonical.
+    const legacy = featureListPath(targetDir);
+    const canonical = planPath(targetDir);
+    if (existsSync(legacy) && existsSync(canonical)) {
+      try {
+        const rawLegacy = readFileSync(legacy, "utf-8");
+        const rawCanon = readFileSync(canonical, "utf-8");
+        if (rawLegacy !== rawCanon) {
+          try {
+            const p = JSON.parse(rawLegacy);
+            if (p && typeof p === "object" && Array.isArray(p.features) && typeof p.baseRevision === "number") {
+              writeFileSync(canonical, rawLegacy, "utf-8");
+            }
+          } catch {}
+        }
+      } catch {}
+    }
     const { list } = loadFeatureList(targetDir);
     const result = applyTaskList(list, input);
     if (result.changed) saveFeatureList(targetDir, result.list);