harness-dispatch 0.4.0 → 0.6.0

package/dist/config.js

@@ -17,7 +17,42 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import yaml from "js-yaml";
 import which from "which";
-import { normalizeSafetyProfile, } from "./safety.js";
+import { inferredPaidUsagePossible } from "./billing.js";
+import { authSourceFrom, billingKindFrom, bool, endpointModeFrom, endpointProviderFrom, inferEndpointProvider, int, num, providerFrom, str, surfaceFrom, wireProtocolFrom, } from "./config/coercions.js";
+import { warnUnknownRouteKeys, warnUnknownSafetyEnums, warnUnknownTopLevelKeys, } from "./config/validation.js";
+import { parseProtocolFields, protocolFrom, stringArrayFrom } from "./config/protocol.js";
+import { effectiveSafetyFrom, resolveSharedRouteFields, } from "./config/route-fields.js";
+import { interpolateTree } from "./config/env-interpolation.js";
+/**
+ * PATH lookups, memoised for the life of the process.
+ *
+ * loadConfig() runs on every CLI invocation and on every config reload, and
+ * each lookup is a real filesystem walk — ~2-3s per harness on Windows. A CLI
+ * that resolves once will resolve the same way a second later, and a
+ * long-running server re-reads config on hot reload where re-probing bought
+ * nothing.
+ *
+ * Deliberately NOT persisted across processes: installing a harness should
+ * take effect on the next command, not after a cache expiry someone has to
+ * discover.
+ */
+const whichCache = new Map();
+const defaultWhich = async (cmd) => {
+    const cached = whichCache.get(cmd);
+    if (cached !== undefined)
+        return cached;
+    const lookup = (async () => {
+        try {
+            const r = await which(cmd, { nothrow: true });
+            return r ?? null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    whichCache.set(cmd, lookup);
+    return lookup;
+};
 // ---------------------------------------------------------------------------
 // Built-in harness defaults — loaded from the package's own bundled
 // config.default.yaml's `clis:` list, NOT hardcoded here. Claude Code,
@@ -30,15 +65,6 @@ import { normalizeSafetyProfile, } from "./safety.js";
 // doesn't matter to JS).
 // ---------------------------------------------------------------------------
 const SAFETY_PROFILES = ["read_only", "workspace_edit", "full_auto"];
-/** The full set of `{{name}}` tokens expandToken() in generic-cli.ts understands. */
-const KNOWN_ARG_PLACEHOLDERS = new Set([
-    "{{prompt}}",
-    "{{model}}",
-    "{{safety}}",
-    "{{working_dir}}",
-    "{{file_dirs}}",
-    "{{native_args}}",
-]);
 /**
  * `harness: generic` is not a harness definition — it's the escape hatch a
  * user's own entry selects when adding a wholly new CLI, so its "defaults"
@@ -71,6 +97,19 @@ export const PROTOCOL_PRESETS = Object.fromEntries(Object.entries(CLI_DEFAULTS)
 // billing.ts/safety.ts/router.ts) and must not change. This mapping only
 // controls what shows up as the service/route name, so it can follow the
 // same `*_cli` convention `endpoints:` uses for `*_api` (e.g. gemini_api).
+/**
+ * Commands auto-detect probes on PATH, exported so `doctor` can name them.
+ *
+ * A zero-route install used to report "0 ready route(s)" and stop, which tells
+ * a new user nothing about what was looked for or what to install. Keyed the
+ * same way as AUTO_DETECT_NAME so the two cannot drift.
+ */
+export const AUTO_DETECT_COMMANDS = {
+    claude_code_cli: "claude",
+    codex_cli: "codex",
+    cursor_cli: "cursor-agent",
+    antigravity_cli: "agy",
+};
 const AUTO_DETECT_NAME = {
     claude_code: "claude_code_cli",
     codex: "codex_cli",
@@ -80,208 +119,6 @@ const AUTO_DETECT_NAME = {
 // ---------------------------------------------------------------------------
 // Env var interpolation (${VAR_NAME})
 // ---------------------------------------------------------------------------
-const ENV_VAR_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
-/**
- * `unsetVars` collects the names of ${VAR} references that resolved to
- * nothing because the env var isn't set at all — distinct from a var
- * deliberately set to "". Without this, a typo'd or forgotten env var
- * (${ANTHROPIC_API_KEY} when the real name is ${ANTHROPIC_KEY}) silently
- * becomes an empty string: `str()` then drops the field entirely, a route
- * that needed an api_key loses it with zero feedback, and doctor reports
- * the route "ready" right up until the first real call 401s.
- */
-function interpolateEnv(value, unsetVars) {
-    const m = ENV_VAR_RE.exec(value);
-    if (!m)
-        return value;
-    const name = m[1];
-    if (!(name in process.env))
-        unsetVars.add(name);
-    return process.env[name] ?? "";
-}
-/** Walk an object tree and replace any "${VAR}" string leaves with env values. */
-function interpolateTree(node, unsetVars) {
-    if (typeof node === "string") {
-        return interpolateEnv(node, unsetVars);
-    }
-    if (Array.isArray(node)) {
-        return node.map((v) => interpolateTree(v, unsetVars));
-    }
-    if (node !== null && typeof node === "object") {
-        const out = {};
-        for (const [k, v] of Object.entries(node)) {
-            out[k] = interpolateTree(v, unsetVars);
-        }
-        return out;
-    }
-    return node;
-}
-const defaultWhich = async (cmd) => {
-    try {
-        const r = await which(cmd, { nothrow: true });
-        return r ?? null;
-    }
-    catch {
-        return null;
-    }
-};
-// ---------------------------------------------------------------------------
-// Normalization helpers
-// ---------------------------------------------------------------------------
-function num(v, def) {
-    if (typeof v === "number")
-        return v;
-    if (typeof v === "string" && v !== "") {
-        const n = Number(v);
-        if (!Number.isNaN(n))
-            return n;
-    }
-    return def;
-}
-function int(v, def) {
-    return Math.trunc(num(v, def));
-}
-function bool(v, def) {
-    if (typeof v === "boolean")
-        return v;
-    if (typeof v === "string") {
-        if (v === "true")
-            return true;
-        if (v === "false")
-            return false;
-    }
-    return def;
-}
-function str(v) {
-    if (typeof v !== "string")
-        return undefined;
-    if (v === "")
-        return undefined;
-    return v;
-}
-function thinkingFrom(v) {
-    if (v === "low" || v === "medium" || v === "high")
-        return v;
-    return undefined;
-}
-function providerFrom(v) {
-    if (v === "anthropic" ||
-        v === "openai" ||
-        v === "cursor" ||
-        v === "google" ||
-        v === "local" ||
-        v === "custom") {
-        return v;
-    }
-    return undefined;
-}
-function surfaceFrom(v) {
-    if (v === "claude_code" ||
-        v === "claude_agent_sdk" ||
-        v === "anthropic_api" ||
-        v === "codex_cli" ||
-        v === "codex_sdk" ||
-        v === "openai_api" ||
-        v === "cursor_agent_cli" ||
-        v === "antigravity_cli" ||
-        v === "gemini_api" ||
-        v === "vertex_ai" ||
-        v === "openai_compatible" ||
-        v === "local_endpoint" ||
-        v === "custom") {
-        return v;
-    }
-    return undefined;
-}
-function authSourceFrom(v) {
-    if (v === "product_login" ||
-        v === "api_key" ||
-        v === "oauth_session" ||
-        v === "local_network" ||
-        v === "configured_endpoint" ||
-        v === "unknown") {
-        return v;
-    }
-    return undefined;
-}
-function billingKindFrom(v) {
-    if (v === "local_compute" ||
-        v === "included_plan_usage" ||
-        v === "included_plan_then_flexible_credits" ||
-        v === "included_credit_then_optional_overage" ||
-        v === "included_usage_then_on_demand" ||
-        v === "metered_api" ||
-        v === "free_quota" ||
-        v === "unknown") {
-        return v;
-    }
-    return undefined;
-}
-function confidenceFrom(v) {
-    if (v === "documented" || v === "inferred" || v === "unknown" || v === "unsupported") {
-        return v;
-    }
-    return undefined;
-}
-function endpointModeFrom(v) {
-    if (v === "provider_cloud" ||
-        v === "direct_openai_compatible" ||
-        v === "harness_native_endpoint") {
-        return v;
-    }
-    return undefined;
-}
-function endpointProviderFrom(v) {
-    if (v === "ollama" ||
-        v === "lmstudio" ||
-        v === "openai_compatible" ||
-        v === "anthropic_gateway" ||
-        v === "gemini_proxy" ||
-        v === "custom") {
-        return v;
-    }
-    return undefined;
-}
-function wireProtocolFrom(v) {
-    if (v === "openai_chat_completions" ||
-        v === "anthropic_messages" ||
-        v === "gemini_generate_content" ||
-        v === "provider_native" ||
-        v === "unknown") {
-        return v;
-    }
-    return undefined;
-}
-function workspacePolicyFrom(v) {
-    if (v === "shared" || v === "shared_locked" || v === "git_worktree" || v === "copy") {
-        return v;
-    }
-    return undefined;
-}
-function inferEndpointProvider(baseUrl) {
-    if (!baseUrl)
-        return "custom";
-    try {
-        const url = new URL(baseUrl);
-        const host = url.hostname.toLowerCase();
-        const port = url.port;
-        if ((host === "localhost" || host === "127.0.0.1" || host === "::1") && port === "11434") {
-            return "ollama";
-        }
-        if ((host === "localhost" || host === "127.0.0.1" || host === "::1") && port === "1234") {
-            return "lmstudio";
-        }
-    }
-    catch {
-        // Fall through to substring checks for partial or nonstandard URLs.
-    }
-    const lower = baseUrl.toLowerCase();
-    if (lower.includes("ollama"))
-        return "ollama";
-    if (lower.includes("lmstudio") || lower.includes("lm-studio"))
-        return "lmstudio";
-    return "custom";
-}
 function endpointFields(raw, type, baseUrl) {
     const endpointMode = endpointModeFrom(raw.endpoint_mode) ??
         (type === "openai_compatible" ? "direct_openai_compatible" : undefined);
@@ -306,7 +143,7 @@ function endpointFields(raw, type, baseUrl) {
  * `retention:`. Parsed once here so legacy `services:` configs and modern
  * `clis:`/`endpoints:` configs behave identically.
  */
-function topLevelSettings(raw) {
+function topLevelSettings(raw, policyWarnings = []) {
     const out = {};
     const telemetryRaw = raw.telemetry;
     if (telemetryRaw !== null && typeof telemetryRaw === "object") {
@@ -320,16 +157,47 @@ function topLevelSettings(raw) {
         if (Number.isFinite(days) && days >= 0)
             out.retention = { jobsDays: days };
     }
+    const leaderboardRaw = raw.leaderboard;
+    if (leaderboardRaw !== null && typeof leaderboardRaw === "object") {
+        const enabled = leaderboardRaw.enabled;
+        if (typeof enabled === "boolean")
+            out.leaderboard = { enabled };
+    }
+    const maxRuns = num(raw.max_concurrent_runs, Number.NaN);
+    if (Number.isFinite(maxRuns) && maxRuns >= 0)
+        out.maxConcurrentRuns = Math.floor(maxRuns);
+    else if (raw.max_concurrent_runs !== undefined) {
+        // Present but unusable. Silently falling back to the default meant a
+        // caller who set a concurrency bound got a different one and was never
+        // told — and this value governs how many agent CLIs run at once.
+        policyWarnings.push(`max_concurrent_runs: ${JSON.stringify(raw.max_concurrent_runs)} is not a ` +
+            `non-negative number — IGNORED, the default applies instead.`);
+    }
     return out;
 }
+/**
+ * `effective_safety` as either one profile or a per-request map.
+ *
+ * An unrecognised value is dropped rather than guessed at, and an unrecognised
+ * KEY or value inside the map is dropped individually — a typo must not
+ * silently widen the floor for a request it was meant to restrict.
+ */
+/**
+ * Billing IDENTITY for a route — the part that genuinely differs per shape.
+ *
+ * Everything that means the same thing everywhere (safety_profile,
+ * effective_safety, workspace_policy, billing_notes, models, …) now comes from
+ * resolveSharedRouteFields instead. What is left here is the set the caller
+ * has already inferred per shape: endpoints derive provider/surface/kind from
+ * the base URL, CLI routes derive them from whether an api_key is present.
+ * This function only reads what it is handed.
+ */
 function billingFields(raw) {
     const out = {};
     const provider = providerFrom(raw.provider);
     const surface = surfaceFrom(raw.surface);
     const authSource = authSourceFrom(raw.auth_source);
     const billingKind = billingKindFrom(raw.billing_kind);
-    const billingConfidence = confidenceFrom(raw.billing_confidence);
-    const safetyProfile = normalizeSafetyProfile(raw.safety_profile);
     if (provider !== undefined)
         out.provider = provider;
     if (surface !== undefined)
@@ -338,21 +206,9 @@ function billingFields(raw) {
         out.authSource = authSource;
     if (billingKind !== undefined)
         out.billingKind = billingKind;
-    if (billingConfidence !== undefined)
-        out.billingConfidence = billingConfidence;
     if (typeof raw.paid_usage_possible === "boolean") {
         out.paidUsagePossible = raw.paid_usage_possible;
     }
-    if (typeof raw.allow_paid_usage === "boolean")
-        out.allowPaidUsage = raw.allow_paid_usage;
-    const notes = str(raw.billing_notes);
-    if (notes !== undefined)
-        out.billingNotes = notes;
-    if (safetyProfile !== undefined)
-        out.safetyProfile = safetyProfile;
-    const workspacePolicy = workspacePolicyFrom(raw.workspace_policy);
-    if (workspacePolicy !== undefined)
-        out.workspacePolicy = workspacePolicy;
     return out;
 }
 function capsFrom(raw) {
@@ -374,276 +230,6 @@ function escalateOnFrom(raw) {
     }
     return out.length > 0 ? out : ["plan", "review"];
 }
-function stringArrayFrom(raw) {
-    if (!Array.isArray(raw))
-        return undefined;
-    const out = raw.filter((v) => typeof v === "string");
-    return out.length > 0 ? out : undefined;
-}
-/**
- * Parse `protocol:` for any route (see CliProtocolConfig in types.ts).
- * Three shapes:
- *  - A string ("cursor", "codex", ...) — looked up in PROTOCOL_PRESETS by
- *    name. Lets a config select a known protocol without retyping it, and
- *    is the extension point for "others add further protocols" — a new
- *    named entry in the shipped config.default.yaml is immediately selectable here,
- *    no code changes.
- *  - An object with `extends: <preset name>` — starts from that preset and
- *    overrides only the fields present, for the common "95% the same, one
- *    flag different" case. safety merges per-profile (overriding just
- *    full_auto doesn't erase read_only/workspace_edit from the preset).
- *  - A plain object — the full protocol, no preset involved (unchanged
- *    behavior from before presets existed).
- *
- * Returns undefined — with a warning — for anything malformed, so a broken
- * block degrades to "route unusable" (isAvailable() checks for a missing
- * protocol) rather than a half-built dispatcher silently doing the wrong
- * thing.
- */
-function protocolFrom(raw, routeLabel, warnings) {
-    if (typeof raw === "string") {
-        const preset = PROTOCOL_PRESETS[raw];
-        if (!preset) {
-            warnings.push(`${routeLabel}: protocol "${raw}" is not a known preset (expected one of: ` +
-                `${Object.keys(PROTOCOL_PRESETS).join(", ")}) — entry ignored.`);
-            return undefined;
-        }
-        return preset;
-    }
-    if (raw === null || typeof raw !== "object")
-        return undefined;
-    const r = raw;
-    let base;
-    if (typeof r.extends === "string") {
-        base = PROTOCOL_PRESETS[r.extends];
-        if (!base) {
-            warnings.push(`${routeLabel}: protocol.extends "${r.extends}" is not a known preset (expected one of: ` +
-                `${Object.keys(PROTOCOL_PRESETS).join(", ")}) — entry ignored.`);
-            return undefined;
-        }
-    }
-    return parseProtocolFields(r, routeLabel, warnings, base);
-}
-function parseProtocolFields(r, routeLabel, warnings, base) {
-    const args = stringArrayFrom(r.args) ?? base?.args;
-    if (args === undefined) {
-        warnings.push(`${routeLabel}: protocol.args is required — entry ignored.`);
-        return undefined;
-    }
-    const outputRaw = r.output;
-    let output = base?.output;
-    if (outputRaw !== undefined) {
-        if (outputRaw === null || typeof outputRaw !== "object") {
-            warnings.push(`${routeLabel}: protocol.output must be an object — entry ignored.`);
-            return undefined;
-        }
-        const o = outputRaw;
-        if (o.mode !== "text" && o.mode !== "json_field" && o.mode !== "jsonl_stream") {
-            warnings.push(`${routeLabel}: protocol.output.mode must be one of text | json_field | jsonl_stream — entry ignored.`);
-            return undefined;
-        }
-        output = { mode: o.mode };
-        const fields = stringArrayFrom(o.fields);
-        if (fields !== undefined)
-            output.fields = fields;
-        const usageRaw = o.usage;
-        if (usageRaw !== null && typeof usageRaw === "object") {
-            const u = usageRaw;
-            const input = stringArrayFrom(u.input);
-            const outputTokens = stringArrayFrom(u.output);
-            if (input !== undefined && outputTokens !== undefined)
-                output.usage = { input, output: outputTokens };
-        }
-        const eventRulesRaw = o.event_rules;
-        if (Array.isArray(eventRulesRaw)) {
-            const eventRules = [];
-            for (const [i, ruleRaw] of eventRulesRaw.entries()) {
-                const rule = eventRuleFrom(ruleRaw, `${routeLabel}: protocol.output.event_rules[${i}]`, warnings);
-                if (rule)
-                    eventRules.push(rule);
-            }
-            if (eventRules.length > 0)
-                output.eventRules = eventRules;
-        }
-        const errorRaw = o.error;
-        if (errorRaw !== null && typeof errorRaw === "object") {
-            const e = errorRaw;
-            const field = str(e.field);
-            if (field !== undefined) {
-                const messageFields = stringArrayFrom(e.message_fields);
-                output.error = messageFields !== undefined ? { field, messageFields } : { field };
-            }
-            else {
-                warnings.push(`${routeLabel}: protocol.output.error.field is required — error detection ignored.`);
-            }
-        }
-    }
-    if (output === undefined) {
-        warnings.push(`${routeLabel}: protocol.output is required — entry ignored.`);
-        return undefined;
-    }
-    const protocol = { args, output };
-    const stdin = typeof r.stdin === "boolean" ? r.stdin : base?.stdin;
-    if (stdin !== undefined)
-        protocol.stdin = stdin;
-    const modelRaw = r.model;
-    if (modelRaw !== undefined && modelRaw !== null) {
-        const m = modelRaw;
-        if (typeof m.flag === "string" && m.flag) {
-            protocol.model = { flag: m.flag };
-        }
-        else {
-            warnings.push(`${routeLabel}: protocol.model set but missing a "flag" string — ignored.`);
-        }
-    }
-    else if (base?.model) {
-        protocol.model = base.model;
-    }
-    const workingDirRaw = r.working_dir;
-    if (workingDirRaw !== undefined && workingDirRaw !== null) {
-        const wd = workingDirRaw;
-        if (typeof wd.flag === "string" && wd.flag) {
-            protocol.workingDir = { flag: wd.flag };
-            const extraArgsWhenSet = stringArrayFrom(wd.extra_args_when_set);
-            if (extraArgsWhenSet !== undefined)
-                protocol.workingDir.extraArgsWhenSet = extraArgsWhenSet;
-            if (wd.fallback === "home")
-                protocol.workingDir.fallback = "home";
-        }
-        else {
-            warnings.push(`${routeLabel}: protocol.working_dir set but missing a "flag" string — ignored.`);
-        }
-    }
-    else if (base?.workingDir) {
-        protocol.workingDir = base.workingDir;
-    }
-    const fileDirsRaw = r.file_dirs;
-    if (fileDirsRaw !== undefined && fileDirsRaw !== null) {
-        const fd = fileDirsRaw;
-        if (typeof fd.flag === "string" && fd.flag) {
-            protocol.fileDirs = { flag: fd.flag };
-        }
-        else {
-            warnings.push(`${routeLabel}: protocol.file_dirs set but missing a "flag" string — ignored.`);
-        }
-    }
-    else if (base?.fileDirs) {
-        protocol.fileDirs = base.fileDirs;
-    }
-    const fileListHeader = str(r.file_list_header) ?? base?.fileListHeader;
-    if (fileListHeader !== undefined)
-        protocol.fileListHeader = fileListHeader;
-    const fileListBullet = (typeof r.file_list_bullet === "string" ? r.file_list_bullet : undefined) ?? base?.fileListBullet;
-    if (fileListBullet !== undefined)
-        protocol.fileListBullet = fileListBullet;
-    const apiKeyEnvVar = str(r.api_key_env_var) ?? base?.apiKeyEnvVar;
-    if (apiKeyEnvVar !== undefined)
-        protocol.apiKeyEnvVar = apiKeyEnvVar;
-    const safetyRaw = r.safety;
-    const safety = { ...base?.safety };
-    if (safetyRaw !== null && typeof safetyRaw === "object") {
-        for (const profile of SAFETY_PROFILES) {
-            const profileArgs = stringArrayFrom(safetyRaw[profile]);
-            if (profileArgs !== undefined)
-                safety[profile] = profileArgs;
-        }
-    }
-    if (Object.keys(safety).length > 0)
-        protocol.safety = safety;
-    if (typeof r.success_requires_output === "boolean") {
-        protocol.successRequiresOutput = r.success_requires_output;
-    }
-    else if (base?.successRequiresOutput !== undefined) {
-        protocol.successRequiresOutput = base.successRequiresOutput;
-    }
-    const endpointNativeArgsRaw = r.endpoint_native_args;
-    if (endpointNativeArgsRaw !== null && typeof endpointNativeArgsRaw === "object") {
-        const ena = {};
-        for (const [k, v] of Object.entries(endpointNativeArgsRaw)) {
-            const args2 = stringArrayFrom(v);
-            if (args2 !== undefined)
-                ena[k] = args2;
-        }
-        if (Object.keys(ena).length > 0)
-            protocol.endpointNativeArgs = ena;
-    }
-    else if (base?.endpointNativeArgs) {
-        protocol.endpointNativeArgs = base.endpointNativeArgs;
-    }
-    // Placeholder sanity checks on the FINAL merged args (so `extends:` results
-    // are covered too). A typo'd placeholder is the most likely user error in a
-    // hand-written protocol, and without these warnings it doesn't just fail
-    // silently — it "succeeds": the CLI receives the literal "{{promt}}" token,
-    // never receives the prompt, exits 0, and the run reports ok.
-    // Matches embedded forms too ("--flag={{prompt}}"), not just whole-token
-    // typos — expansion only ever substitutes a token that IS a placeholder,
-    // so anything merely containing one goes through literally.
-    for (const token of protocol.args) {
-        if (token.includes("{{") && !KNOWN_ARG_PLACEHOLDERS.has(token)) {
-            warnings.push(`${routeLabel}: protocol.args contains unrecognized placeholder "${token}" — it will be ` +
-                `passed to the CLI as a literal argument, not substituted. Placeholders only work as ` +
-                `a whole standalone argument. Known placeholders: ` +
-                `${[...KNOWN_ARG_PLACEHOLDERS].join(", ")}.`);
-        }
-    }
-    if (!protocol.stdin && !protocol.args.includes("{{prompt}}")) {
-        warnings.push(`${routeLabel}: protocol.args has no {{prompt}} placeholder and stdin is not true — ` +
-            `the prompt is never sent to the CLI. Add "{{prompt}}" to args, or set stdin: true.`);
-    }
-    return protocol;
-}
-function eventRuleFrom(raw, label, warnings) {
-    if (raw === null || typeof raw !== "object") {
-        warnings.push(`${label}: must be an object — ignored.`);
-        return undefined;
-    }
-    const r = raw;
-    // "when" is optional — omitted or {} means "matches every line" (e.g. a
-    // usage rule that should fire regardless of event type, matching Codex's
-    // original unconditional `if (event.usage) {...}` check).
-    const whenRaw = r.when ?? {};
-    if (whenRaw === null || typeof whenRaw !== "object" || Array.isArray(whenRaw)) {
-        warnings.push(`${label}: "when" must be a {field: value} map — ignored.`);
-        return undefined;
-    }
-    const when = {};
-    for (const [k, v] of Object.entries(whenRaw)) {
-        if (typeof v === "string")
-            when[k] = v;
-    }
-    const emit = r.emit;
-    if (emit !== "text" &&
-        emit !== "tool_use" &&
-        emit !== "thinking" &&
-        emit !== "usage" &&
-        emit !== "error") {
-        warnings.push(`${label}: "emit" must be one of text | tool_use | thinking | usage | error — ignored.`);
-        return undefined;
-    }
-    const rule = { when, emit };
-    const textField = str(r.text_field);
-    if (textField !== undefined)
-        rule.textField = textField;
-    const nameField = str(r.name_field);
-    if (nameField !== undefined)
-        rule.nameField = nameField;
-    const inputField = str(r.input_field);
-    if (inputField !== undefined)
-        rule.inputField = inputField;
-    const chunkField = str(r.chunk_field);
-    if (chunkField !== undefined)
-        rule.chunkField = chunkField;
-    const inputTokenFields = stringArrayFrom(r.input_token_fields);
-    if (inputTokenFields !== undefined)
-        rule.inputTokenFields = inputTokenFields;
-    const outputTokenFields = stringArrayFrom(r.output_token_fields);
-    if (outputTokenFields !== undefined)
-        rule.outputTokenFields = outputTokenFields;
-    const messageField = str(r.message_field);
-    if (messageField !== undefined)
-        rule.messageField = messageField;
-    return rule;
-}
 // ---------------------------------------------------------------------------
 // Legacy full-format parser (YAML with top-level `services:` key)
 // ---------------------------------------------------------------------------
@@ -685,31 +271,11 @@ function buildLegacyConfig(raw) {
             tier: int(svc.tier, 1),
             weight: num(svc.weight, 1.0),
             cliCapability: num(svc.cli_capability, 1.0),
-            ...(str(svc.leaderboard_model) !== undefined
-                ? { leaderboardModel: str(svc.leaderboard_model) }
-                : {}),
-            ...(() => {
-                const t = thinkingFrom(svc.thinking_level);
-                return t !== undefined ? { thinkingLevel: t } : {};
-            })(),
-            ...(str(svc.escalate_model) !== undefined
-                ? { escalateModel: str(svc.escalate_model) }
-                : {}),
             escalateOn: escalateOnFrom(svc.escalate_on),
             capabilities: capsFrom(svc.capabilities),
             ...(() => {
-                // Declared context size drives router.ts's preferLargeContext boost
-                // (not harness name), so a legacy entry that omits these but names
-                // a known harness (e.g. antigravity_cli's 2M context) must still
-                // inherit them — otherwise the boost silently becomes a no-op.
-                const v = typeof svc.max_output_tokens === "number" ? svc.max_output_tokens : harnessDefaults?.maxOutputTokens;
-                return v !== undefined ? { maxOutputTokens: v } : {};
-            })(),
-            ...(() => {
-                const v = typeof svc.max_input_tokens === "number" ? svc.max_input_tokens : harnessDefaults?.maxInputTokens;
-                return v !== undefined ? { maxInputTokens: v } : {};
-            })(),
-            ...(() => {
+                // Billing IDENTITY only — the rest of the named harness's defaults
+                // reach this entry through resolveSharedRouteFields below.
                 if (!harnessDefaults)
                     return {};
                 return {
@@ -722,37 +288,26 @@ function buildLegacyConfig(raw) {
                     ...(harnessDefaults.paidUsagePossible !== undefined
                         ? { paidUsagePossible: harnessDefaults.paidUsagePossible }
                         : {}),
-                    ...(harnessDefaults.effectiveSafety !== undefined
-                        ? { effectiveSafety: harnessDefaults.effectiveSafety }
-                        : {}),
-                    ...(harnessDefaults.models !== undefined ? { models: harnessDefaults.models } : {}),
-                    ...(harnessDefaults.modelHint !== undefined
-                        ? { modelHint: harnessDefaults.modelHint }
-                        : {}),
                 };
             })(),
             ...billingFields(svc),
-            ...(() => {
-                const effectiveSafety = normalizeSafetyProfile(svc.effective_safety);
-                return effectiveSafety !== undefined ? { effectiveSafety } : {};
-            })(),
-            ...(() => {
-                const models = stringArrayFrom(svc.models);
-                return models !== undefined ? { models } : {};
-            })(),
-            ...(() => {
-                const modelHint = str(svc.model_hint);
-                return modelHint !== undefined ? { modelHint } : {};
-            })(),
+            // The same table the `clis:` and `endpoints:` builders use. This shape
+            // previously read the shared keys through billingFields() plus four
+            // hand-written blocks, which is how it ended up with a DIFFERENT set
+            // again: it inherited maxInput/OutputTokens, effectiveSafety, models and
+            // modelHint from the named harness but not leaderboardModel or
+            // thinkingLevel, so `services: { x: { harness: antigravity_cli } }`
+            // silently lost its scoring key and its thinking level. Passing the
+            // defaults through one table fixes that too.
+            ...resolveSharedRouteFields(svc, harnessDefaults),
             ...endpointFields(svc, type, str(svc.base_url)),
-            ...(typeof svc.timeout_ms === "number" ? { timeoutMs: svc.timeout_ms } : {}),
             ...(() => {
                 // Falls back to the named harness's built-in default protocol (if
                 // any) when this legacy-format entry doesn't declare its own —
                 // same behavior as clis: entries, so `harness: claude_code` here
                 // works without repeating the whole protocol block.
                 const harnessDefaults = CLI_DEFAULTS[str(svc.harness) ?? ""];
-                const protocol = protocolFrom(svc.protocol, `services "${name}"`, warnings) ?? harnessDefaults?.protocol;
+                const protocol = protocolFrom(svc.protocol, `services "${name}"`, warnings, PROTOCOL_PRESETS) ?? harnessDefaults?.protocol;
                 return protocol !== undefined ? { protocol } : {};
             })(),
         };
@@ -763,7 +318,7 @@ function buildLegacyConfig(raw) {
         ...(Array.isArray(raw.disabled)
             ? { disabled: raw.disabled.slice() }
             : {}),
-        ...topLevelSettings(raw),
+        ...topLevelSettings(raw, warnings),
         ...(warnings.length > 0 ? { configWarnings: warnings } : {}),
     };
     return cfg;
@@ -801,31 +356,13 @@ function buildCliServiceConfig(name, defaults, override, apiKeys, warnings = [])
         weight: num(override.weight, 1.0),
         tier: int(override.tier, defaults.tier),
         cliCapability: num(override.cli_capability, defaults.cliCapability),
-        leaderboardModel: str(override.leaderboard_model) ?? defaults.leaderboardModel,
-        ...(() => {
-            const overrideThinking = thinkingFrom(override.thinking_level);
-            if (overrideThinking !== undefined)
-                return { thinkingLevel: overrideThinking };
-            if (defaults.thinkingLevel !== undefined) {
-                return { thinkingLevel: defaults.thinkingLevel };
-            }
-            return {};
-        })(),
-        ...(str(override.escalate_model) !== undefined
-            ? { escalateModel: str(override.escalate_model) }
-            : {}),
         escalateOn: escalateOnFrom(override.escalate_on),
         capabilities: caps,
-        ...(() => {
-            const m = override.max_output_tokens;
-            const v = typeof m === "number" ? m : defaults.maxOutputTokens;
-            return v !== undefined ? { maxOutputTokens: v } : {};
-        })(),
-        ...(() => {
-            const m = override.max_input_tokens;
-            const v = typeof m === "number" ? m : defaults.maxInputTokens;
-            return v !== undefined ? { maxInputTokens: v } : {};
-        })(),
+        // Every field that means the same thing on every route shape, resolved
+        // from ONE table against this harness's shipped defaults. Spread early so
+        // the shape-specific resolutions below (billing identity, which depends on
+        // whether an api_key is present) still win.
+        ...resolveSharedRouteFields(override, defaults),
         provider: providerFrom(override.provider) ?? defaults.provider,
         surface: surfaceFrom(override.surface) ?? defaults.surface,
         authSource: authSourceFrom(override.auth_source) ?? (apiKey ? "api_key" : defaults.authSource),
@@ -834,48 +371,36 @@ function buildCliServiceConfig(name, defaults, override, apiKeys, warnings = [])
             return billingKind !== undefined ? { billingKind } : {};
         })(),
         ...(() => {
+            // A DECLARED billing_kind beats the harness default.
+            //
+            // `harness: generic` defaults paidUsagePossible to true (correctly — an
+            // unknown command might cost money). But a route declaring
+            // `billing_kind: local_compute` has said it cannot, and the default
+            // still won: status showed `billing=local_compute paid=possible`, two
+            // fields of the same record contradicting each other, and the route was
+            // skipped by billing policy. Nothing about a declared non-paid kind
+            // should leave the paid flag set by a fallback.
+            //
+            // An explicit paid_usage_possible still wins over both, and an api_key
+            // still forces true — a key means a metered account exists regardless of
+            // what the kind claims.
+            const declaredKind = billingKindFrom(override.billing_kind);
             const paidUsagePossible = typeof override.paid_usage_possible === "boolean"
                 ? override.paid_usage_possible
                 : apiKey
                     ? true
-                    : defaults.paidUsagePossible;
+                    : declaredKind !== undefined
+                        ? inferredPaidUsagePossible(declaredKind)
+                        : defaults.paidUsagePossible;
             return paidUsagePossible !== undefined ? { paidUsagePossible } : {};
         })(),
-        ...(typeof override.allow_paid_usage === "boolean"
-            ? { allowPaidUsage: override.allow_paid_usage }
-            : {}),
-        ...(() => {
-            const c = confidenceFrom(override.billing_confidence);
-            return c !== undefined ? { billingConfidence: c } : {};
-        })(),
-        ...(() => {
-            const notes = str(override.billing_notes);
-            return notes !== undefined ? { billingNotes: notes } : {};
-        })(),
-        ...(() => {
-            const safetyProfile = normalizeSafetyProfile(override.safety_profile);
-            return safetyProfile !== undefined ? { safetyProfile } : {};
-        })(),
-        ...(() => {
-            const effectiveSafety = normalizeSafetyProfile(override.effective_safety) ?? defaults.effectiveSafety;
-            return effectiveSafety !== undefined ? { effectiveSafety } : {};
-        })(),
-        ...(() => {
-            const models = stringArrayFrom(override.models) ?? defaults.models;
-            return models !== undefined ? { models } : {};
-        })(),
-        ...(() => {
-            const modelHint = str(override.model_hint) ?? defaults.modelHint;
-            return modelHint !== undefined ? { modelHint } : {};
-        })(),
         ...endpointFields(override, "cli", str(override.base_url)),
-        ...(typeof override.timeout_ms === "number" ? { timeoutMs: override.timeout_ms } : {}),
         ...(() => {
             // Falls back to this harness's built-in default (if any) when no
             // override is given, or when the override is malformed — protocolFrom
             // already warned in the latter case; failing the whole route over a
             // typo'd override would be worse than keeping the known-good default.
-            const protocol = protocolFrom(override.protocol, `clis "${name}"`, warnings) ?? defaults.protocol;
+            const protocol = protocolFrom(override.protocol, `clis "${name}"`, warnings, PROTOCOL_PRESETS) ?? defaults.protocol;
             return protocol !== undefined ? { protocol } : {};
         })(),
     };
@@ -883,19 +408,32 @@ function buildCliServiceConfig(name, defaults, override, apiKeys, warnings = [])
 async function detectServices(disabled, apiKeys, overrides, whichFn) {
     const services = {};
     const disabledSet = new Set(disabled);
-    for (const [harness, defaults] of Object.entries(CLI_DEFAULTS)) {
+    // Probe every harness AT ONCE.
+    //
+    // This was a sequential await per harness. Each `which` costs real time on
+    // Windows — measured 2.8s / 3.3s / 2.7s / 2.1s for claude / codex /
+    // cursor-agent / agy on a machine where all four are installed, so ~11s per
+    // loadConfig() call, and loadConfig runs on every CLI invocation. `status`
+    // and `doctor` took ~17s, and the test suite went red with timeouts on any
+    // developer machine that actually has the harnesses installed — it passed in
+    // CI only because CI is bare. The probes are independent, so there was never
+    // a reason to serialise them.
+    const candidates = Object.entries(CLI_DEFAULTS)
         // "generic" has no installable binary of its own — it exists only for
         // explicit clis: entries (addClis), never auto-detection.
-        if (harness === "generic")
-            continue;
-        const name = AUTO_DETECT_NAME[harness] ?? harness;
-        if (disabledSet.has(name))
-            continue;
-        const found = await whichFn(defaults.command);
-        if (!found)
+        .filter(([harness]) => harness !== "generic")
+        .map(([harness, defaults]) => ({
+        harness,
+        defaults,
+        name: AUTO_DETECT_NAME[harness] ?? harness,
+    }))
+        .filter(({ name }) => !disabledSet.has(name));
+    const found = await Promise.all(candidates.map(async (c) => ((await whichFn(c.defaults.command)) ? c : undefined)));
+    for (const c of found) {
+        if (!c)
             continue;
-        const override = overrides[name] ?? {};
-        services[name] = buildCliServiceConfig(name, defaults, override, apiKeys);
+        const override = overrides[c.name] ?? {};
+        services[c.name] = buildCliServiceConfig(c.name, c.defaults, override, apiKeys);
     }
     return services;
 }
@@ -917,6 +455,7 @@ function addClis(services, raw, apiKeys, warnings) {
             warnings.push(`clis[${index}]: missing required "name" and/or "harness" — entry ignored.`);
             continue;
         }
+        warnUnknownRouteKeys(entry, `clis[${index}] "${name}"`, warnings);
         const defaults = CLI_DEFAULTS[harness];
         if (!defaults) {
             warnings.push(`clis[${index}] "${name}": unrecognized harness "${harness}" (expected one of: ` +
@@ -943,7 +482,7 @@ function addClis(services, raw, apiKeys, warnings) {
             // once, from here, since the entry gets skipped before that second
             // parse ever runs.
             const validation = [];
-            if (protocolFrom(entry.protocol, `clis[${index}] "${name}"`, validation) === undefined) {
+            if (protocolFrom(entry.protocol, `clis[${index}] "${name}"`, validation, PROTOCOL_PRESETS) === undefined) {
                 warnings.push(...validation);
                 continue;
             }
@@ -968,16 +507,29 @@ function collectApiKeys(raw) {
     }
     return apiKeys;
 }
-function addEndpoints(services, raw) {
+function addEndpoints(services, raw, apiKeys, warnings = []) {
     const endpoints = Array.isArray(raw.endpoints)
         ? raw.endpoints
         : [];
-    for (const ep of endpoints) {
+    for (const [index, ep] of endpoints.entries()) {
         const name = str(ep.name);
+        warnUnknownRouteKeys(ep, `endpoints[${index}] "${name ?? "?"}"`, warnings);
         const baseUrl = str(ep.base_url);
         const model = str(ep.model);
-        if (!name || !baseUrl || !model)
+        if (!name || !baseUrl || !model) {
+            // Silently dropping the entry was the same class this file keeps
+            // producing: the equivalent `clis:` mistake warns loudly, this one left
+            // `doctor` reporting "ok config-warnings" while three endpoints had
+            // vanished.
+            const missing = [
+                !name ? "name" : undefined,
+                !baseUrl ? "base_url" : undefined,
+                !model ? "model" : undefined,
+            ].filter((v) => v !== undefined);
+            warnings.push(`endpoints[${index}]${name ? ` "${name}"` : ""}: missing required ` +
+                `${missing.join(", ")} — entry ignored.`);
             continue;
+        }
         const svc = {
             name,
             enabled: bool(ep.enabled, true),
@@ -985,13 +537,20 @@ function addEndpoints(services, raw) {
             baseUrl,
             model,
             command: "",
-            ...(str(ep.api_key) !== undefined ? { apiKey: str(ep.api_key) } : {}),
+            // The top-level `api_keys:` block was honoured for `clis:` (see
+            // buildCliServiceConfig) and silently ignored here, so an endpoint whose
+            // credential lived there had NO key at runtime — and `configure` could
+            // not round-trip a reference that had never reached the service. Same
+            // class as workspace_policy: a documented key read for one route shape
+            // and dropped for another.
+            ...(str(ep.api_key) !== undefined
+                ? { apiKey: str(ep.api_key) }
+                : apiKeys[name]
+                    ? { apiKey: apiKeys[name] }
+                    : {}),
             weight: num(ep.weight, 0.6),
             tier: int(ep.tier, 3),
             cliCapability: num(ep.cli_capability, 1.0),
-            ...(str(ep.leaderboard_model) !== undefined
-                ? { leaderboardModel: str(ep.leaderboard_model) }
-                : {}),
             escalateOn: escalateOnFrom(ep.escalate_on),
             capabilities: capsFrom(ep.capabilities),
             ...billingFields({
@@ -1008,21 +567,10 @@ function addEndpoints(services, raw) {
                 billing_confidence: ep.billing_confidence ?? (inferEndpointProvider(baseUrl) === "custom" ? undefined : "documented"),
             }),
             ...endpointFields(ep, "openai_compatible", baseUrl),
-            ...(typeof ep.timeout_ms === "number" ? { timeoutMs: ep.timeout_ms } : {}),
-            ...(typeof ep.max_output_tokens === "number" ? { maxOutputTokens: ep.max_output_tokens } : {}),
-            ...(typeof ep.max_input_tokens === "number" ? { maxInputTokens: ep.max_input_tokens } : {}),
-            ...(() => {
-                const t = thinkingFrom(ep.thinking_level);
-                return t !== undefined ? { thinkingLevel: t } : {};
-            })(),
-            ...(() => {
-                const models = stringArrayFrom(ep.models);
-                return models !== undefined ? { models } : {};
-            })(),
-            ...(() => {
-                const modelHint = str(ep.model_hint);
-                return modelHint !== undefined ? { modelHint } : {};
-            })(),
+            // No defaults argument: an endpoint has no harness whose shipped
+            // defaults it could fall back to. That absence is exactly why the CLI
+            // path could not simply reuse billingFields() — see route-fields.ts.
+            ...resolveSharedRouteFields(ep),
         };
         services[name] = svc;
     }
@@ -1040,19 +588,41 @@ export async function loadConfig(path, opts = {}) {
     const whichFn = opts.whichFn ?? defaultWhich;
     let raw = {};
     const unsetEnvVars = new Set();
+    const envRefs = new Map();
     if (path) {
         try {
             const text = await fs.readFile(path, "utf-8");
             const parsed = yaml.load(text);
             if (parsed && typeof parsed === "object") {
-                raw = interpolateTree(parsed, unsetEnvVars);
+                raw = interpolateTree(parsed, unsetEnvVars, envRefs);
             }
         }
         catch (err) {
-            // File not found -> auto-detect mode. Any other error -> rethrow.
             const e = err;
-            if (e.code !== "ENOENT")
+            if (e.code === "ENOENT") {
+                // configure names an OUTPUT path, so a file that is not there yet is
+                // its normal first run — it alone passes allowMissing.
+                if (opts.allowMissing === true) {
+                    // Fall through to auto-detect with an empty `raw`.
+                }
+                else {
+                    // Otherwise an explicit --config that does not exist is a typo, not
+                    // a request for auto-detection. Continuing printed a confident,
+                    // healthy route table built from defaults, so a mistyped path looked
+                    // like a working config. The implicit fallback (no path given at
+                    // all) never reaches here and is unchanged.
+                    throw new Error(`config file not found: ${path}. Check the path, or omit --config to ` +
+                        `auto-detect installed harness CLIs.`);
+                }
+            }
+            else if (err instanceof yaml.YAMLException) {
+                // A YAML syntax error used to escape as a raw js-yaml stack trace that
+                // never named the file it came from.
+                throw new Error(`config file ${path} is not valid YAML: ${err.message}`);
+            }
+            else {
                 throw err;
+            }
         }
     }
     const envVarWarning = unsetEnvVars.size > 0
@@ -1063,10 +633,16 @@ export async function loadConfig(path, opts = {}) {
     // Legacy full format: has a `services:` key -> use as-is.
     if (raw.services && typeof raw.services === "object") {
         const legacyCfg = buildLegacyConfig(raw);
+        const enumWarnings = [];
+        warnUnknownSafetyEnums(raw, enumWarnings);
+        if (enumWarnings.length > 0) {
+            legacyCfg.configWarnings = [...(legacyCfg.configWarnings ?? []), ...enumWarnings];
+        }
+        const withRefs = envRefs.size > 0 ? { ...legacyCfg, envRefs } : legacyCfg;
         if (envVarWarning !== undefined) {
-            return { ...legacyCfg, configWarnings: [...(legacyCfg.configWarnings ?? []), envVarWarning] };
+            return { ...withRefs, configWarnings: [...(withRefs.configWarnings ?? []), envVarWarning] };
         }
-        return legacyCfg;
+        return withRefs;
     }
     const disabled = Array.isArray(raw.disabled)
         ? raw.disabled.slice()
@@ -1090,13 +666,16 @@ export async function loadConfig(path, opts = {}) {
     const apiKeys = collectApiKeys(raw);
     const services = await detectServices(disabled, apiKeys, overrides, whichFn);
     addClis(services, raw, apiKeys, warnings);
-    addEndpoints(services, raw);
+    addEndpoints(services, raw, apiKeys, warnings);
+    warnUnknownSafetyEnums(raw, warnings);
+    warnUnknownTopLevelKeys(raw, warnings);
     if (envVarWarning !== undefined)
         warnings.push(envVarWarning);
     const cfg = {
         services,
         disabled,
-        ...topLevelSettings(raw),
+        ...topLevelSettings(raw, warnings),
+        ...(envRefs.size > 0 ? { envRefs } : {}),
         ...(warnings.length > 0 ? { configWarnings: warnings } : {}),
     };
     return cfg;
@@ -1196,7 +775,7 @@ function cliDefaultsFrom(raw, warnings) {
             ...(billingKind !== undefined ? { billingKind } : {}),
             ...(typeof raw.paid_usage_possible === "boolean" ? { paidUsagePossible: raw.paid_usage_possible } : {}),
             ...(() => {
-                const effectiveSafety = normalizeSafetyProfile(raw.effective_safety);
+                const effectiveSafety = effectiveSafetyFrom(raw.effective_safety);
                 return effectiveSafety !== undefined ? { effectiveSafety } : {};
             })(),
             ...(() => {