tickmarkr 1.85.0 → 1.86.0

package/dist/adapters/registry.d.ts

@@ -1,9 +1,9 @@
 import { type TickmarkrConfig } from "../config/config.js";
-import { type RoutingProfile } from "../route/profile.js";
+import { type CatalogEntriesOptions, type CliEntry } from "./catalog.js";
 import { type AuthHealth, type BillingChannel, type WorkerAdapter } from "./types.js";
-export declare const CANDIDATE_CLI_CATALOG: readonly ["kimi", "gemini", "qwen", "aider", "goose", "amp", "droid", "auggie", "crush"];
-export declare const REGISTERED_ADAPTER_BINARIES: readonly ["claude", "codex", "cursor-agent", "opencode", "pi", "grok"];
-export declare function resolveShellBinary(bin: string, cwd?: string): {
+export declare const CANDIDATE_CLI_CATALOG: readonly string[];
+export declare function registeredAdapterBinaries(adapters?: WorkerAdapter[]): string[];
+export declare function resolveShellBinary(bin: string, cwd?: string, pathEnv?: string): {
     resolved?: string;
     all: string[];
 };
@@ -27,40 +27,39 @@ export declare function modelAliasLine(excluded: {
 }[]): string;
 export type CandidateCliDetection = {
     binary: string;
-    version: string | undefined;
+    path: string;
 };
-export declare function probeCandidateVersion(bin: string): string | undefined;
-export declare function detectCandidateClis(opts?: {
+export declare function parseHerdrCliNames(help: string): string[];
+export declare function herdrNominatedCliNames(cwd?: string, pathEnv?: string): string[];
+export interface DetectCandidateCliOptions extends CatalogEntriesOptions {
+    cwd?: string;
     pathEnv?: string;
-}): CandidateCliDetection[];
-export declare function formatCandidateCliRow({ binary, version }: CandidateCliDetection): string;
+    entries?: readonly CliEntry[];
+    adapters?: WorkerAdapter[];
+    resolveBinary?: (binary: string) => {
+        resolved?: string;
+        all: string[];
+    };
+}
+export declare function detectCandidateClis(opts?: DetectCandidateCliOptions): CandidateCliDetection[];
+export declare function formatCandidateCliRow({ binary, path }: CandidateCliDetection): string;
 export declare function probeHelpText(bin: string): string | undefined;
 export declare function missingDeclaredFlags(helpText: string, flags: string[]): string[];
 export declare function flagDriftWarnings(adapters: WorkerAdapter[], health: Record<string, AuthHealth>, helpOf?: (bin: string) => string | undefined): string[];
-export declare function allAdapters(opts?: {
+export declare function adaptersFromCliEntries(entries: readonly CliEntry[]): WorkerAdapter[];
+export interface AllAdaptersOptions {
     fakeScriptPath?: string;
-}): WorkerAdapter[];
+    cliEntries?: readonly CliEntry[];
+    operatorYaml?: string | null;
+    operatorPath?: string | false;
+}
+export declare function allAdapters(opts?: AllAdaptersOptions): WorkerAdapter[];
 export declare function getAdapter(id: string, adapters: WorkerAdapter[]): WorkerAdapter;
 export declare function probeAll(adapters: WorkerAdapter[], opts?: {
     cwd?: string;
 }): Promise<Record<string, AuthHealth>>;
 export type ProbeModelStatus = "ok" | "timeout" | "failed";
 export type ProbeModelProgress = (adapter: string, model: string, status: ProbeModelStatus, durationMs: number) => void;
-export interface AutoPreferDoc {
-    derivedAt: string;
-    [shape: string]: string[] | string;
-}
-export declare const pendingAutoPreferKey: unique symbol;
-export declare const DOCTOR_ROUTING_STALE_MS: number;
-export declare function deriveAutoPrefer(cfg: TickmarkrConfig, adapters: WorkerAdapter[], health: Record<string, AuthHealth>, profile?: RoutingProfile): AutoPreferDoc;
-export declare function readAutoPrefer(repoRoot: string): AutoPreferDoc | null;
-export declare function routingPreferContext(repoRoot: string, cfg: TickmarkrConfig, opts?: {
-    globalDir?: string;
-}): {
-    autoPrefer?: AutoPreferDoc;
-    doctorFresh: boolean;
-    overlayPreferShapes: ReadonlySet<string>;
-};
 export declare function probeModels(cfg: TickmarkrConfig, repoRoot: string, adapters: WorkerAdapter[], health: Record<string, AuthHealth>, onProgress?: ProbeModelProgress): Promise<void>;
 export declare function writeDoctor(repoRoot: string, health: Record<string, AuthHealth>): void;
 export declare function readDoctor(repoRoot: string): Record<string, AuthHealth> | null;

package/dist/adapters/registry.js

@@ -1,29 +1,33 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdtempSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { overlayPreferShapes, TIER_RANK } from "../config/config.js";
 import { modelLints, suggestOverlay } from "./model-lints.js";
 import { HerdrDriver } from "../drivers/herdr.js";
 import { tickmarkrDir, stateDirName } from "../graph/graph.js";
 import { disallowedBy, excludedChannels, exclusionLine, preferRanks } from "../route/preference.js";
-import { learnedScore } from "../route/profile.js";
-import { marginalCostRank } from "../route/router.js";
 import { sh } from "../run/git.js";
-import { claudeCode } from "./claude-code.js";
-import { codex } from "./codex.js";
-import { cursorAgent } from "./cursor-agent.js";
 import { FakeAdapter } from "./fake.js";
-import { grok } from "./grok.js";
-import { kimi } from "./kimi.js";
-import { opencode } from "./opencode.js";
-import { pi } from "./pi.js";
+import { parseWorkerResult } from "./prompt.js";
 import { sealHerdrEnv } from "../drivers/subprocess.js";
-import { channelKey, modelAuthed, QUOTA_RE, shq } from "./types.js";
-// Agent-CLI binary names with no tickmarkr adapter — doctor sweeps these advisory-only (v1.48 T1).
-export const CANDIDATE_CLI_CATALOG = ["kimi", "gemini", "qwen", "aider", "goose", "amp", "droid", "auggie", "crush"];
-// Binaries probed by registered adapters — kept beside the catalog so a test can forbid overlap.
-export const REGISTERED_ADAPTER_BINARIES = ["claude", "codex", "cursor-agent", "opencode", "pi", "grok"];
+import { catalogEntries, isNativeCliDrive, projectCliEntries, SHIPPED_CLI_CATALOG, } from "./catalog.js";
+import { channelKey, channelsFromConfig, modelAuthed, MODEL_ID_RE, QUOTA_RE, shq, } from "./types.js";
+// Compatibility projection for callers/tests that only need shipped advisory names. The literal
+// list is gone: both advisory and routable catalog views derive from SHIPPED_CLI_CATALOG. Native
+// definitions (claudeCode, codex, cursorAgent, opencode, pi, grok, kimi) are owned by catalog.ts;
+// this registry consumes their drive contracts instead of restating their registration order.
+export const CANDIDATE_CLI_CATALOG = SHIPPED_CLI_CATALOG
+    .filter((entry) => entry.drive === undefined)
+    .map((entry) => entry.binary);
+const SHIPPED_NATIVE_ADAPTERS = new Set(SHIPPED_CLI_CATALOG.flatMap((entry) => isNativeCliDrive(entry.drive) ? [entry.drive.adapter] : []));
+const declarativeBinaries = new WeakMap();
+// OBS-304: this was a hand-maintained mirror of the registered binaries, and the guard test that
+// forbids catalog overlap checked against IT rather than against the adapters — so when kimi gained
+// an adapter and nobody updated the copy, the guard kept passing on a collision it existed to catch.
+// Derive it. A list that restates another list is the defect, not the entry that fell out of sync.
+export function registeredAdapterBinaries(adapters = allAdapters()) {
+    return adapters.map((a) => a.hardcodedFlags?.binary ?? declarativeBinaries.get(a)).filter((b) => !!b);
+}
 // OBS-117: worker panes run commands through `bash -lc` (SubprocessDriver + sh()), not bare spawnSync(bin).
 // Doctor must resolve adapter binaries the same way so a shadow install on PATH cannot disagree with dispatch.
 function shellSpawnSync(cmd, cwd, timeoutMs = 10000) {
@@ -36,9 +40,24 @@ function shellSpawnSync(cmd, cwd, timeoutMs = 10000) {
     });
     return { code: r.status ?? 1, stdout: (r.stdout || "").trim(), stderr: (r.stderr || "").trim() };
 }
