ultracost 0.2.0

package/docs/TESTING.md

@@ -0,0 +1,260 @@
+# Testing guide
+
+A step-by-step manual test for ultracost — from a zero-risk sandbox install through a live
+Claude Code `ultracode` run. Every command is copy-pasteable.
+
+Each step is tagged:
+
+- **[safe]** — read-only or fully sandboxed; cannot affect your real `~/.claude`.
+- **[touches ~/.claude]** — writes to or registers state in your real Claude Code config.
+  Reversible; cleanup is in the last section.
+
+All commands assume the repo is at `~/projects/ultracost`:
+
+```bash
+cd ~/projects/ultracost
+```
+
+> The plugin steps (Step 3, and the live run in Step 5) require the plugin package
+> (`.claude-plugin/`, `skills/`, `commands/`, `hooks/`) to be present in the repo. The npm
+> steps need only `bin/`, `src/`, and `templates/`.
+
+---
+
+## Step 1 — Sandbox install **[safe]**
+
+Install into a throwaway config dir via `CLAUDE_CONFIG_DIR`. Nothing under your real
+`~/.claude` is read or written.
+
+```bash
+SANDBOX=$(mktemp -d)
+CLAUDE_CONFIG_DIR="$SANDBOX" node bin/cli.js init
+CLAUDE_CONFIG_DIR="$SANDBOX" node bin/cli.js status
+CLAUDE_CONFIG_DIR="$SANDBOX" node bin/cli.js doctor
+```
+
+Inspect exactly what `init` wrote:
+
+```bash
+ls -R "$SANDBOX"
+cat "$SANDBOX/ultracost/policy.json"
+cat "$SANDBOX/CLAUDE.md"
+cat "$SANDBOX/settings.json"
+cat "$SANDBOX/ultracost/reinject.mjs"
+```
+
+Expect:
+
+- `ultracost/policy.json` — the default quality-first policy.
+- `CLAUDE.md` — a `<!-- ultracost:start -->` … `<!-- ultracost:end -->` routing block.
+- `settings.json` — a `SessionStart` hook with matcher `startup|resume|clear|compact` and
+  command `node "<SANDBOX>/ultracost/reinject.mjs"`.
+- `ultracost/reinject.mjs` — the node re-inject hook (no bash/jq).
+
+Throw the sandbox away:
+
+```bash
+rm -rf "$SANDBOX"
+```
+
+---
+
+## Step 2 — Deterministic proof **[safe]**
+
+Read-only checks. `audit` only reads your real workflow scripts; it never writes.
+
+Audit your real history (the proof point — most stages inherit the session model):
+
+```bash
+node bin/cli.js audit ~/.claude/projects
+```
+
+Expect a stage/pin breakdown with a high `unpinned ratio`. If you have no workflow
+scripts yet, it reports none found — generate one in Step 5, then re-run.
+
+Confirm the guard is clean on a correctly-pinned script:
+
+```bash
+node bin/cli.js check examples/workflow.good.js
+```
+
+Expect: `1 file(s) scanned — every agent() stage pins a model.` and exit code `0`:
+
+```bash
+node bin/cli.js check examples/workflow.good.js; echo "exit: $?"
+```
+
+Optional — confirm the guard *catches* problems and that JSON output works. Make a
+throwaway script with two unpinned stages in a temp dir (nothing under the repo or
+`~/.claude` is touched):
+
+```bash
+BADDIR=$(mktemp -d)
+cat > "$BADDIR/bad.js" <<'EOF'
+agent("plan the work");
+agent("apply the decided edit", { label: "apply" });
+EOF
+node bin/cli.js check "$BADDIR/bad.js"          # expect UC001 + UC002, exit 1
+node bin/cli.js check "$BADDIR/bad.js" --json   # same findings, machine-readable
+rm -rf "$BADDIR"
+```
+
+Expect `UC001` (no options object) on the first stage and `UC002` (options object,
+no `model`) on the second, a non-zero exit, and a `findings` array in the JSON form.
+
+---
+
+## Step 3 — Plugin (local, pre-publish) **[touches ~/.claude]**
+
+Two ways to load the plugin from your working copy. Option A registers a marketplace
+(persistent until removed); Option B loads it for one session only.
+
+### Option A — local marketplace install
+
+Inside Claude Code:
+
+```text
+/plugin marketplace add ~/projects/ultracost
+/plugin install ultracost@ultracost
+```
+
+Or non-interactively from a shell:
+
+```bash
+claude plugin marketplace add ~/projects/ultracost
+claude plugin install ultracost@ultracost
+```
+
+### Option B — session-scoped load (most contained)
+
+```bash
+claude --plugin-dir ~/projects/ultracost
+```
+
+### Verify the plugin loaded
+
+Inside the session:
+
+```text
+/help
+/ultracost:check ~/projects/ultracost/examples/workflow.good.js
+```
+
+Expect:
+
+- `/help` lists the `ultracost` plugin and the `/ultracost:check` command.
+- `/ultracost:check` on `workflow.good.js` reports a clean scan.
+- The routing-policy **skill** is available — ask Claude to author a small workflow and
+  confirm it pins `model:` per stage (it should, because the skill is loaded).
+
+If you edited the plugin and want to reload without restarting:
+
+```text
+/reload-plugins
+```
+
+---
+
+## Step 4 — npm (local link) **[touches ~/.claude]**
+
+Link the package so the `ultracost` binary is on your PATH:
+
+```bash
+npm link
+ultracost --version
+ultracost audit ~/.claude/projects   # read-only [safe]
+```
+
+`ultracost init` writes to your real `~/.claude`. To keep it contained, run it sandboxed:
+
+```bash
+CLAUDE_CONFIG_DIR=$(mktemp -d) ultracost init   # [safe]
+```
+
+Or, to test the real install path (reversible via `ultracost uninstall`):
+
+```bash
+ultracost init        # [touches ~/.claude]
+ultracost status
+ultracost doctor
+```
+
+Unlink when done:
+
+```bash
+npm unlink -g ultracost
+```
+
+---
+
+## Step 5 — Live Claude Code CLI run **[touches ~/.claude]**
+
+End-to-end test against a real `ultracode` session. This is the one that proves ultracost
+changes Claude's behavior.
+
+1. Make sure routing is active — either the plugin is installed (Step 3) **or** the npm
+   CLI is installed (`ultracost init`, Step 4).
+2. Start Claude Code and turn on ultracode:
+
+```bash
+claude
+```
+
+```text
+/effort ultracode
+```
+
+3. Give it a small workflow prompt, for example:
+
+```text
+Refactor the error handling across these three files and review the result.
+Use a dynamic workflow with a planning stage, a parallel apply stage, and a review stage.
+```
+
+4. When the run starts, Claude prints the path of the workflow script it authored, under
+   `~/.claude/projects/<project>/workflows/scripts/`. Check the newest one with the guard:
+
+```bash
+ultracost check "$(ls -t ~/.claude/projects/*/workflows/scripts/*.js | head -1)"
+```
+
+   **Eyeball the result:** with ultracost active, the mechanical/apply stages should be
+   pinned to `sonnet` and the planning/review stages to `opus` — the guard reports a clean
+   scan. As a before/after, run the same command in a session *without* ultracost and you
+   should see `UC001`/`UC002` findings.
+
+5. **Confirm the policy injection.** The `SessionStart` hook injects the routing policy as
+   context at the start of every session (and again after compaction). It is delivered as
+   `additionalContext`, so it shapes Claude's behavior without appearing as a chat message.
+   To confirm it is wired and firing, run the hook directly and check it returns the policy:
+
+```text
+printf '{"source":"startup"}' | node "<SANDBOX>/ultracost/reinject.mjs"
+```
+
+   You should get a JSON object whose `additionalContext` states the routing policy. The
+   plugin attaches the same hook on every `SessionStart` source (`startup|resume|clear|compact`).
+
+---
+
+## Cleanup
+
+Undo everything the steps above can install.
+
+```bash
+# npm CLI install (Step 4)
+ultracost uninstall          # removes the CLAUDE.md block, hook, settings entry, policy dir
+npm unlink -g ultracost
+
+# plugin install (Step 3, Option A)
+```
+
+Inside Claude Code:
+
+```text
+/plugin uninstall ultracost@ultracost
+/plugin marketplace remove ultracost
+```
+
+`--plugin-dir` (Step 3, Option B) leaves nothing behind — it ends with the session.
+Sandbox dirs from Steps 1 and 4 are gone once you `rm -rf` them.

