crewhaus 0.1.8 → 0.2.0

package/dist/mcp-doctor.js

@@ -0,0 +1,249 @@
+/**
+ * Ops item 38 — `crewhaus mcp doctor` core, in a side-effect-free module (this
+ * entry file runs an argv switch on import) mirroring `doctor-checks.ts` /
+ * `eval-matrix.ts`. Three capabilities, all pure — the CLI owns the file I/O
+ * and the live `listTools` probe; this module does the aggregation + diffing:
+ *
+ *   1. HEALTH SCORING — fold the durable `mcp_stats` session-log records
+ *      (`{ server, toolName, durationMs, isError }`, mirrored from the
+ *      trace-bus-only `mcp_call_end` by runtime-core) into per-server
+ *      error-rate + latency + a chronic-failure verdict. `mcp_call_*` events
+ *      are trace-bus-ONLY, so this durable mirror is the only cross-session
+ *      history there is to score.
+ *
+ *   2. DRIFT WATCH — snapshot each server's `listTools` (tool name + a stable
+ *      JSON-schema hash) and diff it against the LAST snapshot on disk, so an
+ *      added / removed / schema-changed tool is reported BEFORE a production
+ *      call fails (tool lists are fetched once at connect today; drift is
+ *      otherwise invisible until runtime failure).
+ *
+ *   3. QUARANTINE DECISION — decide which chronically-failing servers' tools
+ *      should be withdrawn from the ToolCatalog (the runtime injects a synthetic
+ *      "unavailable" notice so the model routes around them) and which have
+ *      recovered enough to restore. The catalog mutation lives in the runtime /
+ *      CLI; this module only decides.
+ */
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+/**
+ * F5 — sanitise an mcp_servers KEY into a single safe filename segment before it
+ * is joined onto `.crewhaus/mcp/` (the drift-snapshot write). The mcp_servers
+ * key schema is `z.string().min(1)` (NOT `safeName`), so a server named
+ * `../../evil` — or one carrying a slash / NUL — would let
+ * `join(mcpDir, `${name}.json`)` escape the directory. We `basename` to strip
+ * path components, then replace every character outside the conservative
+ * `[A-Za-z0-9._-]` set with `_` (the same class the eval-runner + graders use),
+ * and floor an empty / dot-only result to a stable placeholder. The result is
+ * always a bare filename that stays inside the snapshot dir.
+ */
+export function safeMcpFileName(name) {
+    const base = basename(name).replace(/[^A-Za-z0-9._-]+/g, "_");
+    if (base === "" || base === "." || base === ".." || /^\.+$/.test(base))
+        return "_server";
+    return base;
+}
+/** Thresholds a server must cross to be judged chronically failing → quarantine
+ *  candidate. Kept together so the report and the quarantine decision agree. */
+export const QUARANTINE_POLICY = {
+    /** Minimum calls before an error rate is trustworthy (cold-start guard). */
+    minCalls: 5,
+    /** Error-rate ceiling; above it (with enough calls) the server is chronic. */
+    errorRate: 0.5,
+    /** OR: this many consecutive errors is chronic regardless of overall rate
+     *  (a server that just went hard-down mid-session). */
+    errorStreak: 4,
+};
+/** Nearest-rank percentile (0-based floor). Empty ⇒ 0. */
+export function percentile(values, p) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const idx = Math.floor(p * (sorted.length - 1));
+    return sorted[idx] ?? 0;
+}
+/**
+ * Fold a flat stream of `mcp_stats` payloads (already read from session logs,
+ * oldest-first) into per-server health. The `maxErrorStreak` is computed over
+ * the input order, so callers should pass records in chronological order (the
+ * session-log reader yields insertion order — which is chronological).
+ */
+export function scoreMcpHealth(records) {
+    const byServer = new Map();
+    for (const r of records) {
+        let acc = byServer.get(r.server);
+        if (acc === undefined) {
+            acc = { calls: 0, errors: 0, durations: [], curStreak: 0, maxStreak: 0 };
+            byServer.set(r.server, acc);
+        }
+        acc.calls += 1;
+        acc.durations.push(r.durationMs);
+        if (r.isError) {
+            acc.errors += 1;
+            acc.curStreak += 1;
+            if (acc.curStreak > acc.maxStreak)
+                acc.maxStreak = acc.curStreak;
+        }
+        else {
+            acc.curStreak = 0;
+        }
+    }
+    const out = [];
+    for (const [server, acc] of byServer) {
+        const errorRate = acc.calls > 0 ? acc.errors / acc.calls : 0;
+        const chronic = isChronic(acc.calls, errorRate, acc.maxStreak);
+        out.push({
+            server,
+            calls: acc.calls,
+            errors: acc.errors,
+            errorRate,
+            p50Ms: percentile(acc.durations, 0.5),
+            p95Ms: percentile(acc.durations, 0.95),
+            maxErrorStreak: acc.maxStreak,
+            chronic,
+        });
+    }
+    // Sickest first (chronic, then by error rate desc) so the report leads with
+    // the servers that need attention.
+    return out.sort((a, b) => {
+        if (a.chronic !== b.chronic)
+            return a.chronic ? -1 : 1;
+        return b.errorRate - a.errorRate;
+    });
+}
+/** Chronic-failure verdict shared by scoring + quarantine decision. */
+export function isChronic(calls, errorRate, maxErrorStreak) {
+    if (maxErrorStreak >= QUARANTINE_POLICY.errorStreak)
+        return true;
+    return calls >= QUARANTINE_POLICY.minCalls && errorRate >= QUARANTINE_POLICY.errorRate;
+}
+/**
+ * Stable hash of a JSON-schema value: recursively sort object keys so
+ * `{a,b}` and `{b,a}` hash identically, then sha256 the canonical form. A
+ * server that reorders its schema keys between connects is NOT drift; a server
+ * that changes a field's type IS. Returns the first 16 hex chars (collision-
+ * safe enough for a per-tool change signal).
+ */
+export function schemaHash(schema) {
+    return createHash("sha256").update(canonicalJson(schema)).digest("hex").slice(0, 16);
+}
+function canonicalJson(value) {
+    if (value === null || value === undefined)
+        return "null";
+    const t = typeof value;
+    if (t === "string" || t === "number" || t === "boolean")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (t === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+    }
+    return JSON.stringify(String(value));
+}
+/** Build a fresh snapshot from a server's live `listTools` result. */
+export function buildSnapshot(server, tools, ts) {
+    return {
+        version: 1,
+        server,
+        ts,
+        tools: tools
+            .map((t) => ({ name: t.name, schemaHash: schemaHash(t.inputSchema) }))
+            .sort((a, b) => a.name.localeCompare(b.name)),
+    };
+}
+/** True when nothing changed. */
+export function driftIsEmpty(drift) {
+    return drift.added.length === 0 && drift.removed.length === 0 && drift.schemaChanged.length === 0;
+}
+/**
+ * Diff a previous snapshot against the current one. `previous` undefined (no
+ * snapshot on disk yet) ⇒ empty drift (the current becomes the new baseline;
+ * a first-ever connect is not "drift"). Added = in current not previous;
+ * removed = in previous not current; schemaChanged = in both, different hash.
+ */
+export function diffSnapshots(previous, current) {
+    if (previous === undefined)
+        return { added: [], removed: [], schemaChanged: [] };
+    const prev = new Map(previous.tools.map((t) => [t.name, t.schemaHash]));
+    const cur = new Map(current.tools.map((t) => [t.name, t.schemaHash]));
+    const added = [];
+    const removed = [];
+    const schemaChanged = [];
+    for (const [name, hash] of cur) {
+        const prevHash = prev.get(name);
+        if (prevHash === undefined)
+            added.push(name);
+        else if (prevHash !== hash)
+            schemaChanged.push(name);
+    }
+    for (const name of prev.keys()) {
+        if (!cur.has(name))
+            removed.push(name);
+    }
+    return {
+        added: added.sort(),
+        removed: removed.sort(),
+        schemaChanged: schemaChanged.sort(),
+    };
+}
+/**
+ * Decide catalog mutations from the current health + the set of servers whose
+ * tools are ALREADY quarantined. A chronic server not yet quarantined →
+ * quarantine; a quarantined server that is no longer chronic (its recent
+ * window is healthy — e.g. a probe succeeded) → restore. A server absent from
+ * `health` entirely (no recent calls) is left as-is: no signal either way.
+ */
+export function decideQuarantine(health, alreadyQuarantined) {
+    const out = new Set(alreadyQuarantined);
+    const byServer = new Map(health.map((h) => [h.server, h]));
+    const quarantine = [];
+    const restore = [];
+    for (const h of health) {
+        if (h.chronic && !out.has(h.server))
+            quarantine.push(h.server);
+    }
+    for (const server of out) {
+        const h = byServer.get(server);
+        if (h !== undefined && !h.chronic)
+            restore.push(server);
+    }
+    return { quarantine: quarantine.sort(), restore: restore.sort() };
+}
+/**
+ * The synthetic notice injected in place of a quarantined server's tools so the
+ * model routes around them — mirrors loop-detection's warning injection. Kept
+ * here so the report and the runtime injection render the identical text.
+ */
+export function quarantineNotice(server, reason) {
+    return `[mcp] tools from server "${server}" are temporarily unavailable (${reason}). Route around them; they auto-restore once the server is healthy again.`;
+}
+// -------- report rendering --------
+/** Render the per-server health table lines for `crewhaus mcp doctor`. */
+export function formatHealthReport(health) {
+    if (health.length === 0) {
+        return ["no MCP call history yet — run the agent against its MCP servers first"];
+    }
+    const lines = ["per-server MCP health (from durable mcp_stats):"];
+    for (const h of health) {
+        const mark = h.chronic ? "✗" : h.errorRate > 0 ? "~" : "✓";
+        lines.push(`  ${mark} ${h.server}: ${h.calls} call(s), ${(h.errorRate * 100).toFixed(1)}% errors, ` +
+            `p50 ${Math.round(h.p50Ms)}ms / p95 ${Math.round(h.p95Ms)}ms, max error streak ${h.maxErrorStreak}` +
+            `${h.chronic ? " — CHRONIC (quarantine candidate)" : ""}`);
+    }
+    return lines;
+}
+/** Render the drift lines for one server. Empty array when no drift. */
+export function formatDriftReport(server, drift) {
+    if (driftIsEmpty(drift))
+        return [];
+    const lines = [`  drift on "${server}":`];
+    if (drift.added.length > 0)
+        lines.push(`    + added: ${drift.added.join(", ")}`);
+    if (drift.removed.length > 0)
+        lines.push(`    - removed: ${drift.removed.join(", ")}`);
+    if (drift.schemaChanged.length > 0) {
+        lines.push(`    ~ schema-changed: ${drift.schemaChanged.join(", ")}`);
+    }
+    return lines;
+}