-export function resolveShellBinary(bin, cwd = process.cwd()) {
-    const r = shellSpawnSync(`type -a ${shq(bin)} 2>/dev/null | sed -n 's/^.* is \\(.*\\)$/\\1/p'`, cwd);
-    const all = r.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+export function resolveShellBinary(bin, cwd = process.cwd(), pathEnv) {
+    // An explicit PATH is a deterministic fixture/operator boundary. The default remains the same
+    // login-shell environment used by dispatched workers (OBS-117).
+    const pathPrefix = pathEnv === undefined ? "" : `export PATH=${shq(pathEnv)}; `;
+    const r = shellSpawnSync(`${pathPrefix}type -a ${shq(bin)} 2>/dev/null | sed -n 's/^.* is \\(.*\\)$/\\1/p'`, cwd);
+    const hits = r.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+    // OBS-304: a duplicated PATH entry makes `type -a` emit the SAME path twice, which doctor then
+    // reported as "2 installs on PATH — …/claude, …/claude". Count distinct real files, so the real
+    // shadows (codex: homebrew + nvm) stop being buried in noise. realpath resolves symlinked twins.
+    const seen = new Set();
+    const all = hits.filter((p) => {
+        let key = p;
+        try {
+            key = realpathSync(p);
+        }
+        catch { /* unreadable or dangling — fall back to the literal path */ }
+        return seen.has(key) ? false : (seen.add(key), true);
+    });
     return { resolved: all[0], all };
 }
 export function probeVersionShell(bin, cwd = process.cwd()) {
@@ -101,39 +120,47 @@ export function modelAliasLine(excluded) {
     const parts = excluded.map(({ key, adapter }) => `${key} (not in ${adapter}'s reported model list)`);
     return `model alias: ${excluded.length} channel(s) invalid — ${parts.join(", ")}`;
 }
-function candidateOnPath(bin, pathEnv) {
-    const r = spawnSync("which", [bin], { encoding: "utf8", env: { ...process.env, PATH: pathEnv } });
-    return r.status === 0 && r.stdout.trim().length > 0;
+// Herdr's supported-kind help is nomination data only. Parse the closed token list and discard
+// everything else before any name can reach a shell resolver.
+export function parseHerdrCliNames(help) {
+    const body = /\[possible values:\s*([^\]]+)\]/m.exec(help)?.[1] ?? "";
+    return [...new Set(body.split(",").map((name) => name.trim()).filter((name) => /^[a-z0-9-]+$/.test(name)))];
 }
-// Fail open: a broken candidate binary never throws and never fails doctor.
-export function probeCandidateVersion(bin) {
-    try {
-        const r = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 10000 });
-        if (r.error || r.status !== 0)
-            return undefined;
-        return (r.stdout || r.stderr).trim().split("\n")[0];
-    }
-    catch {
-        return undefined;
-    }
+export function herdrNominatedCliNames(cwd = process.cwd(), pathEnv) {
+    // This asks a known driver binary for static help. It is deliberately NOT gated on
+    // HerdrDriver.available(), which reports HERDR_ENV rather than binary presence.
+    const { resolved } = resolveShellBinary("herdr", cwd, pathEnv);
+    if (!resolved)
+        return [];
+    const r = shellSpawnSync(`${shq(resolved)} agent start --help`, cwd);
+    return r.code === 0 ? parseHerdrCliNames(`${r.stdout}\n${r.stderr}`) : [];
 }
 export function detectCandidateClis(opts = {}) {
-    const pathEnv = opts.pathEnv ?? process.env.PATH ?? "";
-    const out = [];
-    for (const bin of CANDIDATE_CLI_CATALOG) {
-        if (!candidateOnPath(bin, pathEnv))
-            continue;
-        out.push({ binary: bin, version: probeCandidateVersion(bin) });
+    const cwd = opts.cwd ?? process.cwd();
+    const entries = opts.entries ?? catalogEntries({
+        shipped: opts.shipped,
+        operatorYaml: opts.operatorYaml,
+        operatorPath: opts.operatorPath,
+        herdrNames: opts.herdrNames ?? herdrNominatedCliNames(cwd, opts.pathEnv),
+    });
+    const registered = new Set(registeredAdapterBinaries(opts.adapters ?? allAdapters({ cliEntries: entries })));
+    const advisory = projectCliEntries(entries).advisory.filter((entry) => !registered.has(entry.binary));
+    const resolveBinary = opts.resolveBinary
+        ?? ((binary) => resolveShellBinary(binary, cwd, opts.pathEnv));
+    const discovered = [];
+    for (const entry of advisory) {
+        const { resolved } = resolveBinary(entry.binary);
+        if (resolved)
+            discovered.push({ binary: entry.binary, path: resolved });
     }
-    return out;
+    return discovered;
 }
-export function formatCandidateCliRow({ binary, version }) {
-    const ver = version ?? "version unknown";
-    return `  ! ${binary.padEnd(14)} detected: ${ver} (no tickmarkr adapter — not routable)`;
+export function formatCandidateCliRow({ binary, path }) {
+    return `  ! ${binary.padEnd(14)} detected at ${path} (no drive contract — not routable)`;
 }
-// v1.65 T3: same guarded spawn pattern as probeCandidateVersion — bounded, error/status-checked,
-// fail-open. undefined = binary unavailable/broken ⇒ no drift verdict (the existing auth reporting
-// already names an uninstalled CLI; drift must never pile on).
+// v1.65 T3: bounded, error/status-checked and fail-open. Unlike candidate detection above, this
+// executes only registered adapter binaries with drive contracts. undefined = unavailable/broken,
+// so no drift verdict piles onto the existing auth report.
 export function probeHelpText(bin) {
     try {
         const r = spawnSync(bin, ["--help"], { encoding: "utf8", timeout: 10000 });
@@ -169,11 +196,103 @@ export function flagDriftWarnings(adapters, health, helpOf = probeHelpText) {
     }
     return out;
 }
+function renderDriveTemplate(template, promptFile, model) {
+    return template.replaceAll("{promptFile}", shq(promptFile)).replaceAll("{model}", shq(model));
+}
+function valueAtPath(value, path) {
+    if (!path)
+        return value;
+    return path.split(".").reduce((cursor, part) => {
+        if (!cursor || typeof cursor !== "object")
+            return undefined;
+        return cursor[part];
+    }, value);
+}
+function parseDeclaredModels(raw, parser, path) {
+    let values;
+    if (parser === "json") {
+        try {
+            const selected = valueAtPath(JSON.parse(raw), path);
+            values = Array.isArray(selected) ? selected : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    else if (parser === "pi-table") {
+        const lines = raw.trim().split("\n");
+        const header = lines.findIndex((line) => /^provider\s+model\b/i.test(line.trim()));
+        values = header === -1 ? [] : lines.slice(header + 1).map((line) => {
+            const [provider, model] = line.trim().split(/\s+/);
+            return provider && model ? `${provider}/${model}` : "";
+        });
+    }
+    else {
+        values = raw.split("\n").map((line) => line.trim());
+    }
+    return [...new Set(values.filter((value) => typeof value === "string" && MODEL_ID_RE.test(value)))];
+}
+function declarativeAdapter(entry) {
+    const drive = entry.drive;
+    const adapter = {
+        id: entry.id,
+        vendor: entry.vendor,
+        probe: async () => {
+            const health = probeVersionShell(entry.binary);
+            if (!health.installed)
+                return health;
+            const version = health.version ?? "";
+            if (!new RegExp(entry.identity).test(version)) {
+                return {
+                    installed: true,
+                    authed: false,
+                    version,
+                    models: [],
+                    note: `identity mismatch for ${entry.binary}`,
+                    binaryPaths: health.binaryPaths,
+                };
+            }
+            return health;
+        },
+        channels: (cfg) => channelsFromConfig(entry.id, cfg),
+        headlessCommand: (promptFile, model) => renderDriveTemplate(drive.headless, promptFile, model),
+        interactiveCommand: (promptFile, model) => drive.interactive === null
+            ? null
+            : renderDriveTemplate(drive.interactive, promptFile, model),
+        invoke(_task, _cwd, assignment, ctx) {
+            return { command: this.headlessCommand(ctx.promptFile, assignment.model) };
+        },
+        parse: parseWorkerResult,
+        ...(drive.listModels ? {
+            listModels: async () => {
+                const { resolved } = resolveShellBinary(entry.binary);
+                if (!resolved)
+                    return [];
+                const cmd = [shq(resolved), ...drive.listModels.argv.map(shq)].join(" ");
+                const result = shellSpawnSync(cmd, process.cwd(), 15000);
+                return result.code === 0
+                    ? parseDeclaredModels(result.stdout, drive.listModels.parser, drive.listModels.path)
+                    : [];
+            },
+        } : {}),
+    };
+    declarativeBinaries.set(adapter, entry.binary);
+    return adapter;
+}
+export function adaptersFromCliEntries(entries) {
+    return projectCliEntries(entries).routable.map((entry) => {
+        if (isNativeCliDrive(entry.drive))
+            return entry.drive.adapter;
+        return declarativeAdapter(entry);
+    });
+}
 export function allAdapters(opts = {}) {
-    // pi + grok + kimi appended LAST: same-tier ties resolve by discovery order (Phase 6 D2), so
-    // appending keeps the Phase 6 shape→channel matrix byte-identical; inserting anywhere else
-    // silently reassigns shapes on same-tier ties. kimi is appended AFTER grok for the same reason.
-    const real = [claudeCode, codex, cursorAgent, opencode, pi, grok, kimi];
+    const entries = opts.cliEntries ?? catalogEntries({
+        operatorYaml: opts.operatorYaml,
+        operatorPath: opts.operatorPath,
+        herdrNames: [],
+    });
+    const real = adaptersFromCliEntries(entries);
     const fakePath = opts.fakeScriptPath ?? process.env.TICKMARKR_FAKE_SCRIPT;
     return fakePath ? [new FakeAdapter(fakePath), ...real] : real;
 }
@@ -233,58 +352,6 @@ function probeFailure(code, stdout, stderr, timedOut, timeoutMs = MODEL_PROBE_TI
         ? reasonTail(output) || `probe exited ${code}`
         : undefined;
 }
-export const pendingAutoPreferKey = Symbol.for("tickmarkr.pendingAutoPrefer");
-const median = (xs) => {
-    const s = [...xs].sort((a, b) => a - b);
-    const m = Math.floor(s.length / 2);
-    return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
-};
-// ponytail: 24h TTL matches plan.ts staleness — promote to config when an operator asks.
-export const DOCTOR_ROUTING_STALE_MS = 24 * 60 * 60 * 1000;
-export function deriveAutoPrefer(cfg, adapters, health, profile) {
-    const derivedAt = new Date().toISOString();
-    const out = { derivedAt };
-    // v1.52 T5: routing.floors is the only band authority — a map entry can no longer carry a tier.
-    for (const shape of Object.keys(cfg.routing.map)) {
-        const minTier = cfg.routing.floors[shape] ?? "cheap";
-        const ranked = [];
-        for (const a of adapters) {
-            const h = health[a.id];
-            if (!h?.installed || !h?.authed || typeof a.channels !== "function")
-                continue;
-            const qualifying = a.channels(cfg).filter((c) => TIER_RANK[c.tier] >= TIER_RANK[minTier] && h.modelAuth?.[c.model]?.authed === true);
-            if (!qualifying.length)
-                continue;
-            const durations = qualifying
-                .map((c) => h.modelAuth?.[c.model]?.durationMs)
-                .filter((d) => typeof d === "number");
-            ranked.push({
-                adapter: a.id,
-                mc: Math.min(...qualifying.map(marginalCostRank)),
-                dur: durations.length ? median(durations) : Number.POSITIVE_INFINITY,
-                learned: profile ? Math.max(...qualifying.map((c) => learnedScore(profile, shape, channelKey(c), c.channel))) : 0,
-            });
-        }
-        ranked.sort((a, b) => a.mc - b.mc || a.dur - b.dur || b.learned - a.learned);
-        out[shape] = ranked.map((r) => r.adapter);
-    }
-    return out;
-}
-export function readAutoPrefer(repoRoot) {
-    const raw = readDoctorFile(repoRoot);
-    if (!raw || typeof raw.autoPrefer !== "object" || raw.autoPrefer === null)
-        return null;
-    return raw.autoPrefer;
-}
-export function routingPreferContext(repoRoot, cfg, opts = {}) {
-    const age = doctorAgeMs(repoRoot);
-    const doctorFresh = age !== null && age <= DOCTOR_ROUTING_STALE_MS;
-    return {
-        autoPrefer: doctorFresh ? readAutoPrefer(repoRoot) ?? undefined : undefined,
-        doctorFresh,
-        overlayPreferShapes: overlayPreferShapes(repoRoot, opts),
-    };
-}
 const probeModelStatus = (v) => v.authed ? "ok" : v.reason?.includes("timed out") ? "timeout" : "failed";
 // v1.21: one bounded, headless call per configured model; detected-but-unclassified models never enter this loop.
 export async function probeModels(cfg, repoRoot, adapters, health, onProgress) {
@@ -296,7 +363,7 @@ export async function probeModels(cfg, repoRoot, adapters, health, onProgress) {
         if (!h?.installed)
             return;
         // Tests inject FakeAdapter; never let an incidental default adapter spend a real token in the suite.
-        if (process.env.VITEST && [claudeCode, codex, cursorAgent, opencode, pi, grok, kimi].includes(a))
+        if (process.env.VITEST && SHIPPED_NATIVE_ADAPTERS.has(a))
             return;
         const verdicts = {};
         const priorModelAuth = priorHealth?.[a.id]?.modelAuth;
@@ -360,7 +427,6 @@ export async function probeModels(cfg, repoRoot, adapters, health, onProgress) {
         }
         h.modelAuth = verdicts;
     }));
-    health[pendingAutoPreferKey] = deriveAutoPrefer(cfg, adapters, health);
 }
 // T2: caps concurrent probes per adapter at 2 — v1.33.5 regression, 4 concurrent codex exec in one
 // repo made ALL 4 time out where sequential passed 2/4 (suspected CLI self-contention).
@@ -388,20 +454,17 @@ function readDoctorFile(repoRoot) {
 }
 export function writeDoctor(repoRoot, health) {
     tickmarkrDir(repoRoot);
-    const pending = health[pendingAutoPreferKey];
-    const payload = { ...health };
-    delete payload[pendingAutoPreferKey];
-    if (pending)
-        payload.autoPrefer = pending;
     const path = doctorPath(repoRoot);
     const tmp = `${path}.tmp`;
-    writeFileSync(tmp, JSON.stringify(payload, null, 2) + "\n");
+    writeFileSync(tmp, JSON.stringify(health, null, 2) + "\n");
     renameSync(tmp, path);
 }
 export function readDoctor(repoRoot) {
     const raw = readDoctorFile(repoRoot);
     if (!raw)
         return null;
+    // pre-v1.86 caches may still carry an `autoPrefer` key — strip it; the mechanism is deleted and
+    // the key is never read back into health.
     const { autoPrefer: _, ...health } = raw;
     return health;
 }

package/dist/adapters/types.js

@@ -70,9 +70,21 @@ export function channelsFromConfig(adapterId, cfg) {
     const e = cfg.tiers[adapterId];
     if (!e)
         return [];
-    return Object.entries(e.models).map(([model, tier]) => ({
-        adapter: adapterId, vendor: e.vendor, model, channel: e.channel, tier,
-    }));
+    return Object.entries(e.models).flatMap(([model, tier]) => {
+        const override = e.modelOverrides?.[model];
+        const vendor = override?.vendor ?? e.vendor;
+        // Parsed configs guarantee this only occurs for invalid data, but direct callers must fail closed
+        // too: an undeclared vendor is not review diversity and provider prefixes are never provenance.
+        if (!vendor?.trim())
+            return [];
+        return [{
+                adapter: adapterId,
+                vendor,
+                model,
+                channel: override?.channel ?? e.channel,
+                tier,
+            }];
+    });
 }
 export function channelKey(c) {
     return `${c.adapter}:${c.model}`;

package/dist/brand.d.ts

@@ -16,7 +16,11 @@ export declare function bannerShell(): string;
 export declare const TICKMARKR_EXIT_TRAILER = "printf '\\nTICKMARKR_''EXIT:%s\\n' $?";
 /** OBS-50: visible-pane bootstrap script — banner + agent command + byte-identical exit trailer. */
 export declare function paneDispatchScript(body: string[]): string;
-/** OBS-50: one short herdr pane-run line; bootstrap lives in the script file beside the prompt. */
+/** Record that the command being passed directly to ExecutorDriver.run is a daemon-built launch. */
+export declare function paneLaunchCommand(command: string): string;
+/** Driver-side half of paneLaunchCommand's one-shot handoff. */
+export declare function consumePaneLaunchIntent(): boolean;
+/** OBS-50/342: one short, intent-bearing pane-run line; bootstrap lives beside the prompt. */
 export declare function paneDispatchCommand(scriptPath: string): string;
 /** The settled brand green ramp (256-color), bright → deep. */
 export declare const BRAND_RAMP: readonly [84, 78, 41, 35];

package/dist/brand.js

@@ -78,9 +78,25 @@ export const TICKMARKR_EXIT_TRAILER = `printf '\\nTICKMARKR_''EXIT:%s\\n' $?`;
 export function paneDispatchScript(body) {
     return ["export BASH_SILENCE_DEPRECATION_WARNING=1", ...body, TICKMARKR_EXIT_TRAILER].join("\n");
 }
-/** OBS-50: one short herdr pane-run line; bootstrap lives in the script file beside the prompt. */
+const pendingPaneLaunchIntents = [];
+/** Record that the command being passed directly to ExecutorDriver.run is a daemon-built launch. */
+export function paneLaunchCommand(command) {
+    const intent = { kind: "launch" };
+    pendingPaneLaunchIntents.push(intent);
+    queueMicrotask(() => {
+        const index = pendingPaneLaunchIntents.indexOf(intent);
+        if (index >= 0)
+            pendingPaneLaunchIntents.splice(index, 1);
+    });
+    return command;
+}
+/** Driver-side half of paneLaunchCommand's one-shot handoff. */
+export function consumePaneLaunchIntent() {
+    return pendingPaneLaunchIntents.shift()?.kind === "launch";
+}
+/** OBS-50/342: one short, intent-bearing pane-run line; bootstrap lives beside the prompt. */
 export function paneDispatchCommand(scriptPath) {
-    return `bash ${shq(scriptPath)}`;
+    return paneLaunchCommand(`bash ${shq(scriptPath)}`);
 }
 // ── design system (v1.50) ── contract: docs/codebase/CLI-DESIGN.md ──────────
 // Every cockpit surface styles through these tokens/glyphs/helpers. Styled only

package/dist/cli/commands/doctor.d.ts

@@ -1,9 +1,12 @@
 import { type ClaudeAlias } from "../../adapters/claude-code.js";
 import type { WorkerAdapter } from "../../adapters/types.js";
 import { type KimiDoctorTurnResult } from "../../adapters/kimi.js";
+import { type CatalogReadResult } from "../../adapters/catalog-remote.js";
 export type DoctorOpts = {
     banner?: boolean;
     kimiTurnProbe?: (cwd: string) => Promise<KimiDoctorTurnResult>;
     resolveClaudeAliasIdentity?: (cwd: string, alias: ClaudeAlias) => string | undefined;
+    catalog?: CatalogReadResult;
+    catalogNow?: () => Date;
 };
 export declare function doctor(_argv: string[], cwd?: string, adapters?: WorkerAdapter[], opts?: DoctorOpts): Promise<string>;

package/dist/cli/commands/doctor.js

@@ -1,19 +1,29 @@
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { allAdapters, binaryShadowWarnings, detectCandidateClis, flagDriftWarnings, modelAliasExclusions, modelAliasLine, probeAll, probeModels, readAutoPrefer, servableExclusions, servabilityLine, writeDoctor } from "../../adapters/registry.js";
+import { allAdapters, binaryShadowWarnings, detectCandidateClis, flagDriftWarnings, modelAliasExclusions, modelAliasLine, probeAll, probeModels, servableExclusions, servabilityLine, writeDoctor } from "../../adapters/registry.js";
 import { CLAUDE_ALIAS_IDENTITY_STAMPS, claudeCode, resolveClaudeAliasIdentity } from "../../adapters/claude-code.js";
 import { BANNER, dim, fail, kvRow, legend, ok, rule, statusRow, title } from "../../brand.js";
 import { tickmarkrDir, stateDirName } from "../../graph/graph.js";
-import { declaredModelWindow, hasWindowsConfig, modelLints, suggestOverlay, ttyVisual } from "../../adapters/model-lints.js";
-import { DEFAULT_CONFIG, loadConfig, overlayPreferShapes } from "../../config/config.js";
+import { catalogModelAdvisory, declaredModelWindow, hasWindowsConfig, modelLints, suggestOverlay, ttyVisual } from "../../adapters/model-lints.js";
+import { loadConfig, overlayPreferShapes } from "../../config/config.js";
 import { HerdrDriver } from "../../drivers/herdr.js";
 import { kimi, probeKimiDoctorTurn } from "../../adapters/kimi.js";
 import { denyPreferCollisionLine, denyPreferCollisions, disallowedBy, excludedChannels, exclusionLine, preferRanks } from "../../route/preference.js";
+import { readCachedCatalog, refreshCatalogCommand } from "../../adapters/catalog-remote.js";
 const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
 const alignedStatusRow = (verdict, key, value) => `  ${statusRow(verdict, kvRow(key, value).slice(2))}`;
 const attentionRow = (text) => `  ${statusRow("warn", text)}`;
 export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(), opts = {}) {
+    if (_argv.length === 1 && _argv[0] === "--refresh-catalog") {
+        const refreshed = await refreshCatalogCommand({ repoRoot: cwd, now: opts.catalogNow });
+        return refreshed.updated
+            ? `tickmarkr doctor --refresh-catalog: model catalog refreshed${refreshed.warning ? `; ${refreshed.warning}` : ""}`
+            : `tickmarkr doctor --refresh-catalog: catalog refresh unavailable — ${refreshed.warning ?? "unknown failure"}; retained ${refreshed.catalog.source} catalog`;
+    }
     const cfg = loadConfig(cwd);
+    // T17: synchronous/cache-only by operator ruling. The only network-bearing catalog function is the
+    // separately invoked refreshCatalogCommand; ordinary doctor never calls it.
+    const catalog = opts.catalog ?? readCachedCatalog(cwd, { now: opts.catalogNow });
     // banner at START — the logo greets the operator before the ~60s probe wait, never trailing it (operator report 2026-07-17)
     if (opts.banner !== false && visual())
         process.stdout.write(BANNER);
@@ -72,8 +82,12 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
         const healthy = h.installed && (a.id !== kimi.id || h.authed);
         return alignedStatusRow(healthy ? "pass" : "fail", a.id, state);
     });
-    // v1.48 T1: advisory sweep for known agent CLIs with no adapter — never written to doctor.json health.
-    rows.push(...detectCandidateClis().map(({ binary, version }) => alignedStatusRow("warn", binary, `detected: ${version ?? "version unknown"} (no tickmarkr adapter — not routable)`)));
+    if (catalog.warning) {
+        rows.push(attentionRow(`model catalog cache unreadable — ${catalog.warning}; using vendored fallback (advisory — routing unchanged)`));
+    }
+    // v1.48 T1 / v1.86 T12: advisory sweep for known agent CLIs with no drive contract. Presence is
+    // resolved through the worker's login shell; advisory targets are never executed or written to health.
+    rows.push(...detectCandidateClis({ cwd }).map(({ binary, path }) => alignedStatusRow("warn", binary, `detected at ${path} (no drive contract — not routable)`)));
     const herdr = HerdrDriver.available();
     rows.push(alignedStatusRow(herdr ? "pass" : "fail", "herdr", herdr ? "driver available (HERDR_ENV=1)" : "not detected — subprocess driver will be used"));
     // v1.22 T5: workspace-trust pre-flight — per installed adapter: trusted | seeded | action-required | n/a.
@@ -143,10 +157,23 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
             }
         }
     }