package/docs/architecture.md

@@ -0,0 +1,166 @@
+# Architecture
+
+ultracost is **one shared core** (`src/`) with a single source of truth (`policy.json`),
+exposed through **two delivery surfaces**: a Claude Code **plugin** (primary) and an
+**npm CLI** (secondary). Both compile from the same policy, so the routing rules can never
+drift between them.
+
+```mermaid
+flowchart TD
+    subgraph core["src/ — shared core"]
+        POL["policy.js<br/>(loads/validates policy.json)"]
+        RUL["rules.js<br/>(rule compiler)"]
+        GRD["guard.js<br/>(static analysis + audit)"]
+    end
+
+    subgraph plugin["Claude Code plugin — PRIMARY"]
+        SK["skills/ultracost<br/>routing policy (always-relevant)"]
+        CMD["/ultracost:check command"]
+        HK["hooks/hooks.json<br/>SessionStart + PreToolUse(Workflow)"]
+    end
+
+    subgraph cli["npm CLI — secondary"]
+        BIN["bin/cli.js<br/>init · check · audit · doctor · status · uninstall"]
+        CM["~/.claude/CLAUDE.md block"]
+    end
+
+    POL --> RUL
+    RUL --> SK
+    RUL --> CM
+    BIN --> CM
+    GRD --> CMD
+    GRD --> BIN
+    HK --> RE["reinject.mjs<br/>(node, no bash/jq)"]
+    HK --> WG["workflow-gate.mjs<br/>(PreToolUse cost gate, default-on)"]
+    GRD --> WG
+    BIN --> RE
+
+    classDef ft fill:#1f6feb,stroke:#0b3d91,color:#fff;
+    class POL,RUL,GRD ft;
+```
+
+## The two surfaces
+
+| | Plugin (primary) | npm CLI (secondary) |
+|---|---|---|
+| **Install** | `/plugin marketplace add danielkremen818/ultracost` → `/plugin install ultracost@ultracost` | `npx ultracost init` |
+| **Routing guidance** | **`SessionStart` hook** injects the policy as context (no file mutation); a skill ships alongside for explicit reference | block injected into `~/.claude/CLAUDE.md` |
+| **Guard** | `/ultracost:check` command (runs `guard.js`) | `ultracost check` / `ultracost audit` |
+| **Policy injection** | `hooks/hooks.json` → `node "${CLAUDE_PLUGIN_ROOT}/templates/hooks/reinject.mjs"` (all `SessionStart` sources) | `node "<config>/ultracost/reinject.mjs"`, registered in `settings.json` |
+| **Cost gate** | `hooks/hooks.json` → `PreToolUse` (matcher `Workflow`) runs `workflow-gate.mjs` by default, pausing every launch with an estimate (`ULTRACOST_GATE=off` to disable) | run `ultracost estimate <script>` manually, or wire the same hook |
+| **Best for** | day-to-day use, sharing, marketplace discovery | CI, scripting, the CLAUDE.md-injection path |
+
+The skill and the CLAUDE.md block are both rendered by `rules.js` from the same policy, so
+they say the same thing.
+
+## 1. Policy (`src/policy.js`)
+
+Loads, validates, and normalizes `policy.json`. Resolution order:
+
+1. explicit `--policy`/path argument
+2. installed `<config>/ultracost/policy.json`
+3. bundled `templates/policy.default.json`
+
+`<config>` is `~/.claude` by default, or `$CLAUDE_CONFIG_DIR` when set — all ultracost paths
+hang off it, so a relocated Claude Code config is honored automatically.
+
+Validation rejects a `default` tier that isn't defined and any tier whose `model` is in
+`neverUse`, so a broken policy can never be installed.
+
+## 2. Rules + install (`src/rules.js`, `src/install.js`)
+
+`compileRules(policy)` renders a deterministic Markdown block (between
+`<!-- ultracost:start -->` / `<!-- ultracost:end -->`) so the prose rules can never drift from
+the policy data. The same compiled rules back both the plugin skill and the CLAUDE.md block.
+
+On the **CLI** path, `install()`:
+
+- writes the policy to `<config>/ultracost/policy.json`
+- injects/updates the block in `<config>/CLAUDE.md` (the **canonical** user-global memory —
+  `~/CLAUDE.md` is *not* loaded reliably and is never used)
+- copies the re-inject hook to `<config>/ultracost/reinject.mjs` and registers it for
+  `SessionStart` (matcher `startup|resume|clear|compact`) in `settings.json` as
+  `node "<config>/ultracost/reinject.mjs"`
+
+All `settings.json` access is defensive: a missing file is created; an invalid file is
+reported, never overwritten.
+
+On the **plugin** path, the skill, command, and hook are bundled in the package, so nothing
+in your config is mutated — the plugin loader wires them up.
+
+## 3. The policy-injection hook (`templates/hooks/reinject.mjs`)
+
+A cross-platform **node** script — no bash or `jq` dependency. It reads the hook JSON from
+stdin and emits the routing policy as `SessionStart` `additionalContext`. Claude Code adds
+`SessionStart` context **before the first prompt**, so the policy is present the moment Claude
+authors a workflow — not dependent on the model choosing to open a skill (a model-invoked
+skill is only *offered*, and is reliably ignored during fast workflow authoring). It fires on
+every `SessionStart` source, so the policy is injected at startup/resume/clear and re-injected
+after compaction (when Claude drops earlier context). The text is phrased as factual project
+information, per the hooks docs, so it is treated as context rather than tripping
+prompt-injection defenses.
+
+- **CLI** registers it as `node "<config>/ultracost/reinject.mjs"`.
+- **Plugin** registers it via `hooks/hooks.json` as
+  `node "${CLAUDE_PLUGIN_ROOT}/templates/hooks/reinject.mjs"`.
+
+Both attach to `SessionStart` with matcher `startup|resume|clear|compact`.
+
+## 4. Workflow Guard (`src/guard.js`)
+
+A heuristic, dependency-free static analyzer for the JavaScript workflow scripts Claude Code
+authors.
+
+```mermaid
+sequenceDiagram
+    participant U as You
+    participant CC as Claude Code (ultracode)
+    participant FS as workflow script
+    participant FT as ultracost check / /ultracost:check
+
+    U->>CC: prompt
+    CC->>FS: writes agent()/parallel()/phase() script
+    Note over CC,FS: SessionStart-injected policy / CLAUDE.md block guide per-stage model pins
+    U->>FT: check <script>
+    FT->>FS: scan agent() call sites
+    FT-->>U: flag stages missing a model pin (exit 1 in CI)
+```
+
+It finds every `agent(` call (ignoring `subagent(`, `obj.agent(`), captures the argument
+list with a string-aware paren matcher (handles nested calls and multiline), and classifies
+each stage: missing options (`UC001`), missing model (`UC002`), banned model (`UC003`),
+`inherit` (`UC004`), or dynamic/variable options (`UC005`). Ambiguous cases are **warnings**;
+clear ones are **errors**.
+
+The scan is **string- and comment-aware**: a single pre-pass records the spans inside
+`'...'`, `"..."`, `` `...` `` literals and `//` / `/* */` comments, and any `agent(` token in
+those spans is treated as prose (e.g. text inside a prompt) and never counted as a call. This
+is what makes the output trustworthy on real scripts, whose prompts routinely contain the
+word `agent(`.
+
+`ultracost audit [dir]` reuses the same analysis over `<dir>/**/workflows/scripts/*.js` and
+aggregates totals (stages, pinned, unpinned, banned, inherit, dynamic, and the unpinned
+ratio) — the "audit your history" feature and the project's headline evidence.
+
+`--fix` inserts the default tier's model into the unambiguous cases, processing matches
+back-to-front so edits don't shift later offsets.
+
+## Why this shape
+
+- **Data over prose:** the policy is machine-checkable and user-editable; the rules text is
+  generated for both surfaces from the same source.
+- **Defense in depth:** the `SessionStart` hook (and CLAUDE.md rule on the CLI path) *injects*
+  the policy as always-on context, and the guard *verifies* the output. The model can ignore
+  guidance; it cannot ignore a failing CI check. (Verified on a live run: a model-invoked skill
+  alone left every stage unpinned; the injected policy made the same prompt pin all stages.)
+- **Narrow on purpose:** ultracost only routes the workflow/ultracode path. That keeps it
+  composable with a general router if you run one.
+
+## Limitations
+
+- The guard is a heuristic scanner, not a full JS parser. The string/comment pre-pass
+  removes the common false positives (prompt text containing `agent(`), but deeply unusual
+  constructs could still be misclassified. Dynamic/variable options are reported as warnings
+  (`UC005`) rather than guessed.
+- `--fix` only handles the unambiguous cases (`UC001`, `UC002`); banned models and `inherit`
+  are reported for you to resolve, never silently rewritten.

