@gr8ful/spf 0.5.1 → 0.6.0

package/dist/chains/index.js

@@ -1,5 +1,7 @@
 import * as steps from "./steps.js";
 import * as simpleSdlc from "./simple_sdlc.js";
+import * as otel from "../core/otel.js";
+import * as session from "../core/session.js";
 /**
  * Build a step-based ChainDefinition, deriving phases/requiredAgents/
  * requiredSuites from its steps.
@@ -66,6 +68,15 @@ export const CHAINS = [
     stepChain("document", "write up the work that was just done, from the diff", [steps.request(), steps.changes(), steps.document()]),
     stepChain("refine", "decompose a product spec into a feature/story-or-bug tree of tracker issues — spf watch's spec-ready lane", [
         steps.request(),
+        // Grounds the decomposition in code that actually exists, rather than
+        // leaving "explore the codebase" as prose the refiner may or may not
+        // follow (see assets/prompts/refiner/system.md). Its ScoutOutput flows
+        // into refine() as `previous` — agentStep() threads state.previous into
+        // every agent phase, and refiner/user.md already renders it as
+        // {{previous_envelope}}. This makes `scout` a required agent for this
+        // chain: a roster that pruned it fails agents.validate() by name at
+        // `spf watch` startup, same as any other missing required agent.
+        steps.scout({ description: "Map the subsystems this spec touches — change nothing" }),
         steps.refine(),
         steps.publishIssues(),
     ]),
@@ -147,9 +158,33 @@ export function resolveRequiredSuites(chain, options) {
  * CLI dispatch sites (`spf <chain>` and `spf watch`) go through this, never
  * `chain.run(...)` directly — the whole reason to route through here is that
  * a `steps`-only chain has no `run` to call.
+ *
+ * Also the one call site both dispatch paths share on the way OUT — success
+ * or thrown error alike, `finally` runs either way — which is what makes it
+ * the right seam for `otel.releaseOtelExporter()` (see otel.ts's RUN-SCOPED
+ * CLEANUP note / #26): a `spf watch` daemon calls this once per issue, in
+ * the same process, for as long as it runs, so a run's exporter has to be
+ * dropped here rather than living until the whole daemon exits. `session.
+ * finalize()` is the same idea for the run itself — it stops the process-
+ * wide signal handler from reaching this (now finished) run, and closes its
+ * Tracer's sqlite handle, so a long `spf watch` daemon does not hold every
+ * issue it has ever processed reachable for the rest of its life.
  */
 export async function runChain(chain, ctx, options = {}) {
-    if (chain.run)
-        return chain.run(ctx, options);
-    return steps.runSteps(ctx, resolveRequiredAgents(chain, options), resolveRequiredSuites(chain, options), chain.steps, options);
+    try {
+        if (chain.run)
+            return await chain.run(ctx, options);
+        return await steps.runSteps(ctx, resolveRequiredAgents(chain, options), resolveRequiredSuites(chain, options), chain.steps, options);
+    }
+    finally {
+        // Both are no-ops for a one-shot `spf <chain>` invocation with no
+        // explicit `--adw-id` (ctx.adw_id is null; the id session.ensure()
+        // actually minted never makes it back up here) — that process exits
+        // right after this call returns, and the existing end-of-process
+        // `flushAll()` in `cli/index.ts`'s `finally` still drains the exporter
+        // exactly as it always did (the signal listener needs no such fallback:
+        // the process is gone).
+        await otel.releaseOtelExporter(ctx.adw_id);
+        session.finalize(ctx.adw_id);
+    }
 }

package/dist/chains/repo_chains.js

