projectinator 0.3.0 → 0.4.0

package/src/models.ts

@@ -1,175 +0,0 @@
-// Model pricing table. Rates USD per 1,000,000 tokens — copied verbatim from Pi's
-// bundled catalog (pi-coding-agent 0.85.1, Sept 2026); test/executor.test.ts pins every
-// entry against it. Shape mirrors Pi's models.json `cost` block.
-
-import type { Model } from "./types.js";
-import { findOpenRouterModel } from "./openrouter.js";
-
-export const MODELS: Record<string, Model> = {
-  // ---- OpenAI: GPT-5.6 family (prices cut Sept 2026; past 272k input costs 2x) ----
-  "gpt-5.6-sol": {
-    id: "gpt-5.6-sol",
-    provider: "openai",
-    name: "GPT-5.6 Sol",
-    contextWindow: 272_000,
-    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5, tiers: [{ inputTokensAbove: 272_000, input: 8, output: 30, cacheRead: 0.8, cacheWrite: 10 }] },
-  },
-  "gpt-5.6-terra": {
-    id: "gpt-5.6-terra",
-    provider: "openai",
-    name: "GPT-5.6 Terra",
-    contextWindow: 272_000,
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5, tiers: [{ inputTokensAbove: 272_000, input: 4, output: 18, cacheRead: 0.4, cacheWrite: 5 }] },
-  },
-  "gpt-5.6-luna": {
-    id: "gpt-5.6-luna",
-    provider: "openai",
-    name: "GPT-5.6 Luna",
-    contextWindow: 272_000,
-    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25, tiers: [{ inputTokensAbove: 272_000, input: 0.4, output: 1.8, cacheRead: 0.04, cacheWrite: 0.5 }] },
-  },
-
-  // ---- Anthropic: Claude ----
-  "claude-fable-5-1": {
-    id: "claude-fable-5-1",
-    provider: "anthropic",
-    name: "Claude Fable 5.1",
-    contextWindow: 1_000_000,
-    cost: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
-  },
-  "claude-fable-5": {
-    id: "claude-fable-5",
-    provider: "anthropic",
-    name: "Claude Fable 5",
-    contextWindow: 1_000_000,
-    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
-  },
-  "claude-opus-5": {
-    id: "claude-opus-5",
-    provider: "anthropic",
-    name: "Claude Opus 5",
-    contextWindow: 1_000_000,
-    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-  },
-  "claude-opus-4-8": {
-    id: "claude-opus-4-8",
-    provider: "anthropic",
-    name: "Claude Opus 4.8",
-    contextWindow: 1_000_000,
-    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-  },
-  "claude-sonnet-5": {
-    id: "claude-sonnet-5",
-    provider: "anthropic",
-    name: "Claude Sonnet 5",
-    contextWindow: 1_000_000,
-    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
-  },
-  "claude-sonnet-4-6": {
-    id: "claude-sonnet-4-6",
-    provider: "anthropic",
-    name: "Claude Sonnet 4.6",
-    contextWindow: 1_000_000,
-    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-  },
-  "claude-haiku-4-5": {
-    id: "claude-haiku-4-5",
-    provider: "anthropic",
-    name: "Claude Haiku 4.5",
-    contextWindow: 200_000,
-    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
-  },
-
-  // ---- Google: Gemini ----
-  // NOTE: ids match Pi's built-in registry exactly (provider "google"), so they
-  // resolve directly via ModelRegistry.find() with no alias layer.
-  "gemini-3.1-pro-preview": {
-    id: "gemini-3.1-pro-preview",
-    provider: "google",
-    name: "Gemini 3.1 Pro",
-    contextWindow: 1_000_000,
-    cost: {
-      input: 2,
-      output: 12,
-      cacheRead: 0.2,
-      cacheWrite: 2.5,
-      // Google charges more past 200k input tokens.
-      tiers: [{ inputTokensAbove: 200_000, input: 4, output: 18, cacheRead: 0.4, cacheWrite: 5 }],
-    },
-  },
-  "gemini-3.8-flash": {
-    id: "gemini-3.8-flash",
-    provider: "google",
-    name: "Gemini 3.8 Flash",
-    contextWindow: 1_000_000,
-    cost: { input: 0.75, output: 3.75, cacheRead: 0.075 },
-  },
-  "gemini-3-flash-preview": {
-    id: "gemini-3-flash-preview",
-    provider: "google",
-    name: "Gemini 3 Flash",
-    contextWindow: 1_000_000,
-    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.625 },
-  },
-
-  // ---- OpenRouter (one key → frontier models). ids are Pi's OpenRouter-catalog
-  // slugs (vendor/model). Pricing mirrors the underlying model (OpenRouter passes
-  // it through, ~small margin); ACTUAL cost still comes from Pi per run.
-  "anthropic/claude-opus-5": {
-    id: "anthropic/claude-opus-5",
-    provider: "openrouter",
-    name: "Claude Opus 5 (OpenRouter)",
-    contextWindow: 1_000_000,
-    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-  },
-  "anthropic/claude-opus-4.8": {
-    id: "anthropic/claude-opus-4.8",
-    provider: "openrouter",
-    name: "Claude Opus 4.8 (OpenRouter)",
-    contextWindow: 1_000_000,
-    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-  },
-  "anthropic/claude-sonnet-5": {
-    id: "anthropic/claude-sonnet-5",
-    provider: "openrouter",
-    name: "Claude Sonnet 5 (OpenRouter)",
-    contextWindow: 1_000_000,
-    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
-  },
-  "anthropic/claude-sonnet-4.6": {
-    id: "anthropic/claude-sonnet-4.6",
-    provider: "openrouter",
-    name: "Claude Sonnet 4.6 (OpenRouter)",
-    contextWindow: 1_000_000,
-    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-  },
-  "google/gemini-3.8-flash": {
-    id: "google/gemini-3.8-flash",
-    provider: "openrouter",
-    name: "Gemini 3.8 Flash (OpenRouter)",
-    contextWindow: 1_000_000,
-    cost: { input: 0.75, output: 3.75, cacheRead: 0.075 },
-  },
-  "openai/gpt-5.6-luna": {
-    id: "openai/gpt-5.6-luna",
-    provider: "openrouter",
-    name: "GPT-5.6 Luna (OpenRouter)",
-    contextWindow: 1_050_000,
-    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
-  },
-};
-
-export function getModel(id: string): Model {
-  const m = MODELS[id];
-  if (m) return m;
-  // OpenRouter slugs (vendor/model) aren't in the static table — price them from
-  // the OpenRouter catalog (live cache or Pi's built-in list). Fall back to a
-  // rough estimate so a build never crashes on an unpriced model (actual cost
-  // still comes from Pi per run).
-  if (id.includes("/")) {
-    const or = findOpenRouterModel(id);
-    if (or) return { ...or, provider: "openrouter" };
-    return { id, provider: "openrouter", name: id, contextWindow: 200_000, cost: { input: 1, output: 3, cacheRead: 0.1, cacheWrite: 1.25 } };
-  }
-  throw new Error(`Unknown model id: "${id}". Add it to src/models.ts.`);
-}

