tickmarkr 1.30.0

package/dist/route/router.d.ts

@@ -0,0 +1,26 @@
+import { type Assignment, type BillingChannel } from "../adapters/types.js";
+import { type DrovrConfig } from "../config/config.js";
+import type { Task } from "../graph/schema.js";
+import { type RoutingProfile } from "./profile.js";
+export type LadderStep = "retry" | "escalate" | "consult" | "human";
+export interface RouteDeviation {
+    static: string;
+    chosen: string;
+    score: number;
+    staticScore: number;
+    n: number;
+    explore?: true;
+}
+export interface Route {
+    assignment: Assignment;
+    ladder: LadderStep[];
+    lints: string[];
+    provenance: string;
+    deviation?: RouteDeviation;
+}
+export declare class RoutingError extends Error {
+    constructor(msg: string);
+}
+export declare function marginalCostRank(c: BillingChannel): number;
+export declare function route(task: Task, cfg: DrovrConfig, channels: BillingChannel[], profile?: RoutingProfile): Route;
+export declare function nextChannel(current: Assignment, task: Task, cfg: DrovrConfig, channels: BillingChannel[], tried: string[], profile?: RoutingProfile): Assignment | null;

package/dist/route/router.js

@@ -0,0 +1,200 @@
+import { channelKey, channelsFromConfig } from "../adapters/types.js";
+import { TIER_RANK } from "../config/config.js";
+import { disallowedBy } from "./preference.js";
+import { cellOf, EXPLORE_CAP, explorationBonus, learnedScore } from "./profile.js";
+export class RoutingError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = "RoutingError";
+    }
+}
+export function marginalCostRank(c) {
+    if (c.channel === "sub")
+        return 0; // flat-rate: ~zero marginal cost until quota
+    return TIER_RANK[c.tier] + 1; // metered API: cheap 1, mid 2, frontier 3
+}
+const toAssignment = (c) => ({
+    adapter: c.adapter, model: c.model, channel: c.channel, tier: c.tier,
+});
+function resolvePin(pin, channels) {
+    const c = channels.find((c) => c.adapter === pin.via && c.model === pin.model);
+    if (!c) {
+        throw new RoutingError(`pinned ${pin.via}:${pin.model} not available — doctor found: ${channels.map(channelKey).join(", ") || "(nothing)"}`);
+    }
+    return c;
+}
+function preferIndex(c, prefer = []) {
+    const i = prefer.findIndex((p) => p === c.adapter || p === channelKey(c));
+    return i === -1 ? prefer.length : i;
+}
+function ladderFor(task, entry) {
+    const escalate = task.routingHints?.escalate ?? entry?.escalate ?? true;
+    return escalate ? ["retry", "escalate", "consult", "human"] : ["retry", "consult", "human"];
+}
+export function route(task, cfg, channels, profile) {
+    const lints = [];
+    const floor = cfg.routing.floors[task.shape];
+    const entry = cfg.routing.map[task.shape];
+    const prefActive = !!(cfg.routing.allow || cfg.routing.deny);
+    const disallowedPin = (via, model, kind) => {
+        const d = disallowedBy({ adapter: via, model }, cfg.routing);
+        if (d) {
+            throw new RoutingError(`${task.id}: ${kind} ${via}:${model} is disallowed by routing.${d.by} (${d.entry}) — remove the ${d.by} entry or re-pin to an allowed channel`);
+        }
+    };
+    const preflightPrefer = (p) => {
+        if (p.includes(":")) {
+            const i = p.indexOf(":");
+            disallowedPin(p.slice(0, i), p.slice(i + 1), `prefer entry ${p}`);
+            return;
+        }
+        if (cfg.tiers[p]) {
+            const expanded = channelsFromConfig(p, cfg);
+            if (expanded.length && expanded.every((c) => disallowedBy(c, cfg.routing) !== null)) {
+                const d = disallowedBy(expanded[0], cfg.routing);
+                throw new RoutingError(`${task.id}: prefer entry ${p} is disallowed by routing.${d.by} (${d.entry}) — remove the ${d.by} entry or re-pin to an allowed channel`);
+            }
+            return;
+        }
+        const d = disallowedBy({ adapter: "", model: p }, cfg.routing);
+        if (d) {
+            throw new RoutingError(`${task.id}: prefer entry ${p} is disallowed by routing.${d.by} (${d.entry}) — remove the ${d.by} entry or re-pin to an allowed channel`);
+        }
+    };
+    const lintFloor = (tier, what) => {
+        if (floor && TIER_RANK[tier] < TIER_RANK[floor]) {
+            lints.push(`${task.id} (${task.shape}): ${what} routes ${tier}, below advisory floor ${floor}`);
+        }
+    };
+    const taskFloor = task.routingHints?.floor;
+    const source = task.routingHints?.source;
+    const src = source ? `, ${source}` : ""; // never interpolate a possibly-undefined source
+    // task pin: planner-authored, try-first — degrades on miss or below-floor (D-05, research A3), never throws
+    let degraded = "";
+    const taskPin = task.routingHints?.pin;
+    if (taskPin) {
+        disallowedPin(taskPin.via, taskPin.model, "task pin");
+        const c = channels.find((c) => c.adapter === taskPin.via && c.model === taskPin.model);
+        if (c && (!taskFloor || TIER_RANK[c.tier] >= TIER_RANK[taskFloor])) {
+            lintFloor(c.tier, "task pin");
+            return { assignment: toAssignment(c), ladder: ladderFor(task, entry), lints, provenance: `pin ${taskPin.via}:${taskPin.model} (task hint${src})` };
+        }
+        const why = c ? `below task floor ${taskFloor}` : "unavailable";
+        lints.push(`${task.id}: pinned ${taskPin.via}:${taskPin.model} ${why} — degrading to floor/auto (task hint${src})`);
+        degraded = `pin ${taskPin.via}:${taskPin.model} ${why} → `;
+    }
+    // map pin: operator-authored config — a miss stays fail-loud (D-05)
+    if (entry?.pin) {
+        disallowedPin(entry.pin.via, entry.pin.model, "map pin (config routing.map)");
+        const c = resolvePin(entry.pin, channels);
+        lintFloor(c.tier, "map pin");
+        return { assignment: toAssignment(c), ladder: ladderFor(task, entry), lints, provenance: `${degraded}pin ${entry.pin.via}:${entry.pin.model} (config routing.map)` };
+    }
+    const baseTier = entry?.tier ?? floor ?? "cheap";
+    const minTier = taskFloor && TIER_RANK[taskFloor] > TIER_RANK[baseTier] ? taskFloor : baseTier; // task floor is a hard >= constraint in all paths (D-04)
+    if (entry?.tier)
+        lintFloor(entry.tier, "map tier");
+    if (prefActive)
+        for (const p of entry?.prefer ?? [])
+            preflightPrefer(p);
+    // key order is a contract: prefer > marginal cost > tier (cheapest sufficient) > learned score (v1.6 ROUTE-06)
+    // > discovery order (same-tier fairness, D2). The learned score is the LAST key — it decides only the
+    // discovery-order tail, never a pin/floor/prefer/cost/tier boundary (they all sort above it, ROUTE-08).
+    const staticCmp = (a, b) => preferIndex(a, entry?.prefer) - preferIndex(b, entry?.prefer) || marginalCostRank(a) - marginalCostRank(b) || TIER_RANK[a.tier] - TIER_RANK[b.tier];
+    const eligibleRaw = channels.filter((c) => TIER_RANK[c.tier] >= TIER_RANK[minTier]);
+    if (!eligibleRaw.length) {
+        let msg = `${task.id}: no channel at tier>=${minTier}; available: ${channels.map(channelKey).join(", ") || "(none)"}`;
+        if (prefActive) {
+            const excluded = Object.keys(cfg.tiers).flatMap((id) => channelsFromConfig(id, cfg))
+                .filter((c) => disallowedBy(c, cfg.routing) !== null && TIER_RANK[c.tier] >= TIER_RANK[minTier])
+                .map(channelKey);
+            if (excluded.length)
+                msg += `; ${excluded.length} channel(s) excluded by routing.allow/deny: ${excluded.join(", ")}`;
+        }
+        throw new RoutingError(msg);
+    }
+    let eligible;
+    let deviation;
+    let learnedChosen = "";
+    if (profile) {
+        // scores precomputed ONCE over the eligible set — never inside the comparator (Pitfall 1).
+        // ponytail: no epsilon — two finite scores subtract to a finite number (Phase 12 totality); an
+        // epsilon would be intransitive. Upgrade path if warm cells ever tie near-exactly: quantize the score.
+        // PROF-04: cells are split by channel class, so pass c.channel explicitly (tsc-required). This map
+        // is keyed by channelKey alone, which would collide only if a fleet exposed the same adapter:model on
+        // both classes at once — impossible under today's scalar TierEntrySchema.channel.
+        // ROUTE-15: availWeight threads from config as a pure param; undefined ⇒ module default (byte-identical).
+        const scores = new Map(eligibleRaw.map((c) => [channelKey(c), learnedScore(profile, task.shape, channelKey(c), c.channel, { availWeight: cfg.routing.learnedTuning?.availWeight })]));
+        const scoreOf = (c) => scores.get(channelKey(c));
+        // v1.6 Phase 14: exploration bonus precomputed ONCE (Pitfall 5), a new key ABOVE the score. EXP-01 needs
+        // it above the score (a warm-good incumbent can't permanently outrank an under-cap rival in a static tie);
+        // magnitude-free as its own lexicographic key. EXP-02 holds structurally: pins returned at :67/:78 and the
+        // floor filtered eligibleRaw at :89, all upstream of this block, so the bonus decides only within a static tie.
+        const bonuses = new Map(eligibleRaw.map((c) => [channelKey(c), explorationBonus(cellOf(profile, task.shape, channelKey(c), c.channel))]));
+        const bonusOf = (c) => bonuses.get(channelKey(c));
+        const staticWinner = [...eligibleRaw].sort(staticCmp)[0];
+        // Phase 34 ROUTE-17: prefer becomes a BAND + group-rep keys so exploration fires ACROSS prefer
+        // entries, while intra-entry order (cost > tier > bonus > score) and every cold path stay byte-identical.
+        // Cold reduces to preferIndex || cost || tier ≡ staticCmp (proof P1); rep keys use the group HEAD so
+        // the probed group's budget self-extinguishes at EXPLORE_CAP (P4); flat lexicographic K is total (P5).
+        const prefer = entry?.prefer ?? [];
+        const groupCmp = (a, b) => marginalCostRank(a) - marginalCostRank(b) || TIER_RANK[a.tier] - TIER_RANK[b.tier] ||
+            bonusOf(b) - bonusOf(a) || scoreOf(b) - scoreOf(a);
+        const heads = new Map();
+        for (const c of [...eligibleRaw].sort(groupCmp)) {
+            const g = preferIndex(c, prefer);
+            if (!heads.has(g))
+                heads.set(g, c);
+        }
+        const keyOf = new Map(eligibleRaw.map((c) => {
+            const g = preferIndex(c, prefer);
+            const rep = heads.get(g);
+            return [channelKey(c), [g < prefer.length ? 0 : 1, -bonusOf(rep), -scoreOf(rep), g,
+                    marginalCostRank(c), TIER_RANK[c.tier], -bonusOf(c), -scoreOf(c)]];
+        }));
+        const kOf = (c) => keyOf.get(channelKey(c));
+        const firstDiff = (a, b) => kOf(a).findIndex((v, i) => v !== kOf(b)[i]);
+        eligible = [...eligibleRaw].sort((a, b) => { const i = firstDiff(a, b); return i === -1 ? 0 : kOf(a)[i] - kOf(b)[i]; });
+        const w = eligible[0];
+        const ru = channelKey(staticWinner) !== channelKey(w) ? staticWinner : eligible[1];
+        // Phase 34 ROUTE-17: first-differing-key markers — probe when a rep or intra bonus key decided.
+        const diffKey = ru ? firstDiff(w, ru) : -1;
+        const probe = diffKey === 1 || diffKey === 6;
+        if (probe) {
+            learnedChosen = `via exploration probe (dispatches=${cellOf(profile, task.shape, channelKey(w), w.channel)?.dispatches ?? 0} < ${EXPLORE_CAP})`;
+        }
+        else if (diffKey === 2 || diffKey === 7) {
+            const n = cellOf(profile, task.shape, channelKey(w), w.channel)?.n ?? 0;
+            learnedChosen = `via learned score ${scoreOf(w).toFixed(3)} (n=${n}) over ${channelKey(ru)} ${scoreOf(ru).toFixed(3)}`;
+        }
+        if (channelKey(staticWinner) !== channelKey(w)) {
+            deviation = { static: channelKey(staticWinner), chosen: channelKey(w), score: scoreOf(w), staticScore: scoreOf(staticWinner), n: cellOf(profile, task.shape, channelKey(w), w.channel)?.n ?? 0, ...(probe ? { explore: true } : {}) };
+        }
+    }
+    else {
+        eligible = eligibleRaw.sort(staticCmp); // ROUTE-07/09: literally the v1.5 code path — dead code cannot deviate
+    }
+    const bound = taskFloor && TIER_RANK[taskFloor] >= TIER_RANK[baseTier] ? `floor ${taskFloor} (task hint${src})` :
+        entry?.tier ? `tier ${entry.tier} (config routing.map)` :
+            floor ? `floor ${floor} (config floors)` :
+                "tier cheap (default)";
+    // name the key that actually broke the tie: prefer outranks the marginal-cost/tier keys, so if the
+    // winner matched a prefer entry, prefer decided it — not "cheapest sufficient tier" (ROUTE-03, WR-01)
+    const chosenBy = learnedChosen || (entry?.prefer && preferIndex(eligible[0], entry.prefer) < entry.prefer.length
+        ? "via prefer" : "cheapest sufficient tier");
+    return { assignment: toAssignment(eligible[0]), ladder: ladderFor(task, entry), lints, provenance: `${degraded}${bound}, marginal-cost auto (${chosenBy})`, ...(deviation ? { deviation } : {}) };
+}
+export function nextChannel(current, task, cfg, channels, tried, profile) {
+    // already cheapest-sufficient: TIER_RANK asc is the PRIMARY key so escalation climbs one band at a time.
+    // Do NOT "unify" this onto route()'s key order (marginal-cost first) — that reverses climb-one-band on mixed fleets (ROUTE-02, D2).
+    // ROUTE-13: learnedScore is the STRICTLY-LAST key — within-band tiebreak only. Precomputed
+    // outside the comparator (Pitfall 1), never arithmetic-combined with the band keys, no
+    // profile-dependent filter. NO exploration bonus here (route():110 has one; a probe on the
+    // failure path would spend a real retry). Absent profile ⇒ every score is 0 ⇒ third key
+    // all-ties ⇒ the stable sort preserves the exact v1.7 candidate ORDER.
+    const pool = channels.filter((c) => !tried.includes(channelKey(c)) && TIER_RANK[c.tier] >= TIER_RANK[current.tier]);
+    const scores = new Map(pool.map((c) => [channelKey(c), profile ? learnedScore(profile, task.shape, channelKey(c), c.channel, { availWeight: cfg.routing.learnedTuning?.availWeight }) : 0]));
+    const scoreOf = (c) => scores.get(channelKey(c));
+    const candidates = pool.sort((a, b) => TIER_RANK[a.tier] - TIER_RANK[b.tier] || marginalCostRank(a) - marginalCostRank(b) || scoreOf(b) - scoreOf(a));
+    return candidates.length ? toAssignment(candidates[0]) : null;
+}

