@gr8ful/spf 0.5.1 → 0.7.0

package/dist/cli/commands/watch.js

@@ -16,6 +16,7 @@ import { isRepoAt, makeGit } from "../../core/git_helper.js";
 import { GitHubProvider } from "../../core/issues/github_provider.js";
 import { JiraProvider } from "../../core/issues/jira_provider.js";
 import { BitbucketProvider } from "../../core/issues/bitbucket_provider.js";
+import { isAuthoringProvider } from "../../core/issues/provider.js";
 import { createWatchState, tick } from "../../core/watch.js";
 import { findChain, resolveRequiredAgents, runChain as runChainDef } from "../../chains/index.js";
 import { ReviewOutput } from "../../core/data_types.js";
@@ -107,7 +108,7 @@ function resolveIssueProvider(cfg) {
             console.error('JIRA_EMAIL and JIRA_API_TOKEN must both be set — spf watch needs an Atlassian account email plus an API token (id.atlassian.com -> Security -> API tokens). See README.md\'s "spf watch" section.');
             return null;
         }
-        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token);
+        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token, cfg.watch.jira.issue_types);
     }
     console.error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} is not supported`);
     return null;
@@ -177,6 +178,14 @@ function releaseLock(lockPath) {
  * machine needs, with sensible colors/descriptions. Doesn't touch git or
  * run anything, so it skips watchCommand's repo/chain checks entirely —
  * you can seed labels before ever wiring up a worktree-capable checkout.
+ *
+ * On Jira, with `watch.refine.enabled`, this also runs a READ-ONLY check of
+ * `watch.jira.issue_types` against the real project — the same check
+ * `watchCommand`'s own startup gate runs, exposed here too so a bad mapping
+ * can be caught (and fixed) before ever starting the daemon, not just at
+ * startup time. Labels themselves stay a pure report on Jira either way
+ * (Jira labels are freeform strings with no color/description registry to
+ * seed — see `jira_provider.ts`'s module comment).
  */
 export async function watchInitCommand(argv) {
     const { options } = parseCli(argv, ["cwd", "config"], []);
@@ -193,6 +202,15 @@ export async function watchInitCommand(argv) {
         console.log(`  ~ ${name} (updated color/description)`);
     for (const name of result.unchanged)
         console.log(`  = ${name} (already correct)`);
+    if (cfg.watch.refine.enabled && cfg.watch.issue_provider === "jira" && provider instanceof JiraProvider) {
+        const checks = await provider.validateIssueTypes();
+        console.log(`\nvalidating watch.jira.issue_types against ${cfg.watch.jira.project_key}:`);
+        for (const c of checks) {
+            console.log(`  ${c.exists ? "✓" : "✗"} ${c.kind} → ${c.jiraType}${c.exists ? "" : ` — no issue type named "${c.jiraType}" in ${cfg.watch.jira.project_key}`}`);
+        }
+        if (checks.some((c) => !c.exists))
+            return 1;
+    }
     return 0;
 }
 export async function watchCommand(argv) {
@@ -215,19 +233,37 @@ export async function watchCommand(argv) {
         return 1;
     }
     if (cfg.watch.refine.enabled) {
-        if (cfg.watch.issue_provider !== "github") {
-            // Fail loudly at startup, not silently every tick: JiraProvider
-            // doesn't implement IssueAuthoringProvider yet (see its module
-            // comment) — a refine lane that can never publish would otherwise
-            // just claim every spec-ready spec and block it, forever.
+        if (cfg.watch.issue_provider !== "github" && cfg.watch.issue_provider !== "jira") {
+            // Fail loudly at startup, not silently every tick: neither provider
+            // implements IssueAuthoringProvider besides these two — a refine lane
+            // that can never publish would otherwise just claim every spec-ready
+            // spec and block it, forever.
             console.error(`watch.refine.enabled is true but watch.issue_provider is ${JSON.stringify(cfg.watch.issue_provider)} — ` +
-                `the refine lane needs "github" (issue authoring isn't implemented for Jira yet)`);
+                `the refine lane needs "github" or "jira"`);
             return 1;
         }
         if (!findChain(cfg.watch.refine.chain)) {
             console.error(`watch.refine.chain ${JSON.stringify(cfg.watch.refine.chain)} is not a registered chain — run \`spf list\` to see every chain`);
             return 1;
         }
