@gr8ful/spf 0.5.0 → 0.6.0

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;

package/dist/core/tiering.js

@@ -0,0 +1,235 @@
+/**
+ * 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 { ollamaBaseUrl } from "./ollama_provider.js";
+// ── the classifier (design doc §2) ──────────────────────────────────────────
+/**
+ * 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 const CHAIN_WEIGHTS = {
+    scout: -1,
+    prompt: -1,
+    document: -1,
+    quality: -1,
+    "simple-sdlc": 1,
+    "plan-build-test-quality": 1,
+    refine: 1,
+    plan: 0,
+    build: 0,
+    "plan-build": 0,
+    "build-test": 0,
+    "plan-build-test": 0,
+    "build-review": 0,
+};
+/** `name in CHAIN_WEIGHTS` distinguishes "explicitly 0" from "fell through" — see `CHAIN_WEIGHTS`'s own comment. */
+export function chainWeight(name) {
+    return name in CHAIN_WEIGHTS ? CHAIN_WEIGHTS[name] : 0;
+}
+/** 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 function promptWords(prompt) {
+    return prompt.split(/\s+/).filter(Boolean).length;
+}
+/** `-1` for a terse ask, `+1` for a long one, `0` otherwise. */
+export function promptWeight(words) {
+    if (words <= 60)
+        return -1;
+    if (words >= 400)
+        return 1;
+    return 0;
+}
+/**
+ * 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 function classifyRisk(chainName, prompt) {
+    const chain_weight = chainWeight(chainName);
+    const prompt_words = promptWords(prompt);
+    const prompt_weight = promptWeight(prompt_words);
+    const sum = chain_weight + prompt_weight;
+    const risk = prompt_weight === 1 || sum >= 1 ? "high" : sum <= -2 ? "low" : "standard";
+    return { risk, signals: { chain: chainName, chain_weight, prompt_words, prompt_weight, sum } };
+}
+const RISK_STEP = { low: -1, standard: 0, high: 1 };
+function stripOllamaPrefix(model) {
+    return model.startsWith("ollama/") ? model.slice("ollama/".length) : model;
+}
+/** Usable == not dropped by the availability probe, AND backend-compatible (rule T). */
+function usable(tier, agent, servedOllamaTags) {
+    if (tier.coding_agent !== agent.coding_agent)
+        return false; // rule T
+    if (servedOllamaTags !== null && tier.model.startsWith("ollama/")) {
+        // The comparison strips the "ollama/" prefix before lookup — getting
+        // this backwards fails CLOSED in the wrong direction: every ollama/*
+        // rung would look unserved and every ladder would walk to the bottom.
+        return servedOllamaTags.has(stripOllamaPrefix(tier.model));
+    }
+    return true;
+}
+/**
+ * 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 function resolveTiering(input) {
+    const { cfg, chainName, prompt, servedOllamaTags, required } = input;
+    const { risk, signals } = classifyRisk(chainName, prompt);
+    const routing = {};
+    const notes = [];
+    if (!cfg.tiering.enabled)
+        return { risk, signals, routing, notes };
+    const step = RISK_STEP[risk];
+    for (const agentName of required) {
+        const baseline = cfg.tiering.roles[agentName];
+        if (baseline === undefined)
+            continue; // precedence: not named in roles -> untouched
+        const agent = cfg.agents.find((a) => a.name === agentName);
+        if (!agent) {
+            notes.push(`tiering.roles.${agentName} names an agent not defined in this roster — left unrouted, no change`);
+            continue;
+        }
+        const i = cfg.tiering.tiers.findIndex((t) => t.name === baseline);
+        if (i === -1) {
+            notes.push(`tiering.roles.${agentName} names tier ${JSON.stringify(baseline)}, which is not declared in tiering.tiers — left unrouted`);
+            continue;
+        }
+        const target = Math.min(Math.max(i + step, 0), cfg.tiering.tiers.length - 1);
+        let j = target;
+        while (j >= 0 && !usable(cfg.tiering.tiers[j], agent, servedOllamaTags))
+            j--;
+        if (j < 0) {
+            notes.push(`${agentName}: no rung at or below ${cfg.tiering.tiers[target].name} is usable for this run (unserved tag or backend mismatch) — ` +
+                `left unrouted, dispatching on ${agent.model}`);
+            continue;
+        }
+        const tier = cfg.tiering.tiers[j];
+        routing[agentName] = { tier: tier.name, configured: agent.model, effective: tier.model };
+    }
+    return { risk, signals, routing, notes };
+}
+/**
+ * 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 function changedModels(res) {
+    const changed = {};
+    for (const [agentName, route] of Object.entries(res.routing)) {
+        if (route.configured !== route.effective)
+            changed[agentName] = route.effective;
+    }
+    return changed;
+}
+/**
+ * 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 function effectiveAgent(run, base) {
+    const effective = run.tiering?.routing[base.name]?.effective;
+    return effective === undefined ? base : { ...base, model: effective };
+}
+// ── availability probe (design doc §4.4B) ───────────────────────────────────
+const PROBE_TIMEOUT_MS = 3_000; // same budget spf doctor's own probeGet uses
+let cachedProbe;
+async function fetchServedOllamaTags() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+        // ollamaBaseUrl() is the SAME default-substitution a real dispatch
+        // uses, including treating a set-but-EMPTY OLLAMA_BASE_URL as unset —
+        // never re-derive that default here.
+        const url = ollamaBaseUrl().replace(/\/+$/, "") + "/models";
+        const res = await fetch(url, { signal: controller.signal });
+        if (res.status !== 200)
+            return null;
+        const body = (await res.json());
+        if (!body || !Array.isArray(body.data))
+            return null;
+        const tags = new Set();
+        for (const entry of body.data) {
+            if (entry && typeof entry === "object" && "id" in entry) {
+                tags.add(String(entry.id));
+            }
+        }
+        return tags; // bare tags — no "ollama/" prefix in the response
+    }
+    catch {
+        return null; // timeout | connection refused | unparseable body all fail OPEN
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * `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 async function probeServedOllamaTags(cfg) {
+    if (!cfg.tiering.enabled || !cfg.tiering.tiers.some((t) => t.model.startsWith("ollama/")))
+        return null;
+    if (cachedProbe === undefined)
+        cachedProbe = fetchServedOllamaTags();
+    return cachedProbe;
+}
+/** Test-only: `probeServedOllamaTags` memoizes once per process, so a test that stubs `fetch` differently across cases must reset the cache between them. */
+export function resetProbeCacheForTest() {
+    cachedProbe = undefined;
+}