package/dist/run/consult.d.ts

@@ -0,0 +1,23 @@
+import type { WorkerAdapter } from "../adapters/types.js";
+import type { DrovrConfig } from "../config/config.js";
+import type { ExecutorDriver, Slot } from "../drivers/types.js";
+import type { GateResult } from "../gates/types.js";
+export interface ConsultVerdict {
+    action: "retry" | "reroute" | "decompose" | "human";
+    notes: string;
+    excludeAdapter?: string;
+}
+export interface Dossier {
+    taskId: string;
+    trigger: string;
+    journalTail: string;
+    transcript: string;
+    diff: string;
+    gates: GateResult[];
+}
+export declare function buildDossierPrompt(d: Dossier): string;
+export declare function consult(d: Dossier, cfg: DrovrConfig, adapters: WorkerAdapter[], driver: ExecutorDriver, cwd: string, runDir: string, opts?: {
+    keep?: boolean;
+    onSlot?: (slot: Slot) => void;
+    runId?: string;
+}): Promise<ConsultVerdict>;

package/dist/run/consult.js

@@ -0,0 +1,80 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAdapter } from "../adapters/registry.js";
+import { extractJson, gatePaneName } from "../gates/llm.js";
+import { sh } from "./git.js";
+const ACTIONS = ["retry", "reroute", "decompose", "human"];
+export function buildDossierPrompt(d) {
+    return `DROVR-CONSULT
+You are a senior engineering consult for the drovr orchestrator. A worker task hit trouble.
+Read the dossier and return a verdict. Be decisive; cost is the lowest priority, quality the highest.
+
+## Task: ${d.taskId} — trigger: ${d.trigger}
+
+## Gate results
+${d.gates.map((g) => `- [${g.pass ? "pass" : "FAIL"}] ${g.gate}: ${g.details}`).join("\n") || "(none)"}
+
+## Failure context / diff
+${d.diff || "(none)"}
+
+## Worker transcript (tail)
+${d.transcript || "(none)"}
+
+## Journal (recent events)
+${d.journalTail}
+
+Verdict meanings: retry = same assignment with your notes as feedback; reroute = different CLI/model;
+decompose = task too big, needs human re-planning; human = a person must look at this.
+
+On reroute only, optional excludeAdapter is an adapter id (e.g. "cursor-agent") that bans EVERY
+channel of that adapter for this task. Use it for environmental failures ("the CLI is blocked",
+trust dialog, broken install) — not when a single model produced bad code. Omit for model-level
+reroutes so other models of the same adapter remain eligible.
+
+Respond with ONLY this JSON:
+{"action": "retry" | "reroute" | "decompose" | "human", "notes": "one short paragraph of guidance", "excludeAdapter"?: "<adapter-id>"}
+`;
+}
+let consultSeq = 0;
+export async function consult(d, cfg, adapters, driver, cwd, runDir, 
+// T2 ownership contract: runId names the consult pane canonically (drovr:consult:<task>:0:<runId>)
+// via SlotOpts.owned; without it the legacy gatePaneName shape survives (non-daemon callers/tests).
+opts = {}) {
+    const n = ++consultSeq;
+    const dir = join(runDir, "consults");
+    mkdirSync(dir, { recursive: true });
+    const promptFile = join(dir, `${d.taskId}-${n}.md`);
+    writeFileSync(promptFile, buildDossierPrompt(d));
+    const adapter = getAdapter(cfg.consult.adapter, adapters);
+    let out;
+    if (cfg.visibility.llm === "headless") {
+        const r = await sh(adapter.headlessCommand(promptFile, cfg.consult.model), cwd, cfg.consult.stallMinutes * 60_000);
+        out = r.stdout + r.stderr;
+    }
+    else {
+        // T8: role-first pane name for fleet visibility (consult · T2); consultSeq stays on the dossier artifact only
+        const slot = await driver.slot(cwd, gatePaneName("consult", d.taskId), {
+            label: `CONSULT ${d.taskId}`,
+            ...(opts.runId ? { owned: { role: "consult", taskId: d.taskId, attempt: 0, runId: opts.runId } } : {}),
+        });
+        opts.onSlot?.(slot);
+        await driver.run(slot, `${adapter.headlessCommand(promptFile, cfg.consult.model)}; printf '\\nDROVR_''EXIT:%s\\n' $?`);
+        // digit-suffixed marker only: a dossier quoting drovr's own "DROVR_EXIT:" literal must not
+        // false-complete the consult pane before its verdict (same guard as daemon.ts:193 / llm.ts).
+        await driver.waitOutput(slot, "DROVR_EXIT:\\d", cfg.consult.stallMinutes * 60_000, { regex: true });
+        out = await driver.read(slot, 300);
+        if (!opts.keep)
+            await driver.close(slot);
+    }
+    const v = extractJson(out);
+    if (!v || !ACTIONS.includes(v.action)) {
+        return { action: "human", notes: "consult verdict unparseable — failing safe to human" };
+    }
+    // fail-closed exclusion: only a non-empty string survives. Malformed values (number/array/object/
+    // empty) are dropped — the verdict stays a normal channel-level reroute/retry/…, never a crash
+    // and never silently forced to human. Unknown adapter ids pass through; the daemon treats a
+    // zero-match expansion as channel-level reroute.
+    const raw = v.excludeAdapter;
+    const excludeAdapter = typeof raw === "string" && raw.length > 0 ? raw : undefined;
+    return { action: v.action, notes: String(v.notes ?? ""), ...(excludeAdapter ? { excludeAdapter } : {}) };
+}

package/dist/run/daemon.d.ts

@@ -0,0 +1,23 @@
+import { type WorkerAdapter } from "../adapters/types.js";
+import { type ExecutorDriver } from "../drivers/types.js";
+import { type JournalEvent } from "./journal.js";
+export interface RunOptions {
+    runId?: string;
+    resume?: boolean;
+    concurrency?: number;
+    driver?: ExecutorDriver;
+    adapters?: WorkerAdapter[];
+    globalDir?: string;
+    narrate?: (event: JournalEvent) => void;
+}
+export interface RunSummary {
+    runId: string;
+    branch: string;
+    done: string[];
+    failed: string[];
+    human: string[];
+    pending: string[];
+    blocked: string[];
+}
+export declare function formatSummary(s: RunSummary): string;
+export declare function runDaemon(repoRoot: string, opts?: RunOptions): Promise<RunSummary>;