projectinator 0.3.0 → 0.4.0

package/src/research.ts

@@ -1,123 +0,0 @@
-// Auto-feed the Scout — turn a research report into structured findings.
-//
-// The deep-research harness (or any benchmark write-up) produces prose. This module
-// extracts it into clean Finding[] the Scout can consume: a model reads the report and
-// calls a forced typebox tool. That's reliable because it's reformatting text we give
-// it, not recalling facts from memory.
-//
-// Flow:  research report (text)  ->  extractFindings()  ->  findings.json  ->  scout --from
-
-import {
-  createAgentSession,
-  defineTool,
-  type AgentSession,
-} from "@earendil-works/pi-coding-agent";
-import { Type, type Static } from "typebox";
-import type { Provider } from "./types.js";
-import type { Finding } from "./scout.js";
-import { piRuntime, resolvePiModel } from "./executor.js"
-import { MODELS } from "./models.js";
-
-const FindingsSchema = Type.Object({
-  findings: Type.Array(
-    Type.Object({
-      capability: Type.Union([
-        Type.Literal("plan"), Type.Literal("design"), Type.Literal("code"),
-        Type.Literal("test"), Type.Literal("ops"),
-      ]),
-      tier: Type.Union([Type.Literal("fast"), Type.Literal("mid"), Type.Literal("high")]),
-      backend: Type.Union([Type.Literal("web"), Type.Literal("api")]),
-      provider: Type.Union([Type.Literal("anthropic"), Type.Literal("openai"), Type.Literal("google")]),
-      model: Type.String({ description: "exact model id, e.g. claude-opus-4-8" }),
-      evidence: Type.String({ description: "one-line benchmark/source justification" }),
-    }),
-  ),
-});
-type FindingsRaw = Static<typeof FindingsSchema>;
-
-export interface ValidationIssue {
-  index: number;
-  model: string;
-  problem: string;
-}
-
-/** Pure check: does each finding reference a real model with a matching provider? */
-export function validateFindings(findings: Finding[]): { ok: boolean; issues: ValidationIssue[] } {
-  const issues: ValidationIssue[] = [];
-  findings.forEach((f, index) => {
-    const m = MODELS[f.model];
-    if (!m) {
-      issues.push({ index, model: f.model, problem: "model not in models.ts" });
-    } else if (m.provider !== f.provider) {
-      issues.push({ index, model: f.model, problem: `provider mismatch (models.ts says ${m.provider})` });
-    }
-  });
-  return { ok: issues.length === 0, issues };
-}
-
-function buildFindingsTool() {
-  let captured: Finding[] | undefined;
-  const tool = defineTool({
-    name: "submit_findings",
-    label: "Submit Findings",
-    description: "Submit the extracted model-per-role findings.",
-    parameters: FindingsSchema,
-    execute: async (_id, params: FindingsRaw) => {
-      captured = params.findings as Finding[];
-      return { content: [{ type: "text", text: `Extracted ${params.findings.length} findings.` }], details: {} };
-    },
-  });
-  return { tool, get: () => captured };
-}
-
-export function extractionPrompt(report: string): string {
-  return [
-    "You are a data extractor. From the research report below, extract the single best",
-    "model for each role the report covers, as structured findings.",
-    "",
-    "For each finding set: capability (plan|design|code|test|ops), tier (fast|mid|high),",
-    "backend (usually 'api' for benchmark-driven picks), provider, the EXACT model id,",
-    "and a one-line evidence note. Only include roles the report actually supports.",
-    "Do not invent models. When done, call submit_findings once.",
-    "",
-    "--- REPORT ---",
-    report,
-  ].join("\n");
-}
-
-export interface ExtractOptions {
-  model: { provider: Provider; model: string };
-  onEvent?: Parameters<AgentSession["subscribe"]>[0];
-}
-
-/** Extract findings from a report via a model. Spends money (one model call). */
-export async function extractFindings(report: string, opts: ExtractOptions): Promise<Finding[]> {
-  const runtime = await piRuntime();
-  const model = resolvePiModel(runtime, opts.model.provider, opts.model.model);
-
-  const { tool, get } = buildFindingsTool();
-  const { session } = await createAgentSession({
-    model, modelRuntime: runtime,
-    thinkingLevel: "low",
-    noTools: "all",
-    customTools: [tool],
-    tools: ["submit_findings"],
-  });
-
-  const unsub = opts.onEvent ? session.subscribe(opts.onEvent) : undefined;
-  try {
-    await session.prompt(extractionPrompt(report));
-    let out = get();
-    if (!out) {
-      await session.followUp("Call submit_findings now.");
-      out = get();
-    }
-    if (!out) throw new Error("Extractor did not call submit_findings.");
-    return out;
-  } finally {
-    unsub?.();
-    session.dispose();
-  }
-}
-
-export { FindingsSchema, buildFindingsTool };

