tldr-experts 0.3.0 → 0.4.0

package/dist/hooks/chunk-4cp363kv.js

@@ -0,0 +1,1766 @@
+import {
+  parseHandoff
+} from "./chunk-9zsqxr6y.js";
+import {
+  MAX_PLAN_STORIES,
+  MAX_STORIES_PER_WAVE,
+  MAX_WAVES,
+  STORY_ID_RE,
+  WAVE_ID_RE,
+  parseFrontMatter,
+  requirePattern,
+  requireStringList,
+  requireVersion1
+} from "./chunk-phmdk72a.js";
+import {
+  classifySrc
+} from "./chunk-m3mewgnw.js";
+import {
+  asDocument,
+  isRecord,
+  requireArray,
+  requireEnum,
+  requireKeys,
+  requireNumber,
+  requireRecord,
+  requireString,
+  requireVersion,
+  result
+} from "./chunk-39zh2e44.js";
+import {
+  PROJECT_FRAMEWORK_DIR,
+  listRunDirs,
+  parseYaml
+} from "./chunk-sq44k6g2.js";
+
+// src/hooks/lib/runFile.ts
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+var TERMINAL_STATUSES = ["done", "failed", "skipped", "cancelled"];
+function loadRunView(runDir) {
+  const path = join(runDir, "run.yml");
+  if (!existsSync(path))
+    return null;
+  let doc;
+  try {
+    const parsed = parseYaml(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null)
+      return null;
+    doc = parsed;
+  } catch {
+    return null;
+  }
+  const rawCursor = doc.cursor;
+  const cursor = rawCursor === undefined || rawCursor === null ? null : {
+    phase: str(rawCursor.phase),
+    stage: str(rawCursor.stage),
+    task: typeof rawCursor.task === "string" ? rawCursor.task : null
+  };
+  const phases = [];
+  if (Array.isArray(doc.phases)) {
+    for (const entry of doc.phases) {
+      const stages = [];
+      if (Array.isArray(entry?.stages)) {
+        for (const s of entry.stages) {
+          stages.push({
+            id: str(s?.id),
+            status: str(s?.status),
+            expert: typeof s?.expert === "string" ? s.expert : null,
+            budget_usd: typeof s?.budget_usd === "number" ? s.budget_usd : null,
+            cost_usd: typeof s?.cost_usd === "number" ? s.cost_usd : null,
+            tasks: tasksOf(s?.tasks)
+          });
+        }
+      }
+      phases.push({ id: str(entry?.id), status: str(entry?.status), stages });
+    }
+  }
+  return {
+    dir: runDir,
+    run: str(doc.run) || str(doc.run_id),
+    title: str(doc.title),
+    scope: str(doc.scope),
+    status: str(doc.status),
+    updated_at: str(doc.updated_at),
+    attended_by: typeof doc.attended_by === "string" && doc.attended_by !== "" ? doc.attended_by : null,
+    cursor,
+    phases
+  };
+}
+function tasksOf(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.map((task) => ({
+    cost_usd: typeof task?.cost_usd === "number" ? task.cost_usd : null,
+    metered: task?.metered !== false,
+    tokens: typeof task?.tokens === "number" ? task.tokens : null
+  }));
+}
+function isAttendedByHostView(view) {
+  return view.attended_by === "host";
+}
+function runSpend(view) {
+  let meteredUsd = 0;
+  let hostTokens = 0;
+  let unmeteredTasks = 0;
+  for (const phase of view.phases) {
+    for (const stage of phase.stages) {
+      for (const task of stage.tasks) {
+        if (task.cost_usd !== null)
+          meteredUsd += task.cost_usd;
+        if (!task.metered || task.cost_usd === null)
+          unmeteredTasks += 1;
+        if (task.tokens !== null)
+          hostTokens += task.tokens;
+      }
+    }
+  }
+  return { meteredUsd: Math.round(meteredUsd * 100) / 100, hostTokens, unmeteredTasks };
+}
+function hostTokensIn(view, phaseId) {
+  let tokens = 0;
+  for (const phase of view.phases) {
+    if (phaseId !== null && phase.id !== phaseId)
+      continue;
+    for (const stage of phase.stages) {
+      for (const task of stage.tasks) {
+        if (task.tokens !== null)
+          tokens += task.tokens;
+      }
+    }
+  }
+  return tokens;
+}
+function renderRunEconomies(view) {
+  const spend = runSpend(view);
+  const attended = isAttendedByHostView(view);
+  if (spend.hostTokens === 0 && spend.unmeteredTasks === 0 && !attended)
+    return null;
+  const parts = [`$${spend.meteredUsd.toFixed(2)} metered`];
+  if (spend.hostTokens > 0)
+    parts.push(`${String(spend.hostTokens)} host tokens`);
+  if (spend.unmeteredTasks > 0) {
+    parts.push(`${String(spend.unmeteredTasks)} unmetered turn${spend.unmeteredTasks === 1 ? "" : "s"}`);
+  }
+  const who = attended ? " (attended_by: host — the framework does not spawn on this run)" : "";
+  return `spend so far: ${parts.join(" + ")}${who}. ` + "The dollar figure is METERED spend only; host tokens are a different currency and are never converted.";
+}
+function isTerminal(status) {
+  return TERMINAL_STATUSES.includes(status);
+}
+function cursorStage(view) {
+  if (view.cursor === null)
+    return null;
+  for (const phase of view.phases) {
+    if (phase.id !== view.cursor.phase)
+      continue;
+    return phase.stages.find((s) => s.id === view.cursor?.stage) ?? null;
+  }
+  return null;
+}
+function openRunViews(root) {
+  const open = [];
+  for (const dir of listRunDirs(root)) {
+    const view = loadRunView(dir);
+    if (view === null || isTerminal(view.status))
+      continue;
+    open.push(view);
+  }
+  return open.sort((a, b) => a.updated_at > b.updated_at ? -1 : a.updated_at < b.updated_at ? 1 : 0);
+}
+function newestActiveRun(root) {
+  return openRunViews(root)[0] ?? null;
+}
+function str(value) {
+  return typeof value === "string" ? value : "";
+}
+
+// src/hooks/lib/actor.ts
+function currentActor() {
+  const user = process.env.USER ?? process.env.USERNAME ?? "";
+  return user.trim() === "" ? "unknown" : user.trim();
+}
+function nowRfc3339() {
+  return `${new Date().toISOString().slice(0, 19)}Z`;
+}
+
+// src/core/budget/RunBudget.ts
+var ON_EXCEED = ["block", "warn"];
+var ON_HOST_TOKENS_EXCEED = ["warn", "block"];
+var DEFAULT_ON_HOST_TOKENS_EXCEED = "warn";
+var ECONOMIES = ["metered-usd", "host-tokens"];
+var DEFAULT_ECONOMY = "metered-usd";
+var DEFAULT_WARN_AT_PCT = 80;
+var MAX_PHASES = 5;
+function economyFor(budget, phaseId) {
+  if (budget === null)
+    return DEFAULT_ECONOMY;
+  if (phaseId !== undefined && phaseId !== null) {
+    const phase = budget.phases.find((entry) => entry.id === phaseId);
+    if (phase !== undefined && phase.economy !== null)
+      return phase.economy;
+  }
+  return budget.economy;
+}
+function isHostTokens(budget, phaseId) {
+  return economyFor(budget, phaseId) === "host-tokens";
+}
+function validateRunBudget(input) {
+  const issues = [];
+  const deprecations = [];
+  const doc = asDocument(input, issues);
+  if (!doc)
+    return result(issues);
+  requireVersion(doc, issues, deprecations);
+  requireKeys(doc, ["run", "ceiling_usd", "per_agent_max_usd", "on_exceed", "phases"], "", issues);
+  requireString(doc.run, "run", issues);
+  requireNumber(doc.ceiling_usd, "ceiling_usd", issues);
+  requireNumber(doc.per_agent_max_usd, "per_agent_max_usd", issues);
+  requireEnum(doc.on_exceed, ON_EXCEED, "on_exceed", issues);
+  if (doc.economy !== undefined && doc.economy !== null) {
+    requireEnum(doc.economy, ECONOMIES, "economy", issues);
+  }
+  if (doc.on_host_tokens_exceed !== undefined && doc.on_host_tokens_exceed !== null) {
+    requireEnum(doc.on_host_tokens_exceed, ON_HOST_TOKENS_EXCEED, "on_host_tokens_exceed", issues);
+  }
+  if (doc.warn_at_pct !== undefined) {
+    requireNumber(doc.warn_at_pct, "warn_at_pct", issues);
+    const pct = doc.warn_at_pct;
+    if (typeof pct === "number" && (pct < 1 || pct > 99)) {
+      issues.push({ path: "warn_at_pct", message: "expected 1–99" });
+    }
+  }
+  if (!requireArray(doc.phases, "phases", issues))
+    return result(issues, deprecations);
+  const phases = doc.phases;
+  if (phases.length > MAX_PHASES) {
+    issues.push({ path: "phases", message: `${phases.length} phases exceeds the ${MAX_PHASES} cap` });
+  }
+  let sum = 0;
+  phases.forEach((phase, i) => {
+    const path = `phases[${i}]`;
+    if (!isRecord(phase)) {
+      issues.push({ path, message: "expected a mapping" });
+      return;
+    }
+    requireKeys(phase, ["id", "ceiling_usd", "spent_usd"], path, issues);
+    requireString(phase.id, `${path}.id`, issues);
+    requireNumber(phase.ceiling_usd, `${path}.ceiling_usd`, issues);
+    requireNumber(phase.spent_usd, `${path}.spent_usd`, issues);
+    if (phase.economy !== undefined && phase.economy !== null) {
+      requireEnum(phase.economy, ECONOMIES, `${path}.economy`, issues);
+    }
+    if (typeof phase.ceiling_usd === "number")
+      sum += phase.ceiling_usd;
+  });
+  if (typeof doc.ceiling_usd === "number" && sum > doc.ceiling_usd + 0.000000001) {
+    issues.push({ path: "phases", message: `phase ceilings sum to ${sum} > ceiling_usd ${doc.ceiling_usd}` });
+  }
+  return result(issues, deprecations);
+}
+function asRunBudget(input) {
+  const doc = input;
+  return {
+    version: doc.version ?? 1,
+    run: doc.run ?? "",
+    ceiling_usd: doc.ceiling_usd ?? 0,
+    per_agent_max_usd: doc.per_agent_max_usd ?? 0,
+    warn_at_pct: doc.warn_at_pct ?? DEFAULT_WARN_AT_PCT,
+    on_exceed: doc.on_exceed ?? "block",
+    economy: doc.economy ?? DEFAULT_ECONOMY,
+    on_host_tokens_exceed: doc.on_host_tokens_exceed ?? DEFAULT_ON_HOST_TOKENS_EXCEED,
+    phases: (doc.phases ?? []).map((phase) => ({
+      id: phase.id,
+      ceiling_usd: phase.ceiling_usd,
+      spent_usd: phase.spent_usd,
+      economy: phase.economy ?? null
+    }))
+  };
+}
+function hostTokenCeiling(budget, phaseId) {
+  if (budget === null || !isHostTokens(budget, phaseId))
+    return null;
+  if (phaseId !== undefined && phaseId !== null) {
+    const phase = budget.phases.find((entry) => entry.id === phaseId);
+    if (phase !== undefined)
+      return phase.ceiling_usd;
+  }
+  return budget.ceiling_usd;
+}
+
+// src/core/budget/remainingWork.ts
+import { existsSync as existsSync7, readFileSync as readFileSync7 } from "node:fs";
+import { join as join8 } from "node:path";
+
+// src/core/run/buildProgress.ts
+import { existsSync as existsSync6, readFileSync as readFileSync6 } from "node:fs";
+import { join as join7 } from "node:path";
+
+// src/core/schemas/waves.ts
+function validateWaves(input) {
+  const issues = [];
+  const doc = asDocument(input, issues);
+  if (!doc)
+    return result(issues);
+  requireKeys(doc, ["version", "waves"], "", issues);
+  requireVersion1(doc, issues);
+  if (!requireArray(doc.waves, "waves", issues))
+    return result(issues);
+  const waves = doc.waves;
+  if (waves.length === 0)
+    issues.push({ path: "waves", message: "must not be empty" });
+  if (waves.length > MAX_WAVES) {
+    issues.push({ path: "waves", message: `${waves.length} waves exceeds the ${MAX_WAVES} cap` });
+  }
+  const seenWave = new Set;
+  const seenStory = new Map;
+  let previousNumber = 0;
+  let total = 0;
+  waves.forEach((wave, i) => {
+    const path = `waves[${i}]`;
+    if (!isRecord(wave)) {
+      issues.push({ path, message: "expected a mapping" });
+      return;
+    }
+    requireKeys(wave, ["id", "stories"], path, issues);
+    requirePattern(wave.id, WAVE_ID_RE, "a wave id like `W1`", `${path}.id`, issues);
+    if (typeof wave.id === "string" && WAVE_ID_RE.test(wave.id)) {
+      if (seenWave.has(wave.id)) {
+        issues.push({ path: `${path}.id`, message: `\`${wave.id}\` is listed twice` });
+      }
+      seenWave.add(wave.id);
+      const number = Number(wave.id.slice(1));
+      if (number <= previousNumber) {
+        issues.push({
+          path: `${path}.id`,
+          message: `\`${wave.id}\` comes after \`W${String(previousNumber)}\` — waves are listed in execution order, so ids ascend`
+        });
+      }
+      previousNumber = Math.max(previousNumber, number);
+    }
+    const stories = requireStringList(wave.stories, `${path}.stories`, issues, {
+      nonEmpty: true,
+      max: MAX_STORIES_PER_WAVE,
+      pattern: STORY_ID_RE,
+      patternName: "a story id like `S3`",
+      unique: true
+    });
+    total += stories.length;
+    const waveId = typeof wave.id === "string" ? wave.id : path;
+    for (const story of stories) {
+      const already = seenStory.get(story);
+      if (already !== undefined) {
+        issues.push({
+          path: `${path}.stories`,
+          message: `\`${story}\` is already scheduled in ${already} — a story runs in exactly one wave`
+        });
+        continue;
+      }
+      seenStory.set(story, waveId);
+    }
+  });
+  if (total > MAX_PLAN_STORIES) {
+    issues.push({ path: "waves", message: `${total} scheduled stories exceeds the ${MAX_PLAN_STORIES} cap` });
+  }
+  return result(issues);
+}
+function asWavesFile(input) {
+  const doc = input;
+  return { version: doc.version ?? 1, waves: doc.waves ?? [] };
+}
+
+// src/core/detect/walk.ts
+var SKIPPED_DIRS = new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "bin",
+  "obj",
+  "target",
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".next",
+  ".expo",
+  ".gradle",
+  "vendor",
+  "coverage",
+  "graphify-out",
+  ".tldrx",
+  "tldrx-work",
+  ".idea",
+  ".vscode",
+  "Pods",
+  "DerivedData",
+  ".terraform",
+  ".turbo",
+  ".cache",
+  "storybook-static",
+  "playwright-report",
+  "test-results"
+]);
+
+// src/core/plan/branchModel.ts
+var BRANCH_MODELS = ["per-epic", "integration"];
+function isBranchModelKind(value) {
+  return typeof value === "string" && BRANCH_MODELS.includes(value);
+}
+
+// src/core/experts/expertDocument.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { join as join3 } from "node:path";
+
+// src/core/experts/loadExperts.ts
+import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync2, statSync } from "node:fs";
+import { join as join2 } from "node:path";
+
+// src/core/init/competencyLevel.ts
+var EVIDENCE_KINDS = ["code", "run", "test", "doc", "answer"];
+var ALLOWED_KINDS = EVIDENCE_KINDS.join(", ");
+function isEvidenceKind(value) {
+  return EVIDENCE_KINDS.includes(value);
+}
+var EVIDENCE_CONFIDENCES = ["measured", "inferred", "assumed"];
+function isEvidenceConfidence(value) {
+  return EVIDENCE_CONFIDENCES.includes(value);
+}
+var WEIGHTS = { code: 1, run: 1, test: 1, doc: 0.5, answer: 0.8 };
+var CROSS_MULTIPLIER = 2;
+var ASSUMED_MULTIPLIER = 0.5;
+var THRESHOLDS = [0.5, 1.5, 3, 6, 20];
+var RECENCY_FLOOR = 0.25;
+var RECENCY_HALFLIFE_DAYS = 365;
+var NO_RUN_CAP = 3;
+var MIN_KINDS_FOR_TOP = 2;
+var DAY_MS = 86400000;
+function competencyLevel(evidence, now = new Date) {
+  if (evidence.length === 0)
+    return 0;
+  let weighted = 0;
+  const sources = new Set;
+  const kinds = new Set;
+  for (const item of evidence) {
+    const ageDays = daysBetween(item.at, now);
+    if (ageDays === null)
+      continue;
+    weighted += recency(ageDays) * weightOf(item);
+    sources.add(item.src);
+    kinds.add(item.kind);
+  }
+  let level = THRESHOLDS.filter((threshold) => weighted >= threshold).length;
+  if (!kinds.has("run"))
+    level = Math.min(level, NO_RUN_CAP);
+  if (level === 5 && kinds.size < MIN_KINDS_FOR_TOP)
+    level = 4;
+  return Math.min(level, sources.size);
+}
+function weightOf(item) {
+  const base = WEIGHTS[item.kind];
+  const cross = item.cross === true ? CROSS_MULTIPLIER : 1;
+  const confidence = item.confidence === "assumed" ? ASSUMED_MULTIPLIER : 1;
+  return base * cross * confidence;
+}
+function recency(ageDays) {
+  return Math.max(RECENCY_FLOOR, 1 - ageDays / RECENCY_HALFLIFE_DAYS);
+}
+function daysBetween(at, now) {
+  const then = Date.parse(at);
+  if (Number.isNaN(then))
+    return null;
+  return Math.max(0, (now.getTime() - then) / DAY_MS);
+}
+
+// src/core/experts/evidenceSrc.ts
+function checkEvidenceSrc(kind, src) {
+  const parsed = classifySrc(src);
+  if ("message" in parsed)
+    return { reason: "malformed-src" };
+  return matchesKind(kind, parsed) ? null : { reason: "kind-mismatch" };
+}
+function matchesKind(kind, ref) {
+  switch (kind) {
+    case "code":
+      return ref.kind === "file";
+    case "run":
+      return ref.kind === "cmd" || isRunArtifact(ref);
+    case "test":
+      return ref.kind === "file" || ref.kind === "cmd";
+    case "doc":
+      return ref.kind === "doc";
+    case "answer":
+      return ref.kind === "fact";
+  }
+}
+function isRunArtifact(ref) {
+  return ref.kind === "file" && ref.repo === null && ref.path.startsWith("tldrx-work/");
+}
+
+// src/core/experts/readEvidenceRows.ts
+function readEvidenceRows(input) {
+  if (!Array.isArray(input))
+    return { evidence: [], ignored: [] };
+  const evidence = [];
+  const counts = new Map;
+  const refuse = (reason, kind, src) => {
+    const key = `${reason} ${reason === "unknown-kind" ? kind : `${kind} ${src}`}`;
+    const seen = counts.get(key);
+    counts.set(key, seen === undefined ? { reason, kind, src, count: 1 } : { ...seen, count: seen.count + 1 });
+  };
+  for (const raw of input) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+      continue;
+    const row = raw;
+    const kind = str2(row.kind);
+    const src = str2(row.src);
+    const at = str2(row.at);
+    if (src === "" || at === "")
+      continue;
+    if (!isEvidenceKind(kind)) {
+      refuse("unknown-kind", kind, "");
+      continue;
+    }
+    const problem = checkEvidenceSrc(kind, src);
+    if (problem !== null) {
+      refuse(problem.reason, kind, src);
+      continue;
+    }
+    const confidence = str2(row.confidence);
+    evidence.push({
+      kind,
+      src,
+      at,
+      ...row.cross === true ? { cross: true } : {},
+      ...isEvidenceConfidence(confidence) ? { confidence } : {}
+    });
+  }
+  return { evidence, ignored: [...counts.values()] };
+}
+function str2(value) {
+  return typeof value === "string" ? value : "";
+}
+
+// src/core/experts/loadExperts.ts
+var EXPERTS_DIRNAME = "experts";
+var COMPETENCIES_FILE = "competencies.yml";
+var EXPERT_FILE = "expert.md";
+function expertsDir(root) {
+  return join2(root, PROJECT_FRAMEWORK_DIR, EXPERTS_DIRNAME);
+}
+function expertDir(root, name) {
+  return join2(expertsDir(root), name);
+}
+function loadExperts(root, now = new Date) {
+  const dir = expertsDir(root);
+  if (!existsSync2(dir))
+    return [];
+  const names = readdirSync(dir).filter((entry) => statSync(join2(dir, entry)).isDirectory()).sort();
+  return names.map((name) => loadExpert(root, name, now));
+}
+function loadExpert(root, name, now = new Date) {
+  const dir = expertDir(root, name);
+  const path = join2(dir, COMPETENCIES_FILE);
+  const empty = { name, dir, status: "unknown", lastTrained: null, areas: [], drifted: [] };
+  if (!existsSync2(path))
+    return { ...empty, error: `${COMPETENCIES_FILE} is missing` };
+  let doc;
+  try {
+    const parsed = parseYaml(readFileSync2(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return { ...empty, error: `${COMPETENCIES_FILE} is not a mapping` };
+    }
+    doc = parsed;
+  } catch (error) {
+    return { ...empty, error: error instanceof Error ? error.message : String(error) };
+  }
+  const areas = Array.isArray(doc.areas) ? doc.areas.map((area) => toArea(name, area, now)).filter((area) => area !== null) : [];
+  return {
+    name: typeof doc.expert === "string" && doc.expert !== "" ? doc.expert : name,
+    dir,
+    status: typeof doc.status === "string" ? doc.status : "unknown",
+    lastTrained: typeof doc.last_trained === "string" ? doc.last_trained : null,
+    areas,
+    drifted: areas.filter((area) => area.storedLevel !== null && area.storedLevel !== area.level),
+    error: null
+  };
+}
+function toArea(expert, input, now) {
+  if (typeof input !== "object" || input === null || Array.isArray(input))
+    return null;
+  const raw = input;
+  const id = str3(raw.id) !== "" ? str3(raw.id) : str3(raw.area);
+  if (id === "")
+    return null;
+  const { evidence, ignored } = readEvidenceRows(raw.evidence);
+  return {
+    id,
+    title: str3(raw.title) !== "" ? str3(raw.title) : id,
+    storedLevel: typeof raw.level === "number" ? raw.level : null,
+    level: competencyLevel(evidence, now),
+    trainPrompt: str3(raw.train_prompt) !== "" ? str3(raw.train_prompt) : `tldrx expert train ${expert} --area ${id} --mode light`,
+    evidence,
+    ignored,
+    newestEvidence: newestDate(evidence)
+  };
+}
+function newestDate(evidence) {
+  let newest = null;
+  for (const item of evidence) {
+    if (newest === null || item.at > newest)
+      newest = item.at;
+  }
+  return newest;
+}
+function str3(value) {
+  return typeof value === "string" ? value : "";
+}
+
+// src/core/experts/expertDocument.ts
+var H2_RE = /^##\s+(.+?)\s*$/;
+function readExpertDocument(root, name) {
+  const path = join3(expertDir(root, name), EXPERT_FILE);
+  if (!existsSync3(path)) {
+    return { path, exists: false, frontMatter: new Map, body: "" };
+  }
+  const text = readFileSync3(path, "utf8");
+  const { frontMatter, body } = splitFrontMatter(text);
+  return { path, exists: true, frontMatter, body };
+}
+function splitFrontMatter(text) {
+  const frontMatter = new Map;
+  if (!text.startsWith(`---
+`))
+    return { frontMatter, body: text };
+  const end = text.indexOf(`
+---`, 3);
+  if (end === -1)
+    return { frontMatter, body: text };
+  for (const line of text.slice(4, end).split(`
+`)) {
+    const colon = line.indexOf(":");
+    if (colon <= 0 || line.trimStart().startsWith("#"))
+      continue;
+    const key = line.slice(0, colon).trim();
+    const value = line.slice(colon + 1).replace(/#.*$/, "").trim().replace(/^"(.*)"$/, "$1");
+    if (key !== "")
+      frontMatter.set(key, value);
+  }
+  const newline = text.indexOf(`
+`, end + 1);
+  return { frontMatter, body: newline === -1 ? "" : text.slice(newline + 1) };
+}
+function section(body, heading) {
+  const lines = body.split(`
+`);
+  const collected = [];
+  let inside = false;
+  for (const line of lines) {
+    const match = H2_RE.exec(line);
+    if (match !== null) {
+      if (inside)
+        break;
+      inside = match[1] === heading;
+      continue;
+    }
+    if (inside)
+      collected.push(line);
+  }
+  return collected.join(`
+`).trim();
+}
+
+// src/core/experts/expertDomain.ts
+var PLACEHOLDER_PATHS = new Set(["path/to/module", "path/to/other"]);
+function readExpertDomain(root, name) {
+  const doc = readExpertDocument(root, name);
+  if (!doc.exists)
+    return { name, exists: false, kind: "", repos: [], paths: [] };
+  return {
+    name,
+    exists: true,
+    kind: doc.frontMatter.get("kind") ?? "",
+    repos: parseList(doc.frontMatter.get("repos") ?? ""),
+    paths: domainPaths(section(doc.body, "Domain"))
+  };
+}
+function parseList(value) {
+  const inner = value.trim().replace(/^\[/, "").replace(/\]$/, "");
+  return inner.split(",").map((item) => item.trim().replace(/^["']|["']$/g, "")).filter((item) => item !== "");
+}
+function domainPaths(body) {
+  const paths = [];
+  for (const line of body.split(`
+`)) {
+    const bullet = /^\s*[-*]\s+(.*)$/.exec(line);
+    if (bullet === null)
+      continue;
+    const text = (bullet[1] ?? "").trim();
+    if (/^repo\s/i.test(text))
+      continue;
+    const code = /`([^`]+)`/.exec(text);
+    const raw = (code?.[1] ?? text.split(/\s+—\s+/)[0] ?? "").trim();
+    const path = normalisePath(raw);
+    if (path === "" || PLACEHOLDER_PATHS.has(path) || !path.includes("/"))
+      continue;
+    if (!paths.includes(path))
+      paths.push(path);
+  }
+  return paths;
+}
+function normalisePath(raw) {
+  return raw.trim().replace(/^[a-z0-9-]+:(?=[^/])/i, "").replace(/^\.\//, "").replace(/\/+$/, "").replace(/\\/g, "/");
+}
+function pathsIntersect(a, b) {
+  const left = normalisePath(a);
+  const right = normalisePath(b);
+  if (left === "" || right === "")
+    return false;
+  if (left === right)
+    return true;
+  return left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+// src/core/experts/expertKnowledge.ts
+var DEFAULT_KNOWLEDGE_MAX_BYTES = 48 * 1024;
+
+// src/core/facilitator/paths.ts
+import { join as join4, relative, sep } from "node:path";
+
+// src/core/text/evidence.ts
+var EVIDENCE_VERSION = 1;
+var EVIDENCE_FILE = "evidence.md";
+var GATE_EVIDENCE_DIR = "gate-evidence";
+function gateEvidenceRelPath(phaseId, stageId) {
+  return `${phaseId}/${GATE_EVIDENCE_DIR}/${stageId}.md`;
+}
+var EVIDENCE_VERDICTS = ["sign", "sign-with-fixlist", "refuse"];
+var EVIDENCE_ROLES = ["agent"];
+var DIFF_VS_STORIES = ["matches", "diverges", "n-a"];
+var REQUIRED_EVIDENCE_KEYS = [
+  "version",
+  "gate",
+  "role",
+  "by",
+  "at",
+  "verdict",
+  "read",
+  "citations",
+  "touches",
+  "diff_vs_stories"
+];
+function parseEvidence(text) {
+  const parsed = parseFrontMatter(text);
+  const body = parseHandoff(parsed.frontMatter.body);
+  const bodyLine = parsed.frontMatter.bodyLine;
+  if (parsed.doc === null) {
+    return {
+      front: null,
+      frontIssues: [front(0, parsed.issue?.message ?? "front matter could not be read")],
+      body,
+      bodyLine
+    };
+  }
+  if (!isRecord2(parsed.doc)) {
+    return {
+      front: null,
+      frontIssues: [front(0, "front matter is empty — it must be a mapping of the keys design §A.5 names")],
+      body,
+      bodyLine
+    };
+  }
+  const issues = [];
+  const doc = parsed.doc;
+  for (const key of REQUIRED_EVIDENCE_KEYS) {
+    if (!(key in doc) || doc[key] === undefined) {
+      issues.push(front(0, `front matter is missing required key \`${key}\``));
+    }
+  }
+  const version = doc.version;
+  if (version !== undefined && version !== EVIDENCE_VERSION) {
+    issues.push(front(0, `\`version\` must be ${String(EVIDENCE_VERSION)}, got ${describe(version)}`));
+  }
+  const gate = requireText(doc.gate, "gate", issues);
+  const role = requireEnum2(doc.role, EVIDENCE_ROLES, "role", issues);
+  const by = requireText(doc.by, "by", issues);
+  const at = requireText(doc.at, "at", issues);
+  const verdict = requireEnum2(doc.verdict, EVIDENCE_VERDICTS, "verdict", issues);
+  const read = requireStrings(doc.read, "read", issues);
+  const citations = requireCitations(doc.citations, issues);
+  const touches = requireTouches(doc.touches, issues);
+  const diff = requireEnum2(doc.diff_vs_stories, DIFF_VS_STORIES, "diff_vs_stories", issues);
+  const caveats = doc.caveats === undefined ? [] : requireStrings(doc.caveats, "caveats", issues);
+  const recommend = requireRecommendations(doc.recommend, issues);
+  if (issues.length > 0)
+    return { front: null, frontIssues: issues, body, bodyLine };
+  return {
+    front: {
+      version: EVIDENCE_VERSION,
+      gate,
+      role,
+      by,
+      at,
+      verdict,
+      read,
+      citations,
+      touches,
+      diff_vs_stories: diff,
+      caveats,
+      recommend
+    },
+    frontIssues: [],
+    body,
+    bodyLine
+  };
+}
+var GUIDANCE = {
+  Read: "One bullet per file or artefact you opened, each ending with a `[src: …]` token for it.",
+  "Citations checked": "Which of this stage's citations you re-checked, and what each one turned out to be. " + "Sample honestly: `citations.sampled` above must match what is listed here.",
+  "Touches audited": "The touched paths you looked at, and every path outside the surface the What and the " + "stories declared. Name a new area rather than absorbing it.",
+  Verdict: "SIGN, SIGN-with-fixlist or REFUSE, and the measurement behind it — a command you ran, " + "a file you read. A verdict with no source is an opinion."
+};
+function front(line, message) {
+  return { kind: "front-matter", line, message };
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireText(value, key, issues) {
+  if (typeof value === "string" && value.trim() !== "")
+    return value.trim();
+  if (value !== undefined)
+    issues.push(front(0, `\`${key}\` must be a non-empty string, got ${describe(value)}`));
+  return "";
+}
+function requireEnum2(value, allowed, key, issues) {
+  if (typeof value === "string" && allowed.includes(value))
+    return value;
+  if (value !== undefined) {
+    issues.push(front(0, `\`${key}\` must be one of ${allowed.join(" | ")}, got ${describe(value)}`));
+  }
+  return allowed[0];
+}
+function requireStrings(value, key, issues) {
+  if (!Array.isArray(value)) {
+    if (value !== undefined)
+      issues.push(front(0, `\`${key}\` must be a list, got ${describe(value)}`));
+    return [];
+  }
+  const out = [];
+  for (const [i, entry] of value.entries()) {
+    if (typeof entry === "string")
+      out.push(entry);
+    else
+      issues.push(front(0, `\`${key}[${String(i)}]\` must be a string, got ${describe(entry)}`));
+  }
+  return out;
+}
+function requireCount(value, key, issues) {
+  if (typeof value === "number" && Number.isInteger(value) && value >= 0)
+    return value;
+  issues.push(front(0, `\`${key}\` must be a whole number of 0 or more, got ${describe(value)}`));
+  return 0;
+}
+function requireCitations(value, issues) {
+  if (!isRecord2(value)) {
+    if (value !== undefined) {
+      issues.push(front(0, "`citations` must be a mapping `{sampled, of, resolved, refuted}`, got " + describe(value)));
+    }
+    return { sampled: 0, of: 0, resolved: 0, refuted: 0 };
+  }
+  return {
+    sampled: requireCount(value.sampled, "citations.sampled", issues),
+    of: requireCount(value.of, "citations.of", issues),
+    resolved: requireCount(value.resolved, "citations.resolved", issues),
+    refuted: requireCount(value.refuted, "citations.refuted", issues)
+  };
+}
+function requireTouches(value, issues) {
+  if (!isRecord2(value)) {
+    if (value !== undefined) {
+      issues.push(front(0, "`touches` must be a mapping `{audited, outside_surface, new_areas}`, got " + describe(value)));
+    }
+    return { audited: 0, outside_surface: 0, new_areas: [] };
+  }
+  return {
+    audited: requireCount(value.audited, "touches.audited", issues),
+    outside_surface: requireCount(value.outside_surface, "touches.outside_surface", issues),
+    new_areas: requireStrings(value.new_areas, "touches.new_areas", issues)
+  };
+}
+function requireRecommendations(value, issues) {
+  if (value === undefined)
+    return [];
+  if (!Array.isArray(value)) {
+    issues.push(front(0, `\`recommend\` must be a list of {q, option, why, src}, got ${describe(value)}`));
+    return [];
+  }
+  const out = [];
+  for (const [i, entry] of value.entries()) {
+    if (!isRecord2(entry)) {
+      issues.push(front(0, `\`recommend[${String(i)}]\` must be a mapping {q, option, why, src}`));
+      continue;
+    }
+    const path = `recommend[${String(i)}]`;
+    for (const key of ["q", "option", "why", "src"]) {
+      if (!(key in entry))
+        issues.push(front(0, `\`${path}\` is missing \`${key}\``));
+    }
+    out.push({
+      q: requireText(entry.q, `${path}.q`, issues),
+      option: requireText(entry.option, `${path}.option`, issues),
+      why: requireText(entry.why, `${path}.why`, issues),
+      src: requireText(entry.src, `${path}.src`, issues)
+    });
+  }
+  return out;
+}
+function describe(value) {
+  if (value === null || value === undefined)
+    return "nothing";
+  if (Array.isArray(value))
+    return "a list";
+  if (typeof value === "object")
+    return "a mapping";
+  return typeof value === "string" ? `\`${value}\`` : String(value);
+}
+
+// src/core/facilitator/paths.ts
+function agentDir(runDir, stageId) {
+  return join4(runDir, ".agent", stageId);
+}
+function evidencePath(runDir, stageId) {
+  return join4(agentDir(runDir, stageId), EVIDENCE_FILE);
+}
+function gateEvidencePath(runDir, phaseId, stageId) {
+  return join4(runDir, ...gateEvidenceRelPath(phaseId, stageId).split("/"));
+}
+
+// src/core/facilitator/dispatchNotes.ts
+var DISPATCH_NOTES_MAX_BYTES = 8 * 1024;
+
+// src/core/experts/stackExperts.ts
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "node:fs";
+import { join as join5 } from "node:path";
+function stackExpertNames(root, repos) {
+  const path = join5(root, PROJECT_FRAMEWORK_DIR, "workspace.yml");
+  if (!existsSync4(path))
+    return [];
+  let doc;
+  try {
+    doc = parseYaml(readFileSync4(path, "utf8"));
+  } catch {
+    return [];
+  }
+  const list = doc?.repos;
+  if (!Array.isArray(list))
+    return [];
+  const names = [];
+  for (const row of list) {
+    if (typeof row?.name !== "string" || !repos.includes(row.name))
+      continue;
+    const stack = Array.isArray(row.stack) ? row.stack : [];
+    for (const language of stack) {
+      if (typeof language !== "string" || language === "")
+        continue;
+      const expert = `${language}-stack`;
+      if (!names.includes(expert))
+        names.push(expert);
+    }
+  }
+  return names;
+}
+
+// src/core/build/prompts.ts
+var MAX_TOUCHED_BYTES = 64 * 1024;
+
+// src/core/build/plan.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "node:fs";
+import { join as join6 } from "node:path";
+
+// src/core/schemas/budget.ts
+function validateBudget(input) {
+  const issues = [];
+  const deprecations = [];
+  const doc = asDocument(input, issues);
+  if (!doc)
+    return result(issues);
+  requireVersion(doc, issues, deprecations);
+  requireKeys(doc, ["run", "ceiling_usd", "spent_usd", "per_phase_usd"], "", issues);
+  requireString(doc.run, "run", issues);
+  requireNumber(doc.ceiling_usd, "ceiling_usd", issues);
+  requireNumber(doc.spent_usd, "spent_usd", issues);
+  if (doc.economy !== undefined && doc.economy !== null) {
+    requireEnum(doc.economy, ECONOMIES, "economy", issues);
+  }
+  if (requireRecord(doc.per_phase_usd, "per_phase_usd", issues)) {
+    for (const [key, value] of Object.entries(doc.per_phase_usd)) {
+      requireNumber(value, `per_phase_usd.${key}`, issues);
+    }
+  }
+  return result(issues, deprecations);
+}
+
+// src/core/build/plan.ts
+var BUILD_PHASE = "04-build";
+var PLAN_PHASE = "03-plan";
+var PLAN_BUDGET_FILE = "budget.yml";
+function loadPlanPrices(planDir, stories) {
+  const empty = new Map;
+  const path = join6(planDir, PLAN_BUDGET_FILE);
+  if (!existsSync5(path))
+    return { prices: empty, issue: null };
+  let doc;
+  try {
+    doc = parseYaml(readFileSync5(path, "utf8"));
+  } catch (error) {
+    return { prices: empty, issue: budgetIgnored(`it does not parse (${String(error)})`) };
+  }
+  const validation = validateBudget(doc);
+  if (!validation.ok) {
+    const first = validation.issues[0];
+    return {
+      prices: empty,
+      issue: budgetIgnored(`it does not validate (${first?.path ?? ""} ${first?.message ?? "schema error"})`)
+    };
+  }
+  const declared = doc.economy;
+  if (declared === "host-tokens") {
+    return {
+      prices: empty,
+      issue: budgetIgnored("it is priced in `host-tokens`, and those numbers are not dollars a spawn may spend")
+    };
+  }
+  const perPhase = doc.per_phase_usd ?? {};
+  const prices = new Map;
+  const skipped = [];
+  for (const [key, value] of Object.entries(perPhase)) {
+    if (!STORY_ID_RE.test(key))
+      continue;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+      skipped.push(`${key} (${String(value)})`);
+      continue;
+    }
+    if (!stories.has(key)) {
+      skipped.push(`${key} (not scheduled)`);
+      continue;
+    }
+    prices.set(key, value);
+  }
+  if (prices.size === 0) {
+    return {
+      prices: empty,
+      issue: skipped.length === 0 ? null : budgetIgnored(`no usable story price in it — skipped ${skipped.join(", ")}`)
+    };
+  }
+  return {
+    prices,
+    issue: skipped.length === 0 ? null : `note: ${PLAN_PHASE}/${PLAN_BUDGET_FILE} priced ${String(prices.size)} story(ies); ` + `skipped ${skipped.join(", ")}`
+  };
+}
+function budgetIgnored(why) {
+  return `warning: ${PLAN_PHASE}/${PLAN_BUDGET_FILE} was ignored because ${why} — ` + "story caps fall back to an equal share of the stage ceiling";
+}
+
+// src/core/build/implicitPlan.ts
+var IMPLICIT_PLAN_FILE = "implicit-plan.yml";
+var IMPLICIT_PLAN_REL = `${BUILD_PHASE}/${IMPLICIT_PLAN_FILE}`;
+var IMPLICIT_STORY_NOTE = "Plan was skipped by the scope; this single story applies the run's answered decisions " + "to the files it touches.";
+var EMPTY_ANSWER_INDEX = {
+  answers: new Map,
+  restated: new Map,
+  lines: new Map
+};
+
+// src/core/run/buildProgress.ts
+var PLAN_DIR = "03-plan";
+var BUILD_PHASE2 = "04-build";
+var STATUS_RE = /^status\s*:\s*(\w+)\s*$/m;
+function buildProgress(runDir) {
+  const wavesPath = join7(runDir, PLAN_DIR, "waves.yml");
+  const implicitPath = join7(runDir, BUILD_PHASE2, IMPLICIT_PLAN_FILE);
+  const implicit = !existsSync6(wavesPath) && existsSync6(implicitPath);
+  const path = implicit ? implicitPath : wavesPath;
+  if (!existsSync6(path))
+    return null;
+  let doc;
+  try {
+    doc = parseYaml(readFileSync6(path, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!validateWaves(doc).ok)
+    return null;
+  const costs = costByStory(runDir);
+  const waves = [];
+  let done = 0;
+  let total = 0;
+  let cost = 0;
+  for (const wave of asWavesFile(doc).waves) {
+    const stories = [];
+    for (const id of wave.stories) {
+      const status = implicit ? implicitStatus(implicitPath) : statusOf(runDir, id);
+      const spent = costs.get(id) ?? 0;
+      stories.push({ id, status, cost_usd: spent });
+      total += 1;
+      cost += spent;
+      if (status === "done")
+        done += 1;
+    }
+    waves.push({ id: wave.id, stories });
+  }
+  return { waves, done, total, cost_usd: round(cost), implicit };
+}
+function implicitStatus(path) {
+  try {
+    return STATUS_RE.exec(readFileSync6(path, "utf8"))?.[1] ?? "todo";
+  } catch {
+    return "todo";
+  }
+}
+function statusOf(runDir, id) {
+  const path = join7(runDir, PLAN_DIR, "stories", `${id}.md`);
+  if (!existsSync6(path))
+    return "missing";
+  try {
+    return STATUS_RE.exec(readFileSync6(path, "utf8"))?.[1] ?? "todo";
+  } catch {
+    return "todo";
+  }
+}
+function costByStory(runDir) {
+  const costs = new Map;
+  const path = join7(runDir, "events.jsonl");
+  if (!existsSync6(path))
+    return costs;
+  let text;
+  try {
+    text = readFileSync6(path, "utf8");
+  } catch {
+    return costs;
+  }
+  for (const line of text.split(`
+`)) {
+    if (line.trim() === "")
+      continue;
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (event.type !== "agent.result")
+      continue;
+    const payload = event.payload;
+    const story = typeof payload.story === "string" ? payload.story : payload.key;
+    if (typeof story !== "string" || story === "")
+      continue;
+    costs.set(story, round((costs.get(story) ?? 0) + (typeof event.cost_usd === "number" ? event.cost_usd : 0)));
+  }
+  return costs;
+}
+function round(n) {
+  return Math.round(n * 100) / 100;
+}
+
+// src/core/build/review.ts
+var VERDICT_WORDS = ["approve", "fixlist", "changes"];
+var VERDICT_ENUM = VERDICT_WORDS.join("|");
+var REVIEWER_FAILED = "the reviewer sub-agent failed";
+function looksLikeReviewerError(detail) {
+  const text = detail.trim();
+  return text === REVIEWER_FAILED || looksLikeSpawnError(text);
+}
+function looksLikeSpawnError(detail) {
+  const text = detail.trim();
+  return text.startsWith("claude exited ") || text.startsWith("claude timed out") || text.startsWith("stopped after ");
+}
+
+// src/core/budget/remainingWork.ts
+var MAX_ATTEMPTS = 2;
+var REVIEWER_SHARE = 0.25;
+var REVIEWER_FLOOR_USD = 1;
+function remainingWork(input) {
+  try {
+    return measure(input);
+  } catch {
+    return staticOnly(input);
+  }
+}
+function staticOnly(input) {
+  return {
+    basis: "static",
+    usd: input.stageBudgetUsd,
+    rawUsd: input.stageBudgetUsd,
+    staticUsd: input.stageBudgetUsd,
+    clamped: false,
+    economy: input.economy ?? DEFAULT_ECONOMY,
+    attended: input.attended === true,
+    stories: [],
+    done: 0,
+    total: 0,
+    blocked: []
+  };
+}
+function measure(input) {
+  const economy = input.economy ?? DEFAULT_ECONOMY;
+  const hostPaysDeveloper = economy === "host-tokens" || input.attended === true;
+  const fallback = {
+    basis: "static",
+    usd: input.stageBudgetUsd,
+    rawUsd: input.stageBudgetUsd,
+    staticUsd: input.stageBudgetUsd,
+    clamped: false,
+    economy,
+    attended: input.attended === true,
+    stories: [],
+    done: 0,
+    total: 0,
+    blocked: []
+  };
+  if (input.phaseId !== BUILD_PHASE2)
+    return fallback;
+  const progress = buildProgress(input.runDir);
+  if (progress === null)
+    return fallback;
+  const all = progress.waves.flatMap((wave) => wave.stories);
+  if (all.length === 0)
+    return fallback;
+  const ids = new Set(all.map((story) => story.id));
+  const prices = progress.implicit ? new Map : loadPlanPrices(join8(input.runDir, PLAN_DIR), ids).prices;
+  const verdicts = reviewVerdictsByStory(input.runDir);
+  const caps = new CapMath(input, prices, all.length);
+  const stories = [];
+  const blocked = [];
+  let raw = 0;
+  for (const story of all) {
+    if (story.status === "done")
+      continue;
+    if (story.status === "blocked") {
+      blocked.push(story.id);
+      continue;
+    }
+    const attemptsLeft = Math.max(MAX_ATTEMPTS - (verdicts.get(story.id) ?? 0), 0);
+    if (attemptsLeft === 0)
+      continue;
+    const developerTurns = Math.max(attemptsLeft - (story.status === "review" ? 1 : 0), 0);
+    const developerCapUsd = hostPaysDeveloper ? 0 : caps.developer(story.id);
+    const reviewerCapUsd = caps.reviewer(story.id);
+    const usd = round2(developerCapUsd * developerTurns + reviewerCapUsd * attemptsLeft);
+    if (usd <= 0 && developerTurns === 0 && attemptsLeft === 0)
+      continue;
+    stories.push({
+      id: story.id,
+      status: story.status,
+      developerTurns,
+      reviews: attemptsLeft,
+      developerCapUsd,
+      reviewerCapUsd,
+      usd
+    });
+    raw = round2(raw + usd);
+  }
+  stories.sort((a, b) => b.usd - a.usd || a.id.localeCompare(b.id));
+  const clamped = raw > input.stageBudgetUsd;
+  return {
+    basis: "plan",
+    usd: clamped ? round2(input.stageBudgetUsd) : raw,
+    rawUsd: raw,
+    staticUsd: input.stageBudgetUsd,
+    clamped,
+    economy,
+    attended: input.attended === true,
+    stories,
+    done: progress.done,
+    total: progress.total,
+    blocked
+  };
+}
+class CapMath {
+  input;
+  prices;
+  storyCount;
+  scale;
+  maxBudgetUsd;
+  constructor(input, prices, storyCount) {
+    this.input = input;
+    this.prices = prices;
+    this.storyCount = storyCount;
+    let sum = 0;
+    for (const price of prices.values()) {
+      if (Number.isFinite(price) && price > 0)
+        sum += price;
+    }
+    this.scale = input.stageBudgetUsd <= 0 || sum <= input.stageBudgetUsd ? 1 : input.stageBudgetUsd / sum;
+    this.maxBudgetUsd = this.agentCap(1);
+  }
+  developer(storyId) {
+    const price = this.priceOf(storyId);
+    if (price === null)
+      return this.agentCap(1 / this.worstCaseShares());
+    return this.agentCap(this.shareOf(price / (MAX_ATTEMPTS * (1 + REVIEWER_SHARE))));
+  }
+  reviewer(storyId) {
+    const price = this.priceOf(storyId);
+    const derived = price === null ? this.agentCap(REVIEWER_SHARE / this.worstCaseShares()) : this.agentCap(this.shareOf(price * REVIEWER_SHARE / (MAX_ATTEMPTS * (1 + REVIEWER_SHARE))));
+    const floor = Math.min(REVIEWER_FLOOR_USD, Math.max(this.input.stageBudgetUsd - this.input.stageSpentUsd, 0));
+    return round2(Math.min(Math.max(derived, floor), this.maxBudgetUsd));
+  }
+  priceOf(storyId) {
+    const price = this.prices.get(storyId);
+    if (price === undefined || !Number.isFinite(price) || price <= 0)
+      return null;
+    return price * this.scale;
+  }
+  shareOf(usd) {
+    return this.input.stageBudgetUsd <= 0 ? 1 : usd / this.input.stageBudgetUsd;
+  }
+  worstCaseShares() {
+    return Math.max(this.storyCount, 1) * MAX_ATTEMPTS * (1 + REVIEWER_SHARE);
+  }
+  agentCap(share) {
+    const candidates = [this.input.stageBudgetUsd * share, this.input.perAgentMaxUsd];
+    const flag = this.input.maxUsd;
+    if (flag !== undefined && flag !== null)
+      candidates.push(flag);
+    return round2(Math.min(...candidates));
+  }
+}
+function reviewVerdictsByStory(runDir) {
+  const counts = new Map;
+  const path = join8(runDir, "events.jsonl");
+  if (!existsSync7(path))
+    return counts;
+  let text;
+  try {
+    text = readFileSync7(path, "utf8");
+  } catch {
+    return counts;
+  }
+  for (const line of text.split(`
+`)) {
+    if (line.trim() === "")
+      continue;
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const payload = event.payload ?? {};
+    const story = payload.story;
+    if (typeof story !== "string" || story === "")
+      continue;
+    if (event.type === "story.reopened") {
+      counts.set(story, 0);
+      continue;
+    }
+    if (event.type !== "check.passed" && event.type !== "check.failed")
+      continue;
+    if (payload.check !== "review")
+      continue;
+    if (reviewEventErrored(payload))
+      continue;
+    counts.set(story, (counts.get(story) ?? 0) + 1);
+  }
+  return counts;
+}
+function reviewEventErrored(payload) {
+  if (payload.verdict === "error")
+    return true;
+  if (payload.verdict !== "changes")
+    return false;
+  return typeof payload.detail === "string" && looksLikeReviewerError(payload.detail);
+}
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+// src/core/budget/wouldExceed.ts
+function totalSpent(budget) {
+  return budget.phases.reduce((sum, p) => sum + p.spent_usd, 0);
+}
+function wouldExceed(budget, phaseId, estimate) {
+  const phase = phaseId === null ? undefined : budget.phases.find((p) => p.id === phaseId);
+  const scope = phase === undefined ? "run" : "phase";
+  const ceiling = phase === undefined ? budget.ceiling_usd : phase.ceiling_usd;
+  const spent = phase === undefined ? totalSpent(budget) : phase.spent_usd;
+  const left = round3(ceiling - spent);
+  const exceeds = round3(spent + estimate) > ceiling;
+  const pct = ceiling === 0 ? 100 : (spent + estimate) / ceiling * 100;
+  return {
+    exceeds,
+    blocked: exceeds && budget.on_exceed === "block",
+    scope,
+    phaseId: phase === undefined ? null : phase.id,
+    remaining: left,
+    ceiling,
+    estimate,
+    warns: !exceeds && pct >= budget.warn_at_pct
+  };
+}
+function round3(n) {
+  return Math.round(n * 1e6) / 1e6;
+}
+function wouldExceedHostTokens(budget, phaseId, spentTokens) {
+  const ceiling = hostTokenCeiling(budget, phaseId);
+  if (ceiling === null)
+    return null;
+  const phase = phaseId === null ? undefined : budget.phases.find((p) => p.id === phaseId);
+  const over = ceiling > 0 && spentTokens > ceiling;
+  return {
+    over,
+    blocked: over && budget.on_host_tokens_exceed === "block",
+    scope: phase === undefined ? "run" : "phase",
+    spent: spentTokens,
+    ceiling
+  };
+}
+
+// src/core/run/gatePolicy.ts
+var GATE_POLICIES = ["human", "auto", "agent"];
+function isGatePolicy(value) {
+  return typeof value === "string" && GATE_POLICIES.includes(value);
+}
+function validateGatesPolicy(value, stageIds, issues) {
+  if (value === undefined || value === null)
+    return;
+  if (!isRecord(value)) {
+    issues.push({
+      path: "gates_policy",
+      message: `expected a mapping of stage id -> ${GATE_POLICIES.join(" | ")}`
+    });
+    return;
+  }
+  const known = new Set(stageIds);
+  for (const [key, raw] of Object.entries(value)) {
+    if (!isGatePolicy(raw)) {
+      issues.push({
+        path: `gates_policy.${key}`,
+        message: `expected one of ${GATE_POLICIES.join(" | ")}, got ${JSON.stringify(raw)}`
+      });
+    }
+    if (known.size > 0 && !known.has(key)) {
+      issues.push({ path: `gates_policy.${key}`, message: `names no stage in this run` });
+    }
+  }
+}
+
+// src/core/run/RunFile.ts
+var STAGE_STATUSES = [
+  "pending",
+  "ready",
+  "running",
+  "awaiting_answer",
+  "awaiting_gate",
+  "blocked",
+  "done",
+  "failed",
+  "skipped",
+  "cancelled"
+];
+var TERMINAL_STATUSES2 = ["done", "failed", "skipped", "cancelled"];
+var GATE_TYPES = ["approve", "checks", "auto"];
+var GATE_STATUSES = ["pending", "approved", "rejected", "n-a"];
+var ATTENDED_BY = ["host"];
+var RUN_ID_RE = /^\d{6}-[a-z0-9-]{1,40}$/;
+var PHASE_ID_RE = /^0[1-5]-[a-z]+$/;
+var MAX_PHASES2 = 5;
+var MAX_STAGES = 40;
+var MAX_TASKS = 200;
+function isTerminal2(status) {
+  return TERMINAL_STATUSES2.includes(status);
+}
+function isFinished(status) {
+  return status === "done" || status === "cancelled";
+}
+function isAttendedByHost(run) {
+  return run.attended_by === "host";
+}
+function flatten(run) {
+  const out = [];
+  for (const phase of run.phases)
+    for (const stage of phase.stages)
+      out.push({ phase, stage });
+  return out;
+}
+function stageAt(run, cursor) {
+  return flatten(run).find((e) => e.phase.id === cursor.phase && e.stage.id === cursor.stage) ?? null;
+}
+function deriveRunStatus(run) {
+  const all = flatten(run);
+  if (run.cancelled !== undefined)
+    return "cancelled";
+  if (all.some((e) => e.stage.status === "failed"))
+    return "failed";
+  if (all.length > 0 && all.every((e) => isTerminal2(e.stage.status)))
+    return "done";
+  return stageAt(run, run.cursor)?.stage.status ?? "pending";
+}
+function derivePhaseStatus(phase) {
+  if (phase.stages.length === 0)
+    return "skipped";
+  if (phase.stages.some((s) => s.status === "failed"))
+    return "failed";
+  if (phase.stages.every((s) => isTerminal2(s.status)))
+    return "done";
+  const live = phase.stages.find((s) => !isTerminal2(s.status));
+  return live?.status ?? "pending";
+}
+function validateRunFile(input) {
+  const issues = [];
+  const deprecations = [];
+  const doc = asDocument(input, issues);
+  if (!doc)
+    return result(issues);
+  requireVersion(doc, issues, deprecations);
+  requireKeys(doc, ["run", "title", "scope", "workflow", "repos", "created_at", "updated_at", "status", "cursor", "budget", "phases"], "", issues);
+  if (typeof doc.run !== "string" || !RUN_ID_RE.test(doc.run)) {
+    issues.push({ path: "run", message: "run id must match ^\\d{6}-[a-z0-9-]{1,40}$" });
+  }
+  requireString(doc.title, "title", issues);
+  requireString(doc.scope, "scope", issues);
+  requireString(doc.workflow, "workflow", issues);
+  requireString(doc.created_at, "created_at", issues);
+  requireString(doc.updated_at, "updated_at", issues);
+  requireEnum(doc.status, STAGE_STATUSES, "status", issues);
+  requireArray(doc.repos, "repos", issues);
+  let cursor = null;
+  if (isRecord(doc.cursor)) {
+    requireKeys(doc.cursor, ["phase", "stage", "task"], "cursor", issues);
+    cursor = {
+      phase: String(doc.cursor.phase ?? ""),
+      stage: String(doc.cursor.stage ?? ""),
+      task: typeof doc.cursor.task === "string" ? doc.cursor.task : null
+    };
+  } else if (doc.cursor !== undefined) {
+    issues.push({ path: "cursor", message: "expected a mapping" });
+  }
+  if (isRecord(doc.budget)) {
+    requireKeys(doc.budget, ["ceiling_usd", "spent_usd", "per_agent_max_usd"], "budget", issues);
+    requireNumber(doc.budget.ceiling_usd, "budget.ceiling_usd", issues);
+    requireNumber(doc.budget.spent_usd, "budget.spent_usd", issues);
+    requireNumber(doc.budget.per_agent_max_usd, "budget.per_agent_max_usd", issues);
+  } else if (doc.budget !== undefined) {
+    issues.push({ path: "budget", message: "expected a mapping" });
+  }
+  if (doc.build !== undefined) {
+    if (isRecord(doc.build)) {
+      requireKeys(doc.build, ["epic_branch"], "build", issues);
+      if (requireArray(doc.build.epic_branch, "build.epic_branch", issues)) {
+        doc.build.epic_branch.forEach((branch, i) => {
+          requireString(branch, `build.epic_branch[${i}]`, issues);
+        });
+      }
+      if (doc.build.branch_model !== undefined && !isBranchModelKind(doc.build.branch_model)) {
+        issues.push({
+          path: "build.branch_model",
+          message: `expected one of ${BRANCH_MODELS.join(" | ")}`
+        });
+      }
+    } else {
+      issues.push({ path: "build", message: "expected a mapping" });
+    }
+  }
+  if (doc.cancelled !== undefined) {
+    if (isRecord(doc.cancelled)) {
+      requireKeys(doc.cancelled, ["by", "at", "note"], "cancelled", issues);
+      requireString(doc.cancelled.by, "cancelled.by", issues);
+      requireString(doc.cancelled.at, "cancelled.at", issues);
+      requireString(doc.cancelled.note, "cancelled.note", issues);
+    } else {
+      issues.push({ path: "cancelled", message: "expected a mapping" });
+    }
+  }
+  if (doc.triage !== undefined) {
+    if (isRecord(doc.triage)) {
+      requireKeys(doc.triage, ["split", "depends_on"], "triage", issues);
+      requireString(doc.triage.split, "triage.split", issues);
+      if (requireArray(doc.triage.depends_on, "triage.depends_on", issues)) {
+        doc.triage.depends_on.forEach((slug, i) => {
+          requireString(slug, `triage.depends_on[${i}]`, issues);
+        });
+      }
+    } else {
+      issues.push({ path: "triage", message: "expected a mapping" });
+    }
+  }
+  if (doc.attended_by !== undefined)
+    requireEnum(doc.attended_by, ATTENDED_BY, "attended_by", issues);
+  if (doc.keep_worktrees !== undefined && typeof doc.keep_worktrees !== "boolean") {
+    issues.push({ path: "keep_worktrees", message: `expected a boolean, got ${typeof doc.keep_worktrees}` });
+  }
+  if (!requireArray(doc.phases, "phases", issues))
+    return result(issues, deprecations);
+  const phases = doc.phases;
+  if (phases.length > MAX_PHASES2) {
+    issues.push({ path: "phases", message: `${phases.length} phases exceeds the ${MAX_PHASES2} cap` });
+  }
+  const declaredStageIds = [];
+  for (const phase of phases) {
+    if (!isRecord(phase) || !Array.isArray(phase.stages))
+      continue;
+    for (const stage of phase.stages) {
+      if (isRecord(stage) && typeof stage.id === "string")
+        declaredStageIds.push(stage.id);
+    }
+  }
+  validateGatesPolicy(doc.gates_policy, declaredStageIds, issues);
+  let stageCount = 0;
+  let taskCount = 0;
+  let running = 0;
+  let cursorResolves = false;
+  let spentFromTasks = 0;
+  const phaseIds = new Set;
+  phases.forEach((phase, i) => {
+    const base = `phases[${i}]`;
+    if (!isRecord(phase)) {
+      issues.push({ path: base, message: "expected a mapping" });
+      return;
+    }
+    requireKeys(phase, ["id", "status", "stages"], base, issues);
+    const phaseId = typeof phase.id === "string" ? phase.id : "";
+    if (!PHASE_ID_RE.test(phaseId)) {
+      issues.push({ path: `${base}.id`, message: "phase id must match ^0[1-5]-[a-z]+$" });
+    }
+    if (phaseIds.has(phaseId))
+      issues.push({ path: `${base}.id`, message: `duplicate phase id ${phaseId}` });
+    phaseIds.add(phaseId);
+    requireEnum(phase.status, STAGE_STATUSES, `${base}.status`, issues);
+    if (!requireArray(phase.stages, `${base}.stages`, issues))
+      return;
+    const stageIds = new Set;
+    phase.stages.forEach((stage, j) => {
+      const path = `${base}.stages[${j}]`;
+      stageCount++;
+      if (!isRecord(stage)) {
+        issues.push({ path, message: "expected a mapping" });
+        return;
+      }
+      requireKeys(stage, ["id", "status", "expert", "model", "budget_usd", "cost_usd", "started_at", "ended_at", "inputs", "outputs", "gate", "tasks"], path, issues);
+      const stageId = typeof stage.id === "string" ? stage.id : "";
+      if (stageIds.has(stageId))
+        issues.push({ path: `${path}.id`, message: `duplicate stage id ${stageId}` });
+      stageIds.add(stageId);
+      requireEnum(stage.status, STAGE_STATUSES, `${path}.status`, issues);
+      if (stage.status === "running")
+        running++;
+      requireNumber(stage.budget_usd, `${path}.budget_usd`, issues);
+      requireNumber(stage.cost_usd, `${path}.cost_usd`, issues);
+      requireArray(stage.inputs, `${path}.inputs`, issues);
+      requireArray(stage.outputs, `${path}.outputs`, issues);
+      if (stage.stale !== undefined && typeof stage.stale !== "boolean") {
+        issues.push({ path: `${path}.stale`, message: "expected true or false" });
+      }
+      checkOrder(stage.started_at, stage.ended_at, path, issues);
+      if (cursor !== null && cursor.phase === phaseId && cursor.stage === stageId)
+        cursorResolves = true;
+      if (isRecord(stage.gate)) {
+        const gate = stage.gate;
+        requireKeys(gate, ["type", "status", "by", "at", "note"], `${path}.gate`, issues);
+        requireEnum(gate.type, GATE_TYPES, `${path}.gate.type`, issues);
+        requireEnum(gate.status, GATE_STATUSES, `${path}.gate.status`, issues);
+        if (gate.status === "approved" && (typeof gate.by !== "string" || typeof gate.at !== "string")) {
+          issues.push({ path: `${path}.gate`, message: "an approved gate needs both `by` and `at`" });
+        }
+        validateGateEvidence(gate.evidence, `${path}.gate.evidence`, issues);
+      } else if (stage.gate !== undefined) {
+        issues.push({ path: `${path}.gate`, message: "expected a mapping" });
+      }
+      if (requireArray(stage.tasks, `${path}.tasks`, issues)) {
+        const taskIds = new Set;
+        stage.tasks.forEach((task, k) => {
+          const tp = `${path}.tasks[${k}]`;
+          taskCount++;
+          if (!isRecord(task)) {
+            issues.push({ path: tp, message: "expected a mapping" });
+            return;
+          }
+          requireKeys(task, ["id", "status", "cost_usd", "error", "session_id"], tp, issues);
+          const taskId = typeof task.id === "string" ? task.id : "";
+          if (!/^t\d+$/.test(taskId))
+            issues.push({ path: `${tp}.id`, message: "task id must match ^t\\d+$" });
+          if (taskIds.has(taskId))
+            issues.push({ path: `${tp}.id`, message: `duplicate task id ${taskId}` });
+          taskIds.add(taskId);
+          requireEnum(task.status, STAGE_STATUSES, `${tp}.status`, issues);
+          if (task.cost_usd !== null)
+            requireNumber(task.cost_usd, `${tp}.cost_usd`, issues);
+          if (task.metered !== undefined && typeof task.metered !== "boolean") {
+            issues.push({ path: `${tp}.metered`, message: "expected true or false" });
+          }
+          if (task.cost_usd === null && task.metered !== false) {
+            issues.push({ path: `${tp}.metered`, message: "a null cost_usd must be marked `metered: false`" });
+          }
+          if (typeof task.cost_usd === "number")
+            spentFromTasks += task.cost_usd;
+          checkOrder(task.started_at, task.ended_at, tp, issues);
+        });
+      }
+    });
+  });
+  if (stageCount > MAX_STAGES)
+    issues.push({ path: "phases", message: `${stageCount} stages exceeds the ${MAX_STAGES} cap` });
+  if (taskCount > MAX_TASKS)
+    issues.push({ path: "phases", message: `${taskCount} tasks exceeds the ${MAX_TASKS} cap` });
+  if (running > 1)
+    issues.push({ path: "phases", message: `${running} stages are running; tldrx is single-writer` });
+  if (cursor !== null && !cursorResolves) {
+    issues.push({ path: "cursor", message: `cursor ${cursor.phase}/${cursor.stage} does not resolve to a stage` });
+  }
+  if (isRecord(doc.budget) && typeof doc.budget.spent_usd === "number") {
+    if (Math.abs(doc.budget.spent_usd - spentFromTasks) > 0.01) {
+      issues.push({
+        path: "budget.spent_usd",
+        message: `${doc.budget.spent_usd} does not match the task total ${round5(spentFromTasks)} (tolerance 0.01)`
+      });
+    }
+  }
+  return result(issues, deprecations);
+}
+function checkOrder(started, ended, path, issues) {
+  if (typeof started === "string" && typeof ended === "string" && ended < started) {
+    issues.push({ path: `${path}.ended_at`, message: "ended_at is before started_at" });
+  }
+}
+function round5(n) {
+  return Math.round(n * 100) / 100;
+}
+function asRunFile(input) {
+  return input;
+}
+var GATE_EVIDENCE_KEYS = [
+  "path",
+  "role",
+  "verdict",
+  "sampled",
+  "of",
+  "resolved",
+  "refuted",
+  "outside_surface"
+];
+function validateGateEvidence(value, base, issues) {
+  if (value === undefined || value === null)
+    return;
+  if (!isRecord(value)) {
+    issues.push({ path: base, message: "expected a mapping" });
+    return;
+  }
+  requireKeys(value, GATE_EVIDENCE_KEYS, base, issues);
+  requireString(value.path, `${base}.path`, issues);
+  requireEnum(value.role, EVIDENCE_ROLES, `${base}.role`, issues);
+  requireEnum(value.verdict, EVIDENCE_VERDICTS, `${base}.verdict`, issues);
+  for (const key of ["sampled", "of", "resolved", "refuted", "outside_surface"]) {
+    requireNumber(value[key], `${base}.${key}`, issues);
+  }
+}
+
+// src/core/budget/budgetView.ts
+function raiseCommand(runId, phaseId, amountUsd) {
+  return `tldrx budget raise ${phaseId} ${amountUsd.toFixed(2)} --run ${runId}`;
+}
+function shortBy(estimate, remaining) {
+  return Math.max(0.01, Math.ceil((estimate - remaining) * 100) / 100);
+}
+
+export { loadRunView, isAttendedByHostView, runSpend, hostTokensIn, renderRunEconomies, cursorStage, openRunViews, newestActiveRun, currentActor, nowRfc3339, DEFAULT_ON_HOST_TOKENS_EXCEED, DEFAULT_ECONOMY, economyFor, isHostTokens, validateRunBudget, asRunBudget, expertsDir, loadExperts, readExpertDomain, pathsIntersect, parseEvidence, evidencePath, gateEvidencePath, stackExpertNames, remainingWork, wouldExceed, wouldExceedHostTokens, isTerminal2 as isTerminal, isFinished, isAttendedByHost, flatten, stageAt, deriveRunStatus, derivePhaseStatus, validateRunFile, asRunFile, raiseCommand, shortBy };