@@ -223,6 +223,7 @@ export const RepoChainFileSchema = v.strictObject({
  */
 const RESERVED_COMMAND_NAMES = new Set([
     "run",
+    "fanout",
     "list",
     "init",
     "install-skill",

package/dist/chains/simple_sdlc.js

@@ -148,7 +148,7 @@ export function trailerFor(outcome, identity) {
 }
 export async function main(ctx) {
     const { prompt } = ctx;
-    const run = startRun(ctx, REQUIRED_AGENTS, REQUIRED_SUITES);
+    const run = await startRun(ctx, REQUIRED_AGENTS, REQUIRED_SUITES);
     const baseline = run.git.rev("HEAD"); // pinned before this run commits anything
     await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture the incoming ask" }), async (ph) => {
         ph.log({ input: prompt, baseline: run.git.shortSha(baseline) });

package/dist/chains/steps.d.ts

@@ -82,8 +82,14 @@ export interface Step {
     /** Display fragment for derivePhases() — e.g. "planner", "git(commit)". */
     label?: string;
 }
-/** The identical loadConfig -> validate -> session.ensure prologue every chain repeated. */
-export declare function startRun(ctx: ChainContext, requiredAgents: string[], requiredSuites: string[]): Run;
+/**
+ * The identical loadConfig -> validate -> session.ensure prologue every
+ * chain repeated. `async` since the tiering availability probe below is an
+ * awaited `fetch` — firing it unawaited would let `agents.execute` read
+ * `run.tiering` before the probe resolved. Both call sites are already
+ * inside `async` functions, so this stays a one-token change for each.
+ */
+export declare function startRun(ctx: ChainContext, requiredAgents: string[], requiredSuites: string[]): Promise<Run>;
 /**
  * Commit an envelope in its own author's words — the message-fallback four
  * chains repeated.
@@ -317,13 +323,25 @@ export declare function refine(opts?: {
  * rendering) is `core/refine.ts`'s job; this step is sequencing only, per
  * SKILL.md's "chains stay thin" rule. Requires a preceding refine() step.
  *
- * Writes what it created to `<context_handoff_dir>/refine_publish.json` —
- * the side channel `cli/commands/watch.ts`'s `runRefine` reads after the
- * chain returns, since a chain's own return value is just an exit code.
- * `spf watch`'s own marker/comment/transition bookkeeping for the spec
- * issue lives entirely in `core/watch.ts`'s `runSpec`, never here — a bare
- * `spf refine` run (no daemon, no spec issue in play) still needs this step
- * to work standalone.
+ * When the refiner raised material ambiguity instead of a tree
+ * (`envelope.questions` non-empty — `gates.refinementWellFormed` already
+ * guarantees `issues` is empty whenever that's true), this publishes
+ * nothing: it writes those questions to
+ * `<context_handoff_dir>/refine_questions.json` instead of
+ * `refine_publish.json` and returns. That is a successful phase outcome, not
+ * a failure — escalating to a human is a legitimate way for this chain to
+ * end, same as publishing a tree is.
+ *
+ * Writes what it created (or asked) to `<context_handoff_dir>/`, one of
+ * `refine_publish.json` or `refine_questions.json` — the side channel
+ * `cli/commands/watch.ts`'s `runRefine` reads after the chain returns, since
+ * a chain's own return value is just an exit code. `spf watch`'s own
+ * marker/comment/transition bookkeeping for the spec issue (including
+ * posting the questions and moving it to `needs-feedback`) lives entirely in
+ * `core/watch.ts`'s `runSpec`/`escalateSpec`, never here — a bare `spf
+ * refine` run (no daemon, no spec issue in play) still needs this step to
+ * work standalone, and just leaves the questions on disk for a human to
+ * read.
  */
 export declare function publishIssues(opts?: {
     description?: string;

package/dist/chains/steps.js

@@ -48,6 +48,7 @@ import * as quality from "../core/quality.js";
 import * as agentsCfg from "../core/agents.js";
 import * as session from "../core/session.js";
 import * as refineLib from "../core/refine.js";
+import * as tiering from "../core/tiering.js";
 import { DOCUMENT_NOTES } from "../core/prompts.js";
 import { BuildOutput, DocumentOutput, GenericOutput, PlanOutput, RefineOutput, ReviewOutput, ScoutOutput, makeAgentCall, makeChangeCapture, makeEventRecord, makePhaseParams, } from "../core/data_types.js";
 import { Run } from "../core/runner.js";
@@ -62,8 +63,14 @@ function makeStep(fn, meta = {}) {
     return step;
 }
 // ── layer 1: the shared prologue ────────────────────────────────────────
-/** The identical loadConfig -> validate -> session.ensure prologue every chain repeated. */
-export function startRun(ctx, requiredAgents, requiredSuites) {
+/**
+ * The identical loadConfig -> validate -> session.ensure prologue every
+ * chain repeated. `async` since the tiering availability probe below is an
+ * awaited `fetch` — firing it unawaited would let `agents.execute` read
+ * `run.tiering` before the probe resolved. Both call sites are already
+ * inside `async` functions, so this stays a one-token change for each.
+ */
+export async function startRun(ctx, requiredAgents, requiredSuites) {
     const cfg = agentsCfg.loadConfig(ctx.config_paths);
     agentsCfg.validate(cfg, requiredAgents, requiredSuites, ctx.cwd);
     const run = session.ensure(cfg, ctx.adw_id, ctx.cwd, ctx.chain_name);
@@ -83,6 +90,41 @@ export function startRun(ctx, requiredAgents, requiredSuites) {
     if (ctx.chain_source) {
         run.tracer.event(makeEventRecord({ adw_id: run.adw_id, type: "log", name: "chain_source", payload: { source: ctx.chain_source } }));
     }
+    // Tiering resolution (SPF #14) — one more run-scoped fact, computed once,
+    // before any phase opens, beside chain_source above. `risk`/`signals` are
+    // always computed (a pure function of chain name + prompt); `routing`/
+    // `notes` are only ever non-empty when `cfg.tiering.enabled` — see
+    // `resolveTiering`'s own no-op guarantee.
+    const servedOllamaTags = await tiering.probeServedOllamaTags(cfg);
+    run.tiering = tiering.resolveTiering({
+        cfg,
+        chainName: ctx.chain_name,
+        prompt: ctx.prompt,
+        servedOllamaTags,
+        required: requiredAgents,
+    });
+    run.tracer.event(makeEventRecord({
+        adw_id: run.adw_id,
+        type: "log",
+        name: "tiering",
+        payload: {
+            risk: run.tiering.risk,
+            signals: run.tiering.signals,
+            routing: run.tiering.routing,
+            notes: run.tiering.notes,
+        },
+    }));
+    // One console line per RETIERED agent (changedModels — not per routing
+    // entry: a role whose tier resolves to the model it was already
+    // configured with is not news). Routed through the existing
+    // `Console.note()` — no new Console method. This is what reconciles
+    // `run.cfg.agents[].model` (which keeps the configured value) with
+    // `agent_sessions.model` (which records the effective one) for a human
+    // reading the console when the two disagree.
+    for (const [agentName, effective] of Object.entries(tiering.changedModels(run.tiering))) {
+        const route = run.tiering.routing[agentName];
+        run.console.note(`[spf] tiering ${agentName} ${route.tier} (${route.configured} -> ${effective}) risk=${run.tiering.risk}`);
+    }
     return run;
 }
 /** A trailer line: `Key: value...`, one per line, no blank lines inside the block. */
@@ -622,10 +664,19 @@ export function refine(opts = {}) {
         output_type: RefineOutput,
         description: opts.description ?? "Decompose the spec into a feature/story tree of vertical slices",
         // refinementWellFormed is NOT in GATE_ALLOWLIST — it is meaningless on
-        // any other envelope type (it reads `issues`), so there is nothing to
-        // gain by letting a definition name it, and it stays non-removable here.
+        // any other envelope type (it reads `issues`/`questions`), so there is
+        // nothing to gain by letting a definition name it, and it stays
+        // non-removable here.
+        //
+        // retries: 1, not 0 — this gate's own doc comment says a violation
+        // "re-prompts the SAME refiner session before publishIssues() ever
+        // runs." With 0 retries that was never true: agents.ts throws
+        // GateFailure on the first violation and the whole spec goes straight to
+        // spf:blocked with no correction round-trip. The mutual-exclusion rule
+        // between `issues` and `questions` (see refinementWellFormed) makes that
+        // mismatch more likely to bite in practice, not less.
         gates: withExtraGates([gates.refinementWellFormed], opts.extraGates),
-        retries: opts.retries ?? 0,
+        retries: opts.retries ?? 1,
     });
 }
 /**
@@ -635,13 +686,25 @@ export function refine(opts = {}) {
  * rendering) is `core/refine.ts`'s job; this step is sequencing only, per
  * SKILL.md's "chains stay thin" rule. Requires a preceding refine() step.
  *
- * Writes what it created to `<context_handoff_dir>/refine_publish.json` —
- * the side channel `cli/commands/watch.ts`'s `runRefine` reads after the
- * chain returns, since a chain's own return value is just an exit code.
- * `spf watch`'s own marker/comment/transition bookkeeping for the spec
- * issue lives entirely in `core/watch.ts`'s `runSpec`, never here — a bare
- * `spf refine` run (no daemon, no spec issue in play) still needs this step
- * to work standalone.
+ * When the refiner raised material ambiguity instead of a tree
+ * (`envelope.questions` non-empty — `gates.refinementWellFormed` already
+ * guarantees `issues` is empty whenever that's true), this publishes
+ * nothing: it writes those questions to
+ * `<context_handoff_dir>/refine_questions.json` instead of
+ * `refine_publish.json` and returns. That is a successful phase outcome, not
+ * a failure — escalating to a human is a legitimate way for this chain to
+ * end, same as publishing a tree is.
+ *
+ * Writes what it created (or asked) to `<context_handoff_dir>/`, one of
+ * `refine_publish.json` or `refine_questions.json` — the side channel
+ * `cli/commands/watch.ts`'s `runRefine` reads after the chain returns, since
+ * a chain's own return value is just an exit code. `spf watch`'s own
+ * marker/comment/transition bookkeeping for the spec issue (including
+ * posting the questions and moving it to `needs-feedback`) lives entirely in
+ * `core/watch.ts`'s `runSpec`/`escalateSpec`, never here — a bare `spf
+ * refine` run (no daemon, no spec issue in play) still needs this step to
+ * work standalone, and just leaves the questions on disk for a human to
+ * read.
  */
 export function publishIssues(opts = {}) {
     preflightDescription("publish", opts.description);
@@ -650,12 +713,18 @@ export function publishIssues(opts = {}) {
         if (!envelope || !Array.isArray(envelope.issues)) {
             throw new Error("publishIssues() requires a preceding refine() step in the chain's step list");
         }
+        const questions = envelope.questions ?? [];
         await run.phase(makePhaseParams({
             name: "publish",
             kind: "code",
             owner: "tracker",
             description: opts.description ?? "Create the feature/story tree on the tracker, in dependency order, and link each to its parent",
         }), async (ph) => {
+            if (questions.length > 0) {
+                writeFileSync(path.join(run.context_handoff_dir, "refine_questions.json"), JSON.stringify(questions, null, 2));
+                ph.log({ escalated: questions.length });
+                return;
+            }
             const tracker = refineLib.resolveAuthoringProvider(run.cfg);
             const created = await refineLib.publish(tracker, envelope.issues, {
                 labelPrefix: run.cfg.watch.label_prefix,
@@ -709,7 +778,7 @@ export function derivePhases(steps) {
 // ── the driver ────────────────────────────────────────────────────────────
 /** Run a chain's step list start to finish: prologue, every step in order, then run.finish(). */
 export async function runSteps(ctx, requiredAgents, requiredSuites, steps, options = {}) {
-    const run = startRun(ctx, requiredAgents, requiredSuites);
+    const run = await startRun(ctx, requiredAgents, requiredSuites);
     const state = makeState(ctx.prompt, options, ctx.issue_id ?? null);
     for (const step of steps) {
         await step(run, state);

package/dist/cli/commands/doctor.js

@@ -19,6 +19,7 @@ import { isKnownToolName as isKnownFlueToolName, resolveModel } from "../../core
 import { ollamaBaseUrl } from "../../core/ollama_provider.js";
 import { binaryOnPath, parseCli } from "../../core/utils.js";
 import { PROVIDER_ENV_KEYS } from "../../core/providers.js";
+import { probeServedOllamaTags, resolveTiering } from "../../core/tiering.js";
 import { isRepoAt } from "../../core/git_helper.js";
 import { allChains, findChain, repoChainProblems, resolveRequiredAgents, resolveRequiredSuites } from "../../chains/index.js";
 /**
@@ -265,7 +266,13 @@ export async function doctorCommand(argv) {
     // handled in the per-agent loop below) but DO have a server that might
     // simply not be running — worth a reachability probe the same way
     // ANTHROPIC_BASE_URL gets one above.
-    const usesOllamaFlue = cfg.agents.some((a) => a.coding_agent !== "claude_code" && a.model.startsWith("ollama/"));
+    // Tiering (SPF #14): an ollama/* ladder rung reaches for the same server
+    // whether or not any cfg.agents[] entry itself names one — gated on
+    // tiering.enabled so a disabled (or never-opted-into) ladder can't turn on
+    // a probe nobody asked for. Without this, an all-hosted roster paired with
+    // an ollama ladder got NO reachability probe at all (integration point 18a).
+    const usesOllamaFlue = cfg.agents.some((a) => a.coding_agent !== "claude_code" && a.model.startsWith("ollama/")) ||
+        (cfg.tiering.enabled && cfg.tiering.tiers.some((t) => t.coding_agent !== "claude_code" && t.model.startsWith("ollama/")));
     if (usesOllamaFlue && !flags["no-probe"]) {
         // `ollamaBaseUrl()` (ollama_provider.ts) is the SAME default-substitution
         // logic `registerOllamaModel` uses for a real dispatch, including
@@ -318,6 +325,106 @@ export async function doctorCommand(argv) {
                 check(report, `${label} tool "${toolName}"`, false, "not a known tool name");
         }
     }
+    // Tiering (SPF #14) — three checks, ALL gated on tiering.enabled: a
+    // disabled (or never-opted-into) ladder must be invisible to `spf doctor`,
+    // the same gate agents.validate() uses (see the "roster + suites
+    // validate" check above, which already fails loudly on a rule-T backend
+    // mismatch for the whole roster — nothing here duplicates that failure,
+    // this section only adds VISIBILITY on top of it). Without this gate,
+    // `spf init --template ts && spf doctor` would fail on three unset
+    // provider keys for a ladder that is off and will never dispatch
+    // (integration point 18's own regression note).
+    if (cfg.tiering.enabled) {
+        // 18(b): the SAME provider-key check the per-agent loop above just ran,
+        // over cfg.tiering.tiers[].model instead of cfg.agents[].model,
+        // branching on the TIER's OWN declared coding_agent (never an agent's —
+        // a tier changes `model` and nothing else, see core/tiering.ts's rule
+        // T). Without this, a hosted rung naming a provider whose key is unset
+        // is a green doctor and a first-dispatch failure.
+        for (const tier of cfg.tiering.tiers) {
+            const tierLabel = `tiering tier "${tier.name}"`;
+            if (tier.coding_agent === "claude_code") {
+                check(report, `${tierLabel} provider key`, true, process.env["ANTHROPIC_API_KEY"] ? "ANTHROPIC_API_KEY is set" : "ANTHROPIC_API_KEY not set — fine if authenticated via `claude login` instead");
+            }
+            else {
+                try {
+                    const [provider] = resolveModel(tier.model);
+                    const envKeys = PROVIDER_ENV_KEYS[provider];
+                    if (!envKeys) {
+                        check(report, `${tierLabel} provider key`, true, `provider "${provider}" not in doctor's known list — skipped, not a failure`);
+                    }
+                    else if (envKeys.length === 0) {
+                        check(report, `${tierLabel} provider key`, true, `provider "${provider}" is keyless — no key required`);
+                    }
+                    else {
+                        const set = envKeys.find((k) => process.env[k]);
+                        check(report, `${tierLabel} provider key`, Boolean(set), set ? `${set} is set` : `none of ${envKeys.join(", ")} is set`);
+                    }
+                }
+                catch (error) {
+                    check(report, `${tierLabel} model`, false, error.message);
+                }
+            }
+        }
+        // 18(c): the resolved ladder, each routed role's effective model, and
+        // the served-tag report — imports probeServedOllamaTags FROM
+        // core/tiering.ts (not doctor's own probeGet, which discards the
+        // response body that's the only part that matters here).
+        //
+        // chainName/prompt are deliberately "" — an unlisted chain name weighs
+        // 0 and a zero-word prompt weighs -1, summing to -1, which classifies
+        // as "standard" (short of the -2 "low" needs). That reports the
+        // LADDER'S OWN baseline resolution (step 0 — no risk shift), not any
+        // one chain's risk-shifted view; a risk-shifted projection for a real
+        // chain+prompt is `spf estimate`'s job, not doctor's. `required` is the
+        // WHOLE roster, matching the "roster + suites validate" call above —
+        // every routed role doctor's job covers, not just what one chain needs.
+        const servedOllamaTags = flags["no-probe"] ? null : await probeServedOllamaTags(cfg);
+        const resolution = resolveTiering({
+            cfg,
+            chainName: "",
+            prompt: "",
+            servedOllamaTags,
+            required: cfg.agents.map((a) => a.name),
+        });
+        check(report, "tiering ladder", true, cfg.tiering.tiers.length > 0 ? cfg.tiering.tiers.map((t) => `${t.name}(${t.coding_agent}:${t.model})`).join(" -> ") : "(no tiers declared)", "info");
+        // FULL routing map — an entry for every routed role including the ones
+        // whose effective model equals their configured one (integration point
+        // 18c: "roles whose effective equals their configured model" still
+        // print), never a diff.
+        for (const [agentName, route] of Object.entries(resolution.routing)) {
+            check(report, `tiering role "${agentName}"`, true, `-> tier "${route.tier}" (${route.effective})${route.configured === route.effective ? " [unchanged from configured]" : ` (was ${route.configured})`}`, "info");
+        }
+        // One line per note resolveTiering produced (an unserved tag, a rule-T
+        // backend mismatch, an unknown tier name, ...) — resolveTiering never
+        // assigns severity (agents.validate() owns that; this call only owns
+        // detection), so every note here is informational: the hard failure for
+        // a rule-T mismatch or a malformed rung already came from the "roster +
+        // suites validate" check above, on the SAME resolveTiering-adjacent
+        // detection agents.validate() runs. This just names it again, in context.
+        for (const note of resolution.notes) {
+            check(report, "tiering note", true, note, "warn");
+        }
+        // Served-tag report, fail-open in the SAME direction the probe itself
+        // does: a stopped/unreachable server reports "could not check" once,
+        // never per-rung "not served" — flagging every rung as unserved on a
+        // probe failure would look identical to the prefix-strip bug
+        // core/tiering.ts's usable() guards against, and is exactly the outcome
+        // fail-open exists to prevent.
+        const ollamaTiers = cfg.tiering.tiers.filter((t) => t.coding_agent !== "claude_code" && t.model.startsWith("ollama/"));
+        if (ollamaTiers.length > 0) {
+            if (servedOllamaTags === null) {
+                check(report, "tiering served-tag probe", true, flags["no-probe"] ? "skipped (--no-probe)" : "could not check — Ollama server unreachable (fail-open: nothing is dropped this run)", "warn");
+            }
+            else {
+                for (const tier of ollamaTiers) {
+                    const tag = tier.model.slice("ollama/".length);
+                    const served = servedOllamaTags.has(tag);
+                    check(report, `tiering tier "${tier.name}" served`, true, served ? `"${tag}" is in \`ollama list\`` : `"${tag}" is NOT in \`ollama list\` — a run will walk down to a lower usable rung`, served ? "info" : "warn");
+                }
+            }
+        }
+    }
     for (const spec of cfg.quality.checks) {
         check(report, `quality check "${spec.name}"`, binaryOnPath(spec.argv[0]), `${spec.argv[0]} ${binaryOnPath(spec.argv[0]) ? "found on PATH" : "NOT found on PATH"}`);
     }

package/dist/cli/commands/estimate.d.ts

@@ -0,0 +1,82 @@
+import { type TierResolution } from "../../core/tiering.ts";
+import type { ChainHistorySession } from "../../ui/server/db.ts";
+export declare function usage(): string;
+export type SampleStatus = "success" | "any" | "none";
+export interface Sample {
+    sessions: ChainHistorySession[];
+    status: SampleStatus;
+    fanoutCollapsed: number;
+    joinedExcluded: number;
+}
+/**
+ * Two tiers, stopping at the first that qualifies, and an honest refusal.
+ * `sessions` is already most-recent-first (db.ts's own ORDER BY).
+ */
+export declare function selectSample(sessions: ChainHistorySession[], joinedExcluded: number): Sample;
+/** p50, no interpolation — a 3-sample percentile is false precision (design doc §5.3). Even-length arrays average the two middle values, the ordinary definition. */
+export declare function median(values: number[]): number;
+/** Strip a loop factory's trailing `_<digits>` (`steps.ts:572-579,597-600,670,683`) — `fix_1`/`fix_2` -> `fix`, `test_1` -> `test`. Reads the recorded name; never predicts it. */
+export declare function normalizePhaseName(name: string): string;
+export interface PhaseProjection {
+    name: string;
+    p50: number;
+    min: number;
+    max: number;
+}
+/**
+ * Per run: sum every iteration of a normalized phase into one observation.
+ * Across runs: median (p50) and min/max of those per-run sums. A phase
+ * absent from a given run (a fix loop that never triggered) counts as a
+ * `0` observation for that run — not a skip — so its median reflects how
+ * often the phase actually ran, not just its size when it did.
+ */
+export declare function aggregatePhases(sessions: ChainHistorySession[]): PhaseProjection[];
+export interface RunTotalsProjection {
+    p50: number;
+    min: number;
+    max: number;
+}
+/** The HEADLINE: median of sampled runs' `sessions.total_tokens` — NOT the sum of the per-phase medians (those are different numbers; median of sums != sum of medians). */
+export declare function projectRunTotals(sessions: ChainHistorySession[]): RunTotalsProjection | null;
+/** Where a p50 run would be cut off by `max_run_tokens`, walking the phase breakdown cumulatively in the order phases first appeared. `undefined` means unset; `null` means set but never reached on the p50 path. */
+export declare function findCutoffPhase(phases: PhaseProjection[], maxRunTokens: number | undefined): string | null | undefined;
+export interface DriftWarning {
+    agent: string;
+    historical: string;
+    current: string;
+}
+/**
+ * Compares each sampled agent's HISTORICAL dispatch model against the
+ * resolution's EFFECTIVE model — `res.routing[agent]?.effective ?? agent's
+ * own configured model` — never against `roles`/`tiers` in isolation. That
+ * is what makes the warning fire correctly whether or not tiering is
+ * enabled: with tiering off, "effective" is just the agent's own `model:`,
+ * so an operator who edited the roster directly between runs (no tiering
+ * involved) still gets an accurate warning.
+ */
+export declare function detectModelDrift(historicalModels: Map<string, string>, currentModel: (agent: string) => string | undefined): DriftWarning[];
+export interface EstimateReport {
+    chain: string;
+    risk: TierResolution["risk"];
+    signals: TierResolution["signals"];
+    routing: TierResolution["routing"];
+    notes: string[];
+    sample: {
+        n: number;
+        status: SampleStatus;
+        joined_excluded: number;
+        fanout_collapsed: number;
+    };
+    phases: PhaseProjection[];
+    projected: RunTotalsProjection | null;
+    observed_cost: number;
+    drift: DriftWarning[];
+    validate_error: string | null;
+    ceilings: {
+        max_run_tokens: number | undefined;
+        max_run_cost: number | undefined;
+        cutoff_phase: string | null | undefined;
+    };
+    fanout_n: number;
+}
+export declare function estimateCommand(argv: string[]): Promise<number>;