package/docs/policy.md

@@ -0,0 +1,42 @@
+# Policy reference
+
+The policy lives at `~/.claude/ultracost/policy.json` after install. Edit it, then run
+`ultracost init` to recompile the `~/.claude/CLAUDE.md` rules from it.
+
+```json
+{
+  "version": 1,
+  "neverUse": ["haiku"],
+  "allowInherit": false,
+  "default": "opus",
+  "tieBreaker": "opus",
+  "tiers": {
+    "opus": { "model": "opus", "effort": "xhigh" },
+    "sonnet": { "model": "sonnet", "effort": "high" }
+  },
+  "alwaysOpus": ["orchestrator", "planner", "final-synthesis", "consolidation"],
+  "rules": [
+    { "tier": "opus",   "label": "Coding & reasoning",  "when": "..." },
+    { "tier": "sonnet", "label": "Mechanical & support", "when": "..." }
+  ]
+}
+```
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `version` | number | Policy schema version. |
+| `neverUse` | string[] | Models that must never be used. Matched by alias or substring, so `haiku` also bans `claude-haiku-4-5`. The guard raises `UC003` on these. |
+| `allowInherit` | boolean | If `false`, `model: 'inherit'` is an error (`UC004`). |
+| `default` | string | Tier used by `--fix` and recommended as the fallback. Must exist in `tiers`. |
+| `tieBreaker` | string | Tier the rules tell Claude to use "when in doubt". |
+| `tiers` | object | Named tiers. Each has `model` (alias or full id) and optional `effort`. A tier whose `model` is in `neverUse` is rejected at load time. |
+| `alwaysOpus` | string[] | Stage roles that must always use the default tier (orchestrator, final synthesis, …). Rendered into the rules. |
+| `rules` | object[] | Human/LLM-facing routing guidance. Each has `tier`, optional `label`, and `when` (the natural-language criteria). |
+
+## Notes on effort
+
+`xhigh` is currently available only on Opus 4.8. Sonnet tiers should use `high` (or `max`) — ultracost never downgrades the *model* to obtain more thinking; it keeps the model and uses that model's top effort.
+
+## Switching to a cost-first policy
+
+Edit the tiers/rules — for example, add a `haiku` tier, remove it from `neverUse`, and route search/format stages to it. ultracost is unopinionated about the contents; it only guarantees that whatever you decide is pinned explicitly on every stage.