package/src/retro.ts

@@ -1,99 +0,0 @@
-// Build retro — a free, data-driven summary of a finished build, computed from
-// build-state: what passed, what the tester flagged, cost per epic and per
-// model, retries, and the priciest tasks. No model call.
-
-import { completedIds, type BuildState } from "./build-state.js";
-import type { Bug, Difficulty } from "./types.js";
-import { baselineTokens } from "./estimate.js";
-import { estimateCost } from "./cost.js";
-import { getModel } from "./models.js";
-
-export interface RetroReport {
-  idea: string;
-  status: BuildState["status"];
-  totalCost: number;
-  estCost: number; // baseline predicted cost for the tasks that ran
-  taskCount: number;
-  doneCount: number;
-  tests: { passed: number; failed: number };
-  bugs: Bug[]; // everything the tester flagged during the build
-  retries: { taskId: string; title: string; rounds: number }[];
-  byEpic: { epic: string; cost: number; tasks: number }[];
-  byModel: { model: string; cost: number; tasks: number }[];
-  topCost: { taskId: string; title: string; cost: number }[];
-}
-
-const round2 = (n: number) => Math.round(n * 100) / 100;
-
-export function computeRetro(state: BuildState): RetroReport {
-  const titleById = new Map(state.tasks.map((t) => [t.id, t.title]));
-  const epicById = new Map(state.tasks.map((t) => [t.id, t.epic || "General"]));
-  const diffById = new Map(state.tasks.map((t) => [t.id, t.difficulty]));
-  const outcomes = state.outcomes;
-  const doneIds = completedIds(state);
-
-  // Baseline-predicted cost for each run: static token budget × the model that ran it.
-  let estCost = 0;
-  for (const o of outcomes) {
-    const diff = (diffById.get(o.taskId) ?? "medium") as Difficulty;
-    try {
-      const model = getModel(o.modelId);
-      const tokens = baselineTokens(o.capability, diff);
-      estCost += estimateCost({ input: tokens.input, output: tokens.output, cachedInputFraction: 0.55 }, model);
-    } catch {
-      /* unknown model — skip its estimate */
-    }
-  }
-
-  // Tests: judge each test task by its LAST outcome (final state after retries).
-  const lastTestByTask = new Map<string, (typeof outcomes)[number]>();
-  for (const o of outcomes) if (o.capability === "test") lastTestByTask.set(o.taskId, o);
-  let passed = 0;
-  let failed = 0;
-  for (const o of lastTestByTask.values()) {
-    if (o.verdict?.passed) passed++;
-    else if (o.verdict) failed++;
-  }
-
-  // Bugs the tester flagged anywhere during the build (signal, even if later fixed).
-  const bugs: Bug[] = [];
-  for (const o of outcomes) if (o.verdict?.bugs) bugs.push(...o.verdict.bugs);
-
-  // Retries: any outcome past round 0 means a Tester→Developer rebuild happened.
-  const roundsByTask = new Map<string, number>();
-  for (const o of outcomes) if (o.round > 0) roundsByTask.set(o.taskId, Math.max(roundsByTask.get(o.taskId) ?? 0, o.round));
-  const retries = [...roundsByTask.entries()].map(([taskId, rounds]) => ({ taskId, title: titleById.get(taskId) ?? taskId, rounds }));
-
-  // Cost per epic + per model.
-  const epicCost = new Map<string, { cost: number; tasks: number }>();
-  const modelCost = new Map<string, { cost: number; tasks: number }>();
-  for (const o of outcomes) {
-    const e = epicById.get(o.taskId) ?? "General";
-    const ec = epicCost.get(e) ?? { cost: 0, tasks: 0 };
-    epicCost.set(e, { cost: ec.cost + o.cost, tasks: ec.tasks + 1 });
-    const mc = modelCost.get(o.modelId) ?? { cost: 0, tasks: 0 };
-    modelCost.set(o.modelId, { cost: mc.cost + o.cost, tasks: mc.tasks + 1 });
-  }
-  const byEpic = [...epicCost.entries()].map(([epic, v]) => ({ epic, cost: round2(v.cost), tasks: v.tasks })).sort((a, b) => b.cost - a.cost);
-  const byModel = [...modelCost.entries()].map(([model, v]) => ({ model, cost: round2(v.cost), tasks: v.tasks })).sort((a, b) => b.cost - a.cost);
-
-  const topCost = [...outcomes]
-    .sort((a, b) => b.cost - a.cost)
-    .slice(0, 3)
-    .map((o) => ({ taskId: o.taskId, title: titleById.get(o.taskId) ?? o.taskId, cost: round2(o.cost) }));
-
-  return {
-    idea: state.idea ?? state.id,
-    status: state.status,
-    totalCost: round2(state.totalCost),
-    estCost: round2(estCost),
-    taskCount: state.tasks.length,
-    doneCount: doneIds.size,
-    tests: { passed, failed },
-    bugs,
-    retries,
-    byEpic,
-    byModel,
-    topCost,
-  };
-}

