freeharness 0.4.1 → 0.4.2

package/dist/cli/cost.d.ts

@@ -1,19 +1,20 @@
+import type { EffortLevel } from "@freeharness/core";
 import type { PrefixItem } from "./prefix.js";
-export interface UsageBucket {
+/** Token counts priced by `priceBucket`; legacy has no `cache_write_1h`. */
+export interface Bucket {
     input: number;
     output: number;
     cache_read: number;
     cache_write: number;
+    cache_write_1h?: number;
+}
+export interface UsageBucket extends Bucket {
     messages?: number;
     est_usd?: number;
 }
 export interface AgentUsage {
     model: string;
-    usage: {
-        input: number;
-        output: number;
-        cache_read: number;
-        cache_write: number;
+    usage: Bucket & {
         total: number;
     };
     messages: number;
@@ -48,16 +49,14 @@ export interface UsageRecord {
     }>;
     /** Additive; absent on older lines. */
     by_agent?: Record<string, AgentUsage>;
-    subagents?: {
-        input: number;
-        output: number;
-        cache_read: number;
-        cache_write: number;
+    subagents?: Bucket & {
         total: number;
     };
     context_window?: number;
     model_suffix?: string | null;
     context_window_source?: "model" | "settings" | "inferred";
+    /** The tracker priced some of `est_usd` by the family step. */
+    price_estimated?: true;
 }
 export interface PrunedRecord {
     kind: "pruned";
@@ -78,6 +77,10 @@ export interface CostRow {
     cache_read: number;
     cache_write: number;
     est_usd: number;
+    /** Some of the row's USD came from the family step: the table has no row for that model id. */
+    price_estimated?: true;
+    /** Cache-read tokens per session hour; per-project and total rows only, as session hours do not split by model. */
+    cache_read_per_hour?: number;
 }
 export interface CostReport {
     log: string;
@@ -89,6 +92,14 @@ export interface CostReport {
     byModel: CostRow[];
     total: CostRow;
     last?: string;
+    pricing: PricingMeta;
+}
+/** Read-time pricing metadata for a report's header. */
+export interface PricingMeta {
+    table: string;
+    loaded: boolean;
+    stored_estimate: number;
+    without_split: number;
 }
 /** Filters accepted by `cost report`. */
 export interface CostFilter {
@@ -116,8 +127,8 @@ export declare function readLog(file: string): {
  * in first-seen order.
  */
 export declare function latestPerSession(records: UsageRecord[]): UsageRecord[];
-/** Aggregates usage lines into per-project and per-model rows plus a total; rows sorted by estimated USD descending. */
-export declare function aggregate(records: UsageRecord[], filter?: CostFilter, log?: string): CostReport;
+/** Aggregates usage lines into per-project and per-model rows plus a total, sorted by USD descending; USD comes from `priceRecord`. */
+export declare function aggregate(records: UsageRecord[], filter?: CostFilter, log?: string, prices?: Record<string, PriceRow>, pricesFile?: string): CostReport;
 /** Formats a token count compactly (1.2k, 3.4M). */
 export declare function fmtTokens(n: number): string;
 /** Renders the report as aligned text tables. */
@@ -149,6 +160,7 @@ export interface SinkRow {
     tool_output_share: number;
     pruned_bytes: number;
     est_usd: number;
+    price_estimated?: true;
 }
 export interface ToolRow {
     tool: string;
@@ -169,13 +181,14 @@ export interface SinksReport {
         tools: ToolRow[];
         notes: string[];
     }[];
+    pricing: PricingMeta;
 }
 /**
  * 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 declare function sinks(records: UsageRecord[], filter?: SinksFilter, log?: string): SinksReport;
+export declare function sinks(records: UsageRecord[], filter?: SinksFilter, log?: string, prices?: Record<string, PriceRow>, pricesFile?: string): SinksReport;
 /** Renders the sinks report. */
 export declare function formatSinks(report: SinksReport): string[];
 /** One `.freeharness/telemetry.jsonl` record written by the cost-tracker hook on SessionEnd (data-contract.md Sink Schema). */
@@ -190,19 +203,16 @@ export interface TelemetryRecord {
     task: string | null;
     tier: string | null;
     task_class: string;
+    /** Main-context tokens by model; absent joins a `usage.jsonl` snapshot instead. */
+    by_model?: Record<string, Bucket>;
+    /** Session's activity class; absent is inferred from token totals. */
+    activity?: string;
+    end_reason?: string | null;
     sinks: {
-        main: {
-            input: number;
-            output: number;
-            cache_read: number;
-            cache_write: number;
+        main: Bucket & {
             total: number;
         };
-        subagents: {
-            input: number;
-            output: number;
-            cache_read: number;
-            cache_write: number;
+        subagents: Bucket & {
             total: number;
         };
         by_agent: Record<string, AgentUsage>;
@@ -222,6 +232,12 @@ export interface TelemetryRecord {
     context_max: number;
     context_window: number;
     warnings: string[];
+    /** The session's class; records written before the class existed lack it. */
+    session_class?: string;
+    session_classes?: string[];
+    changes?: string[];
+    /** Claude Code version; its presence marks a record written after subagent transcripts were discovered. */
+    cc_version?: string | null;
 }
 /**
  * Reads `.freeharness/telemetry.jsonl`: a line that is not valid JSON or lacks
@@ -244,32 +260,77 @@ export interface ChangeRow {
     totalObserver: number;
     est_usd: number;
     tierMix: string;
+    price_estimated?: true;
 }
+export type ActivityClass = "measured" | "no-transcript" | "no-model-calls";
 /**
- * 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.
+ * Excluded-session counts; the activity keys are always present. `subagents-unread` is set only
+ * when some record hit it, so a report over current records keeps its two-key shape.
  */
-export declare function changes(records: TelemetryRecord[]): ChangeRow[];
-/** Renders the `--changes` report; `skipped` counts lines `readTelemetry` dropped (malformed or without `session_id`). */
-export declare function formatChanges(rows: ChangeRow[], file: string, skipped: number): string[];
+export type ExcludedCounts = Record<Exclude<ActivityClass, "measured">, number> & {
+    "subagents-unread"?: number;
+};
+export declare const SESSION_CLASS_NAMES: readonly ["sdd", "plan", "archive", "review", "debug", "untagged"];
+/** Measured sessions per class; `legacy` holds the records written before `session_class` existed. */
+export type ClassCounts = Record<(typeof SESSION_CLASS_NAMES)[number], number> & {
+    legacy: number;
+};
+/** `changes()`'s result: rows, the pricing header, the excluded counts, the class mix and the records `--days` dropped for an unparseable `ts`. */
+export interface ChangesReport {
+    rows: ChangeRow[];
+    pricing: PricingMeta;
+    excluded: ExcludedCounts;
+    classes: ClassCounts;
+    skippedTs: number;
+}
+/** Untagged over the measured records that carry a class, so legacy records cannot dilute the share the gate reads; null with none. */
+export declare function untaggedShare(classes: ClassCounts): number | null;
+/**
+ * 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 declare function changes(records: TelemetryRecord[], usage?: UsageRecord[], prices?: Record<string, PriceRow>, pricesFile?: string, opts?: {
+    days?: number;
+    now?: number;
+}): ChangesReport;
+/** 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 declare function formatChanges(rows: ChangeRow[], file: string, skipped: number, pricing: PricingMeta, excluded: ExcludedCounts, classes?: ClassCounts, skippedTs?: number): string[];
 /** Price row per MTok as read from `cost-prices.json` (see `canonical/hooks/cost-prices.json`). */
 interface PriceRow {
     input: number;
     output: number;
     cache_read: number;
     cache_write: number;
+    /** The 1-hour cache-write rate; absent rows derive it at 1.6x `cache_write`. */
+    cache_write_1h?: number;
     window?: number;
 }
+/** 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 declare function priceBucket(row: PriceRow | undefined, bucket: Bucket): number;
 /**
- * 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).
  */
 export declare function loadPriceTable(file: string): Record<string, PriceRow>;
+/** A price lookup's result: the matched key (null when no row matches), its row, and whether the family step chose it. */
+export interface PriceMatch {
+    key: string | null;
+    row: PriceRow | undefined;
+    estimated: boolean;
+}
+/**
+ * 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.
+ */
+export declare function priceMatch(prices: Record<string, PriceRow>, model: string): PriceMatch;
 /** One `cost report --agents` row (ranked by total tokens). */
 export interface AgentRow {
     name: string;
@@ -284,21 +345,322 @@ export interface AgentRow {
     cache_write: number;
     tokens: number;
     est_usd: number;
+    /** Some of the row's USD came from the family step: the table has no row for that model id. */
+    price_estimated?: true;
 }
 /**
- * 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 declare function agents(records: UsageRecord[], prices?: Record<string, PriceRow>): AgentRow[];
-/** Renders the `--agents` report; `priceTable.loaded: false` prints a notice, `true` (or omitted) prints none. */
-export declare function formatAgents(rows: AgentRow[], priceTable?: {
-    file: string;
-    loaded: boolean;
-}): string[];
+export declare function agents(records: UsageRecord[], prices?: Record<string, PriceRow>, pricesFile?: string): {
+    rows: AgentRow[];
+    pricing: PricingMeta;
+};
+/** Renders the `--agents` report; `pricing.loaded: false` prints a warning and every row shows 0.00. */
+export declare function formatAgents(rows: AgentRow[], pricing: PricingMeta): string[];
 /** Per-project telemetry file path: `<dir>/.freeharness/telemetry.jsonl` (may not exist yet); `dir` defaults to the current working directory. */
 export declare function telemetryPath(dir?: string): string;
+/** One role-filtered (impl/fix/review) ledger line for the routing report. */
+export interface RoutingLedgerLine {
+    change: string;
+    ts: string;
+    role: "impl" | "fix" | "review";
+    task: string;
+    model: string;
+    /** Null when absent (a legacy line), outside EFFORT_LEVELS, or read from the agent definition. */
+    effort: EffortLevel | null;
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+    cache_write_1h?: number;
+    /** Null or absent makes the line its own dispatch. */
+    agent_id?: string | null;
+    /** A Stop/SessionEnd backfill line. */
+    late?: boolean;
+    /** `agent`: a legacy backfill line whose effort came from the agent definition; its effort is read as null. */
+    effort_source?: "payload" | "transcript" | "agent" | null;
+    /** The subagent transcript, whose prompt names the brief the dispatch ran under. */
+    transcript?: string;
+    /** The `-r<n>` of the dispatch name; null when the name carries none, so such a fix is a round of its own. */
+    round?: number | null;
+    /** The lead session that ran the dispatch, which weighs a multi-change lead's share. */
+    session?: string | null;
+    /** Read unvalidated; `ccBand` decides whether it names a version. */
+    cc_version?: string | null;
+}
+/** Model families a subscription meters apart; a model id naming none is `other`, never dropped. */
+export type ModelFamily = "opus" | "sonnet" | "haiku" | "fable" | "other";
+/** Cache reads and fresh tokens (input, every cache write, output) kept apart, since a window meters them at different weights. */
+export interface TokenGroup {
+    cache_read: number;
+    fresh: number;
+}
+/** The family a model id names as a whole `-`/`.`/`_`-delimited segment, so `claude-opusx-1` is not Opus. */
+export declare function familyOf(model: string): ModelFamily;
+/** 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 declare function tokenGroups(usageByModel: Record<string, Bucket>): Partial<Record<ModelFamily, TokenGroup>>;
+/** `routingReport`'s row per implementer configuration and task class. */
+export interface RoutingRow {
+    model: string;
+    effort: EffortLevel | "unknown";
+    /** The brief's `Class:` header, or `unclassified`. */
+    class: string;
+    tasks: number;
+    accepted: number;
+    /** Accepted tasks with no `fix` dispatch; `--json` names it `first_pass`. */
+    firstPass: number;
+    impl: number;
+    fix: number;
+    review: number;
+    escalated: number;
+    usd: number;
+    /** Accepted tasks' lines summed, divided by the accepted count; null with zero accepted. */
+    usdPerAccepted: number | null;
+    /** Some line of the row was priced by the family step. */
+    price_estimated?: true;
+    /** The same dispatches' tokens per accepted task by family; empty with zero accepted. `--json`: `tokens_per_accepted`. */
+    tokensPerAccepted: Partial<Record<ModelFamily, TokenGroup>>;
+    /** Seven-day window percent per accepted task from the fitted weights; present only when a calibration holds a seven-day window. `--json`: `seven_day_pct_per_accepted`. */
+    sevenDayPctPerAccepted?: number | null;
+    /** Distinct fix rounds averaged over accepted tasks; null with zero accepted. `--json`: `mean_fix_rounds`. */
+    meanFixRounds: number | null;
+    /** Accepted tasks with more than one distinct fix round. `--json`: `tasks_over_one_round`. */
+    tasksOverOneRound: number;
+    /** The follow-ups this row's accepted tasks left; zero without a follow-ups.md, absent only without the `followUps` option. `--json`: `follow_ups_per_accepted`. */
+    followUpsPerAccepted?: FollowUpsPerAccepted;
+}
+/** A task's acceptance, keyed `<change>\u0000<task>`; absent means not accepted. */
+type AcceptanceMap = Map<string, boolean>;
+/** A task brief's routing facts. */
+export interface TaskBrief {
+    /** The brief's `Task:` header lists the ledger task's `N.N` id. */
+    declared: boolean;
+    class: string;
+}
+/** Task briefs keyed like `AcceptanceMap`; absent means no brief. */
+export type BriefMap = Map<string, TaskBrief>;
+/** Joins a change and task into an `AcceptanceMap` key. */
+export declare function acceptanceKey(change: string, task: string): string;
+/** 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 declare function readLedgerLines(file: string, change: string): {
+    lines: RoutingLedgerLine[];
+    malformed: number;
+    skipped: boolean;
+};
+/** 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 declare function checkedTaskIds(content: string): Set<string>;
+/**
+ * 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 declare function rollUpTask(task: string, tasksMdIds: Set<string>): string | null;
+/**
+ * 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 declare function promptBriefChange(transcriptPath: string, projectRoot?: string): string | null;
+/** Claude Code before this version recorded placeholder output tokens in subagent transcripts. */
+declare const CC_BAND_FLOOR = "2.1.307";
+export type CcBand = `${typeof CC_BAND_FLOOR} or later` | "older" | "unknown";
+/** Dispatch counts per version band. `--json`: `cc_version_bands`. */
+export type CcBands = Record<CcBand, number>;
+/**
+ * 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 declare function ccBand(version: string | null): CcBand;
+/** `routingReport`'s project inputs beyond the ledgers. */
+export interface RoutingOptions {
+    /** The task each ledger task id (keyed like `AcceptanceMap`) counts under, null for a sub-task with no tasks.md ancestor; an absent key keeps the id. */
+    rollUp?: Map<string, string | null>;
+    /** The change a transcript's prompt names, for dispatches in several ledgers. */
+    promptChange?: (transcript: string) => string | null;
+    /** A review dispatch's criterion, keyed by its own change and task; an absent key reads `unrecorded`. */
+    reviewCriteria?: Map<string, string>;
+    /** Each change's follow-ups.md items; when set, every row carries its own follow-up figure. */
+    followUps?: Map<string, FollowUpItem[]>;
+    /** A transcript's Claude Code version, for a dispatch whose line carries none; omitted, such a dispatch bands unknown. */
+    transcriptVersion?: (transcript: string) => string | null;
+}
+/**
+ * Version bands kept beside the rows rather than on them, index-aligned with `rows` and
+ * `reviewRows`, so the row objects stay as callers already compare them.
+ */
+export interface RoutingVersionBands {
+    rows: CcBands[];
+    /** Older or unknown dispatches behind each row's fresh figures (its accepted tasks'). */
+    rowsLowerBound: number[];
+    reviewRows: CcBands[];
+    /** Every dispatch counted in some row, once. */
+    total: CcBands;
+}
+/** A follow-ups.md item's type and `(from <task>)` label. */
+type FollowUpItem = {
+    type: string;
+    from: string | null;
+};
+/** One row per reviewer configuration (model, effort) and `Review tier:` criterion. */
+export interface ReviewRow {
+    model: string;
+    effort: EffortLevel | "unknown";
+    /** The `S<n>` of the task's review package, or `unrecorded`. */
+    criterion: string;
+    dispatches: number;
+    /** Distinct tasks reviewed, sub-tasks rolled up. `--json`: `tasks`. */
+    tasks: number;
+    /** Review tokens over the distinct tasks reviewed. `--json`: `tokens_per_task`. */
+    tokensPerTask: Partial<Record<ModelFamily, TokenGroup>>;
+}
+/** The orchestrating sessions' main-transcript tokens, from telemetry tagged with a reported change. */
+export interface LeadRow {
+    sessions: number;
+    tokens: Partial<Record<ModelFamily, TokenGroup>>;
+}
+/** Tokens per accepted task with the lead counted, since the lead session carries most cache reads. */
+export interface TotalsPerAccepted {
+    accepted: number;
+    dispatches: Partial<Record<ModelFamily, TokenGroup>>;
+    lead: Partial<Record<ModelFamily, TokenGroup>>;
+    total: Partial<Record<ModelFamily, TokenGroup>>;
+}
+/** Follow-up items left by accepted tasks, per accepted task; `total` is null with zero accepted. `--json`: `by_type`. */
+export interface FollowUpsPerAccepted {
+    total: number | null;
+    byType: Record<string, number>;
+}
+/**
+ * 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 declare function routingReport(ledgers: RoutingLedgerLine[], acceptance: AcceptanceMap, prices: Record<string, PriceRow>, briefs?: BriefMap, options?: RoutingOptions): RoutingRow[];
+/** Distinct dispatch `agent_id`s per lead session, of one change's ledger lines. */
+export type SessionAgents = Map<string, Set<string>>;
+/**
+ * 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 declare function leadShares(record: TelemetryRecord, buckets: Record<string, Bucket>, agentsOf: (change: string) => SessionAgents): Map<string, {
+    share: number;
+    buckets: Record<string, Bucket>;
+}>;
+/** `routingReportForProject`'s result; `skippedFiles` are project-relative. */
+export interface RoutingReportResult {
+    rows: RoutingRow[];
+    malformedLines: number;
+    missingTasksFiles: string[];
+    skippedFiles: string[];
+    pricing: Pick<PricingMeta, "table" | "loaded">;
+    /** Distinct sub-task ids with no tasks.md ancestor, counted in no row. */
+    unmatchedSubTasks?: number;
+    /** The figures below the rows; optional so a result built by hand renders the rows alone. */
+    reviewRows?: ReviewRow[];
+    lead?: LeadRow;
+    totalsPerAccepted?: TotalsPerAccepted;
+    followUpsPerAccepted?: FollowUpsPerAccepted;
+    /** The seven-day fit behind the row estimates; absent when no calibration holds a seven-day window. */
+    sevenDay?: {
+        residual: number;
+        unreliable: boolean;
+    };
+    /** Why a calibration file was ignored, printed as one line. */
+    calibrationWarning?: string;
+    versionBands?: RoutingVersionBands;
+    /** In first-dispatch order; `--json` only, as `accepted_tasks`. */
+    acceptedTaskRecords?: AcceptedTaskRecord[];
+}
+/**
+ * One accepted task the rows count, sub-tasks rolled up, so a median over tasks recorded wholly on
+ * a trusted Claude Code version reads straight from the JSON; the rows only hold per-row means.
+ */
+export interface AcceptedTaskRecord {
+    change: string;
+    task: string;
+    class: string;
+    firstTs: string;
+    /** Impl, fix and review dispatches, each counted once. */
+    dispatches: number;
+    bands: CcBands;
+    /** Every dispatch is in the 2.1.307 or later band. */
+    fullyLater: boolean;
+    tokens: Partial<Record<ModelFamily, TokenGroup>>;
+}
+/**
+ * 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 declare function routingReportForProject(projectRoot: string, changeFilter?: string, prices?: Record<string, PriceRow>, pricesFile?: string, calibrationFile?: string): RoutingReportResult;
+/** The `--json` shape of a routing report: rows keyed as the data contract names them, the figures beside them after the existing fields. */
+export declare function routingReportJson(result: RoutingReportResult): Record<string, unknown>;
+/** Escapes DEL and C1 (U+007F to U+009F), which `JSON.stringify` leaves raw, as `\u00XX`; the parsed value is unchanged. */
+export declare function escapeJsonControls(json: string): string;
+/** Renders the `--routing` report; a notice replaces the table when no ledger has an `impl` dispatch, and the trailers print either way. */
+export declare function formatRoutingReport(result: RoutingReportResult): string[];
+/** One change's retrospective figures. */
+export interface RetroFigures {
+    ledger: true;
+    change: string;
+    line: string;
+    date: string;
+    dispatches: number;
+    impl: number;
+    review: number;
+    fix: number;
+    other: number;
+    dispatchCacheRead: number;
+    cacheReadByFamily: Partial<Record<ModelFamily, number>>;
+    fresh: number;
+    freshByFamily: Partial<Record<ModelFamily, number>>;
+    /** Null when the bundled validator could not be loaded or its summary failed. */
+    tasksAtOrOverCeiling: number | null;
+    scopeStops: number | null;
+    fixRounds: number;
+    usd: number;
+    leadSessions: number;
+    leadCacheRead: number;
+    leadUsd: number;
+    leadClasses: Partial<ClassCounts>;
+    ccVersionBands: CcBands;
+}
+/** A change without a ledger carries only its notice. */
+export type RetroResult = RetroFigures | {
+    ledger: false;
+    change: string;
+    line: string;
+};
+/**
+ * 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 declare function retroLine(projectRoot: string, change: string, now?: Date): Promise<RetroResult>;
+/** The `--json` shape of the retrospective: the line first, every figure snake-cased beside it. */
+export declare function retroJson(r: RetroFigures): Record<string, unknown>;
 export {};