package/docs/ultracode.md

@@ -0,0 +1,37 @@
+# Why ultracode needs per-stage routing
+
+`ultracode` (Claude Code v2.1.154+, shipped May 2026 with Opus 4.8) combines two
+things: **`xhigh` reasoning effort** and **automatic dynamic-workflow orchestration**.
+Both interact badly with model defaults.
+
+## The three compounding defaults
+
+1. **`xhigh` is Opus-only.** Turning on ultracode forces the *session* onto Opus 4.8 —
+   you cannot run an ultracode session on Sonnet.
+2. **Subagents inherit the session model.** With no per-stage override, every spawned
+   stage is Opus 4.8.
+3. **Workflow-authoring guidance says to omit the per-agent model.** So inheritance is
+   the path of least resistance, and the whole fan-out lands on Opus.
+
+The result is documented in
+[anthropics/claude-code#66023](https://github.com/anthropics/claude-code/issues/66023):
+a single prompt spawned **46 Opus subagents (~3M tokens)** with no cost warning.
+
+## Why the usual levers don't fit
+
+- **`/model sonnet` on the session** cascades a cheap model to the fan-out — but it's
+  incompatible with ultracode, because ultracode requires Opus for `xhigh`.
+- **`CLAUDE_CODE_SUBAGENT_MODEL`** is a global override that beats per-invocation and
+  per-agent settings — so it *defeats* a mixed, per-stage policy.
+
+That leaves exactly one correct lever: **pin the model per stage inside the workflow
+script** (`agent(task, { model: 'sonnet' })`). ultracost makes that the default behavior
+(via a `SessionStart` hook that injects the policy as context — plus the CLAUDE.md rule on
+the CLI path) and **verifies it** (via the guard).
+
+## ultracost's stance
+
+Quality-first, not cost-first: coding and reasoning stay on Opus @ `xhigh`; only
+pre-planned mechanical execution and search/collection drop to Sonnet; Haiku is never
+used. The biggest win isn't shaving Sonnet off a few stages — it's stopping a 40-agent
+fan-out from running Opus *by accident* on work that was already planned.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "ultracost",
+  "version": "0.2.0",
+  "description": "Per-stage model routing for Claude Code dynamic workflows (ultracode). Quality-first policy, CLAUDE.md rule injection, and a workflow-script guard that catches subagent stages that would silently inherit Opus.",
+  "type": "module",
+  "bin": {
+    "ultracost": "./bin/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --test \"tests/**/*.test.js\"",
+    "check": "node --check bin/cli.js && node --check src/index.js",
+    "ultracost": "node bin/cli.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ultracode",
+    "dynamic-workflows",
+    "subagents",
+    "model-routing",
+    "token-optimization",
+    "cost-optimization",
+    "opus",
+    "sonnet"
+  ],
+  "author": "Daniel Kremen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danielkremen818/ultracost.git"
+  },
+  "bugs": {
+    "url": "https://github.com/danielkremen818/ultracost/issues"
+  },
+  "homepage": "https://github.com/danielkremen818/ultracost#readme",
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  }
+}