+        // Jira's issue-type mapping is user-configured (watch.jira.issue_types)
+        // and project-specific — validated here, at startup, for the same
+        // reason findChain() is: a bad mapping should stop the daemon before
+        // it starts, not fail silently every tick once the first spec-ready
+        // spec tries to publish. Silent on success, matching this function's
+        // other startup checks; loud (and the full per-kind report) on failure.
+        if (cfg.watch.issue_provider === "jira" && provider instanceof JiraProvider) {
+            const checks = await provider.validateIssueTypes();
+            const mismatches = checks.filter((c) => !c.exists);
+            if (mismatches.length > 0) {
+                console.error(`watch.jira.issue_types has ${mismatches.length} mismatch(es) against ${cfg.watch.jira.project_key}:`);
+                for (const c of checks) {
+                    console.error(`  ${c.exists ? "✓" : "✗"} ${c.kind} → ${c.jiraType}${c.exists ? "" : ` — no issue type named "${c.jiraType}" in ${cfg.watch.jira.project_key}`}`);
+                }
+                console.error(`Fix watch.jira.issue_types, or the project's issue types, before running spf watch unattended. Run \`spf watch init\` any time to re-check.`);
+                return 1;
+            }
+        }
     }
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
     const lockPath = path.join(dataPaths.data_dir, "watch.lock");
@@ -352,17 +388,19 @@ export async function watchCommand(argv) {
             unattended: true,
             chain_source: chainDef.source,
         };
-        // KNOWN LIMITATION (not fixed here): runChainDef is called below with no
-        // third `options` argument, so nothing --suite-shaped ever reaches this
-        // dispatch — `resolveRequiredSuites`/`resolveRequiredAgents` below both
-        // fall back to each chain's compiled-in/YAML-declared default. An
-        // unattended watch run therefore can't override a chain's suite the way
-        // an interactive `spf <chain> --suite <name>` can.
-        const code = await runChainDef(chainDef, ctx);
-        // Static for every chain but "prompt" (whose --agent flag `spf watch`
-        // never passes) — resolved with no options, exactly like `runChainDef`
-        // above ran it.
-        const reviewRequired = resolveRequiredAgents(chainDef, {}).includes("reviewer");
+        // `opts.chainOptions` is `watch.chain_options` (see WatchConfigSchema's
+        // doc comment), threaded down from `deps.chainOptions` by
+        // `core/watch.ts`'s `runIssue` — the same options-map shape an
+        // interactive `spf <chain> --suite <name>` builds in
+        // `cli/commands/run.ts`'s `dispatchChain`. This closes the KNOWN
+        // LIMITATION from PR #20: an unattended watch dispatch used to call
+        // `runChainDef` with no options at all, so nothing --suite-shaped could
+        // ever reach it.
+        const code = await runChainDef(chainDef, ctx, opts.chainOptions);
+        // Resolved with the SAME options `runChainDef` just ran the chain with,
+        // so a `chain_options` override that swaps a "reviewer" step in or out
+        // is reflected here too, not just each chain's static/YAML default.
+        const reviewRequired = resolveRequiredAgents(chainDef, opts.chainOptions).includes("reviewer");
         if (code === 0) {
             return { accepted: true, adwId: opts.adwId, detail: "", reviewRequired, reviewSummary: reviewSummaryFor(opts.cwd, opts.adwId) };
         }