+    const resolvedCatalogModel = (adapter, model) => {
+        if (adapter !== "claude-code" || !identityResolver || !(model in CLAUDE_ALIAS_IDENTITY_STAMPS))
+            return undefined;
+        try {
+            return identityResolver(cwd, model);
+        }
+        catch {
+            return undefined;
+        }
+    };
     // MODEL-05/06: print-only drift fragment; advisory, whole-line-commented additions, tickmarkr NEVER applies it.
     // TTY gets a one-line summary + the fragment as a file (the full dump drowned everything else,
     // v1.33.1 onboarding); machine/CI surface keeps the inline dump — layout is pinned by tests.
-    const frag = suggestOverlay(cfg, health, adapters, stateDirName(cwd));
+    const frag = suggestOverlay(cfg, health, adapters, stateDirName(cwd), {
+        catalog,
+        resolvedModel: resolvedCatalogModel,
+    });
     let drift = "";
     if (frag) {
         if (visual()) {
@@ -191,24 +218,19 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
                 : "";
             rows.push(`    ${m.padEnd(w)} ${classified[m].padEnd(8)}${windowCol} ${auth}  ${dim("denied=")}${denied}  ${dim("prefer=")}${pref}`);
         }
-        if (unclassified.length)
+        if (unclassified.length) {
+            // Keep the historical count as an index, but it is no longer the whole report: every model gets
+            // a cache-backed evidence or explicit uncovered line. Neither branch changes cfg, health, or route().
             rows.push(`    ${dim(`(${unclassified.length} more listed, unclassified)`)}`);
+            for (const model of unclassified) {
+                const advisory = catalogModelAdvisory(cfg, catalog, a.id, model, resolvedCatalogModel(a.id, model));
+                rows.push(`    ${dim(`catalog · ${advisory.display}`)}`);
+            }
+        }
         return rows;
     });