package/src/estimate.js

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs';
+import { stageList } from './guard.js';
+
+const PRICE_KEYS = ['opus', 'sonnet', 'haiku'];
+
+// Map any model alias or full id to a pricing key (substring match; defaults to opus).
+export function priceKey(model) {
+  const v = String(model).toLowerCase();
+  return PRICE_KEYS.find((k) => v.includes(k)) || 'opus';
+}
+
+function round(x) {
+  return Math.round(x * 1e4) / 1e4;
+}
+
+function effortMultiplier(effort, policy) {
+  const m = policy.estimation.effortOutputMultiplier;
+  return m[effort] ?? m[policy.effort?.default] ?? 1;
+}
+
+// Default effort for a model: the matching tier's effort, else the global default.
+function tierEffortFor(model, policy) {
+  const key = priceKey(model);
+  for (const t of Object.values(policy.tiers)) {
+    if (priceKey(t.model) === key) return t.effort || policy.effort?.default || 'high';
+  }
+  return policy.effort?.default || 'high';
+}
+
+function stageCost(model, effort, policy) {
+  const price = policy.pricing[priceKey(model)] || policy.pricing.opus;
+  const { input, output } = policy.estimation.tokensPerStage;
+  return (input / 1e6) * price.input + ((output * effortMultiplier(effort, policy)) / 1e6) * price.output;
+}
+
+// Estimate agent count, model mix, and a tiered-vs-baseline cost for a workflow
+// script. Baseline = every stage on the session model (the default tier, opus @
+// xhigh) — what an unguided ultracode run does. Tiered = the per-stage models/effort
+// actually pinned (unpinned stages inherit the session model, so they save nothing).
+export function estimateText(text, policy, opts = {}) {
+  const assumedFanout = opts.assumedFanout ?? policy.estimation.assumedFanout;
+  const sessionModel = policy.tiers[policy.default]?.model || 'opus';
+  const sessionEffort = policy.tiers[policy.default]?.effort || 'xhigh';
+
+  const stages = stageList(text).map((s) => {
+    const tieredModel = s.model || sessionModel;
+    const tieredEffort = s.effort || (s.model ? tierEffortFor(s.model, policy) : sessionEffort);
+    return {
+      line: s.line,
+      fanout: s.fanout,
+      pinned: !!s.model,
+      model: tieredModel,
+      effort: tieredEffort,
+      tieredCost: stageCost(tieredModel, tieredEffort, policy),
+      baselineCost: stageCost(sessionModel, sessionEffort, policy)
+    };
+  });
+
+  const weight = (s) => (s.fanout ? assumedFanout : 1);
+  const tiered = stages.reduce((n, s) => n + s.tieredCost * weight(s), 0);
+  const baseline = stages.reduce((n, s) => n + s.baselineCost * weight(s), 0);
+
+  const known = stages.filter((s) => !s.fanout).length;
+  const fanoutGroups = stages.filter((s) => s.fanout).length;
+
+  const modelMix = {};
+  for (const s of stages) {
+    const k = priceKey(s.model);
+    modelMix[k] = (modelMix[k] || 0) + weight(s);
+  }
+
+  return {
+    agents: {
+      known,
+      fanoutGroups,
+      assumedPerFanout: assumedFanout,
+      assumedTotal: known + fanoutGroups * assumedFanout
+    },
+    modelMix,
+    cost: {
+      tiered: round(tiered),
+      baseline: round(baseline),
+      savings: round(baseline - tiered),
+      savingsPct: baseline ? Math.round((1 - tiered / baseline) * 100) : 0
+    },
+    stages,
+    assumptions: {
+      sessionModel,
+      pricing: policy.pricing,
+      pricingAsOf: policy.pricing?._asOf,
+      tokensPerStage: policy.estimation.tokensPerStage,
+      effortOutputMultiplier: policy.estimation.effortOutputMultiplier,
+      assumedFanout,
+      note: 'Estimate. Unpinned stages inherit the session model and save nothing. Fan-out groups assume N items each; total scales linearly with the real item count.'
+    }
+  };
+}
+
+export function estimateFile(file, policy, opts) {
+  return estimateText(readFileSync(file, 'utf8'), policy, opts);
+}