@@ -371,11 +409,15 @@ export async function watchCommand(argv) {
     };
     /**
      * Same shape as `runChain`, for the refine lane — with one extra step on
-     * success: a chain's return value is just an exit code, so the created-
-     * issues list `steps.publishIssues()` actually produced has to come back
-     * through the side channel it wrote (`refine_publish.json`, under the
-     * SAME symlinked session dir `linkDataDir` already wires up), not through
-     * `runChainDef`'s return value.
+     * success: a chain's return value is just an exit code, so what
+     * `steps.publishIssues()` actually did — published a tree, OR escalated a
+     * question set instead — has to come back through the side channel it
+     * wrote (`refine_publish.json` or `refine_questions.json`, under the SAME
+     * symlinked session dir `linkDataDir` already wires up), not through
+     * `runChainDef`'s return value. The two are read independently and both
+     * default to `[]`: `gates.refinementWellFormed` guarantees a chain never
+     * writes both files in the same run, so exactly one of `created`/
+     * `questions` is ever non-empty on an accepted run.
      */
     const runRefine = async (opts) => {
         const chainDef = findChain(cfg.watch.refine.chain); // checked above
@@ -386,29 +428,47 @@ export async function watchCommand(argv) {
             cwd: opts.cwd,
             chain_name: chainDef.name,
             issue_id: opts.issueId,
-            // Same reasoning as runChain's ctx above — an unattended dispatch,
-            // with no --suite-shaped options reaching it either (same KNOWN
-            // LIMITATION).
+            // Same reasoning as runChain's ctx above — an unattended dispatch.
             unattended: true,
             chain_source: chainDef.source,
         };
-        const code = await runChainDef(chainDef, ctx);
+        // Same `watch.chain_options` threading as runChain above — see its
+        // comment for the KNOWN LIMITATION this fixes.
+        const code = await runChainDef(chainDef, ctx, opts.chainOptions);
         if (code !== 0) {
             const detail = detailFromFailedPhase(opts.cwd, opts.adwId, `Refine chain "${cfg.watch.refine.chain}" (adw_id ${opts.adwId}) did not complete successfully. Run \`spf phases ${opts.adwId} --cwd ${opts.cwd}\` for detail.`);
-            return { accepted: false, adwId: opts.adwId, detail, created: [] };
+            return { accepted: false, adwId: opts.adwId, detail, created: [], questions: [] };
         }
+        const wtAnchor = paths.resolveAnchor(opts.cwd);
+        const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
+        const handoffDir = path.join(wtDataPaths.data_dir, "sessions", opts.adwId, "context_handoff");
         let created = [];
         try {
-            const wtAnchor = paths.resolveAnchor(opts.cwd);
-            const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
-            const summaryPath = path.join(wtDataPaths.data_dir, "sessions", opts.adwId, "context_handoff", "refine_publish.json");
-            created = JSON.parse(readFileSync(summaryPath, "utf-8"));
+            created = JSON.parse(readFileSync(path.join(handoffDir, "refine_publish.json"), "utf-8"));
         }
         catch {
             // best-effort — an empty list still lets runSpec finish cleanly, just with no per-issue summary
         }
-        return { accepted: true, adwId: opts.adwId, detail: "", created };
+        let questions = [];
+        try {
+            questions = JSON.parse(readFileSync(path.join(handoffDir, "refine_questions.json"), "utf-8"));
+        }
+        catch {
+            // best-effort, same as above — no questions file means this run wasn't an escalation
+        }
+        return { accepted: true, adwId: opts.adwId, detail: "", created, questions };
     };