package/src/roles.ts

@@ -1,401 +0,0 @@
-// Phase 4 — role definitions + the real Pi-backed executor.
-//
-// Each capability becomes a role with its own prompt and tool set. The Tester uses
-// a forced typebox verdict tool (like the PM) so its pass/fail is structured, which
-// the orchestrator's feedback loop depends on.
-
-import {
-  createAgentSession,
-  defineTool,
-  type AgentSession,
-} from "@earendil-works/pi-coding-agent";
-import { Type, type Static } from "typebox";
-import {
-  TaskLimitError,
-  type Backend,
-  type Capability,
-  type Provider,
-  type RegistryEntry,
-  type RoleExecutor,
-  type RoleResult,
-  type Task,
-  type TaskLimits,
-  type Verdict,
-} from "./types.js";
-import { piRuntime, resolvePiModel } from "./executor.js"
-import { renderCheck, chromiumAvailable, CHROMIUM_INSTALL_HINT } from "./preview.js";
-import { estimateCost } from "./cost.js";
-import { getModel } from "./models.js";
-import { addSessionCost } from "./session-cost.js";
-import { recordActual } from "./calibration.js";
-import { readdirSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
-
-// ---- role prompts ----
-
-const ROLE_INTRO: Record<Capability, string> = {
-  plan: "You are the PLANNER. Produce a concise plan or decision for this task as text.",
-  design:
-    "You are the DESIGNER. Produce a clear, concrete design spec (layout, components, colours, states) as text. " +
-    "If the product spans multiple files, also specify the intended FILE STRUCTURE — name each file and say what it holds (e.g. index.html, styles.css, app.js, or a src/ tree). Do not write code files. " +
-    "For a plain static site with no build step, DO NOT spec ES modules with relative imports (`<script type=\"module\">` + `import './x.js'`): browsers block those when the user double-clicks the file (file://), so the app looks dead. Prefer one classic `<script src>` (or a few, loaded in order) so it runs on double-click.",
-  code:
-    "You are the DEVELOPER. Write real, working files into the working directory — minimal, correct, no placeholders, no TODO stubs. " +
-    "This is often a MULTI-FILE project: FIRST inspect what already exists (use ls, then read the relevant files) and BUILD ON it — " +
-    "reuse and extend existing files, follow the file structure the design spec defines, and make sure files reference each other with correct paths " +
-    "(imports/requires, <script src> and <link href>, relative paths). Create only the files this task needs; never delete or clobber files unrelated to your task. " +
-    "MUST-RUN-ON-DOUBLE-CLICK: for a plain static site with no bundler/build step, the app has to work when the user just opens index.html as a file (file://). Do NOT use `<script type=\"module\">` with relative `import`s, and do not `fetch()` local files — browsers block both on file://, leaving a blank page. Split code with several plain `<script src>` tags in dependency order (globals), not ES modules. If the app genuinely needs a server (a real backend, bundler, or framework), write a short README.md with the exact run command.",
-  review:
-    "You are the REVIEWER. Do NOT edit files and do NOT run the app. Read the task, the design context, and the files in the working directory. " +
-    "Check: every file the design named exists; every <script src> / <link href> / import resolves to a real file; nothing is referenced but never defined " +
-    "(functions, element ids, CSS classes the JS relies on); a plain static site uses no ES modules or fetch() of local files (both break on double-click / file://); " +
-    "and the task's stated deliverable is actually present. Report only real defects a developer must fix — not style. Then call submit_verdict exactly once.",
-  test: "You are the TESTER. For a web app, FIRST call check_app to actually run it in a headless browser — it reports how the app renders BOTH served over http AND opened directly as a file (double-click / file://). Confirm it renders, shows the expected content, and has no JavaScript/console errors. The app MUST also work on double-click (file://) UNLESS a README documents how to run it — if check_app says double-click is BROKEN and there is no README with a run command, that is a HIGH-severity bug (report it, describe the file:// failure). Then inspect the files against the task and check multi-file wiring (referenced files exist, paths/imports resolve). Then call submit_verdict with pass/fail and any bugs. A blank render or a JS error is a high-severity bug. Do not fix anything yourself.",
-  ops: "You are OPS. Perform the operational task (build, config, deploy prep) using your tools. Report what you did as text.",
-};
-
-export function buildRolePrompt(task: Task, contextText: string): string {
-  const lines = [
-    ROLE_INTRO[task.capability],
-    "",
-    `Task ${task.id}: ${task.title}`,
-    contextText ? `\n${contextText}` : "",
-    "",
-    task.capability === "test" || task.capability === "review"
-      ? "When finished, call submit_verdict exactly once."
-      : "Complete the task, then stop. Do not explain at length.",
-  ];
-  return lines.filter((l) => l !== "").join("\n");
-}
-
-// ---- tester verdict tool (forced structured output) ----
-
-const VerdictSchema = Type.Object({
-  passed: Type.Boolean({ description: "true if the build satisfies the task with no serious bugs" }),
-  bugs: Type.Array(
-    Type.Object({
-      severity: Type.Union([Type.Literal("low"), Type.Literal("medium"), Type.Literal("high")]),
-      description: Type.String(),
-      file: Type.Optional(Type.String()),
-    }),
-    { description: "empty if passed" },
-  ),
-});
-type VerdictRaw = Static<typeof VerdictSchema>;
-
-// ---- tester "run the app" tool: headless render + error capture ----
-
-/** check_app + a flag telling whether a render actually happened this task. */
-function buildCheckTool(workspace: string, chromium: boolean) {
-  let rendered = false;
-  const tool = defineTool({
-    name: "check_app",
-    label: "Run the app",
-    description:
-      "Render a built web page in a headless browser and report its title, the visible text, " +
-      "and any JavaScript/console errors or failed asset requests. Use this on web apps to confirm " +
-      "the app actually RUNS and renders before you judge it — do not rely on reading the code alone.",
-    parameters: Type.Object(
-      { file: Type.Optional(Type.String({ description: "HTML entry file to load; default index.html" })) },
-      { additionalProperties: true },
-    ),
-    execute: async (_id, params: { file?: string }) => {
-      if (!chromium) {
-        return {
-          content: [{ type: "text", text: `check_app is UNAVAILABLE: headless Chromium is not installed (${CHROMIUM_INSTALL_HINT}). You cannot run the app. Review the files by reading them, say so in your verdict, and do not claim the app was executed.` }],
-          details: {},
-        };
-      }
-      try {
-        const r = await renderCheck(workspace, params.file || "index.html");
-        rendered = true;
-        const doubleClick = r.doubleClickBroken
-          ? "BROKEN — renders behind a server but is blank/erroring when opened directly as a file (double-click). "
-            + "Most likely ES modules + relative imports (or fetch of local files), which browsers block on file://. "
-            + "This is a real defect for a user who just opens the folder. Fix: use a classic non-module <script>, "
-            + "or ship a README with a run command (e.g. `python3 -m http.server`)."
-          : r.fileOk
-            ? "OK (works on double-click too)"
-            : `over file://: ${r.fileErrors.length ? r.fileErrors.join("; ") : "(empty page)"}`;
-        const text = [
-          `rendered (served over http): ${r.ok ? "OK (no JS errors)" : "with errors"}`,
-          `title: ${r.title || "(none)"}`,
-          `errors: ${r.errors.length ? "\n  - " + r.errors.join("\n  - ") : "none"}`,
-          `opened as a file (double-click / file://): ${doubleClick}`,
-          `visible text:\n${r.text || "(empty page — nothing rendered)"}`,
-        ].join("\n");
-        return { content: [{ type: "text", text }], details: {} };
-      } catch (e) {
-        return {
-          content: [{ type: "text", text: `check_app could not run (${e instanceof Error ? e.message : e}). If this isn't a web app with an HTML page, inspect the files directly instead.` }],
-          details: {},
-        };
-      }
-    },
-  });
-  return { tool, rendered: () => rendered };
-}
-
-function buildVerdictTool(runtimeChecked: () => boolean) {
-  let captured: Verdict | undefined;
-  const tool = defineTool({
-    name: "submit_verdict",
-    label: "Submit Verdict",
-    description: "Submit your pass/fail judgement and any bugs found.",
-    parameters: VerdictSchema,
-    execute: async (_id, params: VerdictRaw) => {
-      captured = { passed: params.passed, bugs: params.bugs, runtimeChecked: runtimeChecked() };
-      return {
-        content: [{ type: "text", text: `Verdict: ${params.passed ? "PASS" : "FAIL"} (${params.bugs.length} bugs)` }],
-        details: {},
-      };
-    },
-  });
-  return { tool, get: () => captured };
-}
-
-// ---- provider lock: run the whole pipeline on one provider ----
-// Useful when you hold a key for only one provider. Maps each capability+tier to
-// that provider's sensible model, so route() resolves everything to it.
-
-const PROVIDER_MODELS: Record<Provider, { strong: string; mid: string; cheap: string }> = {
-  anthropic: { strong: "claude-opus-5", mid: "claude-sonnet-5", cheap: "claude-haiku-4-5" },
-  openai: { strong: "gpt-5.6-sol", mid: "gpt-5.6-terra", cheap: "gpt-5.6-luna" },
-  google: { strong: "gemini-3.1-pro-preview", mid: "gemini-3.1-pro-preview", cheap: "gemini-3.8-flash" },
-  openrouter: { strong: "anthropic/claude-opus-5", mid: "anthropic/claude-sonnet-5", cheap: "google/gemini-3.8-flash" },
-};
-
-const CAP_STRENGTH: Record<Capability, "strong" | "mid" | "cheap"> = {
-  plan: "mid",
-  design: "strong",
-  code: "strong",
-  review: "cheap",
-  test: "cheap",
-  ops: "strong",
-};
-
-/** A registry where every capability routes to one provider's models. */
-export function lockRegistryToProvider(provider: Provider): RegistryEntry[] {
-  const m = PROVIDER_MODELS[provider];
-  const caps: Capability[] = ["plan", "design", "code", "review", "test", "ops"];
-  const tiers = ["fast", "mid", "high"] as const;
-  const out: RegistryEntry[] = [];
-  for (const capability of caps) {
-    const modelId = m[CAP_STRENGTH[capability]];
-    for (const tier of tiers) {
-      out.push({
-        capability,
-        tier,
-        byBackend: { web: { provider, model: modelId }, api: { provider, model: modelId } },
-        updated: "provider-lock",
-      });
-    }
-  }
-  return out;
-}
-
-// ---- the real Pi executor ----
-
-export interface PiExecutorOptions {
-  workspace: string;
-  backend: Backend;
-  thinkingLevel?: "off" | "low" | "medium" | "high";
-  onEvent?: Parameters<AgentSession["subscribe"]>[0];
-  /** Called when a task falls back from its routed provider to another one. */
-  onFallback?: (info: { taskId: string; from: Provider; to: Provider; model: string }) => void;
-}
-
-// Env vars that hold each provider's key (mirrors run-build's check).
-const ENV_KEYS: Record<Provider, string[]> = {
-  anthropic: ["ANTHROPIC_API_KEY"],
-  openai: ["OPENAI_API_KEY"],
-  google: ["GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
-  openrouter: ["OPENROUTER_API_KEY"],
-};
-
-function providersWithKeys(): Provider[] {
-  return (Object.keys(ENV_KEYS) as Provider[]).filter((p) => ENV_KEYS[p].some((k) => process.env[k]));
-}
-
-/** The routed model first, then the same-strength model on every OTHER provider
- *  that has a key — so a 0-token / errored provider falls back automatically. */
-function fallbackChain(primary: Provider, primaryModel: string, cap: Capability): { provider: Provider; model: string }[] {
-  const chain: { provider: Provider; model: string }[] = [{ provider: primary, model: primaryModel }];
-  for (const p of providersWithKeys()) {
-    if (p === primary) continue;
-    chain.push({ provider: p, model: PROVIDER_MODELS[p][CAP_STRENGTH[cap]] });
-  }
-  return chain;
-}
-
-/** Extract the last assistant text from a session, tolerant of content shape. */
-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((part: unknown) => {
-          if (typeof part === "string") return part;
-          if (part && typeof part === "object" && "text" in part) return String((part as { text: unknown }).text);
-          return "";
-        })
-        .join("")
-        .trim();
-    }
-  }
-  return "";
-}
-
-function listFiles(dir: string): string[] {
-  const out: string[] = [];
-  const skip = new Set([".pi", ".git", "node_modules"]);
-  const walk = (d: string) => {
-    let entries: string[];
-    try {
-      entries = readdirSync(d);
-    } catch {
-      return;
-    }
-    for (const name of entries) {
-      if (skip.has(name)) continue;
-      const full = join(d, name);
-      // Tolerate broken symlinks / files removed mid-build; skip, don't abort the run.
-      let st;
-      try { st = statSync(full); } catch { continue; }
-      if (st.isDirectory()) walk(full);
-      else out.push(relative(dir, full));
-    }
-  };
-  walk(dir);
-  return out.sort();
-}
-
-/** Build a real RoleExecutor backed by Pi. Each call spends money. Falls back to
- *  another key-holding provider when the routed one errors or returns 0 tokens. */
-export function makePiExecutor(opts: PiExecutorOptions): RoleExecutor {
-  // One attempt on a specific provider/model. Returns the result + total tokens
-  // (0 tokens = the provider call didn't really happen → treat as a failure).
-  const runOnce = async (
-    task: Task,
-    contextText: string,
-    provider: Provider,
-    modelId: string,
-    limits: TaskLimits,
-  ): Promise<{ result: RoleResult; tokensTotal: number }> => {
-    const runtime = await piRuntime();
-    const model = resolvePiModel(runtime, provider, modelId);
-
-    const isTest = task.capability === "test";
-    const isReview = task.capability === "review";
-    const checkTool = isTest ? buildCheckTool(opts.workspace, await chromiumAvailable()) : undefined;
-    // A review never runs the app, so its verdict is never "runtime checked".
-    const verdictTool = isTest || isReview ? buildVerdictTool(checkTool ? checkTool.rendered : () => false) : undefined;
-
-    const { session } = await createAgentSession({
-      model,
-      cwd: opts.workspace,
-      modelRuntime: runtime,
-      thinkingLevel: opts.thinkingLevel ?? "medium",
-      ...(isTest
-        ? { customTools: [verdictTool!.tool, checkTool!.tool], tools: ["read", "bash", "ls", "grep", "find", "check_app", "submit_verdict"] }
-        : isReview
-          ? { customTools: [verdictTool!.tool], tools: ["read", "ls", "grep", "find", "submit_verdict"] }
-          : { tools: ["read", "write", "edit", "bash", "ls", "grep", "find"] }),
-    });
-
-    const unsub = opts.onEvent ? session.subscribe(opts.onEvent) : undefined;
-
-    // Per-task limits. Cost is checked on every session event (Pi updates its stats as
-    // each assistant turn lands); time by a timer. On breach the session is aborted and
-    // the awaited prompt settles; we then throw so the orchestrator halts the build.
-    let breach: TaskLimitError | undefined;
-    const trip = (e: TaskLimitError) => {
-      if (breach) return;
-      breach = e;
-      void session.abort();
-    };
-    const unsubCost = limits.costCapUSD > 0
-      ? session.subscribe(() => {
-          const spent = session.getSessionStats().cost;
-          if (spent > limits.costCapUSD) trip(new TaskLimitError("cost", task.id, round2(spent), `spent $${spent.toFixed(2)} > per-task cap $${limits.costCapUSD}`));
-        })
-      : undefined;
-    const timer = limits.timeoutMs > 0
-      ? setTimeout(() => trip(new TaskLimitError("timeout", task.id, round2(session.getSessionStats().cost), `ran longer than ${Math.round(limits.timeoutMs / 60_000)} min`)), limits.timeoutMs)
-      : undefined;
-    try {
-      // Give code/review/test the WHOLE current file tree (not just direct-dep files), so a
-      // dev building one file knows every other file that already exists to wire into.
-      let fullContext = contextText;
-      if (task.capability === "code" || task.capability === "review" || task.capability === "test") {
-        const existing = listFiles(opts.workspace);
-        if (existing.length) {
-          fullContext = [contextText, `Files already in the working directory:\n${existing.map((f) => `  ${f}`).join("\n")}`]
-            .filter(Boolean)
-            .join("\n\n");
-        }
-      }
-      // An aborted prompt may reject with Pi's own error; the breach is the real cause.
-      await session.prompt(buildRolePrompt(task, fullContext)).catch((e: unknown) => { if (!breach) throw e; });
-      if (breach) throw breach;
-
-      let verdict = verdictTool?.get();
-      if (verdictTool && !verdict) {
-        await session.followUp("Call submit_verdict now with your judgement.").catch((e: unknown) => { if (!breach) throw e; });
-        verdict = verdictTool?.get();
-      }
-      if (breach) throw breach;
-
-      const stats = session.getSessionStats();
-      // Feed real usage back to sharpen estimates — but only for a real run.
-      if (stats.tokens.total > 0) {
-        const inputTotal = stats.tokens.input + stats.tokens.cacheRead;
-        recordActual(task.capability, task.difficulty, inputTotal, stats.tokens.output, inputTotal > 0 ? stats.tokens.cacheRead / inputTotal : 0);
-      }
-      const result: RoleResult = {
-        finalText: lastAssistantText(session),
-        files: listFiles(opts.workspace),
-        cost: round2(stats.cost),
-        verdict,
-      };
-      return { result, tokensTotal: stats.tokens.total };
-    } finally {
-      clearTimeout(timer);
-      unsubCost?.();
-      addSessionCost(session.getSessionStats().cost); // bill every attempt, aborted or not
-      unsub?.();
-      session.dispose();
-    }
-  };
-
-  return async ({ task, decision, contextText, limits }) => {
-    const chain = fallbackChain(decision.provider, decision.model.id, task.capability);
-    let lastErr: unknown;
-    for (let i = 0; i < chain.length; i++) {
-      const cand = chain[i]!;
-      try {
-        const att = await runOnce(task, contextText, cand.provider, cand.model, limits);
-        if (att.tokensTotal > 0) {
-          if (i > 0) opts.onFallback?.({ taskId: task.id, from: decision.provider, to: cand.provider, model: cand.model });
-          return att.result;
-        }
-        lastErr = new Error(`${cand.provider}/${cand.model} returned 0 tokens (invalid key, no account credit/balance, or no access to this model)`);
-      } catch (e) {
-        if (e instanceof TaskLimitError) throw e; // a limit breach is final — never retry elsewhere
-        lastErr = e;
-      }
-    }
-    throw lastErr instanceof Error ? lastErr : new Error("all providers failed");
-  };
-}
-
-function round2(n: number): number {
-  return Math.round(n * 100) / 100;
-}
-
-// exported for tests
-export { buildCheckTool, buildVerdictTool, VerdictSchema, estimateCost, getModel };