package/src/narrate.ts

@@ -1,87 +0,0 @@
-// AI narrative for a build retro. Feeds the data-driven RetroReport to a model
-// and gets back a short "what went well / what to improve" write-up. On-demand
-// (costs a small call) and cached on the build state by the caller.
-
-import {
-  createAgentSession,
-  type AgentSession,
-} from "@earendil-works/pi-coding-agent";
-import type { Backend, Provider } from "./types.js";
-import type { RetroReport } from "./retro.js";
-import { findEntry } from "./registry.js";
-import { piRuntime, resolvePiModel } from "./executor.js"
-import { addSessionCost } from "./session-cost.js";
-
-function lastAssistantText(session: AgentSession): string {
-  const msgs = session.messages as Array<{ role?: string; content?: unknown }>;
-  for (let i = msgs.length - 1; i >= 0; i--) {
-    const m = msgs[i];
-    if (m?.role !== "assistant") continue;
-    const c = m.content;
-    if (typeof c === "string") return c;
-    if (Array.isArray(c)) {
-      return c
-        .map((p: unknown) => (typeof p === "string" ? p : p && typeof p === "object" && "text" in p ? String((p as { text: unknown }).text) : ""))
-        .join("")
-        .trim();
-    }
-  }
-  return "";
-}
-
-/** Compact fact sheet the model reasons over — numbers, not prose. */
-function facts(r: RetroReport): string {
-  const lines = [
-    `Idea: ${r.idea}`,
-    `Status: ${r.status}. Tasks done: ${r.doneCount}/${r.taskCount}.`,
-    `Cost: predicted $${r.estCost.toFixed(2)}, actual $${r.totalCost.toFixed(2)}.`,
-    `Tests: ${r.tests.passed} passed, ${r.tests.failed} failed.`,
-    r.retries.length ? `Rebuilds: ${r.retries.map((x) => `${x.taskId}×${x.rounds}`).join(", ")}.` : "Rebuilds: none.",
-    `Cost by epic: ${r.byEpic.map((e) => `${e.epic} $${e.cost}`).join(", ") || "n/a"}.`,
-    `Cost by model: ${r.byModel.map((m) => `${m.model} $${m.cost} (${m.tasks})`).join(", ") || "n/a"}.`,
-    `Priciest tasks: ${r.topCost.map((t) => `${t.taskId} $${t.cost}`).join(", ") || "n/a"}.`,
-    r.bugs.length
-      ? `Tester flags: ${r.bugs.map((b) => `[${b.severity}] ${b.description}`).slice(0, 6).join("; ")}.`
-      : "Tester flags: none.",
-  ];
-  return lines.join("\n");
-}
-
-const PROMPT = [
-  "You are a pragmatic engineering lead writing a SHORT retro for this build.",
-  "Use the facts below — reference the actual numbers. Do not invent anything.",
-  "Write exactly three sections, terse bullets, under 140 words total:",
-  "**What went well** (2-3 bullets)",
-  "**What to improve** (2-3 bullets)",
-  "**Next time** (one line)",
-  "No preamble, no closing remarks.",
-].join("\n");
-
-export interface NarrateOptions {
-  backend: Backend;
-  modelOverride?: { provider: Provider; model: string };
-}
-
-/** Generate the narrative. Throws on failure (caller shows the error). */
-export async function narrateRetro(report: RetroReport, opts: NarrateOptions): Promise<string> {
-  const runtime = await piRuntime();
-  const { entry } = findEntry("plan", "mid");
-  const pick = opts.modelOverride ?? entry.byBackend[opts.backend];
-  const model = resolvePiModel(runtime, pick.provider, pick.model);
-
-  const { session } = await createAgentSession({
-    model,
-    modelRuntime: runtime,
-    thinkingLevel: "low",
-    noTools: "all",
-  });
-  try {
-    await session.prompt(`${PROMPT}\n\n--- FACTS ---\n${facts(report)}`);
-    const text = lastAssistantText(session);
-    if (!text) throw new Error("The model returned no narrative.");
-    return text;
-  } finally {
-    addSessionCost(session.getSessionStats().cost);
-    session.dispose();
-  }
-}

