@gr8ful/spf 0.5.1 → 0.6.0

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,

package/dist/core/data_types.d.ts

@@ -173,6 +173,28 @@ export declare const RefinedIssueSchema: v.ObjectSchema<{
     readonly blocked_by: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
 }, undefined>;
 export type RefinedIssue = v.InferOutput<typeof RefinedIssueSchema>;
+/**
+ * One open question the refiner could not answer itself — material ambiguity
+ * (scope, data model, an external dependency choice, a UX contract, anything
+ * that would contradict an ADR) it is refusing to guess on, per
+ * `assets/prompts/refiner/system.md`'s "ask, don't decide" rule. `id` is
+ * stable within one round so a resumed run's answers can be matched back to
+ * the question they answer; `why_it_matters`/`options`/`recommendation`/
+ * `evidence` exist so a human can answer in one word ("go with your rec")
+ * instead of re-deriving the tradeoff the refiner already worked out.
+ * `gates.refinementWellFormed` requires `issues` to be empty whenever this is
+ * non-empty — escalating means publishing nothing THIS round, never a
+ * partial tree pinned to an unanswered question.
+ */
+export declare const RefineQuestionSchema: v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    readonly question: v.StringSchema<undefined>;
+    readonly why_it_matters: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly options: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+    readonly recommendation: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly evidence: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+}, undefined>;
+export type RefineQuestion = v.InferOutput<typeof RefineQuestionSchema>;
 /** A product spec decomposed into a feature/story tree — see `steps.refine()` and `core/refine.ts`. */
 export declare const RefineOutput: EnvelopeType<{
     status: "fail" | "success";
@@ -187,6 +209,14 @@ export declare const RefineOutput: EnvelopeType<{
         parent: string;
         blocked_by: string[];
     }[];
+    questions: {
+        id: string;
+        question: string;
+        why_it_matters: string;
+        options: string[];
+        recommendation: string;
+        evidence: string[];
+    }[];
 }>;
 export type RefineOutputT = v.InferOutput<typeof RefineOutput.schema>;
 export declare const QualityAreaSchema: v.PicklistSchema<["frontend", "backend"], undefined>;