+    // `IssueAuthoringProvider`'s read-back half — `isAuthoringProvider()` is a
+    // structural check (see `provider.ts`), so both GitHub and Jira are
+    // recognized here without an `instanceof` chain that would need editing
+    // for every future authoring-capable provider. `null` on any tracker that
+    // ISN'T authoring-capable makes `rollUp` a logged no-op there rather than
+    // a startup failure the way `watch.refine.enabled` without authoring
+    // support is above: the build lane functions fine without container
+    // roll-up, unlike refine, which cannot function without authoring at all.
+    // Not a second `resolveAuthoringProvider()` call: that helper's own config
+    // validation already ran to produce `provider` itself.
+    const authoringProvider = isAuthoringProvider(provider) ? provider : null;
     const deps = {
         provider,
         codeHost,
@@ -418,6 +478,7 @@ export async function watchCommand(argv) {
         chain: cfg.watch.chain,
         baseBranch: cfg.watch.base_branch,
         concurrency: cfg.watch.concurrency,
+        chainOptions: cfg.watch.chain_options,
         refineEnabled: cfg.watch.refine.enabled,
         refineConcurrency: cfg.watch.refine.concurrency,
         refineChain: cfg.watch.refine.chain,
@@ -426,6 +487,7 @@ export async function watchCommand(argv) {
         linkDataDir,
         dryRun: Boolean(flags["dry-run"]),
         runChain,
+        listChildren: authoringProvider ? (parent) => authoringProvider.listChildren(parent) : undefined,
         log: (message) => console.log(message),
         notify: (event) => notifier?.send(event),
     };

package/dist/cli/index.js

@@ -13,6 +13,7 @@ import * as paths from "../core/paths.js";
 import { findChain, registerRepoChains, repoChainProblems } from "../chains/index.js";
 import { loadRepoChains } from "../chains/repo_chains.js";
 import { dispatchChain, usageFor } from "./commands/run.js";
+import { estimateCommand } from "./commands/estimate.js";
 import { listCommand } from "./commands/list.js";
 import { initCommand } from "./commands/init.js";
 import { installSkillCommand } from "./commands/install-skill.js";
@@ -25,11 +26,15 @@ import { eventsCommand } from "./commands/events.js";
 import { abortCommand } from "./commands/abort.js";
 import { uiCommand } from "./commands/ui.js";
 import { watchCommand, watchInitCommand } from "./commands/watch.js";
+import { fanoutCommand } from "./commands/fanout.js";
 import { versionCommand } from "./commands/version.js";
 const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
 
   spf list                                  the chain registry — names, phases, what each needs
   spf <chain> "<prompt>" [options]          run a chain (spf run <chain> ... works identically)
+  spf fanout <chain> "<prompt>" [--n 3]     best-of-N: N isolated attempts, one deterministic winner branch — YOU merge it, spf never does
+  spf fanout --clean <base-adw-id>          remove leftover worktrees/branches from a killed or discarded fanout run
+  spf estimate <chain> "<prompt>" [--n N]   read-only: planned model routing + a token/cost projection from real trace history — starts nothing, exits 3 if there's no history yet
   spf init [--force] [--yes] [--template <name>] [--no-skills]  interview to seed .spf/spf.config.yaml + .env, and install the Claude Code skill unless --no-skills (--yes/--template skip the interview, not the skill install)
   spf install-skill [--user] [--force]      (re)install the Claude Code skill by hand — spf init already does this
   spf migrate [--apply] [--force]           move an old stamped adws/ tree onto .spf/ (dry run by default)
@@ -44,7 +49,8 @@ const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
   spf abort <adw_id>                        signal a run's process to stop
   spf version                               print the installed version
 
-Chain options: [--config <path>] [--adw-id <id>] [--cwd <dir>] [--agent <name>] [--base <ref>] [--issue <id>]
+Chain options: [--config <path>] [--adw-id <id>] [--cwd <dir>] [--agent <name>] [--base <ref>] [--issue <id>] [--priority p0|p1|p2|p3]
+Run budget: set defaults.max_run_cost (USD) and/or defaults.max_run_tokens in spf.config.yaml to stop the NEXT agent call once a run has already spent this much — checked before each call, never after, so a single call is never capped and a one-agent-dispatch chain (scout/prompt/build) can never trip it; absent (the default) = unbounded.
 Run \`spf list\` to see every chain and what it needs.`;
 /** A raw scan for `--cwd`, ahead of any command-specific argv parsing — every command that takes it means the same thing by it. */
 function findCwdFlag(argv) {
@@ -138,6 +144,12 @@ export async function main() {
                 process.exitCode = await dispatchChain(chain, chainArgs);
                 return;
             }
+            case "fanout":
+                process.exitCode = await fanoutCommand(rest);
+                return;
+            case "estimate":
+                process.exitCode = await estimateCommand(rest);
+                return;
             case "list":
                 process.exitCode = listCommand();
                 return;

package/dist/cli/interview.js

@@ -286,16 +286,20 @@ export async function runInterview(asker, ctx) {
         watch = { issue_provider: issueProvider, code_host: codeHost, repo, label_prefix: labelPrefix, chain, base_branch: baseBranch };
         if (issueRepo)
             watch.issue_repo = issueRepo;
-        // Issue authoring (create + link a hierarchy) is only implemented on
-        // GitHubProvider today — see jira_provider.ts's module comment — so
-        // this lane isn't offered at all on a Jira tracker rather than asking a
-        // question that would just fail at `spf watch` startup.
-        if (issueProvider === "github") {
+        // Issue authoring (create + link a hierarchy) is implemented on both
+        // GitHubProvider and JiraProvider — see jira_provider.ts's module
+        // comment for how Jira's version works (native issue types + the
+        // `parent` field).
+        if (issueProvider === "github" || issueProvider === "jira") {
             const enableRefine = await asker.confirm(`Also enable the refine lane (decompose a "${labelPrefix}:spec-ready" product spec into a feature/story-or-bug tree)?`, false);
             if (enableRefine) {
                 const refineChainChoices = allChains().map((c) => ({ value: c.name, label: c.name, hint: c.source ? `${c.describe} (repo)` : c.describe }));
                 const refineChain = await asker.select("Chain to run per spec", refineChainChoices, "refine");
                 watch.refine = { enabled: true, chain: refineChain };
+                if (issueProvider === "jira") {
+                    asker.note('Jira issue types default to epic/feature -> "Epic", story -> "Story", bug -> "Bug", task -> "Task" — ' +
+                        "customize per-kind in watch.jira.issue_types if your project renames any of them, then run `spf watch init` to validate.");
+                }
             }
         }
         if (issueProvider === "jira") {

package/dist/core/agents.d.ts

@@ -7,6 +7,7 @@
  * with a correction — context intact, bounded retries. Agent proposes, code
  * disposes.
  */
+import { type TierResolution } from "./tiering.ts";
 import { GateReport, makeEventRecord, type AgentCall, type AgentConfig, type EnvelopeBase, type Phase, type SFConfig } from "./data_types.ts";
 /**
  * `undefined` (no `env_allowlist` configured — the default) means "don't
@@ -18,6 +19,51 @@ import { GateReport, makeEventRecord, type AgentCall, type AgentConfig, type Env
 export declare function agentEnv(agent: AgentConfig): Record<string, string> | undefined;
 export declare class GateFailure extends Error {
 }
+/**
+ * A run that has reached (or passed) one of `defaults`' budget ceilings.
+ *
+ * Its own class, like `GateFailure`, so a caller can tell "this run was cut
+ * off on purpose" from "the agent broke" — thrown from `send()` below, which
+ * puts it inside `run.phase()`'s try/catch, so the phase records `fail` and
+ * the run exits non-zero. That is the intended outcome: fail CLOSED. A budget
+ * that logged a warning and kept spending would not be a budget.
+ */
+export declare class BudgetExceeded extends Error {
+}
+/**
+ * `$0.412` — three decimals, with a trailing zero trimmed so a round ceiling
+ * reads as the operator wrote it (`$0.40`, not `$0.400`). Cents are not
+ * enough precision here: a single cheap call is often sub-cent, and a budget
+ * message that says `$0.00 of max_run_cost $0.40` tells nobody anything.
+ */
+export declare function formatUsd(value: number): string;
+/**
+ * The accumulating totals a budget check reads. Structurally a subset of
+ * `Run` (`core/runner.ts`) — `run.tokens`/`run.cost` are incremented by
+ * `run.addUsage()` after every send — so the real `Run` satisfies it with no
+ * adapter, and a test can pass a plain object with fake usage.
+ */
+export interface RunBudgetState {
+    cfg: SFConfig;
+    tokens: number;
+    cost: number;
+}
+/**
+ * Throw if this run has spent its budget. Called BEFORE every agent
+ * dispatch, never after.
+ *
+ * WHY BEFORE, AND WHY `>=`: the cost of the call about to happen is
+ * unknowable until it finishes, so a ceiling can only ever be enforced as
+ * "no further calls" — checked after the fact it would be a report, not a
+ * cap. `>=` follows from that: a run that has already spent exactly its
+ * ceiling has nothing left to spend, and letting one more (unbounded) call
+ * through would make the ceiling soft by exactly one call — which, on a
+ * chain whose last phase is the expensive one, is the whole overrun.
+ *
+ * Both ceilings absent (the default) returns immediately: zero behavior
+ * change, no arithmetic, nothing to get wrong.
+ */
+export declare function assertRunBudget(run: RunBudgetState): void;
 /**
  * Load and merge every existing path in `configPaths`, in order — later
  * paths override earlier ones. Built-in defaults first, an optional `.spf/`
@@ -35,6 +81,9 @@ export declare function validate(cfg: SFConfig, required: string[], requiredSuit
 interface RunForAgents {
     cfg: SFConfig;
     adw_id: string;
+    /** Run-total tokens/cost so far, mirrored by `addUsage` below — read by `assertRunBudget` before every send. */
+    tokens: number;
+    cost: number;
     repo_root: string;
     spf_dir: string | null;
     data_dir: string;
@@ -45,6 +94,13 @@ interface RunForAgents {
         model: string;
         coding_agent: string;
     }>;
+    /**
+     * Set once by `startRun` (`src/chains/steps.ts`), null until then. Optional
+     * here — a structural interface must not force every present and future
+     * test fake to carry it — and `effectiveAgent`'s own `?? base.model`
+     * fallback already handles absence. See `core/tiering.ts`.
+     */
+    tiering?: TierResolution | null;
     tracer: {
         event: (record: ReturnType<typeof makeEventRecord>) => string;
         processStart: (adwId: string, kind: string, name: string, pid: number, command: string) => void;

package/dist/core/agents.js

@@ -16,6 +16,7 @@ import * as agentFlue from "./agent_flue.js";
 import * as paths from "./paths.js";
 import * as permissions from "./permissions.js";
 import * as prompts from "./prompts.js";
+import { effectiveAgent } from "./tiering.js";
 import { GateReport, UsageBreakdown, makeEventRecord, SFConfigSchema, } from "./data_types.js";
 import { newId, operatorEnv } from "./utils.js";
 const JSON_FIX_ATTEMPTS = 2; // continue-with-correction attempts for malformed JSON
@@ -45,6 +46,55 @@ export function agentEnv(agent) {
 }
 export class GateFailure extends Error {
 }
+/**
+ * A run that has reached (or passed) one of `defaults`' budget ceilings.
+ *
+ * Its own class, like `GateFailure`, so a caller can tell "this run was cut
+ * off on purpose" from "the agent broke" — thrown from `send()` below, which
+ * puts it inside `run.phase()`'s try/catch, so the phase records `fail` and
+ * the run exits non-zero. That is the intended outcome: fail CLOSED. A budget
+ * that logged a warning and kept spending would not be a budget.
+ */
+export class BudgetExceeded extends Error {
+}
+/**
+ * `$0.412` — three decimals, with a trailing zero trimmed so a round ceiling
+ * reads as the operator wrote it (`$0.40`, not `$0.400`). Cents are not
+ * enough precision here: a single cheap call is often sub-cent, and a budget
+ * message that says `$0.00 of max_run_cost $0.40` tells nobody anything.
+ */
+export function formatUsd(value) {
+    const fixed = value.toFixed(3);
+    return `$${fixed.endsWith("0") ? fixed.slice(0, -1) : fixed}`;
+}
+/**
+ * Throw if this run has spent its budget. Called BEFORE every agent
+ * dispatch, never after.
+ *
+ * WHY BEFORE, AND WHY `>=`: the cost of the call about to happen is
+ * unknowable until it finishes, so a ceiling can only ever be enforced as
+ * "no further calls" — checked after the fact it would be a report, not a
+ * cap. `>=` follows from that: a run that has already spent exactly its
+ * ceiling has nothing left to spend, and letting one more (unbounded) call
+ * through would make the ceiling soft by exactly one call — which, on a
+ * chain whose last phase is the expensive one, is the whole overrun.
+ *
+ * Both ceilings absent (the default) returns immediately: zero behavior
+ * change, no arithmetic, nothing to get wrong.
+ */
+export function assertRunBudget(run) {
+    const { max_run_cost: maxCost, max_run_tokens: maxTokens } = run.cfg.defaults;
+    if (maxCost === undefined && maxTokens === undefined)
+        return;
+    if (maxCost !== undefined && run.cost >= maxCost) {
+        throw new BudgetExceeded(`run budget exceeded: ${formatUsd(run.cost)} of max_run_cost ${formatUsd(maxCost)} — ` +
+            `raise defaults.max_run_cost or split the work`);
+    }
+    if (maxTokens !== undefined && run.tokens >= maxTokens) {
+        throw new BudgetExceeded(`run budget exceeded: ${run.tokens.toLocaleString("en-US")} tokens of max_run_tokens ` +
+            `${maxTokens.toLocaleString("en-US")} — raise defaults.max_run_tokens or split the work`);
+    }
+}
 /**
  * A ValiError's own `.message` is only its FIRST issue — fine for a quick
  * console line, not for something a human has to act on or a model has to
@@ -99,6 +149,15 @@ function mergeRawConfig(base, override) {
         defaults: { ...(base.defaults || {}), ...(override.defaults || {}) },
         observability: { ...(base.observability || {}), ...(override.observability || {}) },
         quality: { ...(base.quality || {}), ...(override.quality || {}) },
+        // `watch` is spread WHOLE — no per-sub-key enumeration inside it — so
+        // any WatchConfigSchema field, present or future (jira, refine,
+        // chain_options, ...), already passes through this line untouched.
+        // The silent-drop trap this function's own doc comment warns about is
+        // about the TOP-LEVEL keys named here, not watch's own fields; the
+        // actual boundary for one of those is WatchConfigSchema itself (an
+        // unknown key there is stripped at `v.parse`, same failure mode, just a
+        // different gate) — see `chain_options`'s merge-survival test in
+        // `data_types.test.ts` for the check that actually matters here.
         watch: { ...(base.watch || {}), ...(override.watch || {}) },
         // channels is a whole-array replace on override, same as quality.checks —
         // you don't want an override's channels appended to the built-in's.
@@ -106,6 +165,15 @@ function mergeRawConfig(base, override) {
         // review.require_human_signoff / review.signoff_timeout_seconds — see
         // data_types.ts's ReviewConfigSchema doc comment for why this key exists.
         review: { ...(base.review || {}), ...(override.review || {}) },
+        // tiering.enabled / .tiers / .roles — key-by-key at this level, so a repo
+        // that only flips `enabled` keeps the base's tiers/roles. `tiers` is a
+        // whole-LIST replace on override (like quality.checks and
+        // notifications.channels): a repo that declares its own ladder replaces
+        // the packaged one wholesale rather than getting an unordered splice of
+        // both. `roles` is a whole-OBJECT replace for the same reason — a
+        // half-merged role map would route some agents by the base's ladder and
+        // some by the override's. Pinned by src/test/data_types.test.ts.
+        tiering: { ...(base.tiering || {}), ...(override.tiering || {}) },
         agents: mergeAgentLists(base.agents || [], override.agents || []),
     };
 }
@@ -128,6 +196,15 @@ export function loadConfig(configPaths) {
         raw = mergeRawConfig(raw, parsed);
     }
     const defaults = raw.defaults || {};
+    // THE BACK-FILL LIST IS PER-AGENT SETTINGS ONLY. Every key here is copied
+    // DOWN onto each agent that didn't set it, so only fields that mean
+    // something about ONE agent belong. Run-scoped `defaults` keys must stay
+    // out: `data_dir`, `protected_files`, and `max_run_cost`/`max_run_tokens`
+    // are properties of the RUN, and a per-agent copy of a run budget would
+    // read as "each agent may spend this much" — a different, unenforced
+    // feature. (AgentConfigSchema is a non-strict v.object, so a stray copy
+    // would be silently STRIPPED at parse rather than rejected: the mistake
+    // would look like it worked. See ConfigDefaultsSchema's own note.)
     for (const agent of raw.agents || []) {
         for (const key of ["coding_agent", "model", "thinking", "color", "tools", "writes", "env_allowlist"]) {
             if (key in defaults && !(key in agent))
@@ -216,13 +293,81 @@ export function validate(cfg, required, requiredSuites = [], cwd) {
             }
         }
     }
+    // Tiering (SPF #14) — every check below lives inside this ONE guard. A
+    // disabled ladder is not a config error, it is a config that is off: none
+    // of this fires for `enabled: false`, no matter what `tiers`/`roles` say —
+    // the same reason the packaged ladder + roles map surviving key-by-key
+    // merge into a repo that never opted in must not fail every chain.
+    if (cfg.tiering.enabled) {
+        // cfg-global: every declared rung must be well-formed for its OWN
+        // declared backend — the same branch this function already runs for
+        // agent.model, just keyed off the tier's coding_agent instead.
+        for (const tier of cfg.tiering.tiers) {
+            if (tier.coding_agent === "flue") {
+                try {
+                    agentFlue.resolveModel(tier.model);
+                }
+                catch (error) {
+                    problems.push(`tiering.tiers[${JSON.stringify(tier.name)}]: ${error.message}`);
+                }
+            }
+            else if (!tier.model.trim()) {
+                problems.push(`tiering.tiers[${JSON.stringify(tier.name)}]: model is empty`);
+            }
+        }
+        // cfg-global: `enabled: true` with nothing to route is a silent no-op —
+        // the same reason an unconfigured quality.suites entry above is an
+        // error rather than a quiet pass-through.
+        if (cfg.tiering.tiers.length === 0) {
+            problems.push("tiering.enabled is true but tiering.tiers is empty — declare at least one rung or set tiering.enabled: false");
+        }
+        if (Object.keys(cfg.tiering.roles).length === 0) {
+            problems.push("tiering.enabled is true but tiering.roles is empty — name at least one role or set tiering.enabled: false");
+        }
+        // Scoped to `required` — same precedent as the per-agent loop above
+        // (`:256`/`:277-288`): a `roles` key naming a role no phase in this run
+        // will dispatch is neither routed nor validated. This is what lets the
+        // packaged six-name `roles` map survive key-by-key merge into a repo
+        // with a pruned/renamed roster without failing every chain.
+        for (const name of required) {
+            const tierName = cfg.tiering.roles[name];
+            if (tierName === undefined)
+                continue; // precedence: not named in roles -> untouched, nothing to check
+            const tier = cfg.tiering.tiers.find((t) => t.name === tierName);
+            if (!tier) {
+                problems.push(`tiering.roles.${name} names tier ${JSON.stringify(tierName)}, which is not declared in tiering.tiers`);
+                continue;
+            }
+            const agent = cfg.agents.find((a) => a.name === name);
+            if (!agent)
+                continue; // already reported above by the per-agent loop's own resolve() failure
+            // Rule T — the backend-compatibility rule (§4.4A). A tier changes an
+            // agent's `model` and NOTHING else, so a role is routable by a tier
+            // only when their backends agree; a mismatch is a named error, never
+            // a silent skip, because a config that says "route this role by tier"
+            // and then quietly does not is the failure mode this codebase already
+            // refuses for suites.
+            if (agent.coding_agent !== tier.coding_agent) {
+                problems.push(`agent ${JSON.stringify(name)} (coding_agent: ${agent.coding_agent}) is routed by tiering.roles to tier ${JSON.stringify(tier.name)} ` +
+                    `(coding_agent: ${tier.coding_agent}) — a tier's model only speaks its own backend's vocabulary; declare a ` +
+                    `${agent.coding_agent} rung for ${JSON.stringify(name)} or remove it from tiering.roles`);
+            }
+        }
+    }
     if (problems.length > 0) {
         throw new Error("config validation failed:\n- " + problems.join("\n- "));
     }
 }
 /** One agent call: render prompts -> pi run -> typed parse -> gates -> envelope. */
 export async function execute(run, phase, call) {
-    const agent = resolve(run.cfg, phase.params.owner);
+    // The single dispatch-site change tiering makes: one effective AgentConfig,
+    // `model` and ONLY `model` possibly overridden (rule T — `coding_agent` is
+    // never touched here). Every downstream reader below (`agent_start`'s
+    // payload, `run.console.agentStarted`, the actual `AgentRequest`,
+    // `agentSessionId`'s reuse comparison, the traced `agent_sessions.model`
+    // column, `run.saveAgentMap`) becomes consistent for free. See
+    // `core/tiering.ts`'s `effectiveAgent`.
+    const agent = effectiveAgent(run, resolve(run.cfg, phase.params.owner));
     const agentDir = path.join(run.session_dir, agent.name);
     mkdirSync(agentDir, { recursive: true });
     const variables = {
@@ -258,6 +403,12 @@ export async function execute(run, phase, call) {
     let latest = null;
     const spent = new UsageBreakdown();
     async function send(promptText) {
+        // The ONE dispatch point for this phase — the first prompt, every
+        // JSON-repair retry, and every gate correction all funnel through here,
+        // so checking the run's ceilings here is what makes them a cap on the
+        // WHOLE run rather than on the first call of each phase. See
+        // `assertRunBudget` for why it is checked before, not after.
+        assertRunBudget(run);
         const request = {
             prompt: promptText,
             system_prompt: systemText,