@gr8ful/spf 0.5.1 → 0.7.0

package/dist/core/refine.js

@@ -14,18 +14,37 @@
  * `runSpec` closes that gap using what this module returns).
  */
 import { GitHubProvider } from "./issues/github_provider.js";
+import { JiraProvider } from "./issues/jira_provider.js";
+import { clampPriority } from "./data_types.js";
 /**
- * `IssueAuthoringProvider` has a real implementation only on `GitHubProvider`
- * today — see `jira_provider.ts`'s module comment on why Jira isn't wired up
- * yet. Throws rather than returning `null` so a `code` phase calling this
+ * `IssueAuthoringProvider` has a real implementation on `GitHubProvider` and
+ * `JiraProvider` — any other `issue_provider` value fails here, defensively
+ * (the config schema's picklist already rejects it earlier). Throws rather
+ * than returning `null` so a `code` phase calling this
  * (`steps.publishIssues()`) fails the phase with a clear, specific reason —
  * the same "fail loudly, never silently do nothing" contract
  * `agents.validate()` uses for an unconfigured quality suite.
+ *
+ * Duplicates `cli/commands/watch.ts`'s own `resolveIssueProvider`
+ * construction logic for each provider — a pre-existing pattern for GitHub
+ * (this function has always rebuilt its own `GitHubProvider` rather than
+ * sharing one with the CLI layer's build-lane provider), mirrored for Jira
+ * rather than refactored away, to stay within this change's scope.
  */
 export function resolveAuthoringProvider(cfg) {
+    if (cfg.watch.issue_provider === "jira") {
+        if (!cfg.watch.jira.base_url.trim() || !cfg.watch.jira.project_key.trim()) {
+            throw new Error(`watch.jira.base_url and watch.jira.project_key must both be set when watch.issue_provider is "jira"`);
+        }
+        const email = process.env["JIRA_EMAIL"];
+        const token = process.env["JIRA_API_TOKEN"];
+        if (!email || !token) {
+            throw new Error('JIRA_EMAIL and JIRA_API_TOKEN must both be set — the refine lane needs an Atlassian account email plus an API token (id.atlassian.com -> Security -> API tokens)');
+        }
+        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token, cfg.watch.jira.issue_types);
+    }
     if (cfg.watch.issue_provider !== "github") {
-        throw new Error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} does not support issue authoring — ` +
-            `the refine lane needs "github" (see jira_provider.ts's module comment on why Jira isn't wired up yet)`);
+        throw new Error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} does not support issue authoring — the refine lane needs "github" or "jira"`);
     }
     // Issue authoring always targets the ISSUE tracker's repo — `issue_repo`
     // if set, falling back to plain `repo` (the common case: issue_provider
