tickmarkr 1.45.0 → 1.47.0

package/dist/config/config.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { parse } from "yaml";
+import { parse, stringify } from "yaml";
 import { z } from "zod";
 import { stateDirName } from "../graph/graph.js";
 import { SHAPES, TIERS } from "../graph/schema.js";
@@ -20,6 +20,8 @@ export const TierEntrySchema = z.object({
     vendor: z.string(),
     channel: z.enum(["sub", "api"]),
     models: z.record(z.string(), TierEnum),
+    // v1.47 T3: optional per-model context-window sizes (tokens). Absent block ⇒ no doctor column, no plan lint.
+    windows: z.record(z.string(), z.number().int().positive()).optional(),
 });
 // v1.10 FLEET-06: optional routing.allow/deny fleet preference; absent blocks ⇒ byte-identical routing/discovery.
 // deny wins on conflict; presence of allow (even {} / empty arrays) activates allowlist (fail-closed).
@@ -87,6 +89,15 @@ export const TickmarkrConfigSchema = z.object({
             halfLifeRuns: z.number().positive().optional(),
             availWeight: z.number().nonnegative().optional(),
         }).optional(),
+        // E3 (v1.45-T3): optional exploration fence — absent block ⇒ byte-identical to pre-v1.45 routing.
+        explore: z.object({
+            mode: z.enum(["on", "off"]).optional(),
+            excludeShapes: z.array(z.string()).optional(),
+            excludeComplexityAtOrAbove: z.number().int().min(1).max(10).nullable().optional(),
+            cap: z.number().int().positive().optional(),
+        }).optional(),
+        // v1.47 T4: per-shape time SLA in minutes — advisory plan lint only; absent ⇒ byte-identical routing.
+        sla: z.record(z.string(), z.number().positive()).optional(),
         // Pre-v1.21 doctor.json lacks per-model verdicts. Keep legacy unknown-is-routable behavior opt-in.
         allowUnverifiedModels: z.boolean(),
         allow: PrefBlockSchema.optional(),