package/src/openrouter.ts

@@ -1,119 +0,0 @@
-// The OpenRouter model catalog — so users can pick ANY OpenRouter model by name
-// (Kimi, DeepSeek, Qwen, …) instead of typing slugs.
-//
-//  - refreshOpenRouterModels(): live-fetch openrouter.ai/api/v1/models (freshest
-//    names + pricing), cache to disk. Falls back to Pi's built-in OR catalog.
-//  - openRouterModels() / findOpenRouterModel(): SYNC reads (disk cache, else Pi's
-//    built-in list) so cost estimation (getModel) can price any picked model.
-
-import { piRuntime } from "./executor.js";
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import type { Model, ModelCost } from "./types.js";
-
-/** A pickable OpenRouter model: our Model shape minus the provider (always "openrouter"). */
-export type ORModel = Omit<Model, "provider">;
-
-const CACHE = join(homedir(), ".projectinator", "openrouter-models.json");
-
-let builtinMemo: ORModel[] | null = null;
-let diskMemo: ORModel[] | null | undefined; // undefined = not read yet, null = no cache
-
-/** Pi's built-in OpenRouter catalog — offline, names + pricing. Sync read of the memo;
- *  call warmBuiltinOpenRouterModels() once at startup to fill it (Pi's runtime is async). */
-export function builtinOpenRouterModels(): ORModel[] {
-  return builtinMemo ?? [];
-}
-
-/** Load Pi's built-in OpenRouter list into the memo. Safe to call repeatedly. */
-export async function warmBuiltinOpenRouterModels(): Promise<ORModel[]> {
-  if (builtinMemo) return builtinMemo;
-  try {
-    const runtime = await piRuntime();
-    builtinMemo = runtime
-      .getModels("openrouter")
-      .filter((m) => !!m.cost)
-      .map((m) => ({
-        id: m.id,
-        name: m.name ?? m.id,
-        contextWindow: m.contextWindow ?? 200_000,
-        cost: m.cost,
-      }))
-      .sort((a, b) => a.name.localeCompare(b.name));
-  } catch {
-    builtinMemo = [];
-  }
-  return builtinMemo;
-}
-
-function readDiskCache(): ORModel[] | null {
-  if (diskMemo !== undefined) return diskMemo;
-  try {
-    if (existsSync(CACHE)) {
-      const parsed = JSON.parse(readFileSync(CACHE, "utf8")) as { models?: ORModel[] };
-      diskMemo = Array.isArray(parsed.models) && parsed.models.length ? parsed.models : null;
-    } else diskMemo = null;
-  } catch {
-    diskMemo = null;
-  }
-  return diskMemo;
-}
-
-/** The list to show / price against: live-fetched disk cache if present, else Pi's built-in. */
-export function openRouterModels(): ORModel[] {
-  const cached = readDiskCache();
-  return cached && cached.length ? cached : builtinOpenRouterModels();
-}
-
-/** Look up one model's pricing/name by slug (cache first, then built-in). Sync. */
-export function findOpenRouterModel(id: string): ORModel | undefined {
-  return openRouterModels().find((m) => m.id === id) ?? builtinOpenRouterModels().find((m) => m.id === id);
-}
-
-/** Map OpenRouter's API pricing (USD per token, strings) to our per-1M-token cost. */
-function mapApiModel(m: {
-  id: string;
-  name?: string;
-  context_length?: number;
-  pricing?: { prompt?: string; completion?: string; input_cache_read?: string; input_cache_write?: string };
-}): ORModel | null {
-  const p = m.pricing ?? {};
-  const input = Number(p.prompt) * 1e6;
-  const output = Number(p.completion) * 1e6;
-  if (!Number.isFinite(input) || !Number.isFinite(output)) return null;
-  const cacheRead = p.input_cache_read != null ? Number(p.input_cache_read) * 1e6 : input * 0.1;
-  const cacheWrite = p.input_cache_write != null ? Number(p.input_cache_write) * 1e6 : input * 1.25;
-  return {
-    id: m.id,
-    name: m.name ?? m.id,
-    contextWindow: m.context_length ?? 200_000,
-    cost: { input, output, cacheRead, cacheWrite },
-  };
-}
-
-/** Live-fetch the catalog and cache it. Falls back to the current list on any failure. */
-export async function refreshOpenRouterModels(timeoutMs = 8000): Promise<ORModel[]> {
-  const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
-  try {
-    const res = await fetch("https://openrouter.ai/api/v1/models", { signal: ctrl.signal });
-    if (!res.ok) return openRouterModels();
-    const json = (await res.json()) as { data?: Array<Parameters<typeof mapApiModel>[0]> };
-    const list = (json.data ?? []).map(mapApiModel).filter((m): m is ORModel => m !== null)
-      .sort((a, b) => a.name.localeCompare(b.name));
-    if (list.length) {
-      try {
-        mkdirSync(join(homedir(), ".projectinator"), { recursive: true });
-        writeFileSync(CACHE, JSON.stringify({ fetchedAt: Date.now(), models: list }));
-        diskMemo = list;
-      } catch { /* cache write is best-effort */ }
-      return list;
-    }
-    return openRouterModels();
-  } catch {
-    return openRouterModels();
-  } finally {
-    clearTimeout(timer);
-  }
-}

