harness-dispatch 0.4.0 → 0.5.0

package/dist/config.js

@@ -18,6 +18,41 @@ 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, confidenceFrom, endpointModeFrom, endpointProviderFrom, inferEndpointProvider, int, num, providerFrom, str, surfaceFrom, thinkingFrom, wireProtocolFrom, workspacePolicyFrom, } from "./config/coercions.js";
+import { warnUnknownRouteKeys, warnUnknownSafetyEnums, warnUnknownTopLevelKeys, } from "./config/validation.js";
+import { parseProtocolFields, protocolFrom, stringArrayFrom } from "./config/protocol.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,8 +157,46 @@ 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.
+ */
+function effectiveSafetyFrom(raw) {
+    const single = normalizeSafetyProfile(raw);
+    if (single !== undefined)
+        return single;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const requested = normalizeSafetyProfile(key);
+        const floor = normalizeSafetyProfile(value);
+        if (requested !== undefined && floor !== undefined)
+            out[requested] = floor;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 function billingFields(raw) {
     const out = {};
     const provider = providerFrom(raw.provider);
@@ -350,6 +225,16 @@ function billingFields(raw) {
         out.billingNotes = notes;
     if (safetyProfile !== undefined)
         out.safetyProfile = safetyProfile;
+    // effective_safety was handled by the `clis:` builder and the legacy
+    // `services:` path but not here, so an `endpoints:` entry declaring it was
+    // silently ignored — the fourth instance of this file's parallel-field-list
+    // defect, and the first one caught by a test rather than by a user or a
+    // reviewer. Practically fail-safe (openai_compatible routes are read_only by
+    // construction, so the ignored value could only have widened them), but the
+    // inconsistency is the bug.
+    const effectiveSafety = effectiveSafetyFrom(raw.effective_safety);
+    if (effectiveSafety !== undefined)
+        out.effectiveSafety = effectiveSafety;
     const workspacePolicy = workspacePolicyFrom(raw.workspace_policy);
     if (workspacePolicy !== undefined)
         out.workspacePolicy = workspacePolicy;
@@ -374,276 +259,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)
 // ---------------------------------------------------------------------------
@@ -733,7 +348,7 @@ function buildLegacyConfig(raw) {
             })(),
             ...billingFields(svc),
             ...(() => {
-                const effectiveSafety = normalizeSafetyProfile(svc.effective_safety);
+                const effectiveSafety = effectiveSafetyFrom(svc.effective_safety);
                 return effectiveSafety !== undefined ? { effectiveSafety } : {};
             })(),
             ...(() => {
@@ -752,7 +367,7 @@ function buildLegacyConfig(raw) {
                 // 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 +378,7 @@ function buildLegacyConfig(raw) {
         ...(Array.isArray(raw.disabled)
             ? { disabled: raw.disabled.slice() }
             : {}),
-        ...topLevelSettings(raw),
+        ...topLevelSettings(raw, warnings),
         ...(warnings.length > 0 ? { configWarnings: warnings } : {}),
     };
     return cfg;
@@ -834,11 +449,27 @@ 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"
@@ -857,7 +488,19 @@ function buildCliServiceConfig(name, defaults, override, apiKeys, warnings = [])
             return safetyProfile !== undefined ? { safetyProfile } : {};
         })(),
         ...(() => {
-            const effectiveSafety = normalizeSafetyProfile(override.effective_safety) ?? defaults.effectiveSafety;
+            // `clis:` entries never read this. It was handled for `services:` and
+            // `endpoints:` (both go through billingFields, which this builder does
+            // not call), so `workspace_policy: copy` on the primary, documented way
+            // to define a route was silently dropped and the route fell back to
+            // shared_locked — the LESS isolated default, with no warning, because
+            // the value itself is perfectly valid. The fail-open enum check added
+            // earlier cannot catch this: the key is right and the value is right;
+            // nothing was reading it.
+            const workspacePolicy = workspacePolicyFrom(override.workspace_policy);
+            return workspacePolicy !== undefined ? { workspacePolicy } : {};
+        })(),
+        ...(() => {
+            const effectiveSafety = effectiveSafetyFrom(override.effective_safety) ?? defaults.effectiveSafety;
             return effectiveSafety !== undefined ? { effectiveSafety } : {};
         })(),
         ...(() => {
@@ -875,7 +518,7 @@ function buildCliServiceConfig(name, defaults, override, apiKeys, warnings = [])
             // 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 +526,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 +573,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 +600,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 +625,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 +655,30 @@ 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) }
                 : {}),
+            // escalate_on was honoured here and escalate_model was not — the fifth
+            // instance of this file's parallel-field-list defect, and the second
+            // found by review rather than by the parity test, which pins 16 shared
+            // keys and did not include this one. It does now.
+            ...(str(ep.escalate_model) !== undefined
+                ? { escalateModel: str(ep.escalate_model) }
+                : {}),
             escalateOn: escalateOnFrom(ep.escalate_on),
             capabilities: capsFrom(ep.capabilities),
             ...billingFields({
@@ -1040,19 +727,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 +772,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 +805,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 +914,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 } : {};
             })(),
             ...(() => {