freeharness 0.4.1

package/canonical/skills/subagent-driven-development/scripts/validate-handoff.mjs

@@ -0,0 +1,850 @@
+#!/usr/bin/env node
+// Validator for the subagent-driven-development artifacts (reference/brief.md and
+// reference/handoff.md). Zero dependencies; exit 0 on success, 1 on a rejected artifact or
+// on usage. USAGE lists the subcommands.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+/** Allowed handoff statuses. */
+const STATUSES = new Set(["completed", "partial", "blocked"]);
+/** Allowed per-test results. */
+const TEST_RESULTS = new Set(["pass", "fail", "unavailable"]);
+/** Stop-condition tokens a blocked handoff starts its reason with. */
+const STOP_TOKENS = new Set(["too-big", "needs-confirm", "ambiguous", "regressed", "scope"]);
+/** Tiers a brief may declare. */
+const TIERS = new Set(["strong", "standard", "fast"]);
+/** A `D:<kebab-slug>` or `R:<task>.<n>` digest id; `<task>` is dotted, batch (`1.3b`) or `final`. */
+const DIGEST_ID = /^(D:[a-z0-9]+(?:-[a-z0-9]+)*|R:(?:\d+(?:\.\d+)*b?|final)\.\d+):\s*(.*)$/;
+/** Non-empty-line budget for the `## Why and rulings` section. */
+const DIGEST_BUDGET = 15;
+/** A valid `Ceiling:` header value: a positive integer, no sign, no leading zero. */
+const CEILING_RE = /^[1-9]\d*$/;
+/** Default budget ceiling (cache-read tokens) when a brief or `--ceiling` gives none. */
+const DEFAULT_CEILING = 25000000;
+/** Task id a ledger line may carry: dotted, batch (`1.3b`), or `final`. */
+const LEDGER_TASK_RE = /^(?:\d+(?:\.\d+)*b?|final)$/;
+/** A valid dispatch name: role, underscore-joined task, optional round, optional slug. */
+const DISPATCH_NAME_RE = /^(impl|review|fix)-(\d+(?:_\d+)*b?|final)(?:-r(\d+))?(?:-([a-z0-9-]+))?$/;
+/** Charset a dispatch name may use before correction (letters of either case, digits, `_.-`). */
+const DISPATCH_NAME_CHARSET_RE = /^[A-Za-z0-9_.-]+$/;
+
+/** Handoff JSON of a `.json` file, or a report's first json block. */
+export function readHandoff(file) {
+  const text = fs.readFileSync(file, "utf8");
+  if (file.endsWith(".json")) return JSON.parse(text);
+  const m = /```json\s*\n([\s\S]*?)\n```/.exec(text);
+  if (!m) throw new Error(`${file}: no fenced json block`);
+  return JSON.parse(m[1]);
+}
+
+/** Problems of a parsed handoff against the schema; none when valid. */
+export function validateHandoff(h) {
+  const errors = [];
+  if (!h || typeof h !== "object" || Array.isArray(h)) return ["handoff: not an object"];
+  const o = /** @type {Record<string, unknown>} */ (h);
+  const strList = (key) => Array.isArray(o[key]) && o[key].every((x) => typeof x === "string" && x.trim() !== "");
+  /** A glob or directory path (trailing slash, or a `* ? [ ]` glob character). */
+  const isGlobOrDir = (x) => /[*?[\]]/.test(x) || x.endsWith("/");
+  if (typeof o.task !== "string" || o.task.trim() === "") errors.push("task: non-empty string required");
+  if (typeof o.status !== "string" || !STATUSES.has(o.status)) errors.push(`status: must be one of ${[...STATUSES].join("|")}; got ${JSON.stringify(o.status)}`);
+  if (!strList("files_changed")) errors.push("files_changed: array of non-empty strings required");
+  else if (o.files_changed.some(isGlobOrDir)) errors.push("files_changed: array of non-empty strings required, one file path each, not a directory or a glob");
+  if (!strList("evidence")) errors.push("evidence: array of non-empty strings required");
+  if (!Array.isArray(o.tests_run)) errors.push("tests_run: array required");
+  else {
+    o.tests_run.forEach((t, i) => {
+      if (!t || typeof t !== "object") errors.push(`tests_run[${i}]: object required`);
+      else {
+        if (typeof t.command !== "string" || t.command.trim() === "") errors.push(`tests_run[${i}].command: non-empty string required`);
+        if (!TEST_RESULTS.has(t.result)) errors.push(`tests_run[${i}].result: must be pass|fail|unavailable`);
+        if (typeof t.summary !== "string" || t.summary.trim() === "") errors.push(`tests_run[${i}].summary: non-empty string required`);
+      }
+    });
+  }
+  if (o.concerns !== undefined && !Array.isArray(o.concerns)) errors.push("concerns: array required when present");
+  const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+  if (o.status === "completed") {
+    if (Array.isArray(o.tests_run) && o.tests_run.length === 0) errors.push("status completed: tests_run must not be empty");
+    if (Array.isArray(o.evidence) && o.evidence.length === 0) errors.push("status completed: evidence must not be empty");
+    if (nonEmpty(o.partial_output)) errors.push("status completed: partial_output must be null");
+    if (nonEmpty(o.blocked_reason)) errors.push("status completed: blocked_reason must be null");
+  }
+  if (o.status === "partial" && !nonEmpty(o.partial_output)) errors.push("status partial: partial_output label required");
+  if (o.status === "blocked") {
+    if (!nonEmpty(o.blocked_reason)) errors.push("status blocked: blocked_reason required");
+    else if (!STOP_TOKENS.has(String(o.blocked_reason).split(":")[0].trim())) errors.push(`blocked_reason: must start with one of ${[...STOP_TOKENS].join("|")}`);
+  }
+  return errors;
+}
+
+/** Trimmed non-empty lines of one `## ` section; empty if absent. */
+function readSection(text, title) {
+  const re = new RegExp(`^## ${title}\\s*$`, "m");
+  const section = text.split(/^(?=## )/m).find((s) => re.test(s.split("\n")[0]));
+  if (!section) return [];
+  return section
+    .split("\n")
+    .slice(1)
+    .map((l) => l.trim())
+    .filter((l) => l !== "");
+}
+
+/** Parses a brief into `{ file, header, scope, digest, digestIds, ceiling }`; `ceiling` is null
+ * without the header, NaN when not a positive integer. */
+export function readBrief(file) {
+  const text = fs.readFileSync(file, "utf8");
+  const header = {};
+  for (const line of text.split("\n")) {
+    if (/^## /.test(line)) break;
+    const m = /^([A-Z][\w ]*):\s*(.+)$/.exec(line);
+    if (m) header[m[1]] = m[2].trim();
+  }
+  const scope = [];
+  for (const line of readSection(text, "Write scope")) {
+    const item = /^\s*-\s+`?([^`\s]+)`?\s*$/.exec(line);
+    if (item) scope.push(path.posix.normalize(item[1]));
+  }
+  const digest = readSection(text, "Why and rulings");
+  const digestIds = [];
+  for (const line of digest) {
+    const m = DIGEST_ID.exec(line);
+    if (m) digestIds.push(m[1]);
+  }
+  const ceiling = header.Ceiling === undefined ? null : CEILING_RE.test(header.Ceiling) ? Number(header.Ceiling) : NaN;
+  return { file, header, scope, digest, digestIds, ceiling };
+}
+
+/** Parses a ledger, one JSON object per line, into `{ lines, warnings }`; an unusable field is
+ * coerced with a warning, never thrown. A `task` reaches `ledgerSummary` as a path segment, so
+ * one that is not a task id becomes null. */
+export function readLedger(file) {
+  const text = fs.readFileSync(file, "utf8");
+  const lines = [];
+  const warnings = [];
+  text.split("\n").forEach((raw, i) => {
+    if (raw.trim() === "") return;
+    const lineNumber = i + 1;
+    let obj;
+    try {
+      obj = JSON.parse(raw);
+    } catch {
+      warnings.push(`ledger line ${lineNumber}: invalid JSON, skipped`);
+      return;
+    }
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+      warnings.push(`ledger line ${lineNumber}: invalid JSON, skipped`);
+      return;
+    }
+    if (typeof obj.cache_read === "number" && Number.isFinite(obj.cache_read) && obj.cache_read < 0) {
+      warnings.push(`ledger line ${lineNumber}: cache_read negative, treated as 0`);
+      obj = { ...obj, cache_read: 0 };
+    } else if (typeof obj.cache_read !== "number" || !Number.isFinite(obj.cache_read)) {
+      warnings.push(`ledger line ${lineNumber}: cache_read missing or non-numeric, treated as 0`);
+      obj = { ...obj, cache_read: 0 };
+    }
+    if (obj.task !== null && typeof obj.task !== "string") {
+      warnings.push(`ledger line ${lineNumber}: task missing or non-string, treated as null`);
+      obj = { ...obj, task: null };
+    } else if (typeof obj.task === "string" && !LEDGER_TASK_RE.test(obj.task)) {
+      warnings.push(`ledger line ${lineNumber}: task not a task id, treated as null`);
+      obj = { ...obj, task: null };
+    }
+    lines.push(obj);
+  });
+  return { lines, warnings };
+}
+
+/**
+ * Groups lines by `agent_id` (a resumed line joins its first line's dispatch; a line without a
+ * string `agent_id` is its own dispatch), returning each dispatch's largest `cache_read`.
+ */
+function groupByDispatch(lines) {
+  const perDispatch = new Map();
+  let anon = 0;
+  for (const l of lines) {
+    const id = typeof l.agent_id === "string" ? l.agent_id : `anon/${anon++}`;
+    const current = perDispatch.has(id) ? perDispatch.get(id) : -Infinity;
+    if (l.cache_read > current) perDispatch.set(id, l.cache_read);
+  }
+  return perDispatch;
+}
+
+/**
+ * Sums a task's `cache_read` spend against `ceiling`: total, reserve, dispatch count,
+ * remaining and `over`. A dispatch is one distinct `agent_id`; the reserve (the task's
+ * largest dispatch value) covers the next dispatch still to land, so the task is over once
+ * total plus reserve reaches the ceiling.
+ */
+export function budget(lines, task, ceiling) {
+  const taskLines = lines.filter((l) => l && l.task === task);
+  const perDispatch = groupByDispatch(taskLines);
+  let total = 0;
+  let reserve = 0;
+  for (const v of perDispatch.values()) {
+    total += v;
+    if (v > reserve) reserve = v;
+  }
+  const over = total + reserve >= ceiling;
+  const remaining = Math.max(0, ceiling - total - reserve);
+  return { total, reserve, dispatches: perDispatch.size, remaining, over };
+}
+
+/** Roles counted individually in a ledger-summary task bucket; anything else is `other`. */
+const LEDGER_ROLES = new Set(["impl", "review", "fix"]);
+/** Matches a why-digest P0 line inside a `<task>.review.md` package (case-sensitive). */
+const WHY_DIGEST_P0 = /P0[^\n]*why-digest/;
+
+/** Orders bucket keys: dotted ids naturally, then `final`, `other`. */
+function compareTaskIds(a, b) {
+  const rank = (id) => (id === "final" ? 1 : id === "other" ? 2 : 0);
+  const ra = rank(a);
+  const rb = rank(b);
+  if (ra !== rb) return ra - rb;
+  if (ra !== 0) return 0;
+  const as = a.split(".");
+  const bs = b.split(".");
+  for (let i = 0; i < Math.max(as.length, bs.length); i++) {
+    const sa = as[i] ?? "";
+    const sb = bs[i] ?? "";
+    if (sa === sb) continue;
+    const ma = /^\d+/.exec(sa);
+    const mb = /^\d+/.exec(sb);
+    if (ma && mb) {
+      const na = Number(ma[0]);
+      const nb = Number(mb[0]);
+      if (na !== nb) return na - nb;
+      const ra2 = sa.slice(ma[0].length);
+      const rb2 = sb.slice(mb[0].length);
+      if (ra2 !== rb2) return ra2 < rb2 ? -1 : 1;
+    } else if (sa !== sb) {
+      return sa < sb ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+/** Lines of a `<task>.review.md` matching `WHY_DIGEST_P0`; 0 if absent. */
+function countWhyDigestP0(file) {
+  if (!fs.existsSync(file)) return 0;
+  const text = fs.readFileSync(file, "utf8");
+  return text.split("\n").filter((line) => WHY_DIGEST_P0.test(line)).length;
+}
+
+/** p50/p75/p90 (nearest-rank) of a task-id-keyed map of total-plus-reserve values, plus the
+ * ids at or over `DEFAULT_CEILING`. */
+function percentileSummary(totalPlusReserve) {
+  const entries = Object.entries(totalPlusReserve);
+  const sorted = entries.map(([, v]) => v).sort((a, b) => a - b);
+  const rank = (p) => (sorted.length === 0 ? 0 : sorted[Math.min(sorted.length, Math.max(1, Math.ceil((p / 100) * sorted.length))) - 1]);
+  const atOrOver = entries
+    .filter(([, v]) => v >= DEFAULT_CEILING)
+    .map(([k]) => k)
+    .sort(compareTaskIds);
+  return { p50: rank(50), p75: rank(75), p90: rank(90), atOrOver };
+}
+
+/**
+ * Groups a change directory's `ledger.jsonl` by task: `impl`, `review`, `fix`, `other`
+ * (dispatch counts, one per distinct `agent_id`), `resumed` (the line count), `cache_read`
+ * (per dispatch the largest line, summed, as in `budget`), `max_reviewers_per_round`,
+ * `why_digest_p0` and `percentiles` (total plus reserve per task), plus `readLedger`'s
+ * warnings. A missing ledger yields empty tasks; round 0 covers a missing one; the totals
+ * line's `dispatches` counts distinct `agent_id`s across the whole ledger.
+ */
+export function ledgerSummary(dir) {
+  const file = path.join(dir, "ledger.jsonl");
+  const { lines, warnings } = fs.existsSync(file) ? readLedger(file) : { lines: [], warnings: [] };
+  /** @type {Record<string, Record<string, number>>} */
+  const tasks = {};
+  /** @type {Map<string, Map<number, number>>} */
+  const roundCounts = new Map();
+  const taskLines = new Map();
+  const seenAgents = new Set();
+  let anon = 0;
+  for (const line of lines) {
+    const key = line.task === null ? "other" : line.task;
+    if (!tasks[key]) {
+      tasks[key] = { impl: 0, review: 0, fix: 0, other: 0, resumed: 0, cache_read: 0, max_reviewers_per_round: 0, why_digest_p0: 0 };
+    }
+    const bucket = tasks[key];
+    if (line.resumed === true) bucket.resumed += 1;
+    if (!taskLines.has(key)) taskLines.set(key, []);
+    taskLines.get(key).push(line);
+    const agentId = typeof line.agent_id === "string" ? line.agent_id : `anon/${anon++}`;
+    const isNewDispatch = !seenAgents.has(agentId);
+    seenAgents.add(agentId);
+    if (isNewDispatch) {
+      const role = LEDGER_ROLES.has(line.role) ? line.role : "other";
+      bucket[role] += 1;
+      if (role === "review") {
+        const round = typeof line.round === "number" && Number.isFinite(line.round) ? line.round : 0;
+        if (!roundCounts.has(key)) roundCounts.set(key, new Map());
+        const rounds = roundCounts.get(key);
+        rounds.set(round, (rounds.get(round) ?? 0) + 1);
+      }
+    }
+  }
+  const totals = { dispatches: seenAgents.size, cache_read: 0, max_reviewers_per_round: 0, why_digest_p0: 0 };
+  const totalPlusReserve = {};
+  for (const [key, bucket] of Object.entries(tasks)) {
+    const perDispatch = groupByDispatch(taskLines.get(key) ?? []);
+    let reserve = 0;
+    for (const v of perDispatch.values()) {
+      bucket.cache_read += v;
+      if (v > reserve) reserve = v;
+    }
+    if (key !== "other") totalPlusReserve[key] = bucket.cache_read + reserve;
+    const rounds = roundCounts.get(key);
+    bucket.max_reviewers_per_round = rounds ? Math.max(...rounds.values()) : 0;
+    bucket.why_digest_p0 = countWhyDigestP0(path.join(dir, `${key}.review.md`));
+    totals.cache_read += bucket.cache_read;
+    totals.max_reviewers_per_round = Math.max(totals.max_reviewers_per_round, bucket.max_reviewers_per_round);
+    totals.why_digest_p0 += bucket.why_digest_p0;
+  }
+  return { tasks, totals, warnings, percentiles: percentileSummary(totalPlusReserve) };
+}
+
+/** Git from an absolute PATH entry only; a relative one cannot supply it. */
+function resolveGit() {
+  const bin = process.platform === "win32" ? "git.exe" : "git";
+  for (const dir of String(process.env.PATH || "").split(path.delimiter)) {
+    if (!dir || !path.isAbsolute(dir)) continue;
+    const candidate = path.join(dir, bin);
+    try {
+      if (fs.statSync(candidate).isFile()) return candidate;
+    } catch {
+      // not in this PATH entry
+    }
+  }
+  return null;
+}
+
+/** Runs one git command in `cwd`, throwing with its stderr on a bad exit. */
+function runGit(args, cwd) {
+  const bin = resolveGit();
+  if (!bin) throw new Error(`git ${args.join(" ")}: git not found on an absolute PATH entry`);
+  const r = spawnSync(bin, args, { cwd, encoding: "utf8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${(r.stderr || (r.error && r.error.message) || "").trim()}`);
+  return r.stdout || "";
+}
+
+/** Runs one git command and returns its trimmed stdout. */
+function git(args, cwd) {
+  return runGit(args, cwd).trim();
+}
+
+/** Untracked (`??`) paths of a `git status --porcelain -z` stream; a rename or copy entry's
+ * extra NUL field is skipped, not misread as an entry. */
+function untrackedPaths(raw) {
+  const entries = raw.split("\0");
+  if (entries.length && entries[entries.length - 1] === "") entries.pop();
+  const out = [];
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const code = entry.slice(0, 2);
+    const p = entry.slice(3);
+    if (code === "??") out.push(p);
+    else if (code.includes("R") || code.includes("C")) i++;
+  }
+  return out;
+}
+
+/** Repository-relative paths changed since `base` (a bare base diffs against the working tree,
+ * so commits and uncommitted edits both land) plus untracked paths; `--` keeps a path-shaped
+ * base off the pathspec list. */
+export function changedPaths(base, cwd) {
+  const diff = git(["diff", "--name-only", base, "--"], cwd);
+  const status = runGit(["status", "--porcelain", "-z", "--untracked-files=all"], cwd);
+  const changed = new Set(diff.split("\n").filter((l) => l !== ""));
+  for (const p of untrackedPaths(status)) changed.add(p);
+  return [...changed];
+}
+
+/** Matches a write-scope or lead entry against a repository-relative path (trailing-`/` prefix,
+ * `*`/`**`/`?` glob, or exact). Every other regex character of an entry is a literal, so a glob
+ * never widens the scope it was written for. */
+export function scopeMatches(entry, p) {
+  if (entry.endsWith("/")) return p.startsWith(entry);
+  if (entry.includes("*") || entry.includes("?")) {
+    const pattern = entry
+      .split(/(\*\*|\*|\?)/)
+      .map((part) =>
+        part === "**" ? ".*" : part === "*" ? "[^/]*" : part === "?" ? "[^/]" : part.replace(/[.+^${}()|[\]\\?]/g, "\\$&"),
+      )
+      .join("");
+    return new RegExp(`^${pattern}$`).test(p);
+  }
+  return p === entry;
+}
+
+/** True for a path under `.freeharness/`, always excluded from the changed-unclaimed and scope checks. */
+function isHarnessPath(p) {
+  return p.startsWith(".freeharness/");
+}
+
+/** Problems of a handoff's `files_changed` against `changed` and, with a scope, the brief's
+ * write scope. A `peerScope` or `leadPaths` path leaves the changed-unclaimed and scope passes,
+ * so claiming one is its own outcome (`peer-scope`/`lead-path`), never nothing; `.freeharness/`
+ * is always excluded from those same two passes. */
+export function guardHandoff(h, changed, scope, peerScope = [], leadPaths = []) {
+  const errors = [];
+  const claimed = Array.isArray(h && h.files_changed) ? h.files_changed.filter((p) => typeof p === "string") : [];
+  const changedSet = new Set(changed);
+  const claimedSet = new Set(claimed);
+  const peer = new Set(peerScope);
+  const underLead = (p) => leadPaths.some((l) => scopeMatches(l, p));
+  const owned = changed.filter((p) => !peer.has(p) && !underLead(p) && !isHarnessPath(p));
+  for (const p of claimed) if (!changedSet.has(p)) errors.push(`claimed-unchanged ${p}`);
+  for (const p of claimed) if (peer.has(p)) errors.push(`peer-scope ${p}`);
+  for (const p of claimed) if (underLead(p)) errors.push(`lead-path ${p}`);
+  for (const p of owned) if (!claimedSet.has(p)) errors.push(`changed-unclaimed ${p}`);
+  if (scope) {
+    const inScope = (p) => scope.some((s) => scopeMatches(s, p));
+    const outside = new Set();
+    for (const p of owned) if (!inScope(p)) outside.add(p);
+    for (const p of claimed) if (!inScope(p) && !peer.has(p) && !underLead(p) && !isHarnessPath(p)) outside.add(p);
+    for (const p of outside) errors.push(`scope ${p}`);
+  }
+  return errors;
+}
+
+/** Problems of a batch: each brief's header and digest, plus scope overlap. */
+export function validateBriefs(briefs) {
+  const errors = [];
+  const digestOwner = new Map();
+  for (const b of briefs) {
+    const name = path.basename(b.file);
+    for (const key of ["Change", "Task", "Spec", "Tier"]) if (!b.header[key]) errors.push(`${name}: header line '${key}:' missing`);
+    if (b.header.Tier && !TIERS.has(b.header.Tier)) errors.push(`${name}: Tier must be strong|standard|fast; got ${b.header.Tier}`);
+    if (b.header.Spec && (/[\\/]|\.md$/.test(b.header.Spec))) errors.push(`${name}: Spec must be the change id, not a path (${b.header.Spec})`);
+    if (b.header.Spec && b.header.Change && b.header.Spec !== b.header.Change) errors.push(`${name}: Spec (${b.header.Spec}) differs from Change (${b.header.Change})`);
+    if (b.scope.length === 0) errors.push(`${name}: '## Write scope' must list at least one path`);
+    if (b.header.Ceiling !== undefined && !CEILING_RE.test(b.header.Ceiling)) {
+      errors.push(`${name}: Ceiling must be a positive integer; got ${b.header.Ceiling}`);
+    }
+
+    if (b.digest.length === 0) errors.push(`${name}: '## Why and rulings' section missing`);
+    if (b.digest.length > DIGEST_BUDGET) errors.push(`${name}: '## Why and rulings' has ${b.digest.length} lines, budget is ${DIGEST_BUDGET}`);
+    if (b.digest.some((l) => l.startsWith("```"))) errors.push(`${name}: '## Why and rulings' must not contain a fenced block`);
+
+    const seen = new Set();
+    for (const line of b.digest) {
+      const m = DIGEST_ID.exec(line);
+      if (!m) continue;
+      const [, id, ruling] = m;
+      if (seen.has(id)) {
+        errors.push(`${name}: duplicate id ${id} inside the brief`);
+        continue;
+      }
+      seen.add(id);
+      const prev = digestOwner.get(id);
+      if (!prev) digestOwner.set(id, { text: ruling, file: b.file });
+      else if (prev.text !== ruling) {
+        errors.push(`${name}: duplicate id ${id} differs from its text in ${path.basename(prev.file)}`);
+      }
+    }
+  }
+  const owner = new Map();
+  for (const b of briefs) {
+    for (const p of b.scope) {
+      const prev = owner.get(p);
+      if (prev && prev !== b.file) errors.push(`write scope overlap: ${p} in ${path.basename(prev)} and ${path.basename(b.file)}; batch refused`);
+      else owner.set(p, b.file);
+    }
+  }
+  return errors;
+}
+
+/** Every complete fenced json block; an unterminated fence never matches. */
+const JSON_BLOCK_RE = /```json\s*\n([\s\S]*?)\n```/g;
+
+/** Assistant-authored texts of one line's `message.content`: `text` blocks joined, plus a
+ * `SendMessage` tool_use's `input.message` (the worker's reply channel in the teams runtime);
+ * no other tool input. */
+function assistantCandidates(content) {
+  if (typeof content === "string") return content === "" ? [] : [content];
+  if (!Array.isArray(content)) return [];
+  const out = [];
+  let buf = [];
+  const flushText = () => {
+    if (buf.length > 0) out.push(buf.join(""));
+    buf = [];
+  };
+  for (const b of content) {
+    if (b && typeof b === "object" && b.type === "text" && typeof b.text === "string") {
+      buf.push(b.text);
+      continue;
+    }
+    flushText();
+    if (b && typeof b === "object" && b.type === "tool_use" && b.name === "SendMessage" && b.input && typeof b.input.message === "string") {
+      out.push(b.input.message);
+    }
+  }
+  flushText();
+  return out;
+}
+
+/** The last complete json block of a text plus the text after it; null if none. */
+function lastJsonBlock(text) {
+  JSON_BLOCK_RE.lastIndex = 0;
+  let match;
+  let last = null;
+  while ((match = JSON_BLOCK_RE.exec(text)) !== null) last = match;
+  if (!last) return null;
+  return { block: last[1], remaining: text.slice(last.index + last[0].length) };
+}
+
+/** The report's next text: its first json block replaced by `fenced`, or, when it has none (`existing` null for a report not yet on disk), the block before `remaining`. */
+function spliceReport(existing, fenced, remaining) {
+  if (existing !== null) {
+    const m = /```json\s*\n[\s\S]*?\n```/.exec(existing);
+    if (m) return existing.slice(0, m.index) + fenced + existing.slice(m.index + m[0].length);
+    return `${fenced}\n\n${existing}`;
+  }
+  const body = remaining.replace(/^\n+/, "").trimEnd();
+  return body === "" ? `${fenced}\n` : `${fenced}\n\n${body}\n`;
+}
+
+/** Identity and schema validity of a report's first json block; null if none. */
+function existingBlockInfo(text) {
+  const m = /```json\s*\n([\s\S]*?)\n```/.exec(text);
+  if (!m) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(m[1]);
+  } catch {
+    return { task: null, status: null, valid: false };
+  }
+  const o = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  return {
+    task: typeof o.task === "string" ? o.task : null,
+    status: typeof o.status === "string" ? o.status : null,
+    valid: validateHandoff(parsed).length === 0,
+  };
+}
+
+/** Rebuilds a handoff report from a transcript's last complete json block, so a trailing prose
+ * summary never fails recovery. A schema-valid block in the report survives unless `force`: a
+ * rerun over a stale transcript would replace a good handoff with an old one. */
+export function recover(transcript, report, force = false) {
+  let text;
+  try {
+    text = fs.readFileSync(transcript, "utf8");
+  } catch (err) {
+    return { written: false, replaced: null, errors: [`${transcript}: ${err instanceof Error ? err.message : String(err)}`] };
+  }
+  const candidates = [];
+  for (const raw of text.split("\n")) {
+    if (raw.trim() === "") continue;
+    let obj;
+    try {
+      obj = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (!obj || typeof obj !== "object" || obj.type !== "assistant") continue;
+    candidates.push(...assistantCandidates(obj.message && obj.message.content));
+  }
+  let found = null;
+  for (let i = candidates.length - 1; i >= 0 && !found; i--) found = lastJsonBlock(candidates[i]);
+  if (!found) {
+    return { written: false, replaced: null, errors: [`${transcript}: no assistant message with a complete fenced json block`] };
+  }
+  let errors;
+  try {
+    errors = validateHandoff(JSON.parse(found.block));
+  } catch (err) {
+    errors = [`${transcript}: recovered block is not valid JSON: ${err instanceof Error ? err.message : String(err)}`];
+  }
+  const fenced = "```json\n" + found.block + "\n```";
+  const existing = fs.existsSync(report) ? fs.readFileSync(report, "utf8") : null;
+  const replaced = existing === null ? null : existingBlockInfo(existing);
+  if (replaced && replaced.valid && !force) {
+    return {
+      written: false,
+      replaced,
+      errors: [`${report}: existing handoff block (task ${replaced.task}, status ${replaced.status}) is valid; pass --force to replace it`],
+    };
+  }
+  try {
+    fs.writeFileSync(report, spliceReport(existing, fenced, found.remaining));
+  } catch (err) {
+    return { written: false, replaced, errors: [`${report}: ${err instanceof Error ? err.message : String(err)}`] };
+  }
+  return { written: true, replaced, errors };
+}
+
+/** Brief paths from a directory (sorted `*.brief.md`) or as given. */
+function collectBriefs(args) {
+  const out = [];
+  for (const a of args) {
+    if (fs.statSync(a).isDirectory()) {
+      for (const f of fs.readdirSync(a).sort()) if (f.endsWith(".brief.md")) out.push(path.join(a, f));
+    } else out.push(a);
+  }
+  return out;
+}
+
+/** Usage text: one line per subcommand with its arguments, in order. */
+const USAGE = [
+  "usage: validate-handoff.mjs <subcommand> [args]",
+  "  briefs <dir|file...>",
+  "  handoff <file> [--base <sha>] [--brief <brief.md>] [--in-flight <brief.md>]... [--lead <path>]...",
+  "  budget <ledger.jsonl> <task> [--ceiling <n>]",
+  "  ledger <change-dir>",
+  "  recover <transcript.jsonl> <report> [--force]",
+  "  name <dispatch-name>",
+].join("\n");
+
+/** Splits a runner's options out of its arguments: `--name value` pairs of `allowed`, every
+ * repeated value kept, `valueless` switches recorded as `true`. A trailing valued option
+ * yields `undefined`; an unlisted option is the one `unknown option` error every subcommand
+ * prints. */
+function parseFlags(rest, allowed, valueless = []) {
+  const values = {};
+  for (let i = 0; i < rest.length; i++) {
+    const flag = rest[i];
+    if (!values[flag]) values[flag] = [];
+    if (valueless.includes(flag)) {
+      values[flag].push(true);
+      continue;
+    }
+    if (!allowed.includes(flag)) return { values, error: `unknown option ${JSON.stringify(flag)}` };
+    values[flag].push(rest[i + 1]);
+    i++;
+  }
+  return { values, error: null };
+}
+
+/** The last value given for an option; undefined when absent. */
+function lastValue(values, flag) {
+  const list = values[flag];
+  return list ? list[list.length - 1] : undefined;
+}
+
+/** Prints one `FAIL` per problem, or `OK <label>`; returns the exit code. */
+function report(errors, label) {
+  for (const e of errors) console.error(`FAIL ${e}`);
+  if (errors.length === 0) console.log(`OK ${label}`);
+  return errors.length === 0 ? 0 : 1;
+}
+
+/** Runs `briefs`: headers, digests, scope overlap; null without a path. */
+function runBriefs(rest) {
+  if (rest.length < 1) return null;
+  return report(validateBriefs(collectBriefs(rest).map(readBrief)), rest.join(" "));
+}
+
+/** Runs `handoff`: the schema and, with `--base`, the diff guards. */
+function runHandoff(rest) {
+  if (rest.length < 1) return null;
+  const file = rest[0];
+  const { values, error } = parseFlags(rest.slice(1), ["--base", "--brief", "--in-flight", "--lead"]);
+  if (error) {
+    console.error(`FAIL ${error}`);
+    return 1;
+  }
+  for (const [flag, list] of Object.entries(values)) {
+    if (list.some((v) => v === undefined)) {
+      console.error(`FAIL ${flag} requires a value`);
+      return 1;
+    }
+  }
+  const base = lastValue(values, "--base");
+  const briefFile = lastValue(values, "--brief");
+  const inFlight = values["--in-flight"] ?? [];
+  const leadPaths = values["--lead"] ?? [];
+  if (base !== undefined && base.startsWith("-")) {
+    console.error(`FAIL --base must not start with '-'; got ${JSON.stringify(base)}`);
+    return 1;
+  }
+  for (const l of leadPaths) {
+    if (l.startsWith("-")) {
+      console.error(`FAIL --lead must not start with '-'; got ${JSON.stringify(l)}`);
+      return 1;
+    }
+  }
+  const normalizedLeadPaths = leadPaths.map((l) => path.posix.normalize(l));
+  let handoffObj = null;
+  let errors;
+  try {
+    handoffObj = readHandoff(file);
+    errors = validateHandoff(handoffObj);
+  } catch (err) {
+    errors = [err instanceof Error ? err.message : String(err)];
+  }
+  if (handoffObj && base !== undefined) {
+    try {
+      const changed = changedPaths(base, process.cwd());
+      const scope = briefFile !== undefined ? readBrief(briefFile).scope : null;
+      const peerScope = inFlight.flatMap((f) => readBrief(f).scope);
+      errors = errors.concat(guardHandoff(handoffObj, changed, scope, peerScope, normalizedLeadPaths));
+    } catch (err) {
+      errors.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+  return report(errors, file);
+}
+
+/** Runs `budget`: a task's spend against the ceiling; null without both. */
+function runBudget(rest) {
+  if (rest.length < 2) return null;
+  const [file, task, ...opts] = rest;
+  let ceiling = DEFAULT_CEILING;
+  const { values, error } = parseFlags(opts, ["--ceiling"]);
+  if (error) {
+    console.error(`FAIL ${error}`);
+    return 1;
+  }
+  if (values["--ceiling"]) {
+    const value = lastValue(values, "--ceiling");
+    if (!CEILING_RE.test(value ?? "")) {
+      console.error(`FAIL --ceiling must be a positive integer; got ${JSON.stringify(value ?? null)}`);
+      return 1;
+    }
+    ceiling = Number(value);
+  }
+  if (!fs.existsSync(file)) {
+    console.log(`NOTICE ledger ${file} absent; nothing to check`);
+    return 0;
+  }
+  const { lines, warnings } = readLedger(file);
+  for (const w of warnings) console.error(`WARN ${w}`);
+  const b = budget(lines, task, ceiling);
+  console.log(`task ${task}: dispatches ${b.dispatches}, total ${b.total}, reserve ${b.reserve}, ceiling ${ceiling}, remaining ${b.remaining}`);
+  console.log(b.over ? "FAIL ceiling reached" : "OK under ceiling");
+  return b.over ? 1 : 0;
+}
+
+/** Runs `ledger`: the per-task and totals summary; null without a directory. */
+function runLedger(rest) {
+  if (rest.length < 1) return null;
+  const dir = rest[0];
+  const file = path.join(dir, "ledger.jsonl");
+  if (!fs.existsSync(file)) {
+    console.log(`NOTICE ledger ${file} absent; nothing to summarize`);
+    return 0;
+  }
+  const { tasks, totals, warnings, percentiles } = ledgerSummary(dir);
+  for (const w of warnings) console.error(`WARN ${w}`);
+  for (const id of Object.keys(tasks).sort(compareTaskIds)) {
+    const t = tasks[id];
+    console.log(
+      `task ${id}: impl ${t.impl}, review ${t.review}, fix ${t.fix}, other ${t.other}, resumed ${t.resumed}, cache_read ${t.cache_read}, max reviewers per round ${t.max_reviewers_per_round}, why-digest P0 ${t.why_digest_p0}`,
+    );
+  }
+  console.log(
+    `totals: dispatches ${totals.dispatches}, cache_read ${totals.cache_read}, max reviewers per round ${totals.max_reviewers_per_round}, why-digest P0 ${totals.why_digest_p0}`,
+  );
+  const atOrOver = percentiles.atOrOver.length ? percentiles.atOrOver.join(", ") : "none";
+  console.log(
+    `percentiles: p50 ${percentiles.p50}, p75 ${percentiles.p75}, p90 ${percentiles.p90} (total plus reserve per task); at or over ${DEFAULT_CEILING}: ${atOrOver}`,
+  );
+  return 0;
+}
+
+/** Reason a name fails `DISPATCH_NAME_RE` case-insensitively: the first of `role`, `dot`,
+ * `task`, `round` or `slug` to disagree with the accepted form, case differences included so a
+ * mismatch is never misattributed to `charset` (already ruled out by `parseDispatchName`'s gate). */
+function diagnoseDispatchName(raw) {
+  const hyphenIdx = raw.indexOf("-");
+  const roleSeg = hyphenIdx === -1 ? raw : raw.slice(0, hyphenIdx);
+  if (!["impl", "review", "fix"].includes(roleSeg.toLowerCase())) return "role";
+  if (roleSeg !== roleSeg.toLowerCase()) return "role";
+  const rest = hyphenIdx === -1 ? "" : raw.slice(hyphenIdx + 1);
+  const tokens = rest.split("-");
+  const taskTok = tokens[0] ?? "";
+  if (taskTok.includes(".")) return "dot";
+  if (!/^(\d+(?:_\d+)*b?|final)$/i.test(taskTok)) return "task";
+  if (taskTok !== taskTok.toLowerCase()) return "task";
+  let idx = 1;
+  if (tokens[idx] !== undefined && /^r/i.test(tokens[idx])) {
+    if (!/^r\d+$/i.test(tokens[idx])) return "round";
+    if (tokens[idx] !== tokens[idx].toLowerCase()) return "round";
+    idx++;
+  }
+  if (idx < tokens.length) {
+    const slugTok = tokens.slice(idx).join("-");
+    if (!/^[a-z0-9-]+$/i.test(slugTok)) return "slug";
+    if (slugTok !== slugTok.toLowerCase()) return "slug";
+  }
+  return "charset";
+}
+
+/** Parses a dispatch name against `<role>-<task>[-r<round>][-<slug>]`; `corrected` carries the
+ * dots-to-underscore, lowercased form when that form itself parses, else `null`. */
+export function parseDispatchName(raw) {
+  if (typeof raw !== "string" || raw === "" || /\s/.test(raw) || !DISPATCH_NAME_CHARSET_RE.test(raw)) {
+    return { ok: false, reason: "charset", corrected: null };
+  }
+  const direct = DISPATCH_NAME_RE.exec(raw);
+  if (direct) {
+    return {
+      ok: true,
+      role: direct[1],
+      task: direct[2].replace(/_/g, "."),
+      round: direct[3] !== undefined ? Number(direct[3]) : null,
+      slug: direct[4] ?? null,
+    };
+  }
+  const corrected = raw.replace(/\./g, "_").toLowerCase();
+  const correctedOk = corrected !== raw && DISPATCH_NAME_RE.test(corrected);
+  return { ok: false, reason: diagnoseDispatchName(raw), corrected: correctedOk ? corrected : null };
+}
+
+/** Runs `recover`, naming the replaced block so no overwrite is silent. */
+function runRecover(rest) {
+  if (rest.length < 2) return null;
+  const [transcript, reportPath, ...opts] = rest;
+  const { values, error } = parseFlags(opts, [], ["--force"]);
+  if (error) {
+    console.error(`FAIL ${error}`);
+    return 1;
+  }
+  const force = Boolean(values["--force"]);
+  const { written, errors, replaced } = recover(transcript, reportPath, force);
+  if (!written || errors.length > 0) {
+    for (const e of errors) console.error(`FAIL ${e}`);
+    return 1;
+  }
+  console.log(replaced ? `recovered ${reportPath} (replaced task ${replaced.task}, status ${replaced.status})` : `recovered ${reportPath}`);
+  return 0;
+}
+
+/** Runs `name`: reports a dispatch name's validity; never refuses a dispatch itself. */
+function runName(rest) {
+  if (rest.length < 1) return null;
+  const result = parseDispatchName(rest[0]);
+  if (result.ok) {
+    console.log(`OK role=${result.role} task=${result.task} round=${result.round === null ? "none" : result.round} slug=${result.slug === null ? "none" : result.slug}`);
+    return 0;
+  }
+  console.error(`FAIL ${result.reason}`);
+  if (result.corrected) console.log(`use ${result.corrected}`);
+  return 1;
+}
+
+/** Handlers in usage order; a `Map`, so an `Object.prototype` name resolves to none. */
+const SUBCOMMANDS = new Map([
+  ["briefs", runBriefs],
+  ["handoff", runHandoff],
+  ["budget", runBudget],
+  ["ledger", runLedger],
+  ["recover", runRecover],
+  ["name", runName],
+]);
+
+/** CLI entry over `argv` after the script name; returns the exit code. */
+export function main(argv) {
+  const [mode, ...rest] = argv;
+  const handler = SUBCOMMANDS.get(mode);
+  const code = handler ? handler(rest) : null;
+  if (code !== null) return code;
+  console.error(USAGE);
+  return 1;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === new URL(import.meta.url).pathname) {
+  process.exit(main(process.argv.slice(2)));
+}