package/dist/model-scan.d.ts

@@ -0,0 +1,116 @@
+import { type CandidateProvider, type CapabilityRequirement, type PricingTable } from "@crewhaus/cost-tracker";
+import type { Spec } from "@crewhaus/spec";
+/** Thrown on a malformed model-scan / pricing-sync invocation. */
+export declare class ModelScanError extends Error {
+    readonly name = "ModelScanError";
+}
+/** A spec model string → the `(provider, modelId)` the cost-tracker tables
+ *  key on. `undefined` when unparseable or routed to a provider the tables
+ *  don't cover (local/, azure/, named hosts). */
+export declare function parsedModelForTables(modelString: string): {
+    readonly provider: CandidateProvider;
+    readonly modelId: string;
+} | undefined;
+/** One evaluated candidate cell — the model-scan input from the matrix run. */
+export type ScanCell = {
+    readonly model: string;
+    readonly passRate?: number;
+    readonly meanScore?: number;
+    readonly costPer1kSamplesUsd?: number;
+    readonly error?: string;
+};
+export type ScanProposal = {
+    readonly currentModel: string;
+    readonly candidateModel: string;
+    readonly scoreDelta: number;
+    readonly costDeltaPer1kUsd: number;
+    /** True when the candidate strictly beats current: >= score AND < cost. */
+    readonly recommended: boolean;
+    readonly reason: string;
+};
+export type MarketScanResult = {
+    readonly currentModel: string;
+    readonly current?: ScanCell;
+    readonly candidates: ReadonlyArray<string>;
+    readonly proposals: ReadonlyArray<ScanProposal>;
+    /** The single best recommended proposal (highest score at lowest cost), if any. */
+    readonly best?: ScanProposal;
+};
+export type BuildScanCandidatesOptions = {
+    readonly pricing?: PricingTable;
+    readonly require?: CapabilityRequirement;
+    /** Cross-provider replacements are in scope for a human-reviewed proposal. */
+    readonly sameProviderOnly?: boolean;
+    /** Cap the number of candidates evaled (cheapest-first). Default 6. */
+    readonly limit?: number;
+};
+/**
+ * Enumerate the replacement models model-scan will eval. Cheapest-blended
+ * first, current family excluded, capped. Returns spec model strings.
+ */
+export declare function buildScanCandidates(currentModel: string, opts?: BuildScanCandidatesOptions): string[];
+/**
+ * Fold matrix cells into scan proposals. `current` is the cell for the spec's
+ * existing model; each candidate cell becomes a proposal comparing score +
+ * projected cost. A candidate is RECOMMENDED when it holds score (>= current)
+ * AND costs less — the strict "beats current on score at lower cost" bar. The
+ * `best` proposal maximizes score then minimizes cost among recommended.
+ */
+export declare function buildMarketScan(currentModel: string, cells: ReadonlyArray<ScanCell>): MarketScanResult;
+/** The machine-readable proposal artifact model-scan writes next to a report. */
+export type ScanProposalArtifact = {
+    readonly kind: "model-scan-proposal";
+    readonly generatedAt: string;
+    readonly currentModel: string;
+    readonly recommendedModel: string;
+    readonly scoreDelta: number;
+    readonly costDeltaPer1kUsd: number;
+    /** The spec edit a human (or `--write`) applies: replace agent.model. */
+    readonly patch: {
+        readonly op: "replace";
+        readonly path: ReadonlyArray<string>;
+        readonly value: string;
+    };
+};
+/** Build the patch.json artifact for the best proposal (caller guards `best`). */
+export declare function buildProposalArtifact(result: MarketScanResult, now?: () => Date): ScanProposalArtifact | undefined;
+export type ModelDoctorCheck = {
+    readonly label: string;
+    readonly pass: boolean;
+    readonly warn?: boolean;
+    readonly reason?: string;
+};
+export type BuildModelChecksOptions = {
+    readonly pricing?: PricingTable;
+    readonly now?: Date;
+    /** Warn when the pricing table is older than this many days. Default 120. */
+    readonly maxAgeDays?: number;
+    /** Extra model strings to check (compaction.model, judge model, sub-agents). */
+    readonly auxModels?: ReadonlyArray<{
+        readonly slot: string;
+        readonly model: string;
+    }>;
+};
+/**
+ * doctor --models: (a) every spec model missing from the pricing table
+ * (silently billed $0 today — surfaces the gap), (b) pricing-table staleness,
+ * (c) known-sunset model ids. Pure — the CLI reads the spec + prints.
+ */
+export declare function buildModelChecks(agentModel: string | undefined, opts?: BuildModelChecksOptions): ModelDoctorCheck[];
+/** ~/.crewhaus/pricing/<version>.json target path for a feed version. */
+export declare function pricingFeedPath(homeDir: string, version: string): string;
+/**
+ * Model fields are OUTSIDE `OPTIMIZABLE_PATHS` by design, so the normal
+ * optimizer apply path (`validatePatch` → `applySpecPatch`) REFUSES a model
+ * patch. `crewhaus model-scan --write` deliberately bypasses the whitelist
+ * gate: it calls `applySpecPatch` DIRECTLY (which never consults
+ * OPTIMIZABLE_PATHS — that check lives only in the separately-invoked
+ * `validatePatch`), reusing spec-patch's yaml-document CST technique to
+ * rewrite the value while preserving every comment, key order, and blank
+ * line. The resulting YAML is re-parsed by `applySpecPatch` (so an invalid
+ * model still fails loudly), and every `model-scan --write` is a
+ * human-initiated action on a human-reviewed proposal — never automatic.
+ *
+ * Returns the rewritten YAML text (caller writes it back to disk).
+ */
+export declare function writeModelField(yamlText: string, target: Spec["target"], path: ReadonlyArray<string>, value: string): string;

