freeharness 0.4.1 → 0.4.2

package/dist/cli/cost.js

@@ -6,6 +6,10 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { isEffortLevel } from "@freeharness/core";
+import { quotaCalibrationPath, readCalibration } from "./cost-quota.js";
+import { resolveCanonicalDir } from "../infra/paths.js";
 /** Usage log path: FREEHARNESS_COST_LOG when set, else ~/.claude/freeharness/cost/usage.jsonl (may not exist yet). */
 export function costLogPath() {
     return process.env.FREEHARNESS_COST_LOG || path.join(os.homedir(), ".claude", "freeharness", "cost", "usage.jsonl");
@@ -45,6 +49,27 @@ export function readLog(file) {
 function emptyRow(key) {
     return { key, sessions: 0, turns: 0, input: 0, output: 0, cache_read: 0, cache_write: 0, est_usd: 0 };
 }
+function isBucketLike(v) {
+    return typeof v === "object" && v !== null;
+}
+function isAgentUsageLike(v) {
+    return Boolean(v) && typeof v === "object" && typeof v.model === "string" && isBucketLike(v.usage);
+}
+function modelBuckets(byModel) {
+    return Object.entries(byModel ?? {}).filter((e) => isBucketLike(e[1]));
+}
+function newTally() {
+    return { storedEstimate: 0, withoutSplit: 0 };
+}
+function tally(t, priced) {
+    if (priced.storedEstimate)
+        t.storedEstimate += 1;
+    if (priced.missingSplit)
+        t.withoutSplit += 1;
+}
+function pricingMeta(table, loaded, storedEstimate, withoutSplit) {
+    return { table, loaded, stored_estimate: storedEstimate, without_split: withoutSplit };
+}
 function addBucket(row, b, usd) {
     row.input += Number(b.input) || 0;
     row.output += Number(b.output) || 0;
@@ -71,8 +96,40 @@ export function latestPerSession(records) {
     }
     return [...map.values()];
 }
-/** Aggregates usage lines into per-project and per-model rows plus a total; rows sorted by estimated USD descending. */
-export function aggregate(records, filter = {}, log = costLogPath()) {
+const MIN_SESSION_HOURS = 0.1;
+function sessionKey(r, fallback) {
+    return r.transcript || r.session_id || fallback;
+}
+/**
+ * Hours between a session's first and last snapshot, floored so a single-snapshot session
+ * never divides by zero and a short one does not inflate the rate.
+ */
+function sessionHours(firstTs, lastTs) {
+    const span = (Date.parse(lastTs) - Date.parse(firstTs ?? lastTs)) / 3_600_000;
+    return Number.isFinite(span) ? Math.max(MIN_SESSION_HOURS, span) : MIN_SESSION_HOURS;
+}
+/** Prices one record's buckets (model -> bucket) against `prices`: summed `priceBucket` when non-empty, else a non-zero `storedUsd` (0 unloaded); a record with neither buckets nor a stored value contributes 0 and is not counted as a stored estimate. */
+function priceRecord(buckets, storedUsd, prices, loaded) {
+    if (buckets.length === 0) {
+        if (storedUsd === 0)
+            return { usd: 0, missingSplit: false, storedEstimate: false, estimated: false };
+        return { usd: loaded ? storedUsd : 0, missingSplit: false, storedEstimate: true, estimated: false };
+    }
+    let usd = 0;
+    let missingSplit = false;
+    let estimated = false;
+    for (const [model, b] of buckets) {
+        if (!("cache_write_1h" in b))
+            missingSplit = true;
+        const match = priceMatch(prices, model);
+        usd += priceBucket(match.row, b);
+        if (match.estimated)
+            estimated = true;
+    }
+    return { usd, missingSplit, storedEstimate: false, estimated };
+}
+/** Aggregates usage lines into per-project and per-model rows plus a total, sorted by USD descending; USD comes from `priceRecord`. */
+export function aggregate(records, filter = {}, log = costLogPath(), prices = loadPriceTable(costPricesPath()), pricesFile = costPricesPath()) {
     const now = filter.now ?? new Date();
     const since = filter.days !== undefined ? new Date(now.getTime() - filter.days * 86_400_000) : undefined;
     let sessions = latestPerSession(records);
@@ -80,12 +137,27 @@ export function aggregate(records, filter = {}, log = costLogPath()) {
         sessions = sessions.filter((r) => Date.parse(r.ts) >= since.getTime());
     if (filter.project)
         sessions = sessions.filter((r) => r.project === filter.project);
+    const loaded = Object.keys(prices).length > 0;
     const byProject = new Map();
     const byModel = new Map();
     const total = emptyRow("total");
     let last;
+    const t = newTally();
+    const firstTs = new Map();
+    for (const r of records) {
+        const key = sessionKey(r, "");
+        const prev = firstTs.get(key);
+        if (key && r.ts && (prev === undefined || r.ts < prev))
+            firstTs.set(key, r.ts);
+    }
+    const hoursOf = new Map();
+    let totalHours = 0;
+    const perHour = (cacheRead, hours) => Math.round(cacheRead / (hours || MIN_SESSION_HOURS));
     for (const r of sessions) {
-        const usd = Number(r.est_usd) || 0;
+        const models = modelBuckets(r.by_model);
+        const priced = priceRecord(models, Number(r.est_usd) || 0, prices, loaded);
+        tally(t, priced);
+        const usd = priced.usd;
         const p = byProject.get(r.project) ?? emptyRow(r.project || "(unknown)");
         p.sessions += 1;
         p.turns += Number(r.turns) || 0;
@@ -94,11 +166,20 @@ export function aggregate(records, filter = {}, log = costLogPath()) {
         total.sessions += 1;
         total.turns += Number(r.turns) || 0;
         addBucket(total, r.usage, usd);
-        const models = r.by_model && Object.keys(r.by_model).length > 0 ? Object.entries(r.by_model) : [];
+        const hours = sessionHours(firstTs.get(sessionKey(r, "")), r.ts);
+        hoursOf.set(p, (hoursOf.get(p) ?? 0) + hours);
+        totalHours += hours;
+        if (priced.estimated) {
+            p.price_estimated = true;
+            total.price_estimated = true;
+        }
         for (const [model, b] of models) {
             const m = byModel.get(model) ?? emptyRow(model);
             m.sessions += 1;
-            addBucket(m, b, Number(b.est_usd) || 0);
+            const match = priceMatch(prices, model);
+            addBucket(m, b, priceBucket(match.row, b));
+            if (match.estimated)
+                m.price_estimated = true;
             byModel.set(model, m);
         }
         if (!last || r.ts > last)
@@ -111,10 +192,11 @@ export function aggregate(records, filter = {}, log = costLogPath()) {
         project: filter.project,
         lines: records.length,
         sessions: sessions.length,
-        byProject: finish(byProject.values()),
+        byProject: finish([...byProject.values()].map((p) => ({ ...p, cache_read_per_hour: perHour(p.cache_read, hoursOf.get(p) ?? 0) }))),
         byModel: finish(byModel.values()),
-        total: { ...total, est_usd: round(total.est_usd) },
+        total: { ...total, est_usd: round(total.est_usd), cache_read_per_hour: perHour(total.cache_read, totalHours) },
         last,
+        pricing: pricingMeta(pricesFile, loaded, t.storedEstimate, t.withoutSplit),
     };
 }
 /** Formats a token count compactly (1.2k, 3.4M). */
@@ -125,9 +207,19 @@ export function fmtTokens(n) {
         return `${(n / 1e3).toFixed(1)}k`;
     return String(n);
 }
+/** First line of every text report: the price table and repricing counts, or a load-failure warning. */
+function pricingLine(p) {
+    if (!p.loaded)
+        return priceWarnLine(p.table);
+    return `prices: ${p.table} (repriced from tokens; ${p.stored_estimate} from stored estimate, ${p.without_split} without cache-write split)`;
+}
+function priceWarnLine(table) {
+    return `WARN price table not loaded: ${table}; USD shown as 0`;
+}
 /** Renders the report as aligned text tables. */
 export function formatReport(report) {
     const lines = [];
+    lines.push(pricingLine(report.pricing));
     const scope = [report.since ? `last ${Math.round((Date.now() - Date.parse(report.since)) / 86_400_000)} days` : "all time", report.project ? `project ${report.project}` : ""].filter(Boolean).join(", ");
     lines.push(`cost report (${scope}): ${report.log}`);
     lines.push(`lines ${report.lines}, sessions ${report.sessions}${report.last ? `, last entry ${report.last}` : ""}`);
@@ -138,10 +230,10 @@ export function formatReport(report) {
     const table = (title, rows, showTurns) => {
         lines.push("");
         lines.push(title);
-        const head = [`${"".padEnd(28)}`, "sessions".padStart(8), showTurns ? "turns".padStart(6) : "", "input".padStart(9), "output".padStart(9), "cache_rd".padStart(9), "cache_wr".padStart(9), "est USD".padStart(10)].filter((c) => c !== "");
+        const head = [`${"".padEnd(28)}`, "sessions".padStart(8), showTurns ? "turns".padStart(6) : "", "input".padStart(9), "output".padStart(9), "cache_rd".padStart(9), "cache_wr".padStart(9), "est USD".padStart(10), showTurns ? "cache_rd/h".padStart(11) : ""].filter((c) => c !== "");
         lines.push(`  ${head.join(" ")}`);
         for (const r of rows) {
-            const cells = [r.key.slice(0, 28).padEnd(28), String(r.sessions).padStart(8), showTurns ? String(r.turns).padStart(6) : "", fmtTokens(r.input).padStart(9), fmtTokens(r.output).padStart(9), fmtTokens(r.cache_read).padStart(9), fmtTokens(r.cache_write).padStart(9), r.est_usd.toFixed(4).padStart(10)].filter((c) => c !== "");
+            const cells = [r.key.slice(0, 28).padEnd(28), String(r.sessions).padStart(8), showTurns ? String(r.turns).padStart(6) : "", fmtTokens(r.input).padStart(9), fmtTokens(r.output).padStart(9), fmtTokens(r.cache_read).padStart(9), fmtTokens(r.cache_write).padStart(9), r.est_usd.toFixed(4).padStart(10), showTurns ? fmtTokens(r.cache_read_per_hour ?? 0).padStart(11) : "", r.price_estimated ? "(estimated)" : ""].filter((c) => c !== "");
             lines.push(`  ${cells.join(" ")}`);
         }
     };
@@ -170,7 +262,7 @@ export function costLogLine(file) {
     const kb = (fs.statSync(file).size / 1024).toFixed(1);
     const last = records[records.length - 1];
     const sessions = latestPerSession(records).length;
-    return `OK   cost log: ${records.length} entries (${sessions} sessions), ${kb} KB${last ? `, last ${last.ts} ${last.project} $${(Number(last.est_usd) || 0).toFixed(4)}` : ""} — ${file}`;
+    return `OK   cost log: ${records.length} entries (${sessions} sessions), ${kb} KB${last ? `, last ${last.ts} ${last.project} $${(Number(last.est_usd) || 0).toFixed(4)}${last.price_estimated === true ? " (estimated)" : ""}` : ""} — ${file}`;
 }
 /** Tokens estimated from characters (4 chars per token). */
 function charsToTokens(chars) {
@@ -179,9 +271,9 @@ function charsToTokens(chars) {
 /**
  * Ranks token sinks per project: sessions (or task classes) by total tokens with the
  * tool-output share and the pruned bytes recovered, and tools by output. Sessions without a
- * task class are `untagged` and counted.
+ * task class are `untagged` and counted; USD is repriced per row like `aggregate`.
  */
-export function sinks(records, filter = {}, log = costLogPath()) {
+export function sinks(records, filter = {}, log = costLogPath(), prices = loadPriceTable(costPricesPath()), pricesFile = costPricesPath()) {
     const now = filter.now ?? new Date();
     const since = filter.days !== undefined ? new Date(now.getTime() - filter.days * 86_400_000) : undefined;
     let sessions = latestPerSession(records);
@@ -190,9 +282,11 @@ export function sinks(records, filter = {}, log = costLogPath()) {
     if (filter.project)
         sessions = sessions.filter((r) => r.project === filter.project);
     const top = filter.top && filter.top > 0 ? filter.top : 10;
+    const loaded = Object.keys(prices).length > 0;
     const byProject = new Map();
     let untagged = 0;
     let prunedTotal = 0;
+    const t = newTally();
     for (const r of sessions) {
         const project = r.project || "(unknown)";
         const cls = r.task_class && r.task_class.trim() ? r.task_class.trim() : "untagged";
@@ -207,7 +301,12 @@ export function sinks(records, filter = {}, log = costLogPath()) {
         row.output += Number(r.usage.output) || 0;
         row.tool_output_tokens += charsToTokens(r.tool_output_chars ?? 0);
         row.pruned_bytes += Number(r.pruned_bytes) || 0;
-        row.est_usd += Number(r.est_usd) || 0;
+        const models = modelBuckets(r.by_model);
+        const priced = priceRecord(models, Number(r.est_usd) || 0, prices, loaded);
+        tally(t, priced);
+        row.est_usd += priced.usd;
+        if (priced.estimated)
+            row.price_estimated = true;
         prunedTotal += Number(r.pruned_bytes) || 0;
         p.rows.set(key, row);
         for (const [tool, t] of Object.entries(r.by_tool ?? {})) {
@@ -280,11 +379,22 @@ export function sinks(records, filter = {}, log = costLogPath()) {
         out.push({ project, rows, tools, notes });
     }
     out.sort((a, b) => b.rows.reduce((n, r) => n + r.tokens, 0) - a.rows.reduce((n, r) => n + r.tokens, 0) || a.project.localeCompare(b.project));
-    return { log, since: since?.toISOString(), project: filter.project, by: filter.byTaskClass ? "task-class" : "session", sessions: sessions.length, untagged, pruned_bytes: prunedTotal, byProject: out };
+    return {
+        log,
+        since: since?.toISOString(),
+        project: filter.project,
+        by: filter.byTaskClass ? "task-class" : "session",
+        sessions: sessions.length,
+        untagged,
+        pruned_bytes: prunedTotal,
+        byProject: out,
+        pricing: pricingMeta(pricesFile, loaded, t.storedEstimate, t.withoutSplit),
+    };
 }
 /** Renders the sinks report. */
 export function formatSinks(report) {
     const lines = [];
+    lines.push(pricingLine(report.pricing));
     const scope = [report.since ? `last ${Math.round((Date.now() - Date.parse(report.since)) / 86_400_000)} days` : "all time", report.project ? `project ${report.project}` : ""].filter(Boolean).join(", ");
     lines.push(`cost sinks by ${report.by} (${scope}): ${report.log}`);
     lines.push(`sessions ${report.sessions}, untagged ${report.untagged} (no Class: header in the active brief), pruned bytes recovered ${report.pruned_bytes}`);
@@ -298,7 +408,7 @@ export function formatSinks(report) {
         lines.push(`  ${"".padEnd(30)} ${"class".padEnd(12)} ${"sessions".padStart(8)} ${"tokens".padStart(9)} ${"output".padStart(9)} ${"tool-out".padStart(9)} ${"share%".padStart(7)} ${"pruned".padStart(9)} ${"est USD".padStart(9)}`);
         for (const r of p.rows) {
             const label = r.key === "observer_local" ? "observer (local)" : r.key;
-            lines.push(`  ${label.slice(0, 30).padEnd(30)} ${r.task_class.slice(0, 12).padEnd(12)} ${String(r.sessions).padStart(8)} ${fmtTokens(r.tokens).padStart(9)} ${fmtTokens(r.output).padStart(9)} ${fmtTokens(r.tool_output_tokens).padStart(9)} ${r.tool_output_share.toFixed(1).padStart(7)} ${String(r.pruned_bytes).padStart(9)} ${r.est_usd.toFixed(4).padStart(9)}`);
+            lines.push(`  ${label.slice(0, 30).padEnd(30)} ${r.task_class.slice(0, 12).padEnd(12)} ${String(r.sessions).padStart(8)} ${fmtTokens(r.tokens).padStart(9)} ${fmtTokens(r.output).padStart(9)} ${fmtTokens(r.tool_output_tokens).padStart(9)} ${r.tool_output_share.toFixed(1).padStart(7)} ${String(r.pruned_bytes).padStart(9)} ${r.est_usd.toFixed(4).padStart(9)}${r.price_estimated ? " (estimated)" : ""}`);
         }
         if (p.tools.length > 0) {
             lines.push("  tools by output:");
@@ -356,26 +466,116 @@ function median(values) {
     const mid = Math.floor(sorted.length / 2);
     return sorted.length % 2 === 0 ? round((sorted[mid - 1] + sorted[mid]) / 2) : sorted[mid];
 }
+export const SESSION_CLASS_NAMES = ["sdd", "plan", "archive", "review", "debug", "untagged"];
+/** Untagged over the measured records that carry a class, so legacy records cannot dilute the share the gate reads; null with none. */
+export function untaggedShare(classes) {
+    const classed = SESSION_CLASS_NAMES.reduce((n, c) => n + classes[c], 0);
+    return classed === 0 ? null : classes.untagged / classed;
+}
+/** A record whose subagent figure is a discovery gap, not a measurement: Agent calls were made, no subagent tokens were read, and it predates `cc_version`. */
+function subagentsUnread(r) {
+    return (Number(r.sinks?.agent_calls) || 0) > 0 && (Number(r.sinks?.subagents?.total) || 0) === 0 && !("cc_version" in r);
+}
+/** A record's activity class; an unknown or absent value with tokens is measured, absent with none is `no-model-calls`. */
+function activityClass(r) {
+    if (r.activity === "no-transcript" || r.activity === "no-model-calls")
+        return r.activity;
+    if (r.activity !== undefined)
+        return "measured";
+    const tokens = (Number(r.sinks?.main?.total) || 0) + (Number(r.sinks?.subagents?.total) || 0);
+    return tokens > 0 ? "measured" : "no-model-calls";
+}
+/** Latest `SessionEnd` snapshot per `session_id`, for the by_model-less join. */
+function lastSessionEnd(usage) {
+    const map = new Map();
+    for (const r of usage) {
+        if (r.event !== "SessionEnd")
+            continue;
+        const prev = map.get(r.session_id);
+        if (!prev || (r.ts ?? "") >= (prev.ts ?? ""))
+            map.set(r.session_id, r);
+    }
+    return map;
+}
+/** `by_model` plus `by_agent` entries, each keyed by its own model, for `priceRecord`. */
+function priceableBuckets(byModel, byAgent) {
+    const buckets = modelBuckets(byModel);
+    for (const a of Object.values(byAgent ?? {})) {
+        if (isAgentUsageLike(a))
+            buckets.push([a.model, a.usage]);
+    }
+    return buckets;
+}
+/** Prices one telemetry record: its own buckets, else the joined snapshot's, else the stored `est_usd`. */
+function priceTelemetryRecord(record, snapshots, prices, loaded) {
+    if (record.by_model !== undefined)
+        return priceRecord(priceableBuckets(record.by_model, record.sinks?.by_agent), Number(record.est_usd) || 0, prices, loaded);
+    const snap = snapshots.get(record.session_id);
+    const buckets = snap ? priceableBuckets(snap.by_model, snap.by_agent) : [];
+    return priceRecord(buckets, Number(record.est_usd) || 0, prices, loaded);
+}
 /**
- * Groups telemetry records by their tagged `change` (records with no `change` fall
- * into `untagged`): session count, median and total main/subagent tokens, summed
- * observer tokens, summed est USD, and the tier mix (`standard 2, fast 1`, tiers with
- * no session omitted). One row per change, ranked by total main tokens descending.
+ * Groups telemetry records by tagged `change` (`untagged` catch-all): session count and
+ * median tokens over `measured` records only; total tokens, est USD (repriced at read
+ * time) and the tier mix over every record. Every change with at least one record gets a
+ * row (sessions/medians 0 with none `measured`); ranked by total main tokens descending.
+ * `opts.days` keeps records whose `ts` falls in the last N days of `opts.now`; an unparseable
+ * `ts` cannot be placed in the window, so it is counted in `skippedTs` instead of guessed at.
  */
-export function changes(records) {
+export function changes(records, usage = readUsage(costLogPath()), prices = loadPriceTable(costPricesPath()), pricesFile = costPricesPath(), opts = {}) {
+    let skippedTs = 0;
+    if (opts.days !== undefined) {
+        const cutoff = (opts.now ?? Date.now()) - opts.days * 86_400_000;
+        records = records.filter((r) => {
+            const at = Date.parse(r.ts);
+            if (Number.isNaN(at)) {
+                skippedTs += 1;
+                return false;
+            }
+            return at >= cutoff;
+        });
+    }
+    const loaded = Object.keys(prices).length > 0;
+    const snapshots = lastSessionEnd(usage);
     const groups = new Map();
+    const excluded = { "no-transcript": 0, "no-model-calls": 0 };
+    const classes = { sdd: 0, plan: 0, archive: 0, review: 0, debug: 0, untagged: 0, legacy: 0 };
     for (const r of records) {
+        const cls = activityClass(r);
+        if (cls !== "measured")
+            excluded[cls] += 1;
+        else {
+            if (typeof r.session_class !== "string")
+                classes.legacy += 1;
+            else if (SESSION_CLASS_NAMES.includes(r.session_class))
+                classes[r.session_class] += 1;
+            else
+                classes.untagged += 1;
+            if (subagentsUnread(r))
+                excluded["subagents-unread"] = (excluded["subagents-unread"] ?? 0) + 1;
+        }
         const key = r.change && r.change.trim() ? r.change.trim() : "untagged";
         const arr = groups.get(key) ?? [];
         arr.push(r);
         groups.set(key, arr);
     }
+    const t = newTally();
     const rows = [];
     for (const [change, recs] of groups) {
-        const mains = recs.map((r) => Number(r.sinks?.main?.total) || 0);
-        const subs = recs.map((r) => Number(r.sinks?.subagents?.total) || 0);
+        const measured = recs.filter((r) => activityClass(r) === "measured");
+        const mains = measured.map((r) => Number(r.sinks?.main?.total) || 0);
+        const subs = measured.filter((r) => !subagentsUnread(r)).map((r) => Number(r.sinks?.subagents?.total) || 0);
         const totalObserver = recs.reduce((n, r) => n + (Number(r.sinks?.observer?.tokens) || 0), 0);
-        const est_usd = round(recs.reduce((n, r) => n + (Number(r.est_usd) || 0), 0));
+        let est_usd = 0;
+        let estimated = false;
+        for (const r of recs) {
+            const priced = priceTelemetryRecord(r, snapshots, prices, loaded);
+            est_usd += priced.usd;
+            if (priced.estimated)
+                estimated = true;
+            tally(t, priced);
+        }
+        est_usd = round(est_usd);
         const tierCounts = new Map();
         for (const r of recs) {
             if (!r.tier)
@@ -388,35 +588,57 @@ export function changes(records) {
             .join(", ");
         rows.push({
             change,
-            sessions: recs.length,
+            sessions: measured.length,
             medianMain: median(mains),
-            totalMain: mains.reduce((a, b) => a + b, 0),
+            totalMain: recs.reduce((n, r) => n + (Number(r.sinks?.main?.total) || 0), 0),
             medianSubagents: median(subs),
-            totalSubagents: subs.reduce((a, b) => a + b, 0),
+            totalSubagents: recs.filter((r) => !subagentsUnread(r)).reduce((n, r) => n + (Number(r.sinks?.subagents?.total) || 0), 0),
             totalObserver,
             est_usd,
             tierMix,
+            ...(estimated ? { price_estimated: true } : {}),
         });
     }
-    return rows.sort((a, b) => b.totalMain - a.totalMain || a.change.localeCompare(b.change));
+    rows.sort((a, b) => b.totalMain - a.totalMain || a.change.localeCompare(b.change));
+    return { rows, pricing: pricingMeta(pricesFile, loaded, t.storedEstimate, t.withoutSplit), excluded, classes, skippedTs };
 }
-/** Renders the `--changes` report; `skipped` counts lines `readTelemetry` dropped (malformed or without `session_id`). */
-export function formatChanges(rows, file, skipped) {
+/** Renders the `--changes` report; `skipped` counts lines `readTelemetry` dropped (malformed or without `session_id`); `classes` adds the class line and `skippedTs` (set under `--days`) the unparseable-ts line. */
+export function formatChanges(rows, file, skipped, pricing, excluded, classes, skippedTs) {
     const lines = [];
+    lines.push(pricingLine(pricing));
     lines.push(`cost report --changes: ${file}${skipped > 0 ? ` (${skipped} lines skipped)` : ""}`);
+    lines.push(`excluded sessions: no-transcript ${excluded["no-transcript"]}, no-model-calls ${excluded["no-model-calls"]}, subagents-unread ${excluded["subagents-unread"] ?? 0}`);
+    if (skippedTs !== undefined)
+        lines.push(`skipped records with an unparseable ts: ${skippedTs}`);
+    if (classes) {
+        const share = untaggedShare(classes);
+        const pct = share === null ? "n/a" : `${(share * 100).toFixed(1)}%`;
+        const mix = SESSION_CLASS_NAMES.map((c) => (c === "untagged" ? `untagged ${classes[c]} (${pct})` : `${c} ${classes[c]}`));
+        lines.push(`session classes: ${mix.join(", ")}, legacy ${classes.legacy}`);
+    }
     if (rows.length === 0) {
         lines.push("no sessions recorded yet");
         return lines;
     }
     lines.push(`  ${"change".padEnd(24)} ${"sessions".padStart(8)} ${"median main".padStart(12)} ${"total main".padStart(11)} ${"median sub".padStart(11)} ${"total sub".padStart(10)} ${"observer".padStart(9)} ${"est USD".padStart(9)}  tier mix`);
     for (const r of rows) {
-        lines.push(`  ${r.change.slice(0, 24).padEnd(24)} ${String(r.sessions).padStart(8)} ${fmtTokens(r.medianMain).padStart(12)} ${fmtTokens(r.totalMain).padStart(11)} ${fmtTokens(r.medianSubagents).padStart(11)} ${fmtTokens(r.totalSubagents).padStart(10)} ${fmtTokens(r.totalObserver).padStart(9)} ${r.est_usd.toFixed(4).padStart(9)}  ${r.tierMix || "-"}`);
+        lines.push(`  ${r.change.slice(0, 24).padEnd(24)} ${String(r.sessions).padStart(8)} ${fmtTokens(r.medianMain).padStart(12)} ${fmtTokens(r.totalMain).padStart(11)} ${fmtTokens(r.medianSubagents).padStart(11)} ${fmtTokens(r.totalSubagents).padStart(10)} ${fmtTokens(r.totalObserver).padStart(9)} ${r.est_usd.toFixed(4).padStart(9)}  ${r.tierMix || "-"}${r.price_estimated ? " (estimated)" : ""}`);
     }
     return lines;
 }
+/** USD for one bucket at `row`'s rates (0 with no row); mirrors the hook's `estimate`, deriving the 1-hour rate at 1.6x `cache_write` when absent. */
+export function priceBucket(row, bucket) {
+    if (!row)
+        return 0;
+    const per = (n, price) => ((Number(n) || 0) * (Number(price) || 0)) / 1e6;
+    const write1h = Math.max(0, Math.min(Number(bucket.cache_write_1h) || 0, Number(bucket.cache_write) || 0));
+    const write5m = (Number(bucket.cache_write) || 0) - write1h;
+    const rate1h = row.cache_write_1h ?? (Number(row.cache_write) || 0) * 1.6;
+    return per(bucket.input, row.input) + per(bucket.output, row.output) + per(bucket.cache_read, row.cache_read) + per(write5m, row.cache_write) + per(write1h, rate1h);
+}
 /**
- * Loads the price table for `agents()`'s USD estimate; a missing or malformed file
- * yields an empty table so the estimate degrades to 0 instead of throwing.
+ * Loads the price table every `cost report` mode reprices from; a missing or malformed
+ * file yields an empty table so the estimate degrades to 0 instead of throwing.
  * Mirrors `loadPrices` in canonical/hooks/freeharness-cost-tracker.mjs; kept as a
  * separate copy since the hook is a standalone, dependency-free .mjs the CLI does not
  * import from. Returns model name -> price row (per MTok).
@@ -430,41 +652,94 @@ export function loadPriceTable(file) {
         return {};
     }
 }
+/** An id new to the table (a new version, a retried alias) is priced at its family's rate, not
+ * at `default`, which misprices an opus call several times over. */
+const PRICE_FAMILY_RE = /^claude-(?:opus|sonnet|haiku|fable)-/;
+/** Leading numeric `-` segments of `key` after `prefix`: `claude-opus-5-5` gives [5, 5]. */
+function versionSegments(key, prefix) {
+    const out = [];
+    for (const seg of key.slice(prefix.length).split("-")) {
+        if (!/^\d+$/.test(seg))
+            break;
+        out.push(Number(seg));
+    }
+    return out;
+}
+/** Positive when version `a` is newer than `b`; a missing segment counts lower, so 5-5 beats 5. */
+function compareVersions(a, b) {
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = i < a.length ? a[i] : -1;
+        const y = i < b.length ? b[i] : -1;
+        if (x !== y)
+            return x - y;
+    }
+    return 0;
+}
 /**
- * The price row for a model: exact key, then the longest key the model name starts
- * with, then `default`. Mirrors `priceFor` in canonical/hooks/freeharness-cost-tracker.mjs
- * (same separate-copy rationale as `loadPriceTable`). Undefined when no row matches.
+ * Exact key, else the longest prefix key, else the id's family's newest key (estimated), else
+ * `default`. Mirrors `priceMatch` in canonical/hooks/freeharness-cost-tracker.mjs (same
+ * separate-copy rationale as `loadPriceTable`); a parity test holds the two together.
  */
-function priceRowFor(prices, model) {
-    if (prices[model])
-        return prices[model];
+export function priceMatch(prices, model) {
+    const has = (key) => Object.prototype.hasOwnProperty.call(prices, key) && Boolean(prices[key]);
+    if (has(model))
+        return { key: model, row: prices[model], estimated: false };
     let best;
     for (const key of Object.keys(prices)) {
         if (key !== "default" && model.startsWith(key) && (!best || key.length > best.length))
             best = key;
     }
-    return best ? prices[best] : prices.default;
+    if (best)
+        return { key: best, row: prices[best], estimated: false };
+    const family = PRICE_FAMILY_RE.exec(model);
+    if (family) {
+        let newest;
+        let newestVersion = [];
+        for (const key of Object.keys(prices)) {
+            if (!key.startsWith(family[0]) || !has(key))
+                continue;
+            const version = versionSegments(key, family[0]);
+            const order = newest === undefined ? 1 : compareVersions(version, newestVersion);
+            if (order > 0 || (order === 0 && newest !== undefined && key.length > newest.length)) {
+                newest = key;
+                newestVersion = version;
+            }
+        }
+        if (newest !== undefined)
+            return { key: newest, row: prices[newest], estimated: true };
+    }
+    return has("default") ? { key: "default", row: prices.default, estimated: false } : { key: null, row: undefined, estimated: false };
 }
 /**
- * Ranks subagent dispatches by total tokens from each session's last `by_agent`
- * snapshot: per agent name, the model with the most tokens (ties broken by name,
- * mirroring the hook's `mergeAgentUsage`), `dispatches` and `messages` each summed
- * across sessions from their own fields (an entry from before per-transcript merging
- * carries no `dispatches` and counts as 1), tokens per bucket summed across sessions,
- * and an est USD from the price table. Rows ranked by total tokens descending.
+ * Ranks subagent dispatches by total tokens from each session's last `by_agent` snapshot:
+ * per agent name, the model with the most tokens (ties broken by name, mirroring the hook's
+ * `mergeAgentUsage`), `dispatches`/`messages` summed across sessions (no `dispatches` field
+ * counts as 1), USD from `priceBucket` per entry summed per name. Ranked by tokens
+ * descending, paired with the pricing header `formatAgents` reads.
  */
-export function agents(records, prices = loadPriceTable(costPricesPath())) {
+export function agents(records, prices = loadPriceTable(costPricesPath()), pricesFile = costPricesPath()) {
     const sessions = latestPerSession(records);
+    const loaded = Object.keys(prices).length > 0;
     const byName = new Map();
+    let withoutSplit = 0;
     for (const r of sessions) {
+        let sessionMissingSplit = false;
         for (const [name, a] of Object.entries(r.by_agent ?? {})) {
-            const row = byName.get(name) ?? { model: a.model, bestTotal: -1, dispatches: 0, messages: 0, input: 0, output: 0, cache_read: 0, cache_write: 0 };
+            if (!isAgentUsageLike(a))
+                continue;
+            const row = byName.get(name) ?? { model: a.model, bestTotal: -1, dispatches: 0, messages: 0, input: 0, output: 0, cache_read: 0, cache_write: 0, est_usd: 0, estimated: false };
             row.dispatches += Number(a.dispatches) || 1;
             row.messages += Number(a.messages) || 0;
             row.input += Number(a.usage.input) || 0;
             row.output += Number(a.usage.output) || 0;
             row.cache_read += Number(a.usage.cache_read) || 0;
             row.cache_write += Number(a.usage.cache_write) || 0;
+            const match = priceMatch(prices, a.model);
+            row.est_usd += priceBucket(match.row, a.usage);
+            if (match.estimated)
+                row.estimated = true;
+            if (!("cache_write_1h" in a.usage))
+                sessionMissingSplit = true;
             const total = Number(a.usage.total) || 0;
             if (total > row.bestTotal || (total === row.bestTotal && a.model.localeCompare(row.model) < 0)) {
                 row.bestTotal = total;
@@ -472,26 +747,25 @@ export function agents(records, prices = loadPriceTable(costPricesPath())) {
             }
             byName.set(name, row);
         }
+        if (sessionMissingSplit)
+            withoutSplit += 1;
     }
     const rows = [];
     for (const [name, r] of byName) {
         const tokens = r.input + r.output + r.cache_read + r.cache_write;
-        const price = priceRowFor(prices, r.model);
-        const per = (n, p) => (n * (Number(p) || 0)) / 1e6;
-        const est_usd = price ? per(r.input, price.input) + per(r.output, price.output) + per(r.cache_read, price.cache_read) + per(r.cache_write, price.cache_write) : 0;
-        rows.push({ name, model: r.model, dispatches: r.dispatches, messages: r.messages, input: r.input, output: r.output, cache_read: r.cache_read, cache_write: r.cache_write, tokens, est_usd: round(est_usd) });
+        rows.push({ name, model: r.model, dispatches: r.dispatches, messages: r.messages, input: r.input, output: r.output, cache_read: r.cache_read, cache_write: r.cache_write, tokens, est_usd: round(r.est_usd), ...(r.estimated ? { price_estimated: true } : {}) });
     }
-    return rows.sort((a, b) => b.tokens - a.tokens || a.name.localeCompare(b.name));
+    rows.sort((a, b) => b.tokens - a.tokens || a.name.localeCompare(b.name));
+    return { rows, pricing: pricingMeta(pricesFile, loaded, 0, withoutSplit) };
 }
-/** Renders the `--agents` report; `priceTable.loaded: false` prints a notice, `true` (or omitted) prints none. */
-export function formatAgents(rows, priceTable = { file: costPricesPath(), loaded: true }) {
+/** Renders the `--agents` report; `pricing.loaded: false` prints a warning and every row shows 0.00. */
+export function formatAgents(rows, pricing) {
     const lines = [];
+    lines.push(pricingLine(pricing));
     lines.push("cost report --agents (ranked by total tokens):");
-    if (!priceTable.loaded)
-        lines.push(`price table not loaded (${priceTable.file}): est USD shown as 0.00`);
     lines.push(`  ${"agent".padEnd(30)} ${"model".padEnd(24)} ${"dispatch".padStart(8)} ${"messages".padStart(8)} ${"tokens".padStart(9)} ${"est USD".padStart(9)}`);
     for (const r of rows) {
-        lines.push(`  ${r.name.slice(0, 30).padEnd(30)} ${r.model.slice(0, 24).padEnd(24)} ${String(r.dispatches).padStart(8)} ${String(r.messages).padStart(8)} ${fmtTokens(r.tokens).padStart(9)} ${r.est_usd.toFixed(4).padStart(9)}`);
+        lines.push(`  ${r.name.slice(0, 30).padEnd(30)} ${r.model.slice(0, 24).padEnd(24)} ${String(r.dispatches).padStart(8)} ${String(r.messages).padStart(8)} ${fmtTokens(r.tokens).padStart(9)} ${r.est_usd.toFixed(4).padStart(9)}${r.price_estimated ? " (estimated)" : ""}`);
     }
     return lines;
 }
@@ -499,3 +773,1403 @@ export function formatAgents(rows, priceTable = { file: costPricesPath(), loaded
 export function telemetryPath(dir = process.cwd()) {
     return path.join(path.resolve(dir), ".freeharness", "telemetry.jsonl");
 }
+const FAMILIES = ["opus", "sonnet", "haiku", "fable", "other"];
+/** The family a model id names as a whole `-`/`.`/`_`-delimited segment, so `claude-opusx-1` is not Opus. */
+export function familyOf(model) {
+    const segments = model.toLowerCase().split(/[^a-z0-9]+/);
+    return FAMILIES.find((f) => f !== "other" && segments.includes(f)) ?? "other";
+}
+/** Sums buckets per model into the two groups per family, in `FAMILIES` order; `cache_write_1h` is part of `cache_write`, so it is never added twice. */
+export function tokenGroups(usageByModel) {
+    const sums = new Map();
+    for (const [model, b] of Object.entries(usageByModel)) {
+        const family = familyOf(model);
+        const g = sums.get(family) ?? { cache_read: 0, fresh: 0 };
+        g.cache_read += Number(b.cache_read) || 0;
+        g.fresh += (Number(b.input) || 0) + (Number(b.cache_write) || 0) + (Number(b.output) || 0);
+        sums.set(family, g);
+    }
+    const out = {};
+    for (const f of FAMILIES) {
+        const g = sums.get(f);
+        if (g)
+            out[f] = g;
+    }
+    return out;
+}
+const UNCLASSIFIED = "unclassified";
+/** Joins a change and task into an `AcceptanceMap` key. */
+export function acceptanceKey(change, task) {
+    return `${change}\u0000${task}`;
+}
+const ROUTING_READ_CAP = 16 * 1024 * 1024;
+/** The brief cap the cost tracker and the handoff validator read under. */
+const BRIEF_READ_CAP = 1024 * 1024;
+/** Whether a filesystem error means the file is absent rather than unreadable. */
+function isNotFound(err) {
+    return err.code === "ENOENT";
+}
+/** A regular file's text within `ROUTING_READ_CAP`; a symlink, FIFO, device, oversize or unreadable file lands in `skipped`, an absent one does not. */
+function readRegularFile(file, skipped) {
+    return readRegularEntry(file, skipped)?.text;
+}
+/** `readRegularFile` with the file's mtime, under `cap` bytes. */
+function readRegularEntry(file, skipped, cap = ROUTING_READ_CAP) {
+    let st;
+    try {
+        st = fs.lstatSync(file);
+    }
+    catch (err) {
+        if (!isNotFound(err))
+            skipped.push(file);
+        return undefined;
+    }
+    if (!st.isFile() || st.size > cap) {
+        skipped.push(file);
+        return undefined;
+    }
+    try {
+        return { text: fs.readFileSync(file, "utf8"), mtimeMs: st.mtimeMs };
+    }
+    catch (err) {
+        if (!isNotFound(err))
+            skipped.push(file);
+        return undefined;
+    }
+}
+/** Reads one change's `ledger.jsonl` into role-filtered lines; invalid JSON, an impl/fix/review line without `ts`, `task` or `model`, and a line with any other non-null role (or none) are malformed and counted; a `role: null` line (a non-SDD dispatch) is skipped uncounted. */
+export function readLedgerLines(file, change) {
+    const lines = [];
+    let malformed = 0;
+    const skippedFiles = [];
+    const text = readRegularFile(file, skippedFiles);
+    if (text === undefined)
+        return { lines, malformed, skipped: skippedFiles.length > 0 };
+    for (const raw of text.split("\n")) {
+        if (!raw.trim())
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            malformed += 1;
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object") {
+            malformed += 1;
+            continue;
+        }
+        const r = parsed;
+        if (r.role === null)
+            continue;
+        if (r.role !== "impl" && r.role !== "fix" && r.role !== "review") {
+            malformed += 1;
+            continue;
+        }
+        if (typeof r.ts !== "string" || !r.ts || typeof r.task !== "string" || !r.task || typeof r.model !== "string" || !r.model) {
+            malformed += 1;
+            continue;
+        }
+        const effortSource = r.effort_source === "payload" || r.effort_source === "transcript" || r.effort_source === "agent" ? r.effort_source : null;
+        lines.push({
+            change,
+            ts: r.ts,
+            role: r.role,
+            task: r.task,
+            model: r.model,
+            // The agent definition's effort applies only to plain subagent dispatches, so an agent-sourced effort is unverified and read as null.
+            effort: effortSource !== "agent" && isEffortLevel(r.effort) ? r.effort : null,
+            input: Number(r.input) || 0,
+            output: Number(r.output) || 0,
+            cache_read: Number(r.cache_read) || 0,
+            cache_write: Number(r.cache_write) || 0,
+            cache_write_1h: typeof r.cache_write_1h === "number" ? r.cache_write_1h : undefined,
+            agent_id: typeof r.agent_id === "string" ? r.agent_id : null,
+            late: r.late === true,
+            effort_source: effortSource,
+            transcript: typeof r.transcript === "string" ? r.transcript : undefined,
+            round: typeof r.round === "number" && Number.isFinite(r.round) ? r.round : null,
+            session: typeof r.session === "string" ? r.session : null,
+            cc_version: typeof r.cc_version === "string" ? r.cc_version : null,
+        });
+    }
+    return { lines, malformed, skipped: false };
+}
+/** The vendored engine's `TASK_LINE_PATTERN`; not part of @freeharness/sdd's public surface, so kept as a local copy. */
+const TASK_LINE_PATTERN = /^\s*(?:[-*+]|\d{1,9}[.)])\s*\[(?:\s*([^\]\s])\s*\](?![([])|\](?![([])|\s+\])\s*(.*)/;
+/** A task line's leading `N.N` numbering. */
+const TASK_ID_PATTERN = /^(\d+(?:\.\d+)+)(?=\s|$)/;
+/** Task ids (leading `N.N` numbering) checked (`x`/`X`) in a tasks.md body; mirrors the vendored reader's marker set (dash, star, plus, ordered). */
+export function checkedTaskIds(content) {
+    return taskLineIds(content).checked;
+}
+/** Every task line's id and the checked ones, from one pass over a tasks.md body. */
+function taskLineIds(content) {
+    const all = new Set();
+    const checked = new Set();
+    for (const line of content.split("\n")) {
+        const m = line.match(TASK_LINE_PATTERN);
+        if (!m)
+            continue;
+        const id = m[2].trim().match(TASK_ID_PATTERN)?.[1];
+        if (!id)
+            continue;
+        all.add(id);
+        if ((m[1] ?? "").toLowerCase() === "x")
+            checked.add(id);
+    }
+    return { all, checked };
+}
+/** A dotted numeric id, the only shape that rolls up; linear on untrusted ledger text. */
+const DOTTED_TASK_RE = /^\d+(?:\.\d+)+$/;
+/** A dotted id below the `N.N` depth tasks.md numbers its tasks at. */
+const SUB_TASK_RE = /^\d+(?:\.\d+){2,}$/;
+/**
+ * The tasks.md task a dispatch's task id counts under, so splitting a task into sub-tasks never
+ * raises the task count: the id itself or its longest prefix (cut at a dot) listed as a task line.
+ * @param task The ledger task id.
+ * @param tasksMdIds Every task line id of the change's tasks.md.
+ * @returns The listed id, or null when no prefix is listed or the id is not dotted numbers.
+ */
+export function rollUpTask(task, tasksMdIds) {
+    if (!DOTTED_TASK_RE.test(task))
+        return null;
+    for (let id = task;; id = id.slice(0, id.lastIndexOf("."))) {
+        if (tasksMdIds.has(id))
+            return id;
+        if (!id.includes("."))
+            return null;
+    }
+}
+// The prompt brief path rule below mirrors briefPathFromText in
+// canonical/hooks/freeharness-cost-tracker.mjs, a standalone hook the CLI cannot import, so the
+// report files a dispatch under the change the tracker filed it under.
+/** The tracker's transcript cap; a larger transcript names no brief there, so none here either. */
+const PROMPT_TRANSCRIPT_CAP = 64 * 1024 * 1024;
+const PROMPT_SCAN_CHARS = 16 * 1024;
+const PROMPT_BRIEF_MARK = ".freeharness/sdd/";
+const PROMPT_BRIEF_SUFFIX = ".brief.md";
+const PROMPT_TOKEN_STOPS = new Set(['"', "'", "`", "(", ")", "<", ">", "[", "]"]);
+const PROMPT_TOKEN_TRAIL = new Set([".", ",", ";", ":", "!", "?"]);
+function promptTokenStop(ch) {
+    return PROMPT_TOKEN_STOPS.has(ch) || ch.trim() === "";
+}
+/** Kebab-case only, checked without a nested quantifier since the prompt is untrusted. */
+function kebabSegment(s) {
+    return /^[a-z0-9-]+$/.test(s) && !s.startsWith("-") && !s.endsWith("-") && !s.includes("--");
+}
+function realPathOr(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** A relative prefix, or the project root itself (lexical or real) followed by a slash. */
+function promptRootAccepted(prefix, root) {
+    if (prefix === "" || prefix === "./")
+        return true;
+    if (!path.isAbsolute(prefix) || !prefix.endsWith("/") || !root)
+        return false;
+    const withSep = (p) => (p.endsWith("/") ? p : `${p}/`);
+    const resolved = path.resolve(root);
+    return prefix === withSep(resolved) || prefix === withSep(realPathOr(resolved));
+}
+/** The change of the first `.freeharness/sdd/<change>/<file>.brief.md` token in the prompt's leading slice; an invalid first match yields null so a prompt cannot steer past a refused path. */
+function promptBriefFromText(text, root) {
+    if (!text)
+        return null;
+    const truncated = text.length > PROMPT_SCAN_CHARS;
+    const scan = truncated ? text.slice(0, PROMPT_SCAN_CHARS) : text;
+    let from = 0;
+    for (;;) {
+        const at = scan.indexOf(PROMPT_BRIEF_MARK, from);
+        if (at < 0)
+            return null;
+        let start = at;
+        while (start > from && !promptTokenStop(scan[start - 1]))
+            start -= 1;
+        const restStart = at + PROMPT_BRIEF_MARK.length;
+        let end = restStart;
+        while (end < scan.length && !promptTokenStop(scan[end]))
+            end += 1;
+        if (truncated && end === scan.length)
+            return null;
+        let stop = end;
+        while (stop > restStart && PROMPT_TOKEN_TRAIL.has(scan[stop - 1]))
+            stop -= 1;
+        if (stop - PROMPT_BRIEF_SUFFIX.length >= restStart && scan.endsWith(PROMPT_BRIEF_SUFFIX, stop)) {
+            const token = scan.slice(start, stop);
+            if (token.includes("..") || token.includes("\\"))
+                return null;
+            const parts = scan.slice(restStart, stop - PROMPT_BRIEF_SUFFIX.length).split("/");
+            if (parts.length !== 2 || !kebabSegment(parts[0]) || !parts[1])
+                return null;
+            if (!promptRootAccepted(scan.slice(start, at), root))
+                return null;
+            return parts[0];
+        }
+        from = end;
+    }
+}
+/** A message's text as the tracker reads it: string content, else its text blocks joined. */
+function messageText(msg) {
+    const content = msg && typeof msg === "object" ? msg.content : null;
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((c) => Boolean(c) && c.type === "text" && typeof c.text === "string")
+        .map((c) => c.text)
+        .join("\n");
+}
+/** Claude Code's config directory: `CLAUDE_CONFIG_DIR`, else `~/.claude`. */
+function claudeConfigDir() {
+    return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+}
+/** `file`'s real path when strictly under the real `<config dir>/projects` (the cost tracker's rule), else null: a project's ledger names its own transcript paths. */
+function containedTranscript(file) {
+    try {
+        const base = fs.realpathSync(path.resolve(claudeConfigDir(), "projects"));
+        const real = fs.realpathSync(file);
+        const rel = path.relative(base, real);
+        if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
+            return null;
+        return real;
+    }
+    catch {
+        return null;
+    }
+}
+/** A contained transcript's text through one fd that never follows a symlink leaf or blocks on a FIFO, bounded by the fstat size; null for an unusable file. The fd must be the checked real path's inode, so a parent swapped after the check cannot redirect the read. */
+function readTranscript(file) {
+    const real = containedTranscript(file);
+    if (real === null)
+        return null;
+    let fd;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | (fs.constants.O_NONBLOCK || 0));
+    }
+    catch {
+        return null;
+    }
+    try {
+        const st = fs.fstatSync(fd);
+        if (!st.isFile() || st.size > PROMPT_TRANSCRIPT_CAP)
+            return null;
+        const entry = fs.lstatSync(real);
+        if (entry.dev !== st.dev || entry.ino !== st.ino)
+            return null;
+        const buf = Buffer.allocUnsafe(st.size);
+        let total = 0;
+        while (total < buf.length) {
+            const n = fs.readSync(fd, buf, total, buf.length - total, total);
+            if (n === 0)
+                break;
+            total += n;
+        }
+        return buf.toString("utf8", 0, total);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * The change a dispatch's prompt names by its brief path, read from the first user message of its
+ * transcript, so a dispatch in several ledgers counts where the cost tracker filed it.
+ * @param transcriptPath The ledger line's `transcript` path.
+ * @param projectRoot The project root an absolute prompt path must sit under; without it only a relative path counts.
+ * @returns The named change, in flight or archived, or null for an unusable transcript or no valid path.
+ */
+export function promptBriefChange(transcriptPath, projectRoot) {
+    if (typeof transcriptPath !== "string" || !transcriptPath)
+        return null;
+    const text = readTranscript(transcriptPath);
+    if (text === null)
+        return null;
+    let from = 0;
+    while (from < text.length) {
+        const nl = text.indexOf("\n", from);
+        const raw = text.slice(from, nl < 0 ? text.length : nl);
+        from = nl < 0 ? text.length : nl + 1;
+        if (!raw.trim())
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (!rec || typeof rec !== "object" || Array.isArray(rec))
+            continue;
+        const r = rec;
+        if (r.type === "user")
+            return promptBriefFromText(messageText(r.message), projectRoot);
+    }
+    return null;
+}
+/** Claude Code before this version recorded placeholder output tokens in subagent transcripts. */
+const CC_BAND_FLOOR = "2.1.307";
+/** The cost tracker's version pattern, so the report trusts exactly the values the tracker records. */
+const CC_VERSION_RE = /^(\d{1,4})\.(\d{1,4})\.(\d{1,6})(?:-[0-9A-Za-z.]{1,16})?$/;
+const CC_LATER = `${CC_BAND_FLOOR} or later`;
+function emptyBands() {
+    return { [CC_LATER]: 0, older: 0, unknown: 0 };
+}
+/**
+ * Whether a dispatch's subagent fresh tokens can be trusted: recorded on 2.1.307 or later. A
+ * pre-release suffix is ignored, since it carries the same recording fix as its release.
+ */
+export function ccBand(version) {
+    const m = typeof version === "string" ? CC_VERSION_RE.exec(version) : null;
+    if (!m)
+        return "unknown";
+    const floor = CC_BAND_FLOOR.split(".").map(Number);
+    for (let i = 0; i < floor.length; i++) {
+        const d = Number(m[i + 1]) - floor[i];
+        if (d !== 0)
+            return d > 0 ? CC_LATER : "older";
+    }
+    return CC_LATER;
+}
+/** The last valid `version` of a user or assistant record of a contained transcript, for ledger lines written before they carried `cc_version`. */
+function transcriptCcVersion(transcriptPath) {
+    const text = readTranscript(transcriptPath);
+    if (text === null)
+        return null;
+    let last = null;
+    for (const raw of text.split("\n")) {
+        if (!raw.includes('"version"'))
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (!rec || typeof rec !== "object" || Array.isArray(rec))
+            continue;
+        const r = rec;
+        if ((r.type === "user" || r.type === "assistant") && typeof r.version === "string" && CC_VERSION_RE.test(r.version))
+            last = r.version;
+    }
+    return last;
+}
+/** A dispatch's band: its latest line's `cc_version`, else its transcript's version. */
+function dispatchBand(line, transcriptVersion) {
+    const own = ccBand(line.cc_version ?? null);
+    if (own !== "unknown" || !transcriptVersion || typeof line.transcript !== "string" || !line.transcript)
+        return own;
+    return ccBand(transcriptVersion(line.transcript));
+}
+const ARCHIVE_DATE_PREFIX = /^\d{4}-\d{2}-\d{2}$/;
+/** A file of the change directory (tasks.md, follow-ups.md): in-flight, else archived (exact dir name, else the first `YYYY-MM-DD-<change>` entry, never `model-routing-5` for `routing-5`). */
+function findChangeFile(projectRoot, change, name = "tasks.md") {
+    const active = path.join(projectRoot, "openspec", "changes", change, name);
+    if (fs.existsSync(active))
+        return active;
+    const archiveDir = path.join(projectRoot, "openspec", "changes", "archive");
+    let entries;
+    try {
+        entries = fs
+            .readdirSync(archiveDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return undefined;
+    }
+    const dirName = entries.includes(change) ? change : [...entries].filter((e) => e.endsWith(`-${change}`) && ARCHIVE_DATE_PREFIX.test(e.slice(0, -change.length - 1))).sort()[0];
+    if (!dirName)
+        return undefined;
+    const file = path.join(archiveDir, dirName, name);
+    return fs.existsSync(file) ? file : undefined;
+}
+/** The task ids a brief's `Task:` header lists (comma-separated, a trailing `(...)` note ignored). */
+function taskIdsFromBriefHeader(header) {
+    return header
+        .split(",")
+        .map((part) => /^\s*(\d+(?:\.\d+)+)/.exec(part)?.[1])
+        .filter((id) => Boolean(id));
+}
+/** An id token shaped like a dispatch task: digits and dots, an optional trailing batch `b`, or `final`. */
+const TASK_ID_RE = /^(?:\d+(?:\.\d+)*b?|final)$/;
+/** Whether a `Task:` header declares the task: exact match, a batch id token, or a `b` task
+ * matching the batch's first token (else `2.10` wrongly matches `2.1`). Mirrors the cost
+ * tracker's rule, so the report reads the brief the ledger attributed the dispatch to. */
+function matchesTaskHeader(headerValue, task) {
+    const raw = headerValue.trim();
+    if (raw === task)
+        return true;
+    const ids = raw
+        .split(/[,\s]+/)
+        .map((s) => s.trim())
+        .filter((s) => TASK_ID_RE.test(s));
+    if (ids.includes(task))
+        return true;
+    if (task.endsWith("b") && ids[0] === task.slice(0, -1))
+        return true;
+    return false;
+}
+/** The longest `Task:` or `Class:` line a brief is classified by. */
+const BRIEF_HEADER_LINE_CAP = 256;
+/** The most briefs read per change, so the kept headers stay bounded. */
+const BRIEF_COUNT_CAP = 500;
+/** A copy sharing no storage with `s`: V8 keeps a regex capture as a slice of its source, so a kept capture pins the whole brief text. */
+function detached(s) {
+    return Buffer.from(s, "utf8").toString("utf8");
+}
+/** A brief's `Task:` and `Class:` values; `undefined` when either line exceeds `BRIEF_HEADER_LINE_CAP`. */
+function briefHeaders(text) {
+    const task = /^Task:\s*(.+)$/m.exec(text);
+    const cls = /^Class:[ \t]*(.*)$/m.exec(text);
+    if ((task?.[0].length ?? 0) > BRIEF_HEADER_LINE_CAP || (cls?.[0].length ?? 0) > BRIEF_HEADER_LINE_CAP)
+        return undefined;
+    return { header: task ? detached(task[1]) : undefined, class: cls ? detached(cls[1].trim()) : undefined };
+}
+/** Every `*.brief.md` under `changeDir`, subdirectories included as the tracker walks them (a symlinked directory is not entered), read as `readRegularFile` reads under `BRIEF_READ_CAP`; a skipped brief, a brief with an over-cap header line, and a directory that exists but cannot be listed land in `skipped`, and briefs past `BRIEF_COUNT_CAP` in walk order land there once as a count. */
+function readChangeBriefs(changeDir, skipped) {
+    const out = [];
+    let seen = 0;
+    const walk = (rel) => {
+        const dir = path.join(changeDir, rel);
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        }
+        catch (err) {
+            if (!isNotFound(err))
+                skipped.push(dir);
+            return;
+        }
+        for (const entry of entries) {
+            const name = path.join(rel, entry.name);
+            if (entry.isDirectory()) {
+                walk(name);
+                continue;
+            }
+            if (!entry.name.endsWith(".brief.md"))
+                continue;
+            if (++seen > BRIEF_COUNT_CAP)
+                continue;
+            const file = path.join(changeDir, name);
+            const read = readRegularEntry(file, skipped, BRIEF_READ_CAP);
+            if (!read)
+                continue;
+            const headers = briefHeaders(read.text);
+            if (headers)
+                out.push({ name, mtimeMs: read.mtimeMs, ...headers });
+            else
+                skipped.push(file);
+        }
+    };
+    walk("");
+    if (seen > BRIEF_COUNT_CAP)
+        skipped.push(`${changeDir} (${seen - BRIEF_COUNT_CAP} over the ${BRIEF_COUNT_CAP}-brief cap)`);
+    return out;
+}
+/** The newest brief whose `Task:` header declares `task` (the greater relative path on equal mtime, as the tracker picks); only a task-shaped id resolves a brief. */
+function briefForTask(briefs, task) {
+    if (!TASK_ID_RE.test(task))
+        return undefined;
+    let best;
+    for (const b of briefs) {
+        if (b.header === undefined || !matchesTaskHeader(b.header, task))
+            continue;
+        if (!best || b.mtimeMs > best.mtimeMs || (b.mtimeMs === best.mtimeMs && b.name > best.name))
+            best = b;
+    }
+    return best;
+}
+/** The task ids a brief's `Task:` header lists; empty without a brief or header. */
+function briefTaskIds(brief) {
+    return brief?.header !== undefined ? taskIdsFromBriefHeader(brief.header) : [];
+}
+/** Whether a ledger task id is accepted: via its brief's `Task:` header when it lists numbered ids (a batch `2.1, 2.2 (batch)` needs every one checked), else the task id itself. */
+function resolveAcceptance(brief, checked, task) {
+    const ids = briefTaskIds(brief);
+    return ids.length > 0 ? ids.every((id) => checked.has(id)) : checked.has(task);
+}
+/** A brief's routing facts for a ledger task id (`2.1b` is declared by a header listing `2.1`). */
+function briefFacts(brief, task) {
+    const id = /^\d+(?:\.\d+)+/.exec(task)?.[0];
+    return { declared: id !== undefined && briefTaskIds(brief).includes(id), class: brief?.class || UNCLASSIFIED };
+}
+function byTs(a, b) {
+    return a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0;
+}
+/** The earliest on-time line (else earliest line) in the change a cross-ledger dispatch's prompt names; the transcript is read only when the lines span several changes, so a single-ledger report never opens one. */
+function promptOwner(sorted, promptChange) {
+    if (!promptChange || new Set(sorted.map((l) => l.change)).size < 2)
+        return undefined;
+    const transcript = sorted.find((l) => typeof l.transcript === "string" && l.transcript)?.transcript;
+    const change = transcript ? promptChange(transcript) : null;
+    const named = change === null ? [] : sorted.filter((l) => l.change === change);
+    return named.find((l) => l.late !== true) ?? named[0];
+}
+/**
+ * Collapses ledger lines to one per dispatch (`agent_id` across every ledger read).
+ *
+ * Lines are cumulative snapshots, so the latest one carries the dispatch's totals. Effort skips
+ * late lines when another exists: a SubagentStop payload names the effort the dispatch ran at. A
+ * dispatch in several changes' ledgers counts under the change its prompt's brief path names, the
+ * tracker's own rule, when that change holds one of its lines. Otherwise a backfill copy filed
+ * under another change whose brief also declares the task is always late, so the dispatch takes
+ * the change and task of its earliest on-time line whose brief declares the task, else of its
+ * earliest declaring line, else of its earliest line. The earliest ts is kept so "first impl
+ * dispatch" means first recorded.
+ */
+function collapseDispatches(ledgers, briefs, promptChange) {
+    const byAgent = new Map();
+    const dispatches = [];
+    for (const line of ledgers) {
+        if (typeof line.agent_id !== "string") {
+            dispatches.push([line]);
+            continue;
+        }
+        const group = byAgent.get(line.agent_id);
+        if (group)
+            group.push(line);
+        else {
+            const fresh = [line];
+            byAgent.set(line.agent_id, fresh);
+            dispatches.push(fresh);
+        }
+    }
+    return dispatches.map((group) => {
+        const sorted = [...group].sort(byTs);
+        const declaring = sorted.filter((l) => briefs.get(acceptanceKey(l.change, l.task))?.declared === true);
+        const owner = promptOwner(sorted, promptChange) ?? declaring.find((l) => l.late !== true) ?? declaring[0] ?? sorted[0];
+        const latest = sorted[sorted.length - 1];
+        const onTime = sorted.filter((l) => l.late !== true);
+        const effortLine = onTime.length > 0 ? onTime[onTime.length - 1] : latest;
+        return { ...latest, change: owner.change, task: owner.task, ts: sorted[0].ts, effort: effortLine.effort, effort_source: effortLine.effort_source ?? null };
+    });
+}
+const UNRECORDED = "unrecorded";
+/** An empty per-model sum without a prototype: its keys are model names read from the ledgers and telemetry, so one named `__proto__` stays an own key instead of reaching Object.prototype. */
+function bucketsByModel() {
+    return Object.create(null);
+}
+/** Adds a bucket to its model's sum; fields are coerced, since telemetry buckets are untrusted file data. */
+function addTokens(byModel, model, add) {
+    const b = Object.hasOwn(byModel, model) ? byModel[model] : { input: 0, output: 0, cache_read: 0, cache_write: 0 };
+    b.input += Number(add.input) || 0;
+    b.output += Number(add.output) || 0;
+    b.cache_read += Number(add.cache_read) || 0;
+    b.cache_write += Number(add.cache_write) || 0;
+    byModel[model] = b;
+}
+/** A task's fix rounds: a re-dispatch inside one round counts once, a fix without a round is a round of its own. */
+function distinctFixRounds(lines) {
+    const numbered = new Set();
+    let unnumbered = 0;
+    for (const line of lines) {
+        if (line.role !== "fix")
+            continue;
+        if (typeof line.round === "number")
+            numbered.add(line.round);
+        else
+            unnumbered += 1;
+    }
+    return numbered.size + unnumbered;
+}
+/** Whole tokens per accepted task; empty with zero accepted, so no family reads as a zero-cost measurement. */
+function perAccepted(groups, accepted) {
+    const out = {};
+    if (accepted === 0)
+        return out;
+    for (const [family, g] of Object.entries(groups)) {
+        out[family] = { cache_read: Math.round(g.cache_read / accepted), fresh: Math.round(g.fresh / accepted) };
+    }
+    return out;
+}
+/**
+ * Groups dispatches by task, assigns each task the (model, effort) of its first `impl` dispatch
+ * (none excludes it), and aggregates per (model, effort, class): role counts, first-pass tasks,
+ * `escalated` (a later impl/fix on another model), USD, and, over accepted tasks only, tokens by
+ * family and distinct fix rounds.
+ *
+ * Sub-task dispatches count under the task `options.rollUp` maps them to, so splitting a task
+ * never raises the task count; an id mapped to null counts in no row. A rolled-up task's class is
+ * the brief class of the sub-task its first impl dispatch ran, the configuration that did the work.
+ * @param options Roll-up map and prompt-path resolver; omitted, every id is its own task and
+ *   duplicate dispatches follow the declaring-brief rule.
+ */
+export function routingReport(ledgers, acceptance, prices, briefs = new Map(), options = {}) {
+    return tallyRouting(ledgers, acceptance, prices, briefs, options).rows;
+}
+/** `routingReport` with the figures beside the rows. */
+function tallyRouting(ledgers, acceptance, prices, briefs, options) {
+    const byTask = new Map();
+    const unmatched = new Set();
+    for (const line of collapseDispatches(ledgers, briefs, options.promptChange)) {
+        const own = acceptanceKey(line.change, line.task);
+        const task = options.rollUp?.has(own) ? options.rollUp.get(own) : line.task;
+        if (task === null || task === undefined) {
+            unmatched.add(own);
+            continue;
+        }
+        const key = acceptanceKey(line.change, task);
+        const agg = byTask.get(key) ?? { change: line.change, task, lines: [] };
+        agg.lines.push(line);
+        byTask.set(key, agg);
+    }
+    const rows = new Map();
+    const reviews = new Map();
+    const acceptedTasks = new Map();
+    const acceptedByModel = bucketsByModel();
+    const acceptedTaskRecords = [];
+    const bandOf = new Map();
+    const band = (line) => {
+        let b = bandOf.get(line);
+        if (b === undefined) {
+            b = dispatchBand(line, options.transcriptVersion);
+            bandOf.set(line, b);
+        }
+        return b;
+    };
+    for (const [taskKey, agg] of byTask) {
+        // A review row needs no implementer configuration, so a review-only task (a final round) still counts.
+        for (const line of agg.lines) {
+            if (line.role !== "review")
+                continue;
+            const effort = line.effort ?? "unknown";
+            const criterion = options.reviewCriteria?.get(acceptanceKey(line.change, line.task)) ?? UNRECORDED;
+            const key = `${line.model}\u0000${effort}\u0000${criterion}`;
+            const acc = reviews.get(key) ?? { model: line.model, effort, criterion, dispatches: 0, tasks: new Set(), byModel: bucketsByModel(), bands: emptyBands() };
+            acc.dispatches += 1;
+            acc.bands[band(line)] += 1;
+            acc.tasks.add(taskKey);
+            addTokens(acc.byModel, line.model, line);
+            reviews.set(key, acc);
+        }
+    }
+    for (const agg of byTask.values()) {
+        const sorted = [...agg.lines].sort(byTs);
+        const firstImpl = sorted.find((l) => l.role === "impl");
+        if (!firstImpl)
+            continue;
+        const model = firstImpl.model;
+        const effort = firstImpl.effort ?? "unknown";
+        const taskKey = acceptanceKey(agg.change, agg.task);
+        // A rolled-up task takes the class of the sub-task its first impl dispatch ran.
+        const cls = briefs.get(acceptanceKey(firstImpl.change, firstImpl.task))?.class ?? UNCLASSIFIED;
+        const rowKey = `${model}\u0000${effort}\u0000${cls}`;
+        const row = rows.get(rowKey) ?? { model, effort, class: cls, tasks: 0, accepted: 0, firstPass: 0, impl: 0, fix: 0, review: 0, escalated: 0, usd: 0, estimated: false, acceptedUsd: 0, acceptedByModel: bucketsByModel(), acceptedFixRounds: 0, tasksOverOneRound: 0, acceptedTasks: new Map(), bands: emptyBands(), lowerBound: 0 };
+        row.tasks += 1;
+        const isAccepted = acceptance.get(taskKey) === true;
+        if (isAccepted)
+            row.accepted += 1;
+        if (isAccepted && !sorted.some((l) => l.role === "fix"))
+            row.firstPass += 1;
+        let escalated = false;
+        let taskUsd = 0;
+        const taskBands = emptyBands();
+        for (const line of sorted) {
+            if (line.role === "impl")
+                row.impl += 1;
+            else if (line.role === "fix")
+                row.fix += 1;
+            else
+                row.review += 1;
+            if (line !== firstImpl && (line.role === "impl" || line.role === "fix") && line.model !== model)
+                escalated = true;
+            const lineBand = band(line);
+            row.bands[lineBand] += 1;
+            taskBands[lineBand] += 1;
+            if (isAccepted && lineBand !== CC_LATER)
+                row.lowerBound += 1;
+            const match = priceMatch(prices, line.model);
+            taskUsd += priceBucket(match.row, line);
+            if (match.estimated)
+                row.estimated = true;
+        }
+        row.usd += taskUsd;
+        if (isAccepted) {
+            row.acceptedUsd += taskUsd;
+            const taskByModel = bucketsByModel();
+            for (const line of sorted) {
+                addTokens(row.acceptedByModel, line.model, line);
+                addTokens(acceptedByModel, line.model, line);
+                addTokens(taskByModel, line.model, line);
+            }
+            acceptedTaskRecords.push({ change: agg.change, task: agg.task, class: cls, firstTs: sorted[0].ts, dispatches: sorted.length, bands: taskBands, fullyLater: taskBands[CC_LATER] === sorted.length, tokens: tokenGroups(taskByModel) });
+            for (const byChange of [acceptedTasks, row.acceptedTasks]) {
+                const ids = byChange.get(agg.change) ?? new Set();
+                ids.add(agg.task);
+                byChange.set(agg.change, ids);
+            }
+            const fixRounds = distinctFixRounds(sorted);
+            row.acceptedFixRounds += fixRounds;
+            if (fixRounds > 1)
+                row.tasksOverOneRound += 1;
+        }
+        if (escalated)
+            row.escalated += 1;
+        rows.set(rowKey, row);
+    }
+    const rowAccs = [...rows.values()].sort((a, b) => a.model.localeCompare(b.model) || a.effort.localeCompare(b.effort) || a.class.localeCompare(b.class));
+    const out = rowAccs
+        .map((r) => ({
+        model: r.model,
+        effort: r.effort,
+        class: r.class,
+        tasks: r.tasks,
+        accepted: r.accepted,
+        firstPass: r.firstPass,
+        impl: r.impl,
+        fix: r.fix,
+        review: r.review,
+        escalated: r.escalated,
+        usd: round(r.usd),
+        usdPerAccepted: r.accepted > 0 ? round(r.acceptedUsd / r.accepted) : null,
+        ...(r.estimated ? { price_estimated: true } : {}),
+        tokensPerAccepted: perAccepted(tokenGroups(r.acceptedByModel), r.accepted),
+        meanFixRounds: r.accepted > 0 ? round(r.acceptedFixRounds / r.accepted) : null,
+        tasksOverOneRound: r.tasksOverOneRound,
+        ...(options.followUps ? { followUpsPerAccepted: followUpsPerAccepted(options.followUps, r.acceptedTasks, r.accepted) } : {}),
+    }));
+    const reviewAccs = [...reviews.values()].sort((a, b) => a.model.localeCompare(b.model) || a.effort.localeCompare(b.effort) || a.criterion.localeCompare(b.criterion));
+    const reviewRows = reviewAccs.map((r) => ({ model: r.model, effort: r.effort, criterion: r.criterion, dispatches: r.dispatches, tasks: r.tasks.size, tokensPerTask: perAccepted(tokenGroups(r.byModel), r.tasks.size) }));
+    const total = emptyBands();
+    for (const b of bandOf.values())
+        total[b] += 1;
+    const versionBands = { rows: rowAccs.map((r) => r.bands), rowsLowerBound: rowAccs.map((r) => r.lowerBound), reviewRows: reviewAccs.map((r) => r.bands), total };
+    acceptedTaskRecords.sort((a, b) => (a.firstTs < b.firstTs ? -1 : a.firstTs > b.firstTs ? 1 : a.change.localeCompare(b.change) || a.task.localeCompare(b.task)));
+    return { rows: out, unmatchedSubTasks: unmatched.size, reviewRows, acceptedTasks, acceptedByModel, versionBands, acceptedTaskRecords };
+}
+/** A review package's first `Review tier:` line; the criterion must follow the tier at once, so a later line never stands in for a malformed first one. */
+const REVIEW_TIER_LINE = /^Review tier:[^\n]*$/m;
+const REVIEW_CRITERION = /^Review tier:[ \t]*[a-z]+[ \t]*-[ \t]*(S\d{1,3})(?![0-9A-Za-z])/;
+/** The `S<n>` criterion of `<task>.review.md` in a change's sdd directory, or `unrecorded`; only a task-shaped id names a file, so a ledger id never reaches outside the directory. */
+function reviewCriterion(changeDir, task, skipped) {
+    if (!TASK_ID_RE.test(task))
+        return UNRECORDED;
+    const read = readRegularEntry(path.join(changeDir, `${task}.review.md`), skipped, BRIEF_READ_CAP);
+    const line = read ? REVIEW_TIER_LINE.exec(read.text)?.[0] : undefined;
+    return (line && REVIEW_CRITERION.exec(line)?.[1]) || UNRECORDED;
+}
+/**
+ * The main-transcript buckets per model of a telemetry record. A record without `by_model` takes
+ * its session's snapshot `by_model`, as the cost report prices it, never `by_agent`, since the
+ * ledgers already count the subagents; with no snapshot its `sinks.main` total stays under
+ * `unknown`, so its tokens count under `other`, never dropped.
+ */
+function leadBuckets(record, snapshots) {
+    const byModel = record.by_model ?? snapshots.get(record.session_id)?.by_model;
+    const out = bucketsByModel();
+    if (byModel && typeof byModel === "object" && !Array.isArray(byModel)) {
+        for (const [model, b] of Object.entries(byModel))
+            if (b && typeof b === "object")
+                out[model] = b;
+        return out;
+    }
+    const main = record.sinks?.main;
+    if (main && typeof main === "object")
+        out.unknown = main;
+    return out;
+}
+/** The cost log's records, or none when it cannot be read: the snapshot join only refines the lead row, so a bad log must not fail the report. */
+function readUsageOrNone(file) {
+    try {
+        return readUsage(file);
+    }
+    catch {
+        return [];
+    }
+}
+/** The telemetry records tagged with a reported change; a non-regular telemetry file lands in `skipped` unread, since a cloned project controls the path. */
+function leadRecords(projectRoot, changes, skipped) {
+    const file = telemetryPath(projectRoot);
+    try {
+        if (!fs.lstatSync(file).isFile()) {
+            skipped.push(file);
+            return [];
+        }
+    }
+    catch (err) {
+        if (!isNotFound(err))
+            skipped.push(file);
+        return [];
+    }
+    return readTelemetry(file).filter((r) => recordChanges(r).some((c) => changes.has(c)));
+}
+/** The changes a record worked on: its `changes` array when it has one (even empty), else its `change` tag, as records written before the array carry only the tag. */
+function recordChanges(record) {
+    const listed = record.changes;
+    if (Array.isArray(listed))
+        return [...new Set(listed.filter((c) => typeof c === "string"))];
+    return typeof record.change === "string" ? [record.change] : [];
+}
+function sessionAgents(lines) {
+    const out = new Map();
+    for (const line of lines) {
+        if (typeof line.session !== "string" || typeof line.agent_id !== "string")
+            continue;
+        const ids = out.get(line.session) ?? new Set();
+        ids.add(line.agent_id);
+        out.set(line.session, ids);
+    }
+    return out;
+}
+/** Whole parts of `value` cut at rounded cumulative fractions of `weights`, so the parts always sum to the rounded value. */
+function splitWhole(value, weights) {
+    const total = weights.reduce((a, b) => a + b, 0);
+    let acc = 0;
+    let prev = 0;
+    return weights.map((w) => {
+        acc += w;
+        const cut = Math.round((value * acc) / total);
+        const part = cut - prev;
+        prev = cut;
+        return part;
+    });
+}
+const BUCKET_FIELDS = ["input", "output", "cache_read", "cache_write", "cache_write_1h"];
+/**
+ * A record's main-context buckets split across the changes it worked on, so a lead session that
+ * worked on several changes counts its context once in total rather than once per change. Each
+ * change's weight is the distinct dispatches the session ran in its ledger; with none anywhere the
+ * shares are equal. Parts are whole tokens that sum exactly to the record's figures, whichever
+ * changes a report reads.
+ * @param agentsOf Each named change's dispatches per session.
+ * @returns Per named change, its fraction (to scale a USD figure) and its buckets.
+ */
+export function leadShares(record, buckets, agentsOf) {
+    const named = recordChanges(record);
+    const out = new Map();
+    if (named.length === 1)
+        out.set(named[0], { share: 1, buckets });
+    if (named.length < 2)
+        return out;
+    const counts = named.map((c) => agentsOf(c).get(record.session_id)?.size ?? 0);
+    const sum = counts.reduce((a, b) => a + b, 0);
+    const weights = sum === 0 ? named.map(() => 1) : counts;
+    const parts = named.map((_, i) => ({ share: weights[i] / (sum === 0 ? named.length : sum), buckets: bucketsByModel() }));
+    for (const [model, b] of Object.entries(buckets)) {
+        const split = named.map(() => ({ input: 0, output: 0, cache_read: 0, cache_write: 0 }));
+        for (const field of BUCKET_FIELDS) {
+            if (field === "cache_write_1h" && typeof b.cache_write_1h !== "number")
+                continue;
+            splitWhole(Number(b[field]) || 0, weights).forEach((v, i) => (split[i][field] = v));
+        }
+        split.forEach((s, i) => (parts[i].buckets[model] = s));
+    }
+    named.forEach((c, i) => out.set(c, parts[i]));
+    return out;
+}
+/** Mirrors `FOLLOW_UP_TYPES` of @freeharness/sdd's follow-up shim, which its public surface does not export. */
+const FOLLOW_UP_TYPES = ["defect", "hardening", "refactor", "test-gap", "docs", "design", "owner-step", "upstream"];
+const FOLLOW_UP_ITEM = /^\s*[-*]\s*\[([ xX])\]\s*([^\n]*)$/;
+const FOLLOW_UP_CLAIM = /^->\s*claimed by\s+\S+\s*$/;
+const FOLLOW_UP_TYPE = /^\[([a-z-]+)\]/;
+/** A `(from <task>)` label that names a task: dotted numbers and an optional letter (`6.3a` counts under 6.3). */
+const FOLLOW_UP_TASK = /^(\d+(?:\.\d+)+)[a-z]?$/;
+/**
+ * The trimmed label of a suffix starting at `(from`, or null unless whitespace follows `from`, a
+ * label without `)` precedes the first `)` and only whitespace trails it. Split by index, since a
+ * pattern whose whitespace and label runs overlap backtracks quadratically on a long space run.
+ */
+function followUpFrom(suffix) {
+    const rest = suffix.slice("(from".length);
+    const close = rest.indexOf(")");
+    if (close < 2 || !/\s/.test(rest[0]) || rest.slice(close + 1).trim() !== "")
+        return null;
+    return rest.slice(0, close).trim();
+}
+/**
+ * Each follow-ups.md item's type and `(from <task>)` label, claimed or not, as the follow-up shim
+ * reads them; the suffixes are cut at their last marker rather than by a lazy regex, which a long
+ * hostile line would make quadratic.
+ */
+function followUpItems(text) {
+    const items = [];
+    for (const line of text.split(/\r?\n/)) {
+        const m = FOLLOW_UP_ITEM.exec(line);
+        if (!m)
+            continue;
+        let body = m[2].trimEnd();
+        if (m[1] !== " ") {
+            const at = body.lastIndexOf("->");
+            if (at >= 0 && FOLLOW_UP_CLAIM.test(body.slice(at)))
+                body = body.slice(0, at).trimEnd();
+        }
+        const at = body.lastIndexOf("(from");
+        const from = at >= 0 ? followUpFrom(body.slice(at)) : null;
+        const tag = FOLLOW_UP_TYPE.exec(body)?.[1];
+        items.push({ type: tag && FOLLOW_UP_TYPES.includes(tag) ? tag : "untyped", from });
+    }
+    return items;
+}
+/** Follow-ups whose label rolls up to one of the given accepted tasks (a row's, or the whole report's), per accepted task, by type in the shim's display order. */
+function followUpsPerAccepted(itemsByChange, acceptedTasks, accepted) {
+    if (accepted === 0)
+        return { total: null, byType: {} };
+    const counts = new Map();
+    let total = 0;
+    for (const [change, items] of itemsByChange) {
+        const ids = acceptedTasks.get(change);
+        if (!ids)
+            continue;
+        for (const item of items) {
+            const id = item.from === null ? undefined : FOLLOW_UP_TASK.exec(item.from)?.[1];
+            if (id === undefined || rollUpTask(id, ids) === null)
+                continue;
+            total += 1;
+            counts.set(item.type, (counts.get(item.type) ?? 0) + 1);
+        }
+    }
+    const byType = {};
+    for (const type of [...FOLLOW_UP_TYPES, "untyped"]) {
+        const n = counts.get(type);
+        if (n)
+            byType[type] = round(n / accepted);
+    }
+    return { total: round(total / accepted), byType };
+}
+/** A fit whose median miss exceeds this many percentage points is too loose to quote unmarked. */
+const UNRELIABLE_RESIDUAL = 1;
+/**
+ * Tokens per accepted task as a share of the seven-day window: tokens in millions times the
+ * fitted percent-per-million weight, summed over families and groups.
+ * @returns Null with zero accepted, or when a family with tokens has no fitted weight, since a
+ *   partial sum would understate the row.
+ */
+function sevenDayPct(tokens, weights, accepted) {
+    if (accepted === 0)
+        return null;
+    let pct = 0;
+    for (const [family, g] of Object.entries(tokens)) {
+        if (g.cache_read === 0 && g.fresh === 0)
+            continue;
+        const w = weights[family];
+        if (!w)
+            return null;
+        pct += (g.cache_read / 1e6) * w.cache_read + (g.fresh / 1e6) * w.fresh;
+    }
+    return round(pct);
+}
+/**
+ * Discovers every change under `.freeharness/sdd/` with a `ledger.jsonl` (or just `changeFilter`),
+ * resolves each task's acceptance against its tasks.md, and runs `routingReport` over the union.
+ * The review packages, the telemetry tagged with a reported change and its follow-ups.md add the
+ * review rows, the lead row and the per-accepted-task totals, since a gate counting dispatches
+ * alone would pass by moving cost into the lead session. A quota calibration with a seven-day
+ * window adds the window estimate to every row; an invalid one is ignored with a warning.
+ */
+export function routingReportForProject(projectRoot, changeFilter, prices = loadPriceTable(costPricesPath()), pricesFile = costPricesPath(), calibrationFile = quotaCalibrationPath()) {
+    const project = readRoutingProject(projectRoot, changeFilter);
+    const { acceptance, briefs, rollUp, malformedLines, missingTasksFiles, skipped, reported, reviewCriteria, followUps } = project;
+    const tally = tallyRouting(project.ledgers, acceptance, prices, briefs, { rollUp, promptChange: project.promptChange, reviewCriteria, followUps, transcriptVersion: project.transcriptVersion });
+    const leadByModel = bucketsByModel();
+    const { records, parts } = leadAttribution(projectRoot, project, reported);
+    for (const part of parts)
+        for (const [model, b] of Object.entries(part.buckets))
+            addTokens(leadByModel, model, b);
+    const allByModel = bucketsByModel();
+    for (const byModel of [tally.acceptedByModel, leadByModel])
+        for (const [model, b] of Object.entries(byModel))
+            addTokens(allByModel, model, b);
+    const accepted = [...tally.acceptedTasks.values()].reduce((n, ids) => n + ids.size, 0);
+    const { calibration, warning } = readCalibration(calibrationFile);
+    const fit = calibration?.windows.seven_day;
+    return {
+        rows: fit ? tally.rows.map((r) => ({ ...r, sevenDayPctPerAccepted: sevenDayPct(r.tokensPerAccepted, fit.weights, r.accepted) })) : tally.rows,
+        ...(fit ? { sevenDay: { residual: fit.residual, unreliable: fit.residual > UNRELIABLE_RESIDUAL } } : {}),
+        ...(warning ? { calibrationWarning: warning } : {}),
+        malformedLines,
+        missingTasksFiles,
+        skippedFiles: skipped.map((f) => path.relative(projectRoot, f)),
+        pricing: { table: pricesFile, loaded: Object.keys(prices).length > 0 },
+        unmatchedSubTasks: tally.unmatchedSubTasks,
+        reviewRows: tally.reviewRows,
+        lead: { sessions: records.length, tokens: tokenGroups(leadByModel) },
+        totalsPerAccepted: {
+            accepted,
+            dispatches: perAccepted(tokenGroups(tally.acceptedByModel), accepted),
+            lead: perAccepted(tokenGroups(leadByModel), accepted),
+            total: perAccepted(tokenGroups(allByModel), accepted),
+        },
+        followUpsPerAccepted: followUpsPerAccepted(followUps, tally.acceptedTasks, accepted),
+        versionBands: tally.versionBands,
+        acceptedTaskRecords: tally.acceptedTaskRecords,
+    };
+}
+function readRoutingProject(projectRoot, changeFilter) {
+    const root = path.join(projectRoot, ".freeharness", "sdd");
+    let changeDirs;
+    try {
+        changeDirs = fs
+            .readdirSync(root, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        changeDirs = [];
+    }
+    const listedChanges = new Set(changeDirs);
+    if (changeFilter)
+        changeDirs = changeDirs.filter((c) => c === changeFilter);
+    const ledgers = [];
+    const acceptance = new Map();
+    const briefs = new Map();
+    const rollUp = new Map();
+    let malformedLines = 0;
+    const missingTasksFiles = [];
+    const skipped = [];
+    const reported = new Set();
+    const reviewCriteria = new Map();
+    const followUps = new Map();
+    const linesByChange = new Map();
+    for (const change of changeDirs) {
+        const changeDir = path.join(root, change);
+        const ledgerFile = path.join(changeDir, "ledger.jsonl");
+        const { lines, malformed, skipped: ledgerSkipped } = readLedgerLines(ledgerFile, change);
+        if (ledgerSkipped)
+            skipped.push(ledgerFile);
+        malformedLines += malformed;
+        ledgers.push(...lines);
+        linesByChange.set(change, lines);
+        if (lines.length === 0)
+            continue;
+        reported.add(change);
+        const tasksFile = findChangeFile(projectRoot, change);
+        if (!tasksFile)
+            missingTasksFiles.push(change);
+        const tasksText = tasksFile ? readRegularFile(tasksFile, skipped) : undefined;
+        const { all, checked } = tasksText !== undefined ? taskLineIds(tasksText) : { all: new Set(), checked: new Set() };
+        const changeBriefs = readChangeBriefs(changeDir, skipped);
+        const tasks = new Set(lines.map((l) => l.task));
+        for (const task of tasks) {
+            // A plain N.N id or a non-dotted id (a batch brief, `final`) is a task in its own right even when tasks.md does not list it; only a sub-task needs an ancestor.
+            const rolled = rollUpTask(task, all) ?? (SUB_TASK_RE.test(task) ? null : task);
+            rollUp.set(acceptanceKey(change, task), rolled);
+            if (rolled !== null)
+                acceptance.set(acceptanceKey(change, rolled), resolveAcceptance(briefForTask(changeBriefs, rolled), checked, rolled));
+            briefs.set(acceptanceKey(change, task), briefFacts(briefForTask(changeBriefs, task), task));
+        }
+        for (const task of new Set(lines.filter((l) => l.role === "review").map((l) => l.task)))
+            reviewCriteria.set(acceptanceKey(change, task), reviewCriterion(changeDir, task, skipped));
+        const followUpsFile = findChangeFile(projectRoot, change, "follow-ups.md");
+        const followUpsText = followUpsFile ? readRegularFile(followUpsFile, skipped) : undefined;
+        if (followUpsText !== undefined)
+            followUps.set(change, followUpItems(followUpsText));
+    }
+    const versions = new Map();
+    const transcriptVersion = (t) => {
+        if (!versions.has(t))
+            versions.set(t, transcriptCcVersion(t));
+        return versions.get(t) ?? null;
+    };
+    return { root, listedChanges, ledgers, acceptance, briefs, rollUp, malformedLines, missingTasksFiles, skipped, reported, reviewCriteria, followUps, linesByChange, promptChange: (t) => promptBriefChange(t, projectRoot), transcriptVersion };
+}
+/** The telemetry records tagged with any of `changes`, and each one's part for every such change it names. */
+function leadAttribution(projectRoot, project, changes) {
+    const { root, listedChanges, linesByChange } = project;
+    const records = leadRecords(projectRoot, changes, project.skipped);
+    const snapshots = records.some((r) => r.by_model === undefined) ? lastSessionEnd(readUsageOrNone(costLogPath())) : new Map();
+    // A share's weight needs every named change's ledger, filtered out or not; only a listed directory name is ever read, never a path a record supplies.
+    const agents = new Map();
+    const agentsOf = (change) => {
+        let found = agents.get(change);
+        if (!found) {
+            const lines = linesByChange.get(change) ?? (listedChanges.has(change) ? readLedgerLines(path.join(root, change, "ledger.jsonl"), change).lines : []);
+            found = sessionAgents(lines);
+            agents.set(change, found);
+        }
+        return found;
+    };
+    const parts = [];
+    for (const record of records) {
+        for (const [change, part] of leadShares(record, leadBuckets(record, snapshots), agentsOf)) {
+            if (changes.has(change))
+                parts.push({ record, change, ...part });
+        }
+    }
+    return { records, parts };
+}
+/** A row's `--json` shape: `firstPass` and the token and round fields snake-cased, in column order. */
+function routingRowJson(row) {
+    const { model, effort, class: cls, tasks, accepted, firstPass, tokensPerAccepted, sevenDayPctPerAccepted, meanFixRounds, tasksOverOneRound, followUpsPerAccepted: followUpFigures, ...rest } = row;
+    const estimate = "sevenDayPctPerAccepted" in row ? { seven_day_pct_per_accepted: sevenDayPctPerAccepted ?? null } : {};
+    return { model, effort, class: cls, tasks, accepted, first_pass: firstPass, ...rest, tokens_per_accepted: tokensPerAccepted, ...estimate, mean_fix_rounds: meanFixRounds, tasks_over_one_round: tasksOverOneRound, follow_ups_per_accepted: followUpsJson(followUpFigures) };
+}
+/** A follow-up figure's `--json` shape, null when the result carries none. */
+function followUpsJson(figures) {
+    return figures ? { total: figures.total, by_type: figures.byType } : null;
+}
+/** The `--json` shape of a routing report: rows keyed as the data contract names them, the figures beside them after the existing fields. */
+export function routingReportJson(result) {
+    const { reviewRows, lead, totalsPerAccepted, followUpsPerAccepted: followUpFigures, sevenDay, calibrationWarning, versionBands, acceptedTaskRecords, ...rest } = result;
+    const bands = (list, i) => (list?.[i] ? { cc_version_bands: list[i] } : {});
+    return {
+        ...rest,
+        rows: result.rows.map((row, i) => ({ ...routingRowJson(row), ...bands(versionBands?.rows, i) })),
+        review_rows: (reviewRows ?? []).map(({ tokensPerTask, ...row }, i) => ({ ...row, tokens_per_task: tokensPerTask, ...bands(versionBands?.reviewRows, i) })),
+        lead: lead ?? null,
+        totals_per_accepted: totalsPerAccepted ?? null,
+        follow_ups_per_accepted: followUpsJson(followUpFigures),
+        ...(sevenDay ? { seven_day_estimate: sevenDay } : {}),
+        ...(calibrationWarning ? { calibration_warning: calibrationWarning } : {}),
+        ...(acceptedTaskRecords ? { accepted_tasks: acceptedTaskRecords.map((r) => ({ change: r.change, task: r.task, class: r.class, first_ts: r.firstTs, dispatches: r.dispatches, cc_version_bands: r.bands, fully_later: r.fullyLater, tokens: r.tokens })) } : {}),
+        ...(versionBands ? { cc_version_bands: versionBands.total } : {}),
+    };
+}
+/** The marker after a fresh figure whose dispatches include any recorded before the fix or on an unknown version. */
+function lowerBoundMark(k) {
+    return k ? ` (lower bound: ${k} dispatches before ${CC_BAND_FLOOR} or unknown)` : "";
+}
+/** Drops C0/C1 controls, format characters (bidi overrides included) and line or paragraph separators so a hostile ledger, brief or directory name cannot drive or reorder the terminal. */
+function printable(s) {
+    return s.replace(/[\u0000-\u001f\u007f-\u009f\p{Cf}\p{Zl}\p{Zp}]/gu, "");
+}
+/** Escapes DEL and C1 (U+007F to U+009F), which `JSON.stringify` leaves raw, as `\u00XX`; the parsed value is unchanged. */
+export function escapeJsonControls(json) {
+    return json.replace(/[\u007f-\u009f]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+/** Renders the `--routing` report; a notice replaces the table when no ledger has an `impl` dispatch, and the trailers print either way. */
+export function formatRoutingReport(result) {
+    const { rows, malformedLines, missingTasksFiles, skippedFiles, pricing, unmatchedSubTasks = 0 } = result;
+    const trailers = [];
+    if (malformedLines > 0)
+        trailers.push(`skipped malformed ledger lines: ${malformedLines}`);
+    if (unmatchedSubTasks > 0)
+        trailers.push(`unmatched sub-task ids: ${unmatchedSubTasks}`);
+    if (missingTasksFiles.length > 0)
+        trailers.push(`tasks.md not found: ${missingTasksFiles.map(printable).join(", ")}`);
+    if (skippedFiles.length > 0)
+        trailers.push(`skipped files (symlink or not a regular file, ledger over 16 MiB, brief over 1 MiB, brief past the 500-brief cap or with an over-cap header line, unlistable change directory, or unreadable): ${skippedFiles.map(printable).join(", ")}`);
+    if (result.calibrationWarning)
+        trailers.push(printable(result.calibrationWarning));
+    if (rows.length === 0)
+        return ["no impl dispatch recorded in any ledger yet", ...trailers];
+    const lines = [];
+    if (!pricing.loaded)
+        lines.push(priceWarnLine(printable(pricing.table)));
+    lines.push("cost report --routing (USD per accepted task by implementer configuration and task class):");
+    lines.push(`  ${"model".padEnd(24)} ${"effort".padEnd(9)} ${"class".padEnd(12)} ${"tasks".padStart(5)} ${"accepted".padStart(8)} ${"first-pass".padStart(10)} ${"impl".padStart(5)} ${"fix".padStart(4)} ${"review".padStart(6)} ${"escalated".padStart(9)} ${"usd".padStart(9)} ${"usd/accepted".padStart(12)}`);
+    for (const [i, r] of rows.entries()) {
+        const perAccepted = r.usdPerAccepted === null ? "-" : r.usdPerAccepted.toFixed(4);
+        const mark = lowerBoundMark(result.versionBands?.rowsLowerBound[i]);
+        lines.push(`  ${printable(r.model).slice(0, 24).padEnd(24)} ${printable(r.effort).padEnd(9)} ${printable(r.class).slice(0, 12).padEnd(12)} ${String(r.tasks).padStart(5)} ${String(r.accepted).padStart(8)} ${String(r.firstPass).padStart(10)} ${String(r.impl).padStart(5)} ${String(r.fix).padStart(4)} ${String(r.review).padStart(6)} ${String(r.escalated).padStart(9)} ${r.usd.toFixed(4).padStart(9)} ${perAccepted.padStart(12)}${r.price_estimated ? " (estimated)" : ""}`);
+        // Rendered under the row, never as columns, so the column set and order stay as they were.
+        for (const [family, g] of Object.entries(r.tokensPerAccepted)) {
+            if (g.cache_read > 0 || g.fresh > 0)
+                lines.push(`    ${family}: cache-read ${fmtTokens(g.cache_read)}/task, fresh ${fmtTokens(g.fresh)}/task${mark}`);
+        }
+        if ("sevenDayPctPerAccepted" in r) {
+            const pct = r.sevenDayPctPerAccepted ?? null;
+            lines.push(`    est. 7-day window ${pct === null ? "-" : `${pct.toFixed(1)}%`} per accepted task${pct !== null && result.sevenDay?.unreliable ? " (unreliable)" : ""}`);
+        }
+        const meanRounds = r.meanFixRounds === null ? "-" : r.meanFixRounds.toFixed(1);
+        lines.push(`    mean fix rounds ${meanRounds}, tasks over one round ${r.tasksOverOneRound}`);
+        if (r.followUpsPerAccepted)
+            lines.push(`    ${followUpsLine(r.followUpsPerAccepted)}`);
+    }
+    const total = result.versionBands?.total;
+    const bandLine = total ? [`Claude Code version: ${CC_LATER} ${total[CC_LATER]}, older ${total.older}, unknown ${total.unknown} dispatches`] : [];
+    return [...lines, ...formatRoutingFigures(result), ...bandLine, ...trailers];
+}
+/** The review rows, lead row, totals and follow-up lines below the implementer rows; each part prints only when the result carries it. */
+function formatRoutingFigures({ reviewRows = [], lead, totalsPerAccepted, followUpsPerAccepted: followUpFigures, versionBands }) {
+    const lines = [];
+    const nonZero = (groups) => Object.entries(groups).filter(([, g]) => g.cache_read > 0 || g.fresh > 0);
+    if (reviewRows.length > 0) {
+        lines.push("review rows (by reviewer configuration and Review tier criterion):");
+        lines.push(`  ${"model".padEnd(24)} ${"effort".padEnd(9)} ${"criterion".padEnd(12)} ${"dispatches".padStart(10)} ${"tasks".padStart(5)}`);
+        for (const [i, r] of reviewRows.entries()) {
+            const b = versionBands?.reviewRows[i];
+            const mark = lowerBoundMark(b ? b.older + b.unknown : 0);
+            lines.push(`  ${printable(r.model).slice(0, 24).padEnd(24)} ${printable(r.effort).padEnd(9)} ${printable(r.criterion).slice(0, 12).padEnd(12)} ${String(r.dispatches).padStart(10)} ${String(r.tasks).padStart(5)}`);
+            for (const [family, g] of nonZero(r.tokensPerTask))
+                lines.push(`    ${family}: cache-read ${fmtTokens(g.cache_read)}/task, fresh ${fmtTokens(g.fresh)}/task${mark}`);
+        }
+    }
+    if (lead) {
+        lines.push(`lead (main-session tokens of telemetry records tagged with the change; a session is attributed by its change tag only): ${lead.sessions} session${lead.sessions === 1 ? "" : "s"}`);
+        for (const [family, g] of nonZero(lead.tokens))
+            lines.push(`    ${family}: cache-read ${fmtTokens(g.cache_read)}, fresh ${fmtTokens(g.fresh)}`);
+    }
+    if (totalsPerAccepted && totalsPerAccepted.accepted > 0) {
+        lines.push("total per accepted task (dispatches and lead):");
+        for (const [family, g] of nonZero(totalsPerAccepted.total)) {
+            const fromLead = totalsPerAccepted.lead[family] ?? { cache_read: 0, fresh: 0 };
+            lines.push(`    ${family}: cache-read ${fmtTokens(g.cache_read)}/task (lead ${fmtTokens(fromLead.cache_read)}), fresh ${fmtTokens(g.fresh)}/task (lead ${fmtTokens(fromLead.fresh)})`);
+        }
+    }
+    if (followUpFigures)
+        lines.push(followUpsLine(followUpFigures));
+    return lines;
+}
+/** A follow-up figure as one line, shared by the rows and the report-wide summary. */
+function followUpsLine({ total, byType }) {
+    const split = Object.entries(byType).map(([type, n]) => `${type} ${n.toFixed(1)}`);
+    return `follow-ups per accepted task ${total === null ? "-" : total.toFixed(1)}${split.length > 0 ? ` (${split.join(", ")})` : ""}`;
+}
+const RETRO_VALIDATOR = ["skills", "subagent-driven-development", "scripts", "validate-handoff.mjs"];
+/**
+ * The ceiling and stop counts from the validator's own `ledgerSummary`, loaded by path at run time
+ * so the CLI judges ceilings exactly as the handoff gate does without a build-time dependency.
+ * @returns Null on any failure, which the line prints as `ceilings unknown`.
+ */
+async function ledgerCeilings(changeDir) {
+    try {
+        const mod = (await import(pathToFileURL(path.join(resolveCanonicalDir(), ...RETRO_VALIDATOR)).href));
+        if (typeof mod.ledgerSummary !== "function")
+            return null;
+        const summary = mod.ledgerSummary(changeDir);
+        const atOrOver = summary?.percentiles?.atOrOver;
+        const stops = summary?.handoffs?.stops;
+        if (!Array.isArray(atOrOver) || !stops || typeof stops !== "object")
+            return null;
+        const sum = Object.values(stops).reduce((n, v) => n + (typeof v === "number" && Number.isFinite(v) ? v : 0), 0);
+        return { atOrOver: atOrOver.length, stops: sum };
+    }
+    catch {
+        return null;
+    }
+}
+function localDate(d) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+const mega = (n) => `${(n / 1e6).toFixed(1)}M`;
+const kilo = (n) => `${(n / 1e3).toFixed(1)}k`;
+/**
+ * The retrospective line for one change. Dispatches are the routing collapse over every ledger,
+ * kept where the collapse files them, so a dispatch copied into another change's ledger counts
+ * once; the command reads only and writes nothing.
+ * @param now The moment whose local date the line carries.
+ */
+export async function retroLine(projectRoot, change, now = new Date()) {
+    const project = readRoutingProject(projectRoot);
+    const changeDir = path.join(project.root, change);
+    // Only a listed directory name is read, so a `--change` holding a path never leaves the sdd root.
+    if (!project.listedChanges.has(change) || !fs.lstatSync(path.join(changeDir, "ledger.jsonl"), { throwIfNoEntry: false })) {
+        return { ledger: false, change, line: `no dispatch ledger for ${printable(change)}` };
+    }
+    const prices = loadPriceTable(costPricesPath());
+    const usdOf = (model, b) => priceBucket(priceMatch(prices, model).row, b);
+    const dispatches = collapseDispatches(project.ledgers, project.briefs, project.promptChange).filter((l) => l.change === change);
+    const roles = { impl: 0, review: 0, fix: 0 };
+    const byModel = bucketsByModel();
+    const byTask = new Map();
+    const bands = emptyBands();
+    let usd = 0;
+    for (const line of dispatches) {
+        roles[line.role] += 1;
+        addTokens(byModel, line.model, line);
+        usd += usdOf(line.model, line);
+        bands[dispatchBand(line, project.transcriptVersion)] += 1;
+        const task = project.rollUp.get(acceptanceKey(change, line.task)) ?? line.task;
+        const lines = byTask.get(task) ?? [];
+        lines.push(line);
+        byTask.set(task, lines);
+    }
+    const groups = tokenGroups(byModel);
+    const freshByFamily = {};
+    for (const f of FAMILIES)
+        if ((groups[f]?.fresh ?? 0) > 0)
+            freshByFamily[f] = groups[f]?.fresh ?? 0;
+    const cacheReadByFamily = {};
+    for (const f of FAMILIES)
+        if ((groups[f]?.cache_read ?? 0) > 0)
+            cacheReadByFamily[f] = groups[f]?.cache_read ?? 0;
+    const dispatchCacheRead = Object.values(groups).reduce((n, g) => n + g.cache_read, 0);
+    const fresh = Object.values(groups).reduce((n, g) => n + g.fresh, 0);
+    const fixRounds = [...byTask.values()].reduce((n, lines) => n + distinctFixRounds(lines), 0);
+    const { records, parts } = leadAttribution(projectRoot, project, new Set([change]));
+    const leadByModel = bucketsByModel();
+    let leadUsd = 0;
+    for (const part of parts) {
+        for (const [model, b] of Object.entries(part.buckets)) {
+            addTokens(leadByModel, model, b);
+            leadUsd += usdOf(model, b);
+        }
+    }
+    const leadCacheRead = Object.values(tokenGroups(leadByModel)).reduce((n, g) => n + g.cache_read, 0);
+    const counts = { sdd: 0, plan: 0, archive: 0, review: 0, debug: 0, untagged: 0, legacy: 0 };
+    for (const r of records) {
+        if (typeof r.session_class !== "string")
+            counts.legacy += 1;
+        else if (SESSION_CLASS_NAMES.includes(r.session_class))
+            counts[r.session_class] += 1;
+    }
+    const leadClasses = {};
+    for (const name of [...SESSION_CLASS_NAMES, "legacy"])
+        if (counts[name] > 0)
+            leadClasses[name] = counts[name];
+    const ceilings = await ledgerCeilings(changeDir);
+    const n = dispatches.length;
+    const other = n - roles.impl - roles.review - roles.fix;
+    const date = localDate(now);
+    const paren = (items) => (items.length > 0 ? ` (${items.join(", ")})` : "");
+    const line = [
+        `- Measured ${date} (freeharness cost report --retro): ${n} dispatches (impl ${roles.impl}, review ${roles.review}, fix ${roles.fix}${other > 0 ? `, other ${other}` : ""})`,
+        `dispatch cache-read ${mega(dispatchCacheRead)}${paren(Object.entries(cacheReadByFamily).map(([f, v]) => `${f} ${mega(v)}`))}`,
+        `fresh ${kilo(fresh)}${paren(Object.entries(freshByFamily).map(([f, v]) => `${f} ${kilo(v)}`))}`,
+        ceilings ? `${ceilings.atOrOver} tasks at or over their class ceiling, ${ceilings.stops} scope stops` : "ceilings unknown",
+        `${fixRounds} fix rounds`,
+        `${usd.toFixed(2)} USD dispatches est.`,
+        `lead ${records.length} sessions ${mega(leadCacheRead)} cache-read ${leadUsd.toFixed(2)} USD est.${paren(Object.entries(leadClasses).map(([c, k]) => `${c} ${k}`))}`,
+        `Claude Code ${CC_LATER} ${bands[CC_LATER]}/${n} dispatches`,
+    ].join(", ");
+    return {
+        ledger: true,
+        change,
+        line,
+        date,
+        dispatches: n,
+        ...roles,
+        other,
+        dispatchCacheRead,
+        cacheReadByFamily,
+        fresh,
+        freshByFamily,
+        tasksAtOrOverCeiling: ceilings?.atOrOver ?? null,
+        scopeStops: ceilings?.stops ?? null,
+        fixRounds,
+        usd,
+        leadSessions: records.length,
+        leadCacheRead,
+        leadUsd,
+        leadClasses,
+        ccVersionBands: bands,
+    };
+}
+/** The `--json` shape of the retrospective: the line first, every figure snake-cased beside it. */
+export function retroJson(r) {
+    return {
+        line: r.line,
+        change: r.change,
+        date: r.date,
+        dispatches: r.dispatches,
+        impl: r.impl,
+        review: r.review,
+        fix: r.fix,
+        other: r.other,
+        dispatch_cache_read: r.dispatchCacheRead,
+        cache_read_by_family: r.cacheReadByFamily,
+        fresh: r.fresh,
+        fresh_by_family: r.freshByFamily,
+        tasks_at_or_over_ceiling: r.tasksAtOrOverCeiling,
+        scope_stops: r.scopeStops,
+        fix_rounds: r.fixRounds,
+        usd: round(r.usd),
+        lead_sessions: r.leadSessions,
+        lead_cache_read: r.leadCacheRead,
+        lead_usd: round(r.leadUsd),
+        lead_classes: r.leadClasses,
+        cc_version_bands: r.ccVersionBands,
+    };
+}