package/dist/core/tracer.d.ts

@@ -31,6 +31,16 @@ export declare class Tracer {
     /** `null` unless `observability.otel` is configured — see the header. */
     otel: OtelExporter | null;
     constructor(dbPath: string, eventsJsonl: string, otel?: OtelExporter | null);
+    /**
+     * Close the sqlite handle. A one-shot CLI process never needs this — it
+     * exits right after its one Tracer anyway — but `spf watch`'s daemon loop
+     * builds a fresh Tracer (and a fresh `new Database(dbPath)`) per claimed
+     * issue, in-process, for the life of the daemon; without this, every
+     * issue's handle stayed open forever. Called from `session.ts`'s
+     * `finalize()`, once a run's own dispatch has fully settled — see its
+     * comment for why that timing is safe.
+     */
+    close(): void;
     /** Additive column migrations, so a db from an older SPF still opens. */
     private migrate;
     /**

package/dist/core/tracer.js

@@ -128,6 +128,18 @@ export class Tracer {
         this.db.exec(SCHEMA);
         this.migrate();
     }
+    /**
+     * Close the sqlite handle. A one-shot CLI process never needs this — it
+     * exits right after its one Tracer anyway — but `spf watch`'s daemon loop
+     * builds a fresh Tracer (and a fresh `new Database(dbPath)`) per claimed
+     * issue, in-process, for the life of the daemon; without this, every
+     * issue's handle stayed open forever. Called from `session.ts`'s
+     * `finalize()`, once a run's own dispatch has fully settled — see its
+     * comment for why that timing is safe.
+     */
+    close() {
+        this.db.close();
+    }
     /** Additive column migrations, so a db from an older SPF still opens. */
     migrate() {
         for (const [table, column, decl] of MIGRATIONS) {