-    const autoPrefer = readAutoPrefer(cwd);
-    const preferStatus = autoPrefer
-        ? Object.keys(cfg.routing.map).flatMap((shape) => {
-            const auto = autoPrefer[shape];
-            if (!Array.isArray(auto))
-                return [];
-            const seed = DEFAULT_CONFIG.routing.map[shape]?.prefer ?? [];
-            if (!auto.length && !seed.length)
-                return []; // nothing derived, nothing seeded — an empty line is noise
-            return [`    ${dim(`prefer ${shape} (auto):`)} ${auto.join(" > ")} ${dim("— seed was")} [${seed.join(", ")}]`];
-        })
-        : [];
-    const modelSummary = modelStatus.length || preferStatus.length
-        ? `\n${legend("model status:")}\n${[...modelStatus, ...preferStatus].join("\n")}`
+    const modelSummary = modelStatus.length
+        ? `\n${legend("model status:")}\n${modelStatus.join("\n")}`
         : "";
     const header = visual()
         ? `${statusRow("pass", `${title("tickmarkr doctor")} ${legend("· capability matrix")}`)}\n${rule()}`

package/dist/cli/commands/fleet.d.ts

@@ -15,6 +15,13 @@ export type FleetIO = {
     debug?: boolean;
     reloadGuard?: (bytes: string) => string | null;
 };
+export type FleetWriteHooks = {
+    readPrior?: (path: string) => string;
+    beforeRename?: () => void;
+};
+/** Atomic sibling-temp writer. Reading and serializing happen before `${path}.tmp` exists, and
+ * any pre-rename interruption unlinks only that exact candidate while the original remains intact. */
+export declare function writeFleetOverlay(path: string, serialize: (priorBytes: string) => string, hooks?: FleetWriteHooks): void;
 export declare function fleet(argv: string[], cwd?: string, adapters?: WorkerAdapter[], io?: FleetIO): Promise<string | {
     out: string;
     code: number;