package/src/orchestrator.ts

@@ -1,310 +0,0 @@
-// Phase 4 — the Orchestrator. Runs a whole backlog end to end.
-//
-// - Topologically orders tasks by dependsOn (respects design->code->test->deploy).
-// - Threads handoff context: a task sees the final output of its dependencies.
-// - Runs a Tester -> Developer feedback loop, bounded by maxFeedbackRounds.
-// - Tracks cost and halts on the budget cap.
-//
-// The executor is INJECTED (RoleExecutor), so this entire control flow is testable
-// offline with a fake — no model, no spend. The real Pi executor lives in roles.ts.
-
-import {
-  TaskLimitError,
-  type RegistryEntry,
-  type RoleExecutor,
-  type RoutingPolicy,
-  type Task,
-  type TaskOutcome,
-} from "./types.js";
-import { route } from "./router.js";
-import { REGISTRY } from "./registry.js";
-
-/** Order tasks so every task comes after its dependencies. Throws on a cycle. */
-export function toposort(tasks: Task[]): Task[] {
-  const byId = new Map(tasks.map((t) => [t.id, t]));
-  const state = new Map<string, "visiting" | "done">();
-  const out: Task[] = [];
-
-  const visit = (t: Task, trail: string[]) => {
-    const s = state.get(t.id);
-    if (s === "done") return;
-    if (s === "visiting") {
-      throw new Error(`Dependency cycle: ${[...trail, t.id].join(" -> ")}`);
-    }
-    state.set(t.id, "visiting");
-    for (const dep of t.dependsOn ?? []) {
-      const d = byId.get(dep);
-      if (d) visit(d, [...trail, t.id]); // unknown deps already stripped by normalize
-    }
-    state.set(t.id, "done");
-    out.push(t);
-  };
-
-  for (const t of tasks) visit(t, []);
-  return out;
-}
-
-export interface RunOptions {
-  policy: RoutingPolicy;
-  execute: RoleExecutor;
-  /** Registry to route against. Swap this to lock every role to one provider. */
-  registry?: RegistryEntry[];
-  onProgress?: (event: OrchestratorEvent) => void;
-  /** Prior outcomes to resume from (append-only record). Their tasks are skipped. */
-  seedOutcomes?: TaskOutcome[];
-  /** Called after each task settles, with the full record + running total, for persistence. */
-  onCheckpoint?: (outcomes: TaskOutcome[], totalCost: number) => void;
-  /** Max tasks to run at once. 1 (default) = sequential. >1 runs independent tasks in parallel. */
-  concurrency?: number;
-  /** Optional human gate before development begins (design done → dev). Resolve "stop" to halt. */
-  onGate?: (info: { stage: string }) => Promise<"continue" | "stop">;
-}
-
-export type OrchestratorEvent =
-  | { type: "task_start"; task: Task; round: number; provider: string; modelId: string }
-  | { type: "task_done"; outcome: TaskOutcome; runningTotal: number }
-  | { type: "task_failed"; outcome: TaskOutcome; runningTotal: number }
-  | { type: "task_skipped"; taskId: string }
-  | { type: "test_failed"; taskId: string; bugs: number; round: number }
-  | { type: "retry_dev"; taskId: string; forTest: string; round: number }
-  | { type: "budget_halt"; runningTotal: number; cap: number }
-  | { type: "gate"; stage: string }
-  | { type: "cycle_or_error"; message: string };
-
-export interface RunResult {
-  outcomes: TaskOutcome[];
-  totalCost: number;
-  halted: boolean;
-  haltReason?: string;
-}
-
-/** Build handoff text from a task's dependency outcomes. */
-function gatherContext(task: Task, outcomes: Map<string, TaskOutcome>): string {
-  const deps = task.dependsOn ?? [];
-  if (deps.length === 0) return "";
-  const parts: string[] = [];
-  for (const depId of deps) {
-    const o = outcomes.get(depId);
-    if (!o) continue;
-    const snippet = o.finalText.trim();
-    if (snippet) parts.push(`### From ${depId} (${o.capability}):\n${snippet}`);
-    if (o.files.length) parts.push(`### Files from ${depId}: ${o.files.join(", ")}`);
-  }
-  return parts.length ? `Context from upstream work:\n\n${parts.join("\n\n")}` : "";
-}
-
-function bugReport(bugs: { severity: string; description: string; file?: string }[]): string {
-  return [
-    "The tester found these issues. Fix them, then stop:",
-    ...bugs.map((b) => `- [${b.severity}]${b.file ? ` (${b.file})` : ""} ${b.description}`),
-  ].join("\n");
-}
-
-export async function runBacklog(tasks: Task[], opts: RunOptions): Promise<RunResult> {
-  const { policy, execute } = opts;
-  const registry = opts.registry ?? REGISTRY;
-  const byId = new Map(tasks.map((t) => [t.id, t]));
-  const outcomes = new Map<string, TaskOutcome>();
-  const record: TaskOutcome[] = [];
-  let running = 0;
-
-  // Resume: replay prior outcomes so finished tasks are skipped and cost is restored.
-  // A failed attempt is billed but never "done" — it is rebuilt.
-  const seed = opts.seedOutcomes ?? [];
-  for (const o of seed) {
-    record.push(o);
-    if (o.error) outcomes.delete(o.taskId); // last wins: a later failure voids an earlier pass
-    else outcomes.set(o.taskId, o);
-    running += o.cost;
-  }
-  running = round2(running);
-  const wasDone = new Set(outcomes.keys());
-
-  let halted = false;
-  let haltReason: string | undefined;
-
-  const emit = opts.onProgress ?? (() => {});
-  const checkpoint = () => opts.onCheckpoint?.(record, round2(running));
-
-  let ordered: Task[];
-  try {
-    ordered = toposort(tasks);
-  } catch (e) {
-    const message = e instanceof Error ? e.message : String(e);
-    emit({ type: "cycle_or_error", message });
-    return { outcomes: [], totalCost: 0, halted: true, haltReason: message };
-  }
-
-  const runOne = async (task: Task, round: number, contextOverride?: string): Promise<TaskOutcome> => {
-    const decision = route(task, { policy, registry, runningTotalBefore: running });
-    emit({ type: "task_start", task, round, provider: decision.provider, modelId: decision.model.id });
-    const contextText = contextOverride ?? gatherContext(task, outcomes);
-    const meta = { taskId: task.id, capability: task.capability, provider: decision.provider, modelId: decision.model.id, round };
-    let outcome: TaskOutcome;
-    try {
-      outcome = { ...(await execute({ task, decision, contextText, round, limits: policy.taskLimits })), ...meta };
-    } catch (e) {
-      if (!(e instanceof TaskLimitError)) throw e;
-      // Limit breach: bill what was spent, record the failure, halt the build.
-      outcome = { finalText: "", files: [], cost: e.costSoFar, error: e.message, ...meta };
-      running += outcome.cost;
-      record.push(outcome);
-      halted = true;
-      haltReason = `${task.id} aborted: ${e.message}`;
-      emit({ type: "task_failed", outcome, runningTotal: round2(running) });
-      return outcome;
-    }
-    running += outcome.cost;
-    outcomes.set(task.id, outcome);
-    record.push(outcome);
-    emit({ type: "task_done", outcome, runningTotal: round2(running) });
-    return outcome;
-  };
-
-  // One task's full lifecycle: run it, then its Reviewer/Tester -> Developer feedback loop.
-  const runTaskUnit = async (task: Task): Promise<void> => {
-    let outcome = await runOne(task, 0);
-    const judges = task.capability === "test" || task.capability === "review";
-    if (!outcome.error && judges && outcome.verdict && !outcome.verdict.passed) {
-      // The code to fix: direct code deps, plus code deps reached through a review
-      // (a test depends on the review, which depends on the code).
-      const codeDeps: Task[] = [];
-      for (const id of task.dependsOn ?? []) {
-        const dep = byId.get(id);
-        if (!dep) continue;
-        if (dep.capability === "code") codeDeps.push(dep);
-        else if (dep.capability === "review") {
-          for (const id2 of dep.dependsOn ?? []) {
-            const d2 = byId.get(id2);
-            if (d2?.capability === "code" && !codeDeps.includes(d2)) codeDeps.push(d2);
-          }
-        }
-      }
-
-      let round = 1;
-      fix: while (outcome.verdict && !outcome.verdict.passed && round <= policy.maxFeedbackRounds) {
-        emit({ type: "test_failed", taskId: task.id, bugs: outcome.verdict.bugs.length, round });
-        const fixContext = bugReport(outcome.verdict.bugs);
-        for (const dep of codeDeps) {
-          emit({ type: "retry_dev", taskId: dep.id, forTest: task.id, round });
-          if ((await runOne(dep, round, fixContext)).error) break fix;
-        }
-        outcome = await runOne(task, round); // re-test
-        if (outcome.error) break;
-        round++;
-      }
-    }
-    checkpoint();
-  };
-
-  // Human gate: pause once before the first development (code) task begins.
-  let gateDone = false;
-  const passGate = async (): Promise<boolean> => {
-    if (gateDone || !opts.onGate) return true;
-    gateDone = true;
-    emit({ type: "gate", stage: "design→dev" });
-    const decision = await opts.onGate({ stage: "design→dev" });
-    return decision !== "stop";
-  };
-
-  const concurrency = Math.max(1, Math.floor(opts.concurrency ?? 1));
-
-  // ---- sequential path (concurrency 1) — unchanged behavior ----
-  if (concurrency === 1) {
-    for (const task of ordered) {
-      if (wasDone.has(task.id)) {
-        emit({ type: "task_skipped", taskId: task.id });
-        continue;
-      }
-      if (task.capability === "code" && !(await passGate())) {
-        checkpoint();
-        return { outcomes: record, totalCost: round2(running), halted: true, haltReason: "stopped at review gate" };
-      }
-      const est = route(task, { policy, registry, runningTotalBefore: running });
-      if (est.overCap) {
-        emit({ type: "budget_halt", runningTotal: round2(running + est.cost), cap: policy.budgetCapUSD });
-        checkpoint();
-        return { outcomes: record, totalCost: round2(running), halted: true, haltReason: "budget cap" };
-      }
-      await runTaskUnit(task);
-      if (halted) return { outcomes: record, totalCost: round2(running), halted, haltReason };
-    }
-    return { outcomes: record, totalCost: round2(running), halted: false };
-  }
-
-  // ---- parallel path (concurrency > 1) — ready-set scheduler ----
-  // JS is single-threaded, so mutations between awaits are atomic (no locks needed).
-  // Independent tasks (deps satisfied) run concurrently up to `concurrency`. A budget
-  // reservation on in-flight estimates prevents launches that could cross the cap.
-  const remaining = new Set(ordered.filter((t) => !wasDone.has(t.id)).map((t) => t.id));
-  for (const id of wasDone) emit({ type: "task_skipped", taskId: id });
-
-  const inFlight = new Map<string, Promise<void>>();
-  let reserved = 0;
-  let codeInFlight = 0; // code tasks are serialized (they share files) even in parallel mode
-  let failure: unknown; // first task error; rethrown after in-flight work drains
-
-  const depsSatisfied = (t: Task) => (t.dependsOn ?? []).every((d) => !remaining.has(d));
-  const readyTasks = () =>
-    ordered.filter((t) => remaining.has(t.id) && !inFlight.has(t.id) && depsSatisfied(t));
-
-  while (remaining.size > 0 && !halted) {
-    // Gate before any development task launches.
-    if (!gateDone && opts.onGate && readyTasks().some((t) => t.capability === "code")) {
-      if (!(await passGate())) {
-        halted = true;
-        haltReason = "stopped at review gate";
-        break;
-      }
-    }
-    for (const task of readyTasks()) {
-      if (inFlight.size >= concurrency) break;
-      // Only one code task builds at a time — they write to the shared workspace.
-      if (task.capability === "code" && codeInFlight >= 1) continue;
-      // Reservations keep full precision: rounding each one to cents drops sub-cent
-      // estimates entirely, so a wide backlog of cheap tasks would under-reserve.
-      const est = route(task, { policy, registry, runningTotalBefore: running + reserved });
-      if (running + reserved + est.cost > policy.budgetCapUSD) {
-        if (inFlight.size === 0) {
-          emit({ type: "budget_halt", runningTotal: round2(running + est.cost), cap: policy.budgetCapUSD });
-          halted = true;
-          haltReason = "budget cap";
-        }
-        break; // wait for in-flight tasks to free budget/capacity
-      }
-      reserved += est.cost;
-      const cost = est.cost;
-      const isCode = task.capability === "code";
-      if (isCode) codeInFlight++;
-      const settle = () => {
-        if (isCode) codeInFlight--;
-        reserved -= cost;
-        remaining.delete(task.id);
-        inFlight.delete(task.id);
-      };
-      // A rejection must NOT escape through Promise.race below: that abandons the
-      // sibling promises, and their later rejections would have no handler attached
-      // (unhandled rejection -> the host process dies mid-build). Capture the first
-      // failure, stop launching, drain what's running, checkpoint, then rethrow.
-      const p = runTaskUnit(task).then(settle, (e: unknown) => {
-        settle();
-        halted = true;
-        haltReason ??= e instanceof Error ? e.message : String(e);
-        failure ??= e;
-      });
-      inFlight.set(task.id, p);
-    }
-
-    if (inFlight.size === 0) break; // nothing running and nothing launchable -> done or halted
-    await Promise.race(inFlight.values());
-  }
-
-  await Promise.all(inFlight.values());
-  checkpoint();
-  if (failure) throw failure;
-  return { outcomes: record, totalCost: round2(running), halted, haltReason };
-}
-
-function round2(n: number): number {
-  return Math.round(n * 100) / 100;
-}