@@ -305,6 +316,8 @@ export function configTemplate(overlay) {
 #     migration: frontier
 #   learned: on            # default ON (ROUTE-14); cold profile = exact v1.5 static routing, warms per workspace. Set 'off' to pin static routing; preview with 'tickmarkr plan'
 #   learnedTuning: { halfLifeRuns: 5, availWeight: 0.05 }  # optional; defaults byte-identical
+#   explore: { mode: on, excludeShapes: [], excludeComplexityAtOrAbove: null, cap: 5 }  # optional; absent ⇒ byte-identical
+#   sla: { implement: 15 }  # optional per-shape minutes — advisory plan lint only; absent ⇒ no lint
 #   allow: { adapters: [claude-code, codex] }   # optional fleet allowlist; presence activates even if empty (fail-closed)
 #   deny: { models: [codex:gpt-5.5] }           # optional fleet denylist; deny beats allow on conflict
 #   # entry grammar: adapter id | model id | adapter:model (entries in either list accept all three forms)
@@ -365,3 +378,277 @@ export function configTemplate(overlay) {
     const nl = base.indexOf("\n");
     return `${base.slice(0, nl + 1)}${lines.join("\n")}\n${base.slice(nl + 1)}`;
 }
+/** Fleet-owned overlay keys — the only config surface `tickmarkr fleet` may write. */
+export const FLEET_OVERLAY_KEYS = ["routing", "tiers"];
+export function repoOverlayPath(repoRoot) {
+    return join(repoRoot, stateDirName(repoRoot), "config.yaml");
+}
+export function readOverlayFile(path) {
+    const raw = readYaml(path);
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== "object" || Array.isArray(raw))
+        throw new ConfigError(`invalid overlay at ${path}`);
+    return raw;
+}
+export function fleetEditableFromConfig(cfg) {
+    const tiers = {};
+    for (const [adapter, entry] of Object.entries(cfg.tiers)) {
+        tiers[adapter] = {};
+        for (const [model, tier] of Object.entries(entry.models))
+            tiers[adapter][model] = { tier };
+    }
+    return {
+        denyAdapters: [...(cfg.routing.deny?.adapters ?? [])].sort(),
+        denyModels: [...(cfg.routing.deny?.models ?? [])].sort(),
+        tiers,
+        map: structuredClone(cfg.routing.map),
+        floors: { ...cfg.routing.floors },
+    };
+}
+function fleetSubset(obj) {
+    const out = {};
+    for (const k of FLEET_OVERLAY_KEYS) {
+        if (obj[k] !== undefined)
+            out[k] = obj[k];
+    }
+    return out;
+}
+/** Resolve which layer last set a dotted fleet path (defaults < global < repo). */
+export function fleetKeyLayer(repoRoot, dotted, opts = {}) {
+    const gdir = opts.globalDir ?? globalConfigDir();
+    const globalRaw = readOverlayFile(join(gdir, "config.yaml"));
+    const repoRaw = readOverlayFile(repoOverlayPath(repoRoot));
+    const parts = dotted.split(".");
+    const at = (layer) => {
+        let cur = layer;
+        for (const p of parts) {
+            if (cur === undefined || cur === null || typeof cur !== "object" || Array.isArray(cur))
+                return undefined;
+            cur = cur[p];
+        }
+        return cur;
+    };
+    if (at(repoRaw) !== undefined)
+        return "repo";
+    if (at(globalRaw) !== undefined)
+        return "global";
+    return "defaults";
+}
+/** Non-interactive fleet state for CI drift checks (`tickmarkr fleet --print`). */
+export function formatFleetPrint(repoRoot, opts = {}) {
+    const gdir = opts.globalDir ?? globalConfigDir();
+    const effective = loadConfig(repoRoot, { globalDir: gdir });
+    const editable = fleetEditableFromConfig(effective);
+    const lines = ["# tickmarkr fleet — effective state (repo > global > defaults)"];
+    const annotate = (dotted, yaml) => `${yaml}  # ${fleetKeyLayer(repoRoot, dotted, opts)}`;
+    const denyAdapters = editable.denyAdapters;
+    const denyModels = editable.denyModels;
+    if (denyAdapters.length || denyModels.length) {
+        lines.push("routing:");
+        lines.push("  deny:");
+        if (denyAdapters.length)
+            lines.push(annotate("routing.deny.adapters", `    adapters: ${stringify(denyAdapters).trim()}`));
+        if (denyModels.length)
+            lines.push(annotate("routing.deny.models", `    models: ${stringify(denyModels).trim()}`));
+    }
+    const mapKeys = Object.keys(editable.map).sort();
+    if (mapKeys.length) {
+        if (!lines.some((l) => l === "routing:"))
+            lines.push("routing:");
+        lines.push("  map:");
+        for (const shape of mapKeys) {
+            const entry = editable.map[shape];
+            const body = stringify(entry, { indent: 4 }).trim().split("\n").map((l) => `    ${l}`).join("\n");
+            lines.push(annotate(`routing.map.${shape}`, `    ${shape}:`));
+            lines.push(body.split("\n").slice(1).join("\n"));
+        }
+    }
+    const floorKeys = Object.keys(editable.floors).sort();
+    if (floorKeys.length) {
+        if (!lines.some((l) => l === "routing:"))
+            lines.push("routing:");
+        lines.push(annotate("routing.floors", `  floors: ${stringify(Object.fromEntries(floorKeys.map((k) => [k, editable.floors[k]]))).trim().replace(/^/gm, "  ")}`));
+    }
+    const tierAdapters = Object.keys(editable.tiers).sort();
+    if (tierAdapters.length) {
+        lines.push("tiers:");
+        for (const adapter of tierAdapters) {
+            const models = editable.tiers[adapter];
+            const modelIds = Object.keys(models).sort();
+            if (!modelIds.length)
+                continue;
+            lines.push(`  ${adapter}:`);
+            lines.push("    models:");
+            for (const model of modelIds) {
+                const v = models[model];
+                if (v === null)
+                    lines.push(`      ${model}: null`);
+                else
+                    lines.push(annotate(`tiers.${adapter}.models.${model}`, `      ${model}: ${v.tier}`));
+            }
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+function sortedUnique(xs) {
+    return [...new Set(xs)].sort();
+}
+/** Build the repo overlay fragment fleet would write for edits since session start. */
+export function fleetRepoOverlayFromDelta(initial, edited, existingRepo = {}) {
+    if (fleetEditableEquals(initial, edited))
+        return {};
+    const out = structuredClone(existingRepo);
+    const routing = { ...out.routing };
+    let routingTouched = false;
+    const denyChanged = sortedUnique(initial.denyAdapters).join() !== sortedUnique(edited.denyAdapters).join()
+        || sortedUnique(initial.denyModels).join() !== sortedUnique(edited.denyModels).join();
+    if (denyChanged) {
+        routing.deny = {
+            adapters: edited.denyAdapters.length ? edited.denyAdapters : null,
+            models: edited.denyModels.length ? edited.denyModels : null,
+        };
+        routingTouched = true;
+    }
+    const mapDelta = {};
+    for (const shape of new Set([...Object.keys(initial.map), ...Object.keys(edited.map)])) {
+        if (JSON.stringify(initial.map[shape]) !== JSON.stringify(edited.map[shape]))
+            mapDelta[shape] = edited.map[shape];
+    }
+    if (Object.keys(mapDelta).length) {
+        routing.map = { ...routing.map, ...mapDelta };
+        routingTouched = true;
+    }
+    const floorDelta = {};
+    for (const shape of new Set([...Object.keys(initial.floors), ...Object.keys(edited.floors)])) {
+        if (initial.floors[shape] !== edited.floors[shape])
+            floorDelta[shape] = edited.floors[shape];
+    }
+    if (Object.keys(floorDelta).length) {
+        routing.floors = { ...routing.floors, ...floorDelta };
+        routingTouched = true;
+    }
+    if (routingTouched)
+        out.routing = routing;
+    const tiersOut = {
+        ...out.tiers,
+    };
+    let tiersTouched = false;
+    const adapters = new Set([...Object.keys(initial.tiers), ...Object.keys(edited.tiers)]);
+    for (const adapter of adapters) {
+        const models = new Set([
+            ...Object.keys(initial.tiers[adapter] ?? {}),
+            ...Object.keys(edited.tiers[adapter] ?? {}),
+        ]);
+        const modelDelta = {};
+        for (const model of models) {
+            const a = initial.tiers[adapter]?.[model];
+            const b = edited.tiers[adapter]?.[model];
+            if (JSON.stringify(a) !== JSON.stringify(b)) {
+                modelDelta[model] = b === null || b === undefined ? null : b.tier;
+            }
+        }
+        if (Object.keys(modelDelta).length) {
+            tiersOut[adapter] = { models: { ...tiersOut[adapter]?.models, ...modelDelta } };
+            tiersTouched = true;
+        }
+    }
+    if (tiersTouched)
+        out.tiers = tiersOut;
+    return out;
+}
+export function repoOverlayYaml(overlay, provenance = {}) {
+    if (!Object.keys(overlay).length)
+        return "";
+    const fleet = fleetSubset(overlay);
+    const fleetBody = serializeFleetOverlay(fleet, provenance);
+    const rest = { ...overlay };
+    for (const k of FLEET_OVERLAY_KEYS)
+        delete rest[k];
+    if (!Object.keys(rest).length)
+        return fleetBody;
+    const head = stringify(rest).trimEnd();
+    return fleetBody ? `${head}\n${fleetBody}` : `${head}\n`;
+}
+export function serializeFleetOverlay(overlay, provenance = {}) {
+    if (!Object.keys(overlay).length)
+        return "";
+    const lines = [];
+    const today = new Date().toISOString().slice(0, 10);
+    const routing = overlay.routing;
+    if (routing) {
+        lines.push("routing:");
+        const deny = routing.deny;
+        if (deny) {
+            lines.push("  deny:");
+            if (deny.adapters)
+                lines.push(`    adapters: ${stringify(deny.adapters).trim()}`);
+            if (deny.models)
+                lines.push(`    models: ${stringify(deny.models).trim()}`);
+        }
+        if (routing.map) {
+            lines.push("  map:");
+            for (const [shape, entry] of Object.entries(routing.map)) {
+                lines.push(`    ${shape}:`);
+                const body = stringify(entry, { indent: 2 }).trim().split("\n");
+                lines.push(...body.map((l) => `      ${l}`));
+            }
+        }
+        if (routing.floors)
+            lines.push(`  floors: ${stringify(routing.floors).trim().replace(/^/gm, "  ")}`);
+    }
+    const tiers = overlay.tiers;
+    if (tiers) {
+        lines.push("tiers:");
+        for (const [adapter, entry] of Object.entries(tiers)) {
+            lines.push(`  ${adapter}:`);
+            if (entry.vendor)
+                lines.push(`    vendor: ${entry.vendor}`);
+            if (entry.channel)
+                lines.push(`    channel: ${entry.channel}`);
+            lines.push("    models:");
+            for (const [model, tier] of Object.entries(entry.models ?? {})) {
+                if (tier === null)
+                    lines.push(`      ${model}: null`);
+                else {
+                    const note = provenance[adapter]?.[model];
+                    const suffix = note ? `  # ${note} — fleet ${today}` : "";
+                    lines.push(`      ${model}: ${tier}${suffix}`);
+                }
+            }
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function unifiedYamlDiff(before, after, label = "config overlay") {
+    const a = before.split("\n");
+    const b = after.split("\n");
+    if (before === after)
+        return "";
+    const header = [`--- ${label} (current)`, `+++ ${label} (proposed)`];
+    const hunks = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length || j < b.length) {
+        if (i < a.length && j < b.length && a[i] === b[j]) {
+            i++;
+            j++;
+            continue;
+        }
+        const startI = i;
+        const startJ = j;
+        while (i < a.length && (j >= b.length || a[i] !== b[j]))
+            i++;
+        while (j < b.length && (i >= a.length || a[i] !== b[j]))
+            j++;
+        hunks.push("@@");
+        for (let k = startI; k < i; k++)
+            hunks.push(`-${a[k]}`);
+        for (let k = startJ; k < j; k++)
+            hunks.push(`+${b[k]}`);
+    }
+    return `${header.join("\n")}\n${hunks.join("\n")}\n`;
+}
+export function fleetEditableEquals(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}

package/dist/drivers/herdr.d.ts

@@ -28,6 +28,7 @@ export declare class HerdrDriver implements ExecutorDriver {
     private glyphFor;
     private joinGroup;
     run(slot: Slot, cmd: string): Promise<void>;
+    private waitOk;
     waitOutput(slot: Slot, pattern: string, timeoutMs: number, opts?: {
         regex?: boolean;
     }): Promise<boolean>;

package/dist/drivers/herdr.js

@@ -275,15 +275,25 @@ export class HerdrDriver {
         if (r.code !== 0)
             throw new Error(`herdr pane run failed: ${r.stderr || r.stdout}`);
     }
+    waitOk(code, stdout) {
+        if (code !== 0 || !stdout.trim())
+            return code === 0; // herdr's successful waits may be silent
+        try {
+            return !Object.hasOwn(JSON.parse(stdout), "error");
+        }
+        catch {
+            return false; // a non-empty herdr wait response must be a parseable envelope
+        }
+    }
     async waitOutput(slot, pattern, timeoutMs, opts) {
         const pane = await this.paneId(slot);
         const r = await this.herdr(`wait output ${shq(pane)} --match ${shq(pattern)}${opts?.regex ? " --regex" : ""} --timeout ${Math.floor(timeoutMs)}`, slot.cwd, timeoutMs + 15_000);
-        return r.code === 0 && !r.stdout.includes('"error"'); // dead pane: exit 0 + error json (herdr bite)
+        return this.waitOk(r.code, r.stdout); // dead pane: exit 0 + top-level error envelope (herdr bite)
     }
     async waitAgentStatus(slot, status, timeoutMs) {
         const pane = await this.paneId(slot);
         const r = await this.herdr(`wait agent-status ${shq(pane)} --status ${shq(status)} --timeout ${Math.floor(timeoutMs)}`, slot.cwd, timeoutMs + 15_000);
-        return r.code === 0 && !r.stdout.includes('"error"');
+        return this.waitOk(r.code, r.stdout);
     }
     async status(slot) {
         return this.statusByName(slot.name);

package/dist/gates/acceptance.js

@@ -61,14 +61,19 @@ const isTest = (a) => typeof a === "object" && a.oracle === "test";
 const isJudge = (a) => typeof a === "string" || (typeof a === "object" && a.oracle === "judge");
 // npm/yarn/pnpm/npx script wrappers need `--` to forward -t to the underlying vitest/jest runner; a bare
 // runner (vitest/jest) takes -t directly. -t is the shared testNamePattern shorthand both honor.
+// OBS-62: vitest -t treats the name as a regex — escape metachars so a verbatim-titled test matches.
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 // OBS-55: when the base command already contains `--`, append -t after forwarded args — a second `--`
 // makes vitest treat -t as a positional file filter and the name filter is dropped.
 export function testFiltered(testCmd, name) {
+    const pattern = escapeRegExp(name);
     const wrapped = /^\s*(npm|yarn|pnpm|npx)\b/.test(testCmd);
     if (wrapped && /\s--\s/.test(testCmd))
-        return `${testCmd} -t ${shq(name)}`;
+        return `${testCmd} -t ${shq(pattern)}`;
     const fwd = wrapped ? "-- " : "";
-    return `${testCmd} ${fwd}-t ${shq(name)}`;
+    return `${testCmd} ${fwd}-t ${shq(pattern)}`;
 }
 // vitest/jest summary: "Tests  N passed | M skipped (T)" — count passed+failed as actually ran.
 function testsRan(output) {

package/dist/gates/scope.d.ts

@@ -1,8 +1,9 @@
 import type { WorkerResult } from "../adapters/types.js";
 import type { GateResult } from "./types.js";
+export declare function scopeDiffBase(worktree: string, integrationTip: string): Promise<string>;
 /** Pure offender split — corpus-replay oracle exercises this exact decision logic. */
 export declare function dispositionOffenders(offenders: string[], allowDeviations: string[]): {
     hard: string[];
     allowed: string[];
 };
-export declare function scopeGate(worktree: string, baseRef: string, files: string[], result: WorkerResult, allowDeviations?: string[]): Promise<GateResult>;
+export declare function scopeGate(worktree: string, integrationTip: string, files: string[], result: WorkerResult, allowDeviations?: string[]): Promise<GateResult>;

package/dist/gates/scope.js

@@ -1,5 +1,14 @@
 import picomatch from "picomatch";
-import { shOk } from "../run/git.js";
+import { shGitOk } from "../run/git.js";
+// OBS-61: the live integration tip can advance between attempts (sibling merge) while a resumed
+// worktree stays parented on the old base — merge-base(tip, HEAD) pins the diff to the worktree's
+// creation ancestor so sibling edits cannot leak into scope as false out-of-scope offenders.
+export async function scopeDiffBase(worktree, integrationTip) {
+    const head = (await shGitOk("git rev-parse HEAD", worktree)).trim();
+    if (head === integrationTip)
+        return integrationTip;
+    return (await shGitOk(`git merge-base '${integrationTip}' '${head}'`, worktree)).trim();
+}
 /** Pure offender split — corpus-replay oracle exercises this exact decision logic. */
 export function dispositionOffenders(offenders, allowDeviations) {
     const allowedMatch = allowDeviations.length ? picomatch(allowDeviations, { dot: true }) : () => false;
@@ -13,10 +22,11 @@ export function dispositionOffenders(offenders, allowDeviations) {
     }
     return { hard, allowed };
 }
-export async function scopeGate(worktree, baseRef, files, result, allowDeviations = []) {
+export async function scopeGate(worktree, integrationTip, files, result, allowDeviations = []) {
     if (!files.length)
         return { gate: "scope", pass: true, details: "no file scope declared — unrestricted" };
-    const changed = (await shOk(`git diff --name-only '${baseRef}..HEAD'`, worktree)).trim().split("\n").filter(Boolean);
+    const baseRef = await scopeDiffBase(worktree, integrationTip);
+    const changed = (await shGitOk(`git diff --name-only '${baseRef}..HEAD'`, worktree)).trim().split("\n").filter(Boolean);
     const inScope = picomatch(files, { dot: true }); // byte-identical options to assertWriteScope in src/compile/common.ts
     const offenders = changed.filter((f) => !inScope(f));
     if (!offenders.length)

package/dist/plan/prompt.js

@@ -1,5 +1,5 @@
 export function scopePrompt(intent, repair) {
-    return `TICKMARKR-JUDGE
+    return `TICKMARKR-SCOPE
 You are drafting a tickmarkr native spec from an answered intent. Return only the Markdown spec, with no commentary or code fence.
 
 The draft must:

package/dist/route/profile.d.ts

@@ -11,6 +11,7 @@ export interface ProfileRow {
     consults?: number;
     parkKind?: string;
     runId?: string;
+    taskId?: string;
     quotaFailover?: true;
     overrun?: true;
 }
@@ -23,6 +24,7 @@ export interface ProfileCell {
     doneMedianMs?: number;
     nRaw?: number;
     overruns?: number;
+    discounted?: number;
 }
 export interface RoutingProfile {
     cells: Map<string, ProfileCell>;
@@ -38,10 +40,20 @@ export declare const EXPLORE_CAP = 5;
 export declare const HALF_LIFE_RUNS = 5;
 export declare const DECAY_CAP = 30;
 export declare function decayWeight(age: number, halfLife?: number): number;
-export declare function explorationBonus(cell: ProfileCell | undefined): number;
+export declare const HYGIENE_WEIGHTS: readonly [0, 0.5, 1];
+export type HygieneWeight = (typeof HYGIENE_WEIGHTS)[number];
+export interface ProfileDiscount {
+    runId: string;
+    taskId?: string;
+    weight: 0 | 0.5;
+    reason: string;
+}
+export declare function resolveHygieneWeight(row: ProfileRow, discounts?: readonly ProfileDiscount[]): HygieneWeight;
+export declare function explorationBonus(cell: ProfileCell | undefined, cap?: number): number;
 export declare function classify(r: ProfileRow): 1 | 0.5 | 0 | null;
 export declare function buildProfile(rows: ProfileRow[], opts?: {
     halfLifeRuns?: number;
+    discounts?: readonly ProfileDiscount[];
 }): RoutingProfile;
 export declare function cellOf(profile: RoutingProfile | undefined, shape: string, chKey: string, channel: string): ProfileCell | undefined;
 export declare function cellsOf(profile: RoutingProfile): Generator<{
@@ -58,8 +70,20 @@ export interface CellSummary {
     quotaHits: number;
     cold: boolean;
     exploreRemaining: number;
+    discounted: number;
 }
 export declare function cellSummary(cell: ProfileCell): CellSummary;
+export interface LearnedScoreTerms {
+    quality: number;
+    perf: number;
+    avail: number;
+    overrun: number;
+}
+export declare function learnedScoreTerms(profile: RoutingProfile | undefined, shape: string, chKey: string, channel: string, opts?: {
+    availWeight?: number;
+    slaMinutes?: number;
+}): LearnedScoreTerms;
 export declare function learnedScore(profile: RoutingProfile | undefined, shape: string, chKey: string, channel: string, opts?: {
     availWeight?: number;
+    slaMinutes?: number;
 }): number;

package/dist/route/profile.js

@@ -31,6 +31,25 @@ export const DECAY_CAP = 30;
 export function decayWeight(age, halfLife = HALF_LIFE_RUNS) {
     return 2 ** -Math.min(Math.floor(age / halfLife), DECAY_CAP);
 }
+// v1.46 T5 evidence hygiene — operator-filed discounts on poisoned runs/tasks. h ∈ {0, 0.5, 1} is dyadic
+// so h·w (w a power of two) and every partial sum stay exact; magnitude headroom loses one bit (2^-32 floor).
+export const HYGIENE_WEIGHTS = [0, 0.5, 1];
+// Resolve h for one row: run-level marks (no taskId) apply to every row in the run; task-level marks are
+// selective. Multiple marks ⇒ minimum weight (most aggressive discount wins).
+export function resolveHygieneWeight(row, discounts = []) {
+    if (!discounts.length || row.runId === undefined)
+        return 1;
+    let h = 1;
+    for (const d of discounts) {
+        if (d.runId !== row.runId)
+            continue;
+        if (d.taskId !== undefined && d.taskId !== row.taskId)
+            continue;
+        if (d.weight < h)
+            h = d.weight;
+    }
+    return h;
+}
 // Phase 14 exploration bonus: an under-observed channel keeps gathering evidence so early bad luck can't
 // starve it permanently (EXP-01). Total by construction — dispatches is a finite non-negative integer counter,
 // the denominator is a compile-time positive constant; no ln/sqrt/data-dependent divide, so none of the
@@ -40,10 +59,11 @@ export function decayWeight(age, halfLife = HALF_LIFE_RUNS) {
 // yielded no quality obs (quota parks) has spent its budget — stop probing it, don't probe it forever.
 // ponytail: rank-decay ships in v1.8 (buildProfile below); remaining ceiling = doneMedianMs staleness
 // (perf term is undecayed) and per-cell EWMA as the finer upgrade path.
-export function explorationBonus(cell) {
+// ROUTE-15 PARAM-SHAPE: optional cap threads from routing.explore.cap; undefined ⇒ module default (byte-identical).
+export function explorationBonus(cell, cap = EXPLORE_CAP) {
     if (!cell)
         return 0;
-    return Math.max(0, 1 - cell.dispatches / EXPLORE_CAP); // ∈ [0,1]; exactly 0 once dispatches ≥ cap
+    return Math.max(0, 1 - cell.dispatches / cap); // ∈ [0,1]; exactly 0 once dispatches ≥ cap
 }
 const QUALITY_FAIL_PARKS = new Set(["ladder-exhausted", "attempt-cap", "gate-fail"]);
 // Quality observation per row: 1 clean, 0.5 degraded, 0 verified failure, null excluded/unobserved.
@@ -107,8 +127,12 @@ export function buildProfile(rows, opts = {}) {
         // in IEEE-754 ⇒ the fold stays order-insensitive (v1.7's invariant EXTENDED, not abandoned). Magnitude
         // headroom: weights are multiples of 2^-31, so exactness holds while row-count ≪ 2^21. nRaw is the
         // integer undecayed observation count (Phase 28) — never enters the score arithmetic.
+        // SINGLE evidence-fold site — hygiene h multiplies quality evidence ONLY (n, qSum), never dispatches/quotaHits/overruns.
         if (q !== null) {
-            const w = decayWeight(ageOf(r.runId), halfLife);
+            const h = resolveHygieneWeight(r, opts.discounts);
+            const w = decayWeight(ageOf(r.runId), halfLife) * h;
+            if (h < 1)
+                c.discounted = (c.discounted ?? 0) + 1;
             c.n += w;
             c.qSum += q * w;
             c.nRaw = (c.nRaw ?? 0) + 1;
@@ -154,18 +178,16 @@ export function cellSummary(cell) {
         quotaHits: cell.quotaHits,
         cold: cell.n < MIN_SAMPLES,
         exploreRemaining: Math.max(0, EXPLORE_CAP - cell.dispatches),
+        discounted: cell.discounted ?? 0,
     };
 }
-// Total by construction: every miss returns the explicit NEUTRAL constant; every denominator is a
-// compile-time-positive constant sum; no Record indexing by row strings (the TIER_RANK[typo] scar).
-// Score 0 defers to the static sort keys, which already encode the benchmark-dated tier seeds — a
-// per-channel numeric prior would give differing n=0 scores and break ROUTE-07's byte-identical cold
-// start. Shrinking toward 0 IS shrinking toward the static prior.
-export function learnedScore(profile, shape, chKey, channel, opts = {}) {
+// Per-term decomposition of learnedScore — the single arithmetic source for profile --explain.
+export function learnedScoreTerms(profile, shape, chKey, channel, opts = {}) {
     const availWeight = opts.availWeight ?? AVAIL_WEIGHT;
+    const refMs = opts.slaMinutes !== undefined ? opts.slaMinutes * 60_000 : REF_MS;
     const cell = cellOf(profile, shape, chKey, channel);
     if (!cell)
-        return NEUTRAL; // unknown channel ⇒ exactly neutral (empty-profile / cold-start leg, ROUTE-07)
+        return { quality: NEUTRAL, perf: NEUTRAL, avail: NEUTRAL, overrun: NEUTRAL };
     // Cold-start proof (ROUTE-07): n ≤ nRaw ≤ dispatches and doneCount ≤ dispatches by construction, so a
     // thin-dispatch cell (dispatches < MIN_SAMPLES) gates ALL THREE terms to literal +0 ⇒ exactly NEUTRAL.
     // Each term is gated INDEPENDENTLY (no early-exit) so a dispatch-warm/quality-cold HIGH-throttle cell can
@@ -178,7 +200,7 @@ export function learnedScore(profile, shape, chKey, channel, opts = {}) {
     // 0 — a silent ROUTE-07 break. With it, every quotaHits=0 cell is byte-identical to pre-ROUTE-12.
     const perf = cell.n < MIN_SAMPLES || cell.doneMedianMs === undefined || cell.doneCount < MIN_SAMPLES
         ? 0
-        : PERF_WEIGHT * (REF_MS / (REF_MS + cell.doneMedianMs) - 0.5);
+        : PERF_WEIGHT * (refMs / (refMs + cell.doneMedianMs) - 0.5);
     // PENALTY-ONLY availability (ROUTE-12): a throttling channel is less available — deprioritize it without ever
     // treating quota as a quality signal, ejecting it, or predicting quota. quotaHits=0 ⇒ avail 0 (no-throttle
     // byte-identity). Gated on dispatches (≥ MIN_SAMPLES > 0 ⇒ positive denominator, no divide-by-zero) INDEPENDENTLY
@@ -192,6 +214,18 @@ export function learnedScore(profile, shape, chKey, channel, opts = {}) {
     // fact as a quality signal, ejecting it, or predicting it. overruns=0 ⇒ overrunPen 0 (overrun-free byte-identity).
     // Gated on dispatches (≥ MIN_SAMPLES > 0 ⇒ positive denominator, no divide-by-zero) INDEPENDENTLY of n, mirroring
     // the ROUTE-12 avail term exactly. NOT the symmetric (0.5 − ratio) form (the v1.9 ROUTE-16 penalty-only precedent).
-    const overrunPen = cell.dispatches < MIN_SAMPLES ? 0 : -OVERRUN_WEIGHT * ((cell.overruns ?? 0) / cell.dispatches); // ∈ [−OVERRUN_WEIGHT, 0]
-    return quality + perf + avail + overrunPen; // score ∈ (−0.625, +0.525), finite for every input
+    const overrun = cell.dispatches < MIN_SAMPLES ? 0 : -OVERRUN_WEIGHT * ((cell.overruns ?? 0) / cell.dispatches); // ∈ [−OVERRUN_WEIGHT, 0]
+    return { quality, perf, avail, overrun };
+}
+// Total by construction: every miss returns the explicit NEUTRAL constant; every denominator is a
+// compile-time-positive constant sum; no Record indexing by row strings (the TIER_RANK[typo] scar).
+// Score 0 defers to the static sort keys, which already encode the benchmark-dated tier seeds — a
+// per-channel numeric prior would give differing n=0 scores and break ROUTE-07's byte-identical cold
+// start. Shrinking toward 0 IS shrinking toward the static prior.
+export function learnedScore(profile, shape, chKey, channel, opts = {}) {
+    const cell = cellOf(profile, shape, chKey, channel);
+    if (!cell)
+        return NEUTRAL; // unknown channel ⇒ exactly neutral (empty-profile / cold-start leg, ROUTE-07)
+    const t = learnedScoreTerms(profile, shape, chKey, channel, opts);
+    return t.quality + t.perf + t.avail + t.overrun; // score ∈ (−0.625, +0.525), finite for every input
 }

package/dist/route/router.d.ts

@@ -1,5 +1,5 @@
 import { type Assignment, type BillingChannel } from "../adapters/types.js";
-import { type TickmarkrConfig } from "../config/config.js";
+import { type TickmarkrConfig, type Tier } from "../config/config.js";
 import type { Task } from "../graph/schema.js";
 import { type RoutingProfile } from "./profile.js";
 export type LadderStep = "retry" | "escalate" | "consult" | "human";
@@ -26,9 +26,16 @@ export interface RoutingPreferContext {
     doctorFresh: boolean;
     overlayPreferShapes: ReadonlySet<string>;
 }
+export interface ExploreContext {
+    noExplore?: boolean;
+    quality?: boolean;
+}
+export declare const NO_EXPLORE_ENV = "TICKMARKR_NO_EXPLORE";
+export declare const QUALITY_ENV = "TICKMARKR_QUALITY";
+export declare const raiseTier: (tier: Tier) => Tier;
 export declare class RoutingError extends Error {
     constructor(msg: string);
 }
 export declare function marginalCostRank(c: BillingChannel): number;
-export declare function route(task: Task, cfg: TickmarkrConfig, channels: BillingChannel[], profile?: RoutingProfile, preferCtx?: RoutingPreferContext): Route;
-export declare function nextChannel(current: Assignment, task: Task, cfg: TickmarkrConfig, channels: BillingChannel[], tried: string[], profile?: RoutingProfile): Assignment | null;
+export declare function route(task: Task, cfg: TickmarkrConfig, channels: BillingChannel[], profile?: RoutingProfile, preferCtx?: RoutingPreferContext, exclude?: ReadonlySet<string>, exploreCtx?: ExploreContext): Route;
+export declare function nextChannel(current: Assignment, task: Task, cfg: TickmarkrConfig, channels: BillingChannel[], tried: string[], profile?: RoutingProfile, exclude?: ReadonlySet<string>): Assignment | null;