package/dist/model-scan.js

@@ -0,0 +1,226 @@
+import { DEFAULT_CAPABILITIES, DEFAULT_PRICING, classifyPricingStaleness, enumerateCandidates, findSunset, resolvePricing, } from "@crewhaus/cost-tracker";
+/**
+ * Item 24 — `crewhaus model-scan`, `crewhaus doctor --models`, and
+ * `crewhaus pricing sync`, in a side-effect-free module (the CLI entry file
+ * runs an argv switch on import) mirroring `eval-matrix.ts` / `doctor-checks.ts`.
+ *
+ * All three read the pricing/capability tables that ship in `@crewhaus/cost-tracker`:
+ *   - model-scan enumerates capability-compatible replacement candidates for
+ *     the cwd spec's `agent.model`, evals each on the spec's dataset (the same
+ *     `--models` matrix machinery, injected as `runMatrix`), and emits a
+ *     proposal + patch.json when a candidate beats current on score at lower
+ *     cost. NEVER auto-applied — model fields are outside OPTIMIZABLE_PATHS by
+ *     design, so `--write` does its OWN comment-preserving CST edit
+ *     (`writeModelField`, reusing spec-patch's yaml-document technique).
+ *   - doctor --models flags pricing misses / staleness / known sunsets.
+ *   - pricing sync loads a versioned feed into ~/.crewhaus/pricing/.
+ */
+import { parseModelString } from "@crewhaus/model-router";
+import { applySpecPatch } from "@crewhaus/spec-patch";
+/** Thrown on a malformed model-scan / pricing-sync invocation. */
+export class ModelScanError extends Error {
+    name = "ModelScanError";
+}
+// ---------- provider mapping ----------
+const CANDIDATE_PROVIDERS = ["anthropic", "openai", "gemini", "bedrock"];
+/** A spec model string → the `(provider, modelId)` the cost-tracker tables
+ *  key on. `undefined` when unparseable or routed to a provider the tables
+ *  don't cover (local/, azure/, named hosts). */
+export function parsedModelForTables(modelString) {
+    let parsed;
+    try {
+        parsed = parseModelString(modelString);
+    }
+    catch {
+        return undefined;
+    }
+    // local/azure/named-host all parse to providerId "openai" but with a
+    // baseUrl/azure/hostId — those aren't in the pricing table, so skip.
+    if (parsed.providerId === "openai") {
+        if (parsed.baseUrl !== undefined || parsed.azure !== undefined || parsed.hostId !== undefined) {
+            return undefined;
+        }
+    }
+    if (!CANDIDATE_PROVIDERS.includes(parsed.providerId))
+        return undefined;
+    return { provider: parsed.providerId, modelId: parsed.modelId };
+}
+/**
+ * Enumerate the replacement models model-scan will eval. Cheapest-blended
+ * first, current family excluded, capped. Returns spec model strings.
+ */
+export function buildScanCandidates(currentModel, opts = {}) {
+    const parsed = parsedModelForTables(currentModel);
+    if (parsed === undefined)
+        return [];
+    const cands = enumerateCandidates(parsed, {
+        pricing: opts.pricing ?? DEFAULT_PRICING,
+        capabilities: DEFAULT_CAPABILITIES,
+        ...(opts.require !== undefined ? { require: opts.require } : {}),
+        sameProviderOnly: opts.sameProviderOnly === true,
+        excludeCurrent: true,
+    });
+    const limit = opts.limit ?? 6;
+    return cands.slice(0, limit).map((c) => c.modelString);
+}
+/**
+ * Fold matrix cells into scan proposals. `current` is the cell for the spec's
+ * existing model; each candidate cell becomes a proposal comparing score +
+ * projected cost. A candidate is RECOMMENDED when it holds score (>= current)
+ * AND costs less — the strict "beats current on score at lower cost" bar. The
+ * `best` proposal maximizes score then minimizes cost among recommended.
+ */
+export function buildMarketScan(currentModel, cells) {
+    const current = cells.find((c) => c.model === currentModel);
+    const candidateCells = cells.filter((c) => c.model !== currentModel);
+    const curScore = current?.meanScore ?? 0;
+    const curCost = current?.costPer1kSamplesUsd;
+    const proposals = candidateCells.map((cell) => {
+        if (cell.error !== undefined || cell.meanScore === undefined) {
+            return {
+                currentModel,
+                candidateModel: cell.model,
+                scoreDelta: 0,
+                costDeltaPer1kUsd: 0,
+                recommended: false,
+                reason: cell.error !== undefined ? `cell errored: ${cell.error}` : "no score",
+            };
+        }
+        const scoreDelta = cell.meanScore - curScore;
+        const candCost = cell.costPer1kSamplesUsd;
+        const costDelta = candCost !== undefined && curCost !== undefined ? candCost - curCost : Number.NaN;
+        const cheaper = Number.isFinite(costDelta) && costDelta < 0;
+        const holdsScore = scoreDelta >= 0;
+        const recommended = holdsScore && cheaper;
+        return {
+            currentModel,
+            candidateModel: cell.model,
+            scoreDelta,
+            costDeltaPer1kUsd: Number.isFinite(costDelta) ? costDelta : 0,
+            recommended,
+            reason: recommended
+                ? `+${scoreDelta.toFixed(3)} score at ${costDelta < 0 ? "" : "+"}${costDelta.toFixed(4)} $/1k`
+                : !Number.isFinite(costDelta)
+                    ? "cost unknown (pricing miss) — cannot compare spend"
+                    : !holdsScore
+                        ? `score dropped ${scoreDelta.toFixed(3)}`
+                        : "not cheaper than current",
+        };
+    });
+    const recommended = proposals.filter((p) => p.recommended);
+    // Best: max score delta, then min (most-negative) cost delta.
+    const best = recommended.sort((a, b) => {
+        if (b.scoreDelta !== a.scoreDelta)
+            return b.scoreDelta - a.scoreDelta;
+        return a.costDeltaPer1kUsd - b.costDeltaPer1kUsd;
+    })[0];
+    return {
+        currentModel,
+        ...(current !== undefined ? { current } : {}),
+        candidates: candidateCells.map((c) => c.model),
+        proposals,
+        ...(best !== undefined ? { best } : {}),
+    };
+}
+/** Build the patch.json artifact for the best proposal (caller guards `best`). */
+export function buildProposalArtifact(result, now = () => new Date()) {
+    if (result.best === undefined)
+        return undefined;
+    return {
+        kind: "model-scan-proposal",
+        generatedAt: now().toISOString(),
+        currentModel: result.currentModel,
+        recommendedModel: result.best.candidateModel,
+        scoreDelta: result.best.scoreDelta,
+        costDeltaPer1kUsd: result.best.costDeltaPer1kUsd,
+        patch: { op: "replace", path: ["agent", "model"], value: result.best.candidateModel },
+    };
+}
+/**
+ * doctor --models: (a) every spec model missing from the pricing table
+ * (silently billed $0 today — surfaces the gap), (b) pricing-table staleness,
+ * (c) known-sunset model ids. Pure — the CLI reads the spec + prints.
+ */
+export function buildModelChecks(agentModel, opts = {}) {
+    const pricing = opts.pricing ?? DEFAULT_PRICING;
+    const now = opts.now ?? new Date();
+    const checks = [];
+    const models = [];
+    if (agentModel !== undefined)
+        models.push({ slot: "agent.model", model: agentModel });
+    for (const aux of opts.auxModels ?? [])
+        models.push({ slot: aux.slot, model: aux.model });
+    for (const { slot, model } of models) {
+        const parsed = parsedModelForTables(model);
+        if (parsed === undefined) {
+            checks.push({
+                label: `${slot} pricing (${model})`,
+                pass: true,
+                warn: true,
+                reason: "routed to a provider outside the pricing table (local/azure/named-host or unparseable) — cost tracking reports $0 for this model",
+            });
+            continue;
+        }
+        const row = resolvePricing(pricing, parsed.provider, parsed.modelId);
+        if (row === undefined) {
+            checks.push({
+                label: `${slot} pricing (${model})`,
+                pass: false,
+                reason: `no pricing row for ${parsed.provider}/${parsed.modelId} — cost-tracker silently bills it $0; add a row to DEFAULT_PRICING or \`crewhaus pricing sync\` a feed`,
+            });
+        }
+        else {
+            checks.push({ label: `${slot} pricing (${model})`, pass: true });
+        }
+        // Sunset watch.
+        const sunset = findSunset(parsed.provider, parsed.modelId);
+        if (sunset !== undefined) {
+            checks.push({
+                label: `${slot} sunset (${model})`,
+                pass: true,
+                warn: true,
+                reason: `retires ${sunset.retiresOn} — migrate to ${sunset.replacement}${sunset.note !== undefined ? ` (${sunset.note})` : ""}`,
+            });
+        }
+    }
+    // Pricing-table freshness.
+    const staleness = classifyPricingStaleness(pricing, now, opts.maxAgeDays ?? 120);
+    checks.push({
+        label: `pricing table freshness (v${staleness.version})`,
+        pass: true,
+        ...(staleness.stale ? { warn: true, reason: staleness.reason } : {}),
+    });
+    return checks;
+}
+// ---------- pricing sync ----------
+/** ~/.crewhaus/pricing/<version>.json target path for a feed version. */
+export function pricingFeedPath(homeDir, version) {
+    // Basename-safe version (dates are already safe; be defensive).
+    const safe = version.replace(/[^A-Za-z0-9._-]+/g, "_");
+    return `${homeDir}/.crewhaus/pricing/${safe}.json`;
+}
+// ---------- --write: direct comment-preserving CST edit of agent.model ----------
+/**
+ * Model fields are OUTSIDE `OPTIMIZABLE_PATHS` by design, so the normal
+ * optimizer apply path (`validatePatch` → `applySpecPatch`) REFUSES a model
+ * patch. `crewhaus model-scan --write` deliberately bypasses the whitelist
+ * gate: it calls `applySpecPatch` DIRECTLY (which never consults
+ * OPTIMIZABLE_PATHS — that check lives only in the separately-invoked
+ * `validatePatch`), reusing spec-patch's yaml-document CST technique to
+ * rewrite the value while preserving every comment, key order, and blank
+ * line. The resulting YAML is re-parsed by `applySpecPatch` (so an invalid
+ * model still fails loudly), and every `model-scan --write` is a
+ * human-initiated action on a human-reviewed proposal — never automatic.
+ *
+ * Returns the rewritten YAML text (caller writes it back to disk).
+ */
+export function writeModelField(yamlText, target, path, value) {
+    const { yaml } = applySpecPatch(yamlText, {
+        target,
+        path: [...path],
+        op: "replace",
+        value,
+        rationale: "model-scan --write: human-reviewed model replacement (outside OPTIMIZABLE_PATHS)",
+    });
+    return yaml;
+}