@@ -388,6 +418,50 @@ export declare const ConfigDefaultsSchema: v.ObjectSchema<{
     readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
     readonly protected_files: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => string[]>;
     readonly data_dir: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data">;
+    /**
+     * RUN BUDGET CEILINGS — the two knobs that bound what one adw_id may spend.
+     *
+     * BOTH ABSENT BY DEFAULT, and absence is a total no-op: `agents.ts`'s
+     * `assertRunBudget()` returns immediately when neither is set, so every
+     * existing config behaves byte-identically to before this field existed.
+     * There is no ambient environment variable and no implicit default — an
+     * unbounded run stays the default because a surprise mid-run failure on a
+     * ceiling nobody chose is worse than the spend.
+     *
+     * SCOPE IS THE RUN, NOT THE CALL. Enforced against the Run's ACCUMULATED
+     * usage (`run.tokens`/`run.cost` — the same totals `run.addUsage()` mirrors
+     * into the sessions row), checked BEFORE every agent dispatch including
+     * every JSON-repair retry and every gate correction, because the cost of
+     * the call about to happen is unknowable in advance. That makes these a
+     * hard cap on FURTHER spend rather than a post-hoc report: reaching the
+     * ceiling stops the next call, it does not merely note that the last one
+     * was expensive. A tripped ceiling fails the phase closed — see
+     * `agents.ts`'s `BudgetExceeded`.
+     *
+     * `max_run_cost` is USD (the same unit the provider's own usage.cost
+     * arrives in, summed by `UsageBreakdown`); `max_run_tokens` is TOTAL
+     * tokens, i.e. the spend number — every turn re-sends the whole
+     * conversation, so this counts cached re-reads too, exactly like the
+     * `total_tokens` column in `sessions` (see `ui/server/db.ts`'s `usage()`
+     * for why that number is much larger than "material moved").
+     *
+     * Both are `> 0`, not `>= 0`: a zero ceiling would mean "no agent may ever
+     * run", which is a config mistake, not a budget — it would fail the first
+     * phase of every chain with a budget message instead of saying what is
+     * actually wrong.
+     *
+     * THE BACK-FILL TRAP (see `agents.ts`'s `loadConfig`): that function copies
+     * a handful of `defaults` keys DOWN onto each agent that hasn't set them
+     * (coding_agent/model/thinking/color/tools/writes/env_allowlist). These two
+     * keys are deliberately NOT in that list and must never be added to it —
+     * they are RUN-scoped ceilings, not per-agent settings, and a per-agent
+     * copy would read as "each agent may spend this much", which is a
+     * different (and unenforced) feature. `mergeRawConfig`'s `defaults` spread
+     * is what carries them through config layering, key-by-key; pinned by
+     * `src/test/budget.test.ts`.
+     */
+    readonly max_run_cost: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
+    readonly max_run_tokens: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
 }, undefined>;
 export type ConfigDefaults = v.InferOutput<typeof ConfigDefaultsSchema>;
 /**
@@ -492,6 +566,22 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
     readonly base_branch: v.OptionalSchema<v.StringSchema<undefined>, "main">;
     readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 60000>;
     readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 2>;
+    /**
+     * Threaded straight through as `runChainDef`'s `options` argument for
+     * every unattended `spf watch` dispatch (build lane AND refine lane) —
+     * the exact same `Record<string, string>` shape an interactive `spf
+     * <chain> --suite <name>` builds in `cli/commands/run.ts`'s
+     * `dispatchChain` (e.g. `{suite: "strict"}`, `{agent: "..."}`). Fixes the
+     * KNOWN LIMITATION called out in PR #20: `cli/commands/watch.ts`'s
+     * `runChain`/`runRefine` wrappers used to call `runChainDef` with no
+     * options at all, so nothing --suite-shaped could ever reach a chain run
+     * `spf watch` dispatched — see `cli/commands/watch.ts`. Empty by default,
+     * so an existing `watch:` config's behavior is unchanged by upgrading.
+     * Whole-object replace on merge, like `jira`/`refine` above and
+     * `observability.otel` — see `agents.ts`'s `mergeRawConfig` and
+     * `data_types.test.ts`'s merge-survival test for this field.
+     */
+    readonly chain_options: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, () => {}>;
     readonly jira: v.OptionalSchema<v.ObjectSchema<{
         readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
         readonly project_key: v.OptionalSchema<v.StringSchema<undefined>, "">;
@@ -574,6 +664,64 @@ export declare const ReviewConfigSchema: v.ObjectSchema<{
     readonly signoff_timeout_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 300>;
 }, undefined>;
 export type ReviewConfig = v.InferOutput<typeof ReviewConfigSchema>;
+/**
+ * Risk-tiered per-role model routing — SPF #14. One rung of a ladder:
+ * `name` is what `tiering.roles` points at, `model` speaks EXACTLY the same
+ * vocabulary as an agent's own `model:` for that backend (provider/model-id
+ * for flue, Claude Code's bare alias/full-name for claude_code) — there is
+ * deliberately no per-provider table, since for flue the provider is
+ * already the first segment of the value.
+ *
+ * `coding_agent` declares WHICH BACKEND'S VOCABULARY this rung's `model`
+ * speaks — same picklist and same default as `AgentConfigSchema`'s own
+ * field (`:409`), reused rather than restated. A tier changes an agent's
+ * `model` and NOTHING else (`coding_agent` stays the agent's own, always),
+ * so a rung can only route roles whose `coding_agent` matches its own — see
+ * `core/tiering.ts`'s rule T, enforced by `agents.ts`'s `validate()`.
+ */
+export declare const TierSchema: v.ObjectSchema<{
+    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+    readonly model: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+}, undefined>;
+export type Tier = v.InferOutput<typeof TierSchema>;
+/**
+ * OFF by default, and `enabled: false`/absent is a TOTAL no-op: every agent
+ * dispatches at exactly the model its roster entry names, byte-identical to
+ * before this key existed — same discipline `max_run_cost`/`max_run_tokens`
+ * hold themselves to (`ConfigDefaultsSchema`'s own comment above).
+ *
+ * TOP-LEVEL (`SFConfigSchema` below), deliberately NOT nested under
+ * `defaults:` — `agents.ts`'s `loadConfig` back-fill loop copies a FIXED
+ * list of `defaults` keys DOWN onto every agent that hasn't set them, and
+ * `AgentConfigSchema` is a non-strict `v.object`, so a stray copy would be
+ * silently STRIPPED at parse rather than rejected (see
+ * `ConfigDefaultsSchema`'s "THE BACK-FILL TRAP" comment — `max_run_cost`/
+ * `max_run_tokens` needed an explicit never-add-this-to-the-list comment to
+ * survive exactly that trap). A top-level key sits outside that loop
+ * entirely, so the trap cannot apply here at all.
+ *
+ * `tiers` is the ladder, WEAKEST FIRST: a risk level shifts every routed
+ * role UP or DOWN this list by the same step, so order is the whole
+ * semantics — a SEQUENCE states that unambiguously where a mapping's key
+ * order would be parser-dependent.
+ *
+ * `roles` is the baseline tier per ROLE (an agent name). Naming an agent
+ * here IS the operator's statement "route this one by tier" — so the
+ * resolved tier wins over that agent's own `model:`. An agent NOT named
+ * here is never retiered: its `model:` stands, untouched. See
+ * `core/tiering.ts`'s `resolveTiering` for the full precedence rule.
+ */
+export declare const TieringConfigSchema: v.ObjectSchema<{
+    readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+    readonly tiers: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+        readonly model: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    }, undefined>, undefined>, () => never[]>;
+    readonly roles: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, () => {}>;
+}, undefined>;
+export type TieringConfig = v.InferOutput<typeof TieringConfigSchema>;
 export declare const SFConfigSchema: v.ObjectSchema<{
     readonly defaults: v.OptionalSchema<v.ObjectSchema<{
         readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
@@ -584,6 +732,50 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
         readonly protected_files: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => string[]>;
         readonly data_dir: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data">;
+        /**
+         * RUN BUDGET CEILINGS — the two knobs that bound what one adw_id may spend.
+         *
+         * BOTH ABSENT BY DEFAULT, and absence is a total no-op: `agents.ts`'s
+         * `assertRunBudget()` returns immediately when neither is set, so every
+         * existing config behaves byte-identically to before this field existed.
+         * There is no ambient environment variable and no implicit default — an
+         * unbounded run stays the default because a surprise mid-run failure on a
+         * ceiling nobody chose is worse than the spend.
+         *
+         * SCOPE IS THE RUN, NOT THE CALL. Enforced against the Run's ACCUMULATED
+         * usage (`run.tokens`/`run.cost` — the same totals `run.addUsage()` mirrors
+         * into the sessions row), checked BEFORE every agent dispatch including
+         * every JSON-repair retry and every gate correction, because the cost of
+         * the call about to happen is unknowable in advance. That makes these a
+         * hard cap on FURTHER spend rather than a post-hoc report: reaching the
+         * ceiling stops the next call, it does not merely note that the last one
+         * was expensive. A tripped ceiling fails the phase closed — see
+         * `agents.ts`'s `BudgetExceeded`.
+         *
+         * `max_run_cost` is USD (the same unit the provider's own usage.cost
+         * arrives in, summed by `UsageBreakdown`); `max_run_tokens` is TOTAL
+         * tokens, i.e. the spend number — every turn re-sends the whole
+         * conversation, so this counts cached re-reads too, exactly like the
+         * `total_tokens` column in `sessions` (see `ui/server/db.ts`'s `usage()`
+         * for why that number is much larger than "material moved").
+         *
+         * Both are `> 0`, not `>= 0`: a zero ceiling would mean "no agent may ever
+         * run", which is a config mistake, not a budget — it would fail the first
+         * phase of every chain with a budget message instead of saying what is
+         * actually wrong.
+         *
+         * THE BACK-FILL TRAP (see `agents.ts`'s `loadConfig`): that function copies
+         * a handful of `defaults` keys DOWN onto each agent that hasn't set them
+         * (coding_agent/model/thinking/color/tools/writes/env_allowlist). These two
+         * keys are deliberately NOT in that list and must never be added to it —
+         * they are RUN-scoped ceilings, not per-agent settings, and a per-agent
+         * copy would read as "each agent may spend this much", which is a
+         * different (and unenforced) feature. `mergeRawConfig`'s `defaults` spread
+         * is what carries them through config layering, key-by-key; pinned by
+         * `src/test/budget.test.ts`.
+         */
+        readonly max_run_cost: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
+        readonly max_run_tokens: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
     }, undefined>, () => {
         coding_agent: "claude_code" | "flue";
         model: string;
@@ -593,6 +785,8 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         tools?: string[] | null | undefined;
         protected_files: string[];
         data_dir: string;
+        max_run_cost?: number | undefined;
+        max_run_tokens?: number | undefined;
     }>;
     readonly observability: v.OptionalSchema<v.ObjectSchema<{
         readonly db: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data/spf.db">;
@@ -660,6 +854,22 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly base_branch: v.OptionalSchema<v.StringSchema<undefined>, "main">;
         readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 60000>;
         readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 2>;
+        /**
+         * Threaded straight through as `runChainDef`'s `options` argument for
+         * every unattended `spf watch` dispatch (build lane AND refine lane) —
+         * the exact same `Record<string, string>` shape an interactive `spf
+         * <chain> --suite <name>` builds in `cli/commands/run.ts`'s
+         * `dispatchChain` (e.g. `{suite: "strict"}`, `{agent: "..."}`). Fixes the
+         * KNOWN LIMITATION called out in PR #20: `cli/commands/watch.ts`'s
+         * `runChain`/`runRefine` wrappers used to call `runChainDef` with no
+         * options at all, so nothing --suite-shaped could ever reach a chain run
+         * `spf watch` dispatched — see `cli/commands/watch.ts`. Empty by default,
+         * so an existing `watch:` config's behavior is unchanged by upgrading.
+         * Whole-object replace on merge, like `jira`/`refine` above and
+         * `observability.otel` — see `agents.ts`'s `mergeRawConfig` and
+         * `data_types.test.ts`'s merge-survival test for this field.
+         */
+        readonly chain_options: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, () => {}>;
         readonly jira: v.OptionalSchema<v.ObjectSchema<{
             readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
             readonly project_key: v.OptionalSchema<v.StringSchema<undefined>, "">;
@@ -686,6 +896,9 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         base_branch: string;
         poll_ms: number;
         concurrency: number;
+        chain_options: {
+            [x: string]: string;
+        };
         jira: {
             base_url: string;
             project_key: string;
@@ -722,6 +935,25 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         require_human_signoff: boolean;
         signoff_timeout_seconds: number;
     }>;
+    readonly tiering: v.OptionalSchema<v.ObjectSchema<{
+        readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+        readonly tiers: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+            readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+            readonly model: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        }, undefined>, undefined>, () => never[]>;
+        readonly roles: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, () => {}>;
+    }, undefined>, () => {
+        enabled: boolean;
+        tiers: {
+            name: string;
+            coding_agent: "claude_code" | "flue";
+            model: string;
+        }[];
+        roles: {
+            [x: string]: string;
+        };
+    }>;
 }, undefined>;
 export type SFConfig = v.InferOutput<typeof SFConfigSchema>;
 /** The full set of event kinds any tracer.event()/makeEventRecord() call site emits — kept in sync with src/ui/shared/types.ts's EventType. */