@@ -47,31 +66,78 @@ export function resolveAuthoringProvider(cfg) {
 function typeLabel(labelPrefix, kind) {
     return `${labelPrefix}:type:${kind}`;
 }
+/** `spf:priority:p0..p3` — see `RefinedPrioritySchema`'s doc comment for what each rung means. Mirrors `typeLabel` above, and `github_provider.ts`'s own private `priorityLabel()` method (used by `ensureLabels()` to seed these) — the two aren't unified for the same reason `typeLabel` isn't: this file stays provider-agnostic, building label strings by convention rather than reaching into a concrete `GitHubProvider`. */
+function priorityLabel(labelPrefix, priority) {
+    return `${labelPrefix}:priority:${priority}`;
+}
+/**
+ * Sentinel distinct from `github_provider.ts`'s `MARKER_RE` on purpose: that
+ * one matches a hidden comment (`spf watch`'s own scratch state — worktree,
+ * branch, PR number); this one matches a hidden block INSIDE the issue BODY
+ * this file renders — the graph `spf watch`'s build lane needs to schedule
+ * correctly (`parent`, `blocked_by`, `priority`) but that gets lost once
+ * `blocked_by` is flattened to the human-readable `## Blocked by` prose
+ * below. The two live in different places on the issue and are read by
+ * different code (`readMarker`'s comment scan vs. a plain `Issue.body`
+ * parse), so a single tracker `GET` — which already returns the body — is
+ * all `claimNewWork`'s ordering needs, no per-issue marker-comment fetch.
+ */
+const REFINE_MARKER_RE = /<!--\s*spf-refine:\s*(\{.*?\})\s*-->/s;
+/** What `parseRefineMarker` returns absent (or on a malformed/hand-edited) marker — exactly today's pre-priority, pre-frontier behavior: no parent, no blockers, the default priority. */
+const NO_REFINE_MARKER = { parent: null, blocked_by: [], priority: "p2" };
+/**
+ * Pure and exported so it's directly unit-testable without a provider —
+ * `core/watch.ts`'s `claimNewWork` and `rollUp` are the real callers, reading
+ * it straight out of the `Issue.body` a `listEligible`/`getIssue` call
+ * already returned. Never throws: a body with no marker (any issue not
+ * created by this lane, or one whose marker a human stripped while editing)
+ * degrades to `NO_REFINE_MARKER`, same as malformed JSON inside one.
+ */
+export function parseRefineMarker(body) {
+    const match = REFINE_MARKER_RE.exec(body);
+    if (!match)
+        return NO_REFINE_MARKER;
+    try {
+        const parsed = JSON.parse(match[1]);
+        return {
+            parent: typeof parsed.parent === "string" ? parsed.parent : null,
+            blocked_by: Array.isArray(parsed.blocked_by) ? parsed.blocked_by.filter((b) => typeof b === "string") : [],
+            priority: ["p0", "p1", "p2", "p3"].includes(parsed.priority) ? parsed.priority : "p2",
+        };
+    }
+    catch {
+        return NO_REFINE_MARKER; // malformed marker JSON — tolerate it, same policy as github_provider.ts's own findMarkerComment
+    }
+}
 /**
  * The body GitHub actually stores: the refiner's own `## What to build` /
  * `## Acceptance criteria` text, plus a `## Parent` back-reference to the
  * source spec (when there is one — a bare `spf refine` run with no
- * `--issue` has none), plus a `## Blocked by` section with real `#n`
- * references — `to-tickets`' own template shape, ported. Every `blocked_by`
- * key is guaranteed to already be in `byKey` by the time this runs:
- * `topoOrder` visits a node's dependencies before the node itself.
+ * `--issue` has none), a `## Blocked by` section with real `#n` references
+ * — `to-tickets`' own template shape, ported — and finally the hidden
+ * `spf-refine:` marker `parseRefineMarker` reads back. Every `blocked_by`
+ * key (and `node.parent`) is guaranteed to already be in `byKey` by the time
+ * this runs: `topoOrder` visits a node's dependencies before the node itself.
  */
 function renderBody(node, byKey, specIssueId) {
     const parts = [node.body.trim()];
     if (specIssueId)
         parts.push(`## Parent\n\nDecomposed from #${specIssueId}.`);
-    if (node.blocked_by.length > 0) {
-        const refs = node.blocked_by.map((key) => {
-            const published = byKey.get(key);
-            // Defensive only: gates.refinementWellFormed already rejects a
-            // blocked_by key that doesn't resolve to another node in the list.
-            return published ? `#${published.issue.id}` : key;
-        });
-        parts.push(`## Blocked by\n\n${refs.map((r) => `- ${r}`).join("\n")}`);
+    const blockedByIds = node.blocked_by.map((key) => {
+        const published = byKey.get(key);
+        // Defensive only: gates.refinementWellFormed already rejects a
+        // blocked_by key that doesn't resolve to another node in the list.
+        return published ? published.issue.id : key;
+    });
+    if (blockedByIds.length > 0) {
+        parts.push(`## Blocked by\n\n${blockedByIds.map((id) => `- #${id}`).join("\n")}`);
     }
     else {
         parts.push(`## Blocked by\n\nNone (can start immediately).`);
     }
+    const parentId = node.parent ? byKey.get(node.parent)?.issue.id ?? node.parent : null;
+    const marker = { parent: parentId, blocked_by: blockedByIds, priority: node.priority };
+    parts.push(`<!-- spf-refine: ${JSON.stringify(marker)} -->`);
     return parts.join("\n\n");
 }
 /**
@@ -112,10 +178,12 @@ function topoOrder(issues) {
 }
 /**
  * Create every node in `issues`, in dependency order, with its
- * `<prefix>:type:<kind>` label (plus `<prefix>:refined` on leaves only —
- * see `WatchState`'s doc comment in `provider.ts`), link each to its parent
- * via the tracker's native hierarchy, and render real `#n` references into
- * `## Blocked by`. Returns what it created, in creation order.
+ * `<prefix>:type:<kind>` and `<prefix>:priority:<pN>` labels (plus
+ * `<prefix>:refined` on leaves only — see `WatchState`'s doc comment in
+ * `provider.ts`), link each to its parent via the tracker's native
+ * hierarchy, and render real `#n` references into `## Blocked by` plus the
+ * hidden `spf-refine:` marker `parseRefineMarker` reads back. Returns what
+ * it created, in creation order.
  *
  * Not transactional: if a create or link call throws partway through, the
  * nodes already published stay published, orphaned from whatever hadn't run
@@ -129,13 +197,19 @@ export async function publish(tracker, issues, opts) {
     const childKeys = new Set(issues.filter((i) => i.parent).map((i) => i.parent));
     const byKey = new Map();
     const created = [];
-    for (const node of ordered) {
+    for (const rawNode of ordered) {
+        // Clamp once, up front — every downstream use (the label AND the hidden
+        // marker's own `priority`) must agree, or `claimNewWork`'s label-based
+        // ordering and a human reading the marker would disagree about what this
+        // issue's priority actually is.
+        const priority = clampPriority(rawNode.priority, opts.priorityCeiling);
+        const node = { ...rawNode, priority };
         const isLeaf = !childKeys.has(node.key);
-        const labels = [typeLabel(opts.labelPrefix, node.kind)];
+        const labels = [typeLabel(opts.labelPrefix, node.kind), priorityLabel(opts.labelPrefix, priority)];
         if (isLeaf)
             labels.push(`${opts.labelPrefix}:refined`);
         const body = renderBody(node, byKey, opts.specIssueId);
-        const issue = await tracker.createIssue({ title: node.title, body, labels });
+        const issue = await tracker.createIssue({ title: node.title, body, labels, kind: node.kind });
         const published = { key: node.key, issue, kind: node.kind, isLeaf };
         byKey.set(node.key, published);
         created.push(published);

package/dist/core/runner.d.ts

@@ -12,6 +12,7 @@ import { type GitHandle } from "./git_helper.ts";
 import { Console } from "./console.ts";
 import { Tracer } from "./tracer.ts";
 import { type AgentCall, type EnvelopeBase, type Phase, type PhaseParams, type SFConfig } from "./data_types.ts";
+import type { TierResolution } from "./tiering.ts";
 import type { Notifier } from "./notify/notifier.ts";
 interface AgentMapEntry {
     session_id: string;
@@ -59,6 +60,13 @@ export declare class Run {
     session_dir: string;
     context_handoff_dir: string;
     agent_map: Record<string, AgentMapEntry>;
+    /**
+     * Set once by `startRun` (`src/chains/steps.ts`), before any phase opens —
+     * `null` until then. Not a `RunInit` field: it is computed FROM the `Run`
+     * (it needs `run.tracer`/`run.console` to trace and print its own
+     * finding), not passed into its construction. See `core/tiering.ts`.
+     */
+    tiering: TierResolution | null;
     private seq;
     private agentMapPath;
     constructor(init: RunInit);

package/dist/core/runner.js

@@ -64,6 +64,13 @@ export class Run {
     session_dir;
     context_handoff_dir;
     agent_map;
+    /**
+     * Set once by `startRun` (`src/chains/steps.ts`), before any phase opens —
+     * `null` until then. Not a `RunInit` field: it is computed FROM the `Run`
+     * (it needs `run.tracer`/`run.console` to trace and print its own
+     * finding), not passed into its construction. See `core/tiering.ts`.
+     */
+    tiering = null;
     seq; // a joined run continues the sequence
     agentMapPath;
     constructor(init) {

package/dist/core/session.d.ts

@@ -7,6 +7,31 @@
  */
 import { Run } from "./runner.ts";
 import type { SFConfig } from "./data_types.ts";
+/**
+ * The symmetric teardown for `finalizeWhenKilled()` above: drop `adwId` from
+ * `ACTIVE` (so a later signal can no longer reach it) and close its Tracer's
+ * sqlite handle. Call once a run's own dispatch has fully settled — success
+ * or thrown error alike; `chains/index.ts`'s `runChain()` finally is the one
+ * seam every dispatch path (one-shot CLI and `spf watch` alike) shares on
+ * the way out, exactly where `otel.releaseOtelExporter()` already lives for
+ * the identical reason (see otel.ts's RUN-SCOPED CLEANUP note / #26).
+ *
+ * Without this, `spf watch` held every finished run's `Run` (and its
+ * Tracer, its open sqlite handle, and its Notifier) strongly reachable from
+ * the signal listener for the rest of the daemon's life — the listener
+ * closes over the `run` a fresh `finalizeWhenKilled()` call captured, but
+ * since #26 only that one listener installs once now, and `ACTIVE` is the
+ * only thing keeping a finished run reachable from it.
+ *
+ * A one-shot invocation with no explicit `--adw-id` makes `adwId` here the
+ * caller's `ctx.adw_id` (`null`) rather than the id `session.ensure()`
+ * actually minted, so this is a harmless no-op for it — same caveat as
+ * `releaseOtelExporter`, and harmless for the same reason: that process
+ * exits right after anyway.
+ */
+export declare function finalize(adwId: string | null | undefined): void;
+/** Tests only: which adw_ids the process-wide signal handler currently considers active. */
+export declare function activeRunIdsForTest(): string[];
 /**
  * `cwd` anchors this run's repo_root and data_dir — it is NOT where the
  * process happened to start; it is an explicit decision, threaded down from

package/dist/core/session.js

@@ -10,16 +10,35 @@ import * as paths from "./paths.js";
 import { Run } from "./runner.js";
 import { Tracer } from "./tracer.js";
 import { engineerName, newId } from "./utils.js";
-import { resolveNotifier } from "./notify/notifier.js";
+import { resolveNotifier, drainAll as drainNotifiers } from "./notify/notifier.js";
 import * as otel from "./otel.js";
 /**
- * How long a signalled run may spend pushing spans before it exits anyway.
- * Short on purpose: someone who just pressed ^C is waiting, and an
- * observability projection is never worth making a kill feel broken. The
- * budget is enforced inside `otel.flushAll()` (a raced, unref'd deadline), so
- * an unreachable collector costs exactly this and not one tick more.
+ * How long a signalled run may spend pushing spans / webhook sends before it
+ * exits anyway. Short on purpose: someone who just pressed ^C is waiting, and
+ * neither an observability projection nor a Slack ping is ever worth making a
+ * kill feel broken. The budget is enforced inside `otel.flushAll()` and
+ * `notify.drainAll()` (each a raced, unref'd deadline), so an unreachable
+ * collector or webhook host costs exactly this and not one tick more.
  */
 const SIGNAL_DRAIN_MS = 750;
+/**
+ * Runs currently in flight in THIS process, keyed by adw_id — what the one
+ * shared signal handler below acts on, and what `finalize()` removes a run
+ * from once its own dispatch has settled.
+ *
+ * `spf watch`'s daemon loop calls `ensure()` once per claimed issue, in the
+ * same process, for the life of the daemon. Installing a FRESH
+ * SIGTERM/SIGINT listener per `ensure()` call (the old shape) meant every
+ * listener ever registered stayed registered and fired on the NEXT signal —
+ * so ^C during issue 72 would also re-run issue 70 and 71's long-finished
+ * handlers, flipping their already-`success` sessions back to `fail`, on top
+ * of leaking a `MaxListenersExceededWarning` at the 11th run. One listener,
+ * installed once, acting on whichever runs are still in `ACTIVE`, fixes
+ * both: a signal only ever finalizes runs that are actually still running.
+ */
+const ACTIVE = new Map();
+let installed = false;
+let draining = false;
 /**
  * A killed run still closes its own trace.
  *
@@ -31,32 +50,82 @@ const SIGNAL_DRAIN_MS = 750;
  * (best-effort: a signal can still land mid-write).
  *
  * SQLite is written FIRST and synchronously, exactly as before — the otel
- * drain is appended after it and can only ever cost time, never correctness.
- * (`notify` has no equivalent drain on this path: its in-flight webhooks are
- * dropped on a signal today. Fixing that means touching the notifier's
- * lifecycle, which is outside this change; only the otel path is drained here.)
+ * and notify drains are appended after it and can only ever cost time, never
+ * correctness. `notify`'s in-flight Slack/Teams/webhook sends get the SAME
+ * timeout-and-swallow discipline as the otel drain (see `Notifier.drain()` /
+ * `notify.drainAll()` in `notify/notifier.ts`): bounded by the same
+ * `SIGNAL_DRAIN_MS` budget, run concurrently with the otel drain (not after
+ * it, so a killed run never pays both budgets back to back), and never able
+ * to throw into this handler.
  * A second signal during the drain exits immediately — someone pressing ^C
  * twice means "now", and a shutdown path that ignores that is a hang.
  */
-function finalizeWhenKilled(run) {
-    let draining = false;
-    const handler = (signal) => {
-        const code = 128 + (signal === "SIGINT" ? 2 : 15);
-        if (draining)
-            process.exit(code);
-        draining = true;
+function handleSignal(signal) {
+    const code = 128 + (signal === "SIGINT" ? 2 : 15);
+    if (draining)
+        process.exit(code);
+    draining = true;
+    const runs = [...ACTIVE.values()]; // snapshot: finalize() may mutate ACTIVE mid-drain
+    for (const run of runs)
         run.tracer.sessionFinish(run.adw_id, false); // also closes process rows
-        // Unconfigured (the default) exits SYNCHRONOUSLY, exactly as it did before
-        // otel existed — no extra tick between the signal and the exit for the
-        // repos that never opted in.
-        if (!run.tracer.otel)
-            process.exit(code);
-        // Bounded and never-throwing: flushAll() swallows its own failures and
-        // resolves on its own deadline, so this always reaches process.exit().
-        void otel.flushAll(SIGNAL_DRAIN_MS).then(() => process.exit(code), () => process.exit(code));
-    };
-    process.on("SIGTERM", handler);
-    process.on("SIGINT", handler);
+    const drains = [];
+    if (runs.some((run) => run.tracer.otel))
+        drains.push(otel.flushAll(SIGNAL_DRAIN_MS));
+    if (runs.some((run) => run.notify))
+        drains.push(drainNotifiers(SIGNAL_DRAIN_MS));
+    // Unconfigured (the default) exits SYNCHRONOUSLY, exactly as it did before
+    // otel/notify existed — no extra tick between the signal and the exit for
+    // the repos that never opted in to either.
+    if (drains.length === 0) {
+        process.exit(code);
+        return;
+    }
+    // Bounded and never-throwing: both drains swallow their own failures and
+    // resolve on their own deadline, so this always reaches process.exit().
+    void Promise.all(drains).then(() => process.exit(code), () => process.exit(code));
+}
+function finalizeWhenKilled(run) {
+    ACTIVE.set(run.adw_id, run);
+    if (installed)
+        return;
+    installed = true;
+    process.on("SIGTERM", handleSignal);
+    process.on("SIGINT", handleSignal);
+}
+/**
+ * The symmetric teardown for `finalizeWhenKilled()` above: drop `adwId` from
+ * `ACTIVE` (so a later signal can no longer reach it) and close its Tracer's
+ * sqlite handle. Call once a run's own dispatch has fully settled — success
+ * or thrown error alike; `chains/index.ts`'s `runChain()` finally is the one
+ * seam every dispatch path (one-shot CLI and `spf watch` alike) shares on
+ * the way out, exactly where `otel.releaseOtelExporter()` already lives for
+ * the identical reason (see otel.ts's RUN-SCOPED CLEANUP note / #26).
+ *
+ * Without this, `spf watch` held every finished run's `Run` (and its
+ * Tracer, its open sqlite handle, and its Notifier) strongly reachable from
+ * the signal listener for the rest of the daemon's life — the listener
+ * closes over the `run` a fresh `finalizeWhenKilled()` call captured, but
+ * since #26 only that one listener installs once now, and `ACTIVE` is the
+ * only thing keeping a finished run reachable from it.
+ *
+ * A one-shot invocation with no explicit `--adw-id` makes `adwId` here the
+ * caller's `ctx.adw_id` (`null`) rather than the id `session.ensure()`
+ * actually minted, so this is a harmless no-op for it — same caveat as
+ * `releaseOtelExporter`, and harmless for the same reason: that process
+ * exits right after anyway.
+ */
+export function finalize(adwId) {
+    if (!adwId)
+        return;
+    const run = ACTIVE.get(adwId);
+    if (!run)
+        return;
+    ACTIVE.delete(adwId);
+    run.tracer.close();
+}
+/** Tests only: which adw_ids the process-wide signal handler currently considers active. */
+export function activeRunIdsForTest() {
+    return [...ACTIVE.keys()];
 }
 /**
  * `cwd` anchors this run's repo_root and data_dir — it is NOT where the

package/dist/core/tiering.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Risk-tiered per-role model routing — SPF #14.
+ *
+ * PURE except for `probeServedOllamaTags`, the one async/impure export (a
+ * network probe — see its own doc comment below). Everything else here is a
+ * function of its own arguments: no `Run`, no `ChainContext`, no git handle,
+ * no filesystem. That purity is deliberate — it is what lets `startRun`
+ * (`src/chains/steps.ts`) and `spf estimate` call the IDENTICAL
+ * `resolveTiering` and get identical answers with no drift between "what
+ * will dispatch" and "what would dispatch".
+ *
+ * No imports from `src/chains/` and none from `src/cli/` — `spf doctor` and
+ * `startRun` both import FROM this module, never the reverse.
+ *
+ * ── The mechanism, in one paragraph ─────────────────────────────────────
+ * A run's `risk` (`low`/`standard`/`high`) is a single run-global scalar,
+ * classified once from the chain's name and the prompt's word count
+ * (`classifyRisk`). Separately, `tiering.roles` names a baseline tier per
+ * ROLE (an agent name) on `tiering.tiers`, a ladder ordered weakest first.
+ * `resolveTiering` shifts every routed role's baseline by the SAME step in
+ * the SAME direction (down for `low`, up for `high`), walking down to the
+ * nearest rung that is both available (§ probe) and backend-compatible
+ * (rule T) — never up, because a degradation must never silently escalate
+ * spend. An agent not named in `roles` is never touched: its own `model:`
+ * stands. `effectiveAgent` is the one place that turns a resolution into an
+ * actual `AgentConfig` — overriding `model` and NOTHING else.
+ */
+import type { AgentConfig, SFConfig } from "./data_types.ts";
+/**
+ * One explicit `name -> weight` table entry per BUILT-IN chain
+ * (`src/chains/index.ts`'s `CHAINS`), including every chain that weighs
+ * `0` — an entry, not a fallthrough. A name absent from this table (any
+ * repo-local `.spf/chains/*.yaml` chain, or a built-in nobody has wired in
+ * yet) falls to `0` through `chainWeight`'s own default — a DIFFERENT code
+ * path from being explicitly listed as `0`, which is what lets a test
+ * assert "every built-in chain has a real entry here" rather than merely
+ * "this returned 0", so a new built-in nobody wired in cannot land in the
+ * `0` bucket unnoticed.
+ */
+export declare const CHAIN_WEIGHTS: Record<string, -1 | 0 | 1>;
+/** `name in CHAIN_WEIGHTS` distinguishes "explicitly 0" from "fell through" — see `CHAIN_WEIGHTS`'s own comment. */
+export declare function chainWeight(name: string): number;
+/** Whitespace-delimited word count, deliberately not tokens — no tokenizer exists for an arbitrary ollama/<tag>, and a word count is free, stable, and reproducible from the trace. */
+export declare function promptWords(prompt: string): number;
+/** `-1` for a terse ask, `+1` for a long one, `0` otherwise. */
+export declare function promptWeight(words: number): number;
+export type Risk = "low" | "standard" | "high";
+export interface TierSignals {
+    chain: string;
+    chain_weight: number;
+    prompt_words: number;
+    prompt_weight: number;
+    sum: number;
+}
+/**
+ * The classifier. Asymmetric on purpose: demotion (`low`) requires TWO
+ * agreeing signals (`sum <= -2` — both `chain_weight` and `prompt_weight`
+ * at `-1`); promotion (`high`) requires only ONE. Concretely that means a
+ * long prompt (`prompt_weight === 1`, ≥400 words) forces `high`
+ * UNCONDITIONALLY, even riding on top of a `-1` chain (`spf scout "<≥400
+ * words>"` → `high`, not the `sum === 0` "standard" a naive `sum >= 1`
+ * threshold would give) — the design doc's own §2 3×3 table and its §3.1
+ * reachability table both pin this cell as `high`, so the table (not the
+ * simpler-looking `sum` arithmetic sketched alongside it) is what
+ * `src/test/tiering.test.ts`'s full-grid test treats as the specification.
+ * An unnecessarily weak model produces a wrong answer that costs a whole
+ * re-run — the expensive failure; an unnecessarily strong one just costs
+ * some tokens — the cheap failure. Skewed toward the cheap one.
+ */
+export declare function classifyRisk(chainName: string, prompt: string): {
+    risk: Risk;
+    signals: TierSignals;
+};
+/** PURE input — no `Run`, no `ChainContext`. `required` scopes everything: an agent no phase in this run will dispatch is neither routed nor reported. */
+export interface TierInput {
+    cfg: SFConfig;
+    chainName: string;
+    prompt: string;
+    /** `null` == "not probed / probe failed" == fail open, drop nothing. */
+    servedOllamaTags: Set<string> | null;
+    required: string[];
+}
+export interface TierRoute {
+    /** the tier NAME finally selected, after the shift and any walk-down */
+    tier: string;
+    /** agent.model as CONFIGURED (post-back-fill) */
+    configured: string;
+    /** the model that will actually dispatch */
+    effective: string;
+}
+export interface TierResolution {
+    risk: Risk;
+    signals: TierSignals;
+    /**
+     * FULL routing: one entry for every agent in `required` that tiering
+     * routes — including entries where `effective === configured`. NOT a
+     * diff; `changedModels()` below is the derived diff view. An agent not in
+     * `required`, or not named in `roles`, has no entry.
+     */
+    routing: Record<string, TierRoute>;
+    /** One line per degradation or non-routable role. Empty when tiering is disabled or has nothing to say. */
+    notes: string[];
+}
+/**
+ * The ladder walk (design doc §4.3). Never throws and never reports a
+ * severity — a backend mismatch (rule T) or an unknown tier name is a
+ * `notes` line plus a role left unrouted; `agents.validate()` owns
+ * severity, this owns detection.
+ */
+export declare function resolveTiering(input: TierInput): TierResolution;
+/**
+ * The diff view, derived — `{agent: effective}` for entries where
+ * `configured !== effective`. Empty means tiering changed nothing this run.
+ * Deriving it (rather than storing it) is what keeps this view and the
+ * full `routing` map from disagreeing: one source, one filter.
+ */
+export declare function changedModels(res: TierResolution): Record<string, string>;
+/**
+ * The single dispatch-site change (design doc §4.6): `model` and ONLY
+ * `model`. `run` is a minimal structural shape — deliberately not
+ * `agents.ts`'s `RunForAgents`, which would import this module and create a
+ * cycle — so any run-shaped object with an (optional) `tiering` field
+ * satisfies it.
+ */
+export declare function effectiveAgent(run: {
+    tiering?: TierResolution | null;
+}, base: AgentConfig): AgentConfig;
+/**
+ * `Promise<Set<string> | null>` of bare (unprefixed) served Ollama tags, or
+ * `null` on any failure — non-200, timeout, connection refused, an
+ * unparseable/`data`-less body. `null` means "fail open, drop nothing",
+ * never "everything is unserved": an unreachable probe silently degrading
+ * every agent to the bottom rung is a worse outcome than the honest
+ * "Unknown model ID" error Ollama itself raises at first dispatch.
+ *
+ * Only actually probes when tiering is enabled AND at least one declared
+ * tier's model starts with `ollama/` — never on a run whose tiers are all
+ * hosted, and never when tiering is off. Memoized once per process.
+ *
+ * A NEW helper, not a reuse of `spf doctor`'s `probeGet`: that helper
+ * discards the response body, which is the only part that matters here.
+ */
+export declare function probeServedOllamaTags(cfg: SFConfig): Promise<Set<string> | null>;
+/** Test-only: `probeServedOllamaTags` memoizes once per process, so a test that stubs `fetch` differently across cases must reset the cache between them. */
+export declare function resetProbeCacheForTest(): void;