harness-dispatch 0.7.9 → 0.9.0

package/dist/config/validation.js

@@ -68,6 +68,9 @@ export const FAIL_OPEN_ENUMS = {
  */
 export const KNOWN_TOP_LEVEL_KEYS = new Set([
     "version",
+    // Opt back into auto-detection when a config defines its own routes, or
+    // opt out when it does not. See loadConfig for the three cases.
+    "detect",
     "clis",
     "endpoints",
     "services",
@@ -122,6 +125,203 @@ export function warnUnknownRouteKeys(entry, label, warnings) {
         warnings.push(`${label}: unknown key "${key}" — IGNORED. If this was meant to be a ` +
             `safety or workspace setting, it is NOT in effect; check the spelling.`);
     }
+    warnMistypedRouteValues(entry, label, warnings);
+}
+/** Recognised keys whose value must be a number, and what they mean if lost. */
+const NUMERIC_ROUTE_KEYS = new Set([
+    "tier",
+    "weight",
+    "cli_capability",
+    "max_output_tokens",
+    "max_input_tokens",
+    "timeout_ms",
+]);
+/**
+ * The smallest value each numeric route key can carry and still mean anything.
+ *
+ * Every one of these is positive-only, and being in range is not a style
+ * preference — the router multiplies three of them together
+ * (`quality * cli_capability * capability * quota * weight`) and orders by
+ * `tier` ASCENDING. A negative pair therefore does not degrade a route, it
+ * PROMOTES it: an acceptance pass measured `tier: -5, weight: -100,
+ * cli_capability: -3` scoring 299.8 against a normal route's 0.88, from a
+ * tier that sorts ahead of every real one — a route that wins every routing
+ * decision, silently, with no warning anywhere.
+ *
+ * `tier` starts at 1 because tier 1 is the frontier band and lower sorts
+ * first; 0 and below are ahead of a band that already means "best". The rest
+ * are exclusive of 0 (a zero weight or capability multiplies the score to
+ * nothing, and a zero timeout is not a timeout).
+ *
+ * No upper bounds. `cli_capability: 1.1` ships in this repo's own default
+ * config as deliberate tuning, so a cap would reject a documented value; the
+ * defect being fixed is sign, not magnitude.
+ */
+const NUMERIC_ROUTE_MINIMUMS = {
+    tier: { min: 1, exclusive: false },
+    weight: { min: 0, exclusive: true },
+    cli_capability: { min: 0, exclusive: true },
+    max_output_tokens: { min: 0, exclusive: true },
+    max_input_tokens: { min: 0, exclusive: true },
+    timeout_ms: { min: 0, exclusive: true },
+};
+/**
+ * Of those, the ones the router actually multiplies into a score.
+ *
+ * Only these three get the "PROMOTES the route" explanation. Giving that
+ * reason for `timeout_ms` or a token cap told the operator something untrue
+ * about their own config: routing multiplies neither.
+ */
+const ROUTING_SCORED_KEYS = new Set(["tier", "weight", "cli_capability"]);
+/** Recognised keys whose value must be a boolean. */
+const BOOLEAN_ROUTE_KEYS = new Set([
+    "enabled",
+    "paid_usage_possible",
+    "allow_paid_usage",
+    "stdin",
+]);
+/**
+ * Is this a value that reads as a USABLE number?
+ *
+ * Finite on both branches, and the string branch is the one that was wrong:
+ * `Number("1e999")` is `Infinity`, and `!Number.isNaN(Infinity)` is true, so a
+ * YAML `weight: 1e999` (which parses as a string, not a number) sailed through
+ * as "reads as a number", then sailed through the range check too — `Infinity`
+ * is not below any minimum. An acceptance pass measured it loading as
+ * `weight = Infinity` with NO warning of any kind.
+ *
+ * `Number.isFinite` on both branches closes that: `.inf`, `-.inf`, `.nan` and
+ * `1e999` are all unusable, whichever way YAML happened to type them.
+ */
+function readsAsNumber(v) {
+    if (typeof v === "number")
+        return Number.isFinite(v);
+    return typeof v === "string" && v !== "" && Number.isFinite(Number(v));
+}
+/**
+ * How to name the offending value back to the operator.
+ *
+ * `JSON.stringify` has no representation for the non-finite numbers and emits
+ * `null`, so a warning about YAML's `-.inf` read "tier is null" — naming a
+ * value that appears nowhere in the file the reader is being asked to fix.
+ */
+function describeValue(v) {
+    if (typeof v === "number" && !Number.isFinite(v))
+        return String(v);
+    return JSON.stringify(v);
+}
+/**
+ * A RECOGNISED key carrying the wrong TYPE of value.
+ *
+ * The unknown-key warner above covers a misspelled key. It does not cover a
+ * correctly-spelled one whose value cannot be read: the coercions in
+ * coercions.ts drop on mismatch and the caller supplies a default, silently.
+ * That file's own header names this gap and points at the unknown-key warning
+ * as the mitigation — which does not cover it, because the key is not unknown.
+ *
+ * Found live on the maintainer's machine by an acceptance pass: four routes
+ * carrying `tier: metered`, which is not a number, silently running at the
+ * default tier 3. Nothing had ever said so. `weight: very-high` becomes 1.0 the
+ * same way, and both feed routing decisions.
+ *
+ * Reports rather than rejects, like every other warning here: the config still
+ * loads, and `doctor` exits non-zero so the signal is not merely decorative.
+ *
+ * The one thing it does beyond reporting is DELETE an out-of-range numeric
+ * value from the entry, so the built-in default applies. That is not a second
+ * behaviour bolted on: a non-numeric `tier: metered` already ends up at the
+ * default, because `num()` cannot read it. `tier: -5` is different only in
+ * that the coercion CAN read it, which is exactly why it is dangerous — it
+ * reaches routing and wins. Deleting the key makes the two unusable cases
+ * behave the same way, which is what an operator reading either warning
+ * ("IGNORED, and the built-in default applies instead") is being told.
+ *
+ * Every caller warns before it parses the same object, so the deletion is
+ * visible to the parse that follows.
+ */
+export function warnMistypedRouteValues(entry, label, warnings) {
+    for (const [key, value] of Object.entries(entry)) {
+        if (value === null || value === undefined)
+            continue;
+        if (NUMERIC_ROUTE_KEYS.has(key) && !readsAsNumber(value)) {
+            // Per field, for the same reason the range branch varies its text: the
+            // routing sentence was emitted for all six keys, and routing does not
+            // read `timeout_ms` or the token caps. The very next acceptance pass
+            // found this branch still saying it after the other was fixed — the
+            // same defect one branch over, in one function.
+            warnings.push(`${label}: ${key} is ${describeValue(value)}, which is not a number — ` +
+                `IGNORED, and the built-in default applies instead. ` +
+                (ROUTING_SCORED_KEYS.has(key)
+                    ? `Routing reads this field, so the route is not behaving the way this ` +
+                        `line says it does.`
+                    : `The route runs with the built-in ${key}, not the one written here.`));
+            // This branch WARNED without neutralising, and for a plain unreadable
+            // value that was harmless — `num()` returns the default anyway, so the
+            // warning was true by accident. `.inf` and `.nan` are `typeof "number"`,
+            // so `num()` hands them straight back: the route loaded at
+            // `tier=-Infinity, weight=Infinity` — ahead of every tier and above
+            // every score — underneath a warning reading "IGNORED, and the built-in
+            // default applies instead". The message asserted the opposite of what
+            // happened, which is worse than the silence it replaced.
+            delete entry[key];
+        }
+        else if (NUMERIC_ROUTE_KEYS.has(key)) {
+            const bound = NUMERIC_ROUTE_MINIMUMS[key];
+            const n = Number(value);
+            if (bound !== undefined && (bound.exclusive ? n <= bound.min : n < bound.min)) {
+                // The consequence differs by field, and stating the routing one for
+                // all six was simply false: routing does not multiply `timeout_ms` or
+                // the token caps. A warning that explains the wrong mechanism teaches
+                // the reader something untrue about their own config.
+                const consequence = ROUTING_SCORED_KEYS.has(key)
+                    ? `Routing multiplies these fields and orders tiers ascending, so a ` +
+                        `negative one PROMOTES the route over every other rather than demoting it.`
+                    : `A value at or below ${bound.min} here does not mean "no limit"; it ` +
+                        `describes a route that can never do any work.`;
+                warnings.push(`${label}: ${key} is ${describeValue(value)}, which is below the minimum ` +
+                    `of ${bound.min}${bound.exclusive ? " (exclusive)" : ""} — IGNORED, and the ` +
+                    `built-in default applies instead. ${consequence}`);
+                delete entry[key];
+            }
+        }
+        if (BOOLEAN_ROUTE_KEYS.has(key) && typeof value !== "boolean") {
+            // A quoted "true"/"false" is accepted by bool() and is not a mistake
+            // worth reporting; anything else selects the default silently.
+            if (value === "true" || value === "false")
+                continue;
+            warnings.push(`${label}: ${key} is ${describeValue(value)}, which is not true or false — ` +
+                `IGNORED, and the built-in default applies instead.`);
+        }
+    }
+}
+/**
+ * Two route entries sharing one name.
+ *
+ * The later entry wins outright, so everything the earlier one declared is
+ * gone. An acceptance pass measured the consequence: a first entry setting
+ * `safety_profile: read_only` and `workspace_policy: copy` was replaced by a
+ * second with neither, and the surviving route ran `workspace_edit` /
+ * `shared_locked` — silently LESS restrictive than what was written, with no
+ * warning on any surface.
+ */
+export function warnDuplicateRouteNames(names, block, warnings) {
+    const seen = new Set();
+    const reported = new Set();
+    for (const name of names) {
+        if (name === undefined || name === "")
+            continue;
+        if (!seen.has(name)) {
+            seen.add(name);
+            continue;
+        }
+        if (reported.has(name))
+            continue;
+        reported.add(name);
+        warnings.push(`${block}: "${name}" is declared more than once — only the LAST entry ` +
+            `survives, and every field the earlier one set is discarded, including ` +
+            `safety_profile and workspace_policy. If the earlier entry restricted ` +
+            `this route, that restriction is NOT in effect.`);
+    }
 }
 /**
  * Keys the parser ACCEPTS and nothing reads.
@@ -133,8 +333,22 @@ export function warnUnknownRouteKeys(entry, label, warnings) {
  *
  * Verified read-nowhere in src/ at the time of writing; if one is implemented
  * later, delete it from here and the warning goes away.
+ *
+ * `policy` and `workspace_policy` were added after an acceptance pass found
+ * them allow-listed at top level and read nowhere — top-level isolation
+ * controls that do nothing, the same shape as `default_safety_profile` above.
+ * Both names ARE real per-route keys (see KNOWN_ROUTE_KEYS), which is what
+ * makes the top-level spelling plausible enough to write by mistake: it looks
+ * like a global default for the per-route setting, and there is no such thing.
+ * Re-verified read-nowhere at top level on 2026-08-31 — `raw?.policy` in
+ * jobs.ts reads a JOB MANIFEST, not this config file.
  */
-const ACCEPTED_BUT_UNIMPLEMENTED = new Set(["protocols", "default_safety_profile"]);
+const ACCEPTED_BUT_UNIMPLEMENTED = new Set([
+    "protocols",
+    "default_safety_profile",
+    "policy",
+    "workspace_policy",
+]);
 export function warnUnknownTopLevelKeys(raw, warnings) {
     for (const key of Object.keys(raw)) {
         if (ACCEPTED_BUT_UNIMPLEMENTED.has(key)) {

package/dist/config/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/config/validation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/config/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAsC;IAChE,wEAAwE;IACxE,wEAAwE;IACxE,4EAA4E;IAC5E,yEAAyE;IACzE,sEAAsE;IACtE,6EAA6E;IAC7E,WAAW;IACX,YAAY,EAAE;QACZ,eAAe;QACf,qBAAqB;QACrB,qCAAqC;QACrC,uCAAuC;QACvC,+BAA+B;QAC/B,aAAa;QACb,YAAY;QACZ,SAAS;KACV;IACD,kBAAkB,EAAE,CAAC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,CAAC;IACxE,cAAc,EAAE,CAAC,WAAW,EAAE,gBAAgB,EAAE,WAAW,CAAC;IAC5D,gBAAgB,EAAE,CAAC,WAAW,EAAE,gBAAgB,EAAE,WAAW,CAAC;IAC9D,gBAAgB,EAAE,CAAC,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,CAAC;CACtE,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC;IAC1C,SAAS;IACT,wEAAwE;IACxE,gEAAgE;IAChE,QAAQ;IACR,MAAM;IACN,WAAW;IACX,UAAU;IACV,UAAU;IACV,WAAW;IACX,UAAU;IACV,WAAW;IACX,QAAQ;IACR,WAAW;IACX,WAAW;IACX,aAAa;IACb,qBAAqB;IACrB,wBAAwB;IACxB,kBAAkB;IAClB,UAAU;CACX,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IACtC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY;IAChF,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY;IAChE,kBAAkB,EAAE,mBAAmB,EAAE,gBAAgB;IACzD,mBAAmB,EAAE,gBAAgB,EAAE,aAAa,EAAE,iBAAiB;IACvE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ;IAC3C,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,oBAAoB;IAC1E,eAAe,EAAE,qBAAqB,EAAE,kBAAkB;IAC1D,gBAAgB,EAAE,kBAAkB,EAAE,kBAAkB;IACxD,eAAe,EAAE,mBAAmB,EAAE,eAAe;CACtD,CAAC,CAAC;AAEH,MAAM,UAAU,oBAAoB,CAClC,KAA8B,EAC9B,KAAa,EACb,QAAkB;IAElB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,IAAI,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QACxC,QAAQ,CAAC,IAAI,CACX,GAAG,KAAK,kBAAkB,GAAG,yCAAyC;YACpE,uEAAuE,CAC1E,CAAC;IACJ,CAAC;IACD,uBAAuB,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AAClD,CAAC;AAED,gFAAgF;AAChF,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,MAAM;IACN,QAAQ;IACR,gBAAgB;IAChB,mBAAmB;IACnB,kBAAkB;IAClB,YAAY;CACb,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,sBAAsB,GAAwD;IAClF,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE;IAClC,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;IACnC,cAAc,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;IAC3C,iBAAiB,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;IAC9C,gBAAgB,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;IAC7C,UAAU,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;CACxC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAE1E,qDAAqD;AACrD,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,SAAS;IACT,qBAAqB;IACrB,kBAAkB;IAClB,OAAO;CACR,CAAC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,SAAS,aAAa,CAAC,CAAU;IAC/B,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACrD,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,CAAU;IAC/B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAA8B,EAC9B,KAAa,EACb,QAAkB;IAElB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QACpD,IAAI,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;YACzD,uEAAuE;YACvE,sEAAsE;YACtE,qEAAqE;YACrE,oEAAoE;YACpE,gDAAgD;YAChD,QAAQ,CAAC,IAAI,CACX,GAAG,KAAK,KAAK,GAAG,OAAO,aAAa,CAAC,KAAK,CAAC,4BAA4B;gBACrE,qDAAqD;gBACrD,CAAC,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC;oBAC3B,CAAC,CAAC,sEAAsE;wBACtE,oBAAoB;oBACtB,CAAC,CAAC,oCAAoC,GAAG,6BAA6B,CAAC,CAC5E,CAAC;YACF,sEAAsE;YACtE,uEAAuE;YACvE,yEAAyE;YACzE,2DAA2D;YAC3D,oEAAoE;YACpE,wEAAwE;YACxE,sEAAsE;YACtE,yDAAyD;YACzD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;aAAM,IAAI,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACvC,MAAM,KAAK,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;YAC1C,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YACxB,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC9E,oEAAoE;gBACpE,sEAAsE;gBACtE,sEAAsE;gBACtE,sDAAsD;gBACtD,MAAM,WAAW,GAAG,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC;oBAC9C,CAAC,CAAC,mEAAmE;wBACnE,2EAA2E;oBAC7E,CAAC,CAAC,uBAAuB,KAAK,CAAC,GAAG,qCAAqC;wBACrE,+CAA+C,CAAC;gBACpD,QAAQ,CAAC,IAAI,CACX,GAAG,KAAK,KAAK,GAAG,OAAO,aAAa,CAAC,KAAK,CAAC,+BAA+B;oBACxE,MAAM,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,sBAAsB;oBAC7E,qCAAqC,WAAW,EAAE,CACrD,CAAC;gBACF,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;QACD,IAAI,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;YAC9D,qEAAqE;YACrE,+DAA+D;YAC/D,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,OAAO;gBAAE,SAAS;YACpD,QAAQ,CAAC,IAAI,CACX,GAAG,KAAK,KAAK,GAAG,OAAO,aAAa,CAAC,KAAK,CAAC,iCAAiC;gBAC1E,oDAAoD,CACvD,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAgC,EAChC,KAAa,EACb,QAAkB;IAElB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE;YAAE,SAAS;QAChD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACf,SAAS;QACX,CAAC;QACD,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACjC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnB,QAAQ,CAAC,IAAI,CACX,GAAG,KAAK,MAAM,IAAI,qDAAqD;YACrE,wEAAwE;YACxE,uEAAuE;YACvE,gDAAgD,CACnD,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,0BAA0B,GAAG,IAAI,GAAG,CAAC;IACzC,WAAW;IACX,wBAAwB;IACxB,QAAQ;IACR,kBAAkB;CACnB,CAAC,CAAC;AAEH,MAAM,UAAU,uBAAuB,CAAC,GAA4B,EAAE,QAAkB;IACtF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,0BAA0B,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACxC,QAAQ,CAAC,IAAI,CACX,GAAG,GAAG,+DAA+D;gBACnE,gDAAgD,CACnD,CAAC;YACF,SAAS;QACX,CAAC;QACD,IAAI,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5C,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC;YAAE,SAAS,CAAC,iCAAiC;QACzE,QAAQ,CAAC,IAAI,CACX,iCAAiC,GAAG,yCAAyC;YAC3E,wBAAwB,CAAC,GAAG,oBAAoB,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CACpF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,IAAa,EAAE,QAAkB,EAAE,KAAK,GAAG,EAAE;IAClF,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE;YAAE,sBAAsB,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3F,OAAO;IACT,CAAC;IACD,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO;IACtD,MAAM,GAAG,GAAG,IAA+B,CAAC;IAC5C,MAAM,KAAK,GACT,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,QAAQ,CAAC;IACzF,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;QAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,SAAS;QACnE,uEAAuE;QACvE,sEAAsE;QACtE,oCAAoC;QACpC,IAAI,GAAG,KAAK,kBAAkB,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACvG,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,CAAC;YACjE,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CACxB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAClF,CAAC;YACF,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAC/B,QAAQ,CAAC,IAAI,CACX,GAAG,KAAK,uBAAuB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBAC5F,YAAY,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,qCAAqC,CACrE,CAAC;YACF,SAAS;QACX,CAAC;QACD,QAAQ,CAAC,IAAI,CACX,GAAG,KAAK,KAAK,GAAG,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,kBAAkB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YACjF,gFAAgF;YAChF,qDAAqD,CACxD,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,sBAAsB,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,CAAC;AACH,CAAC"}

package/dist/config.d.ts

@@ -49,8 +49,10 @@ export interface LoadConfigOptions {
  */
 /**
  * The config file a process should load: an explicit `--config`, else
- * `HARNESS_DISPATCH_CONFIG`, else `./config.yaml` if it exists, else nothing
- * (auto-detect).
+ * `HARNESS_DISPATCH_CONFIG`, else `./config.yaml` if it exists, else the
+ * state directory's `config.yaml` (where `configure` writes) if it exists,
+ * else nothing (auto-detect). The current directory stays ahead of the user
+ * file so a per-project config still wins when one is present.
  *
  * ONE function because there used to be two, and they disagreed. job-runner.ts
  * read the environment variable and bin.ts did not, while job-runner's own

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA6BH,2EAA2E;AAC3E,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AA+B9D,OAAO,KAAK,EAOV,iBAAiB,EAGjB,YAAY,EAOb,MAAM,YAAY,CAAC;AAsEpB,iKAAiK;AACjK,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAI9D,CAAC;AAQF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAKvD,CAAC;AA0lBF,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKvE;AAED,wBAAsB,UAAU,CAC9B,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAkHvB;AAMD,MAAM,WAAW,aAAa;IAC5B,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,EACnC,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GACpD,aAAa,CAkCf"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAgCH,2EAA2E;AAC3E,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AA+B9D,OAAO,KAAK,EAOV,iBAAiB,EAGjB,YAAY,EAOb,MAAM,YAAY,CAAC;AAsEpB,iKAAiK;AACjK,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAI9D,CAAC;AAQF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAKvD,CAAC;AAooBF,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOvE;AAED,wBAAsB,UAAU,CAC9B,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAuNvB;AAMD,MAAM,WAAW,aAAa;IAC5B,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,EACnC,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GACpD,aAAa,CAkCf"}

package/dist/config.js

@@ -13,13 +13,14 @@
  * the corresponding environment variable.
  */
 import { existsSync, readFileSync, promises as fs } from "node:fs";
+import { userConfigPath } from "./state-dir.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import yaml from "js-yaml";
 import which from "which";
 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 { warnDuplicateRouteNames, warnMistypedRouteValues, warnUnknownRouteKeys, warnUnknownSafetyEnums, warnUnknownTopLevelKeys, } from "./config/validation.js";
 import { parseProtocolFields, protocolFrom, stringArrayFrom } from "./config/protocol.js";
 import { effectiveSafetyFrom, resolveSharedRouteFields, } from "./config/route-fields.js";
 import { ENV_VAR_RE, interpolateTree } from "./config/env-interpolation.js";
@@ -237,6 +238,31 @@ function buildLegacyConfig(raw) {
     const services = {};
     const rawServices = (raw.services ?? {});
     const warnings = [];
+    // `services:` must be a MAP of route id -> settings, but `typeof [] ===
+    // "object"`, so a list slips through and Object.entries turns it into routes
+    // called "0", "1", … with each item's `name:` silently ignored. Everything
+    // then looks healthy — doctor reports the routes, status lists them — right
+    // up until `--service my_route` answers "Unknown service".
+    //
+    // The mistake is a natural one rather than carelessness: the sibling
+    // top-level keys `clis:` and `endpoints:` ARE lists, and their items DO
+    // carry `name:`. Found by an acceptance pass; it predates the work that pass
+    // was reviewing.
+    if (Array.isArray(raw.services)) {
+        const intended = raw.services
+            .map((e) => (e !== null && typeof e === "object" ? e.name : undefined))
+            .filter((n) => typeof n === "string" && n !== "");
+        const got = Object.keys(rawServices);
+        warnings.push(`services: is a LIST, but it must be a map of route id to settings. Its ` +
+            `${got.length} entr${got.length === 1 ? "y" : "ies"} became route id${got.length === 1 ? "" : "s"} ` +
+            `${got.join(", ")}` +
+            (intended.length > 0
+                ? `, and each item's name: (${intended.join(", ")}) was ignored — so anything ` +
+                    `referring to a route by name will not find it`
+                : "") +
+            `. Write it as \`services:\` then \`  <id>:\` per route (unlike clis: and ` +
+            `endpoints:, which ARE lists).`);
+    }
     // A top-level `services:` key selects the legacy parser entirely — it
     // never looks at clis:/endpoints:/overrides:, so any of those sitting
     // alongside it are silently dropped unless we say so here. The likely
@@ -251,6 +277,18 @@ function buildLegacyConfig(raw) {
             `clis:/endpoints:/overrides: exclusively (see the shipped config.default.yaml).`);
     }
     for (const [name, svc] of Object.entries(rawServices)) {
+        // The legacy shape gets the same value checks as `clis:` and `endpoints:`.
+        //
+        // It got neither: both validators were wired into the two modern loops and
+        // not this one, so a `services:` config — still supported, still what an
+        // older `configure` wrote — reported one warning where the modern shape
+        // reports four. A delegate audit found the asymmetry.
+        //
+        // Deliberately only the VALUE checks. The unknown-KEY warner is not called
+        // here because the legacy shape accepts a wider set of keys than
+        // KNOWN_ROUTE_KEYS lists, and reporting those as typos would be worse than
+        // the silence it replaces.
+        warnMistypedRouteValues(svc, `services."${name}"`, warnings);
         const type = (str(svc.type) ?? "cli");
         // Computed once and reused below for both max-tokens fallback and the
         // billing/safety/model-hint inheritance IIFE — legacy-format entries
@@ -448,6 +486,7 @@ async function detectServices(disabled, apiKeys, overrides, whichFn) {
  */
 function addClis(services, raw, apiKeys, warnings) {
     const clis = Array.isArray(raw.clis) ? raw.clis : [];
+    warnDuplicateRouteNames(clis.map((e) => str(e.name)), "clis", warnings);
     for (const [index, entry] of clis.entries()) {
         const name = str(entry.name);
         const harness = str(entry.harness);
@@ -558,6 +597,7 @@ function addEndpoints(services, raw, apiKeys, warnings = []) {
     const endpoints = Array.isArray(raw.endpoints)
         ? raw.endpoints
         : [];
+    warnDuplicateRouteNames(endpoints.map((e) => str(e.name)), "endpoints", warnings);
     for (const [index, ep] of endpoints.entries()) {
         const name = str(ep.name);
         warnUnknownRouteKeys(ep, `endpoints[${index}] "${name ?? "?"}"`, warnings);
@@ -633,8 +673,10 @@ function addEndpoints(services, raw, apiKeys, warnings = []) {
  */
 /**
  * The config file a process should load: an explicit `--config`, else
- * `HARNESS_DISPATCH_CONFIG`, else `./config.yaml` if it exists, else nothing
- * (auto-detect).
+ * `HARNESS_DISPATCH_CONFIG`, else `./config.yaml` if it exists, else the
+ * state directory's `config.yaml` (where `configure` writes) if it exists,
+ * else nothing (auto-detect). The current directory stays ahead of the user
+ * file so a per-project config still wins when one is present.
  *
  * ONE function because there used to be two, and they disagreed. job-runner.ts
  * read the environment variable and bin.ts did not, while job-runner's own
@@ -656,7 +698,10 @@ export function resolveConfigPath(explicit) {
     const fromEnv = process.env["HARNESS_DISPATCH_CONFIG"];
     if (fromEnv !== undefined && fromEnv !== "")
         return fromEnv;
-    return existsSync("config.yaml") ? "config.yaml" : undefined;
+    if (existsSync("config.yaml"))
+        return "config.yaml";
+    const user = userConfigPath();
+    return existsSync(user) ? user : undefined;
 }
 export async function loadConfig(path, opts = {}) {
     const whichFn = opts.whichFn ?? defaultWhich;
@@ -715,6 +760,12 @@ export async function loadConfig(path, opts = {}) {
         const legacyCfg = buildLegacyConfig(raw);
         const enumWarnings = [];
         warnUnknownSafetyEnums(raw, enumWarnings);
+        // The legacy shape returns before the modern path's top-level key check
+        // ever runs, so the same `policy: copy` that warns twice in a `clis:`
+        // config warned about nothing here. An acceptance pass reproduced the two
+        // shapes side by side. The check is about the top level of the FILE, which
+        // both shapes have; only route-entry validation is format-specific.
+        warnUnknownTopLevelKeys(raw, enumWarnings);
         if (enumWarnings.length > 0) {
             legacyCfg.configWarnings = [...(legacyCfg.configWarnings ?? []), ...enumWarnings];
         }
@@ -741,14 +792,95 @@ export async function loadConfig(path, opts = {}) {
                 `before a route rename, the route it used to refer to is no longer disabled.`);
         }
     }
-    for (const name of Object.keys(overrides)) {
+    for (const [name, entry] of Object.entries(overrides)) {
         if (!knownAutoDetectNames.has(name)) {
             warnings.push(`overrides.${name}: doesn't match any auto-detected route (expected one of: ` +
                 `${[...knownAutoDetectNames].join(", ")}) — ignored, none of these settings were applied.`);
+            continue;
+        }
+        // `overrides:` gets the same value checks as the three route shapes.
+        //
+        // It was left out when they were added, and it is the block most likely to
+        // carry exactly the fields the check exists for: config.default.yaml
+        // presents `overrides:` as the way to "tweak auto-detected service defaults
+        // without writing a full config", naming tier and weight. An acceptance
+        // pass measured `overrides: { claude_code_cli: { tier: metered, weight:
+        // very-high, enabled: yes-please } }` producing ZERO warnings while none of
+        // it applied. The enum walk already reached here; only the numeric,
+        // boolean and unknown-key checks stopped at the block boundary.
+        if (entry !== null && typeof entry === "object") {
+            warnUnknownRouteKeys(entry, `overrides.${name}`, warnings);
         }
     }
     const apiKeys = collectApiKeys(raw);
-    const services = await detectServices(disabled, apiKeys, overrides, whichFn);
+    // A CONFIG FILE THAT DEFINES ROUTES IS AUTHORITATIVE about them.
+    //
+    // Detection used to run unconditionally, so `clis: []` did NOT isolate a
+    // config from the harnesses installed on the machine — the file added to
+    // auto-detection rather than replacing it, and only `disabled:` (naming
+    // every route, including ones you might not know existed) subtracted. That
+    // default caught three acceptance passes in a row DESPITE explicit warnings,
+    // and caught this project's own test suite: one boundary test dispatched to
+    // the real Claude Code CLI on every `npm test` and every CI run, measured at
+    // 6.4s and 47k input tokens, under a comment asserting it could not reach a
+    // route. When a default surprises the maintainer, the reviewers, and the
+    // product's own tests, it is a least-surprise violation rather than a
+    // convenience.
+    //
+    // It also decayed: a future release adding a fifth supported harness would
+    // auto-add it to every existing config, so a `disabled:` list written today
+    // silently stops isolating tomorrow.
+    //
+    // The legacy `services:` format has ALWAYS been authoritative (it returns
+    // above without calling detection), so this makes the two shapes agree
+    // rather than inventing a rule.
+    //
+    // Three cases, and the third is what keeps the migration safe:
+    //   detect: true/false   — explicit, always wins.
+    //   file defines routes  — authoritative; detection off.
+    //   file defines NO routes — detection ON, with a warning. A file carrying
+    //     only `overrides:`/`disabled:`/settings exists to TUNE detection; it
+    //     cannot be authoritative about routes it does not describe, and
+    //     switching detection off for it would leave such a user with nothing.
+    // PRESENCE of the key, not a non-empty list. `clis: []` is someone writing
+    // down "no CLI routes" — an opinion about routes, and the most explicit one
+    // available. Requiring a non-empty array meant `clis: []` still loaded every
+    // harness on the machine, which is the precise failure the comment above
+    // describes in the past tense. An acceptance pass caught the contradiction:
+    // `clis: []` returned all four real CLIs, so the fix did not cover its own
+    // motivating example, and this project's test suite still leans on
+    // `disabled:` naming every route to stay off them.
+    const definesRoutes = Array.isArray(raw.clis) || Array.isArray(raw.endpoints);
+    // A `clis:` written as a MAPPING rather than a list is the same silent-drop
+    // class this module exists to prevent, and it fails in the worst direction:
+    // the entries vanish, `definesRoutes` is false, detection runs, and the user
+    // who was trying to name their own routes gets every installed paid harness
+    // instead — under a warning telling them their config "defines no routes",
+    // which contradicts the file in front of them.
+    for (const key of ["clis", "endpoints"]) {
+        const value = raw[key];
+        if (value !== undefined && value !== null && !Array.isArray(value)) {
+            warnings.push(`${key}: must be a LIST, but this config has ${typeof value === "object" ? "a mapping" : `a ${typeof value}`} — every entry under it was IGNORED. Write it as \`${key}:\` followed by ` +
+                `\`  - name: ...\` items. As written this config defines no ${key} at all.`);
+        }
+    }
+    const detectRequested = typeof raw.detect === "boolean" ? raw.detect : undefined;
+    const detect = detectRequested ?? !definesRoutes;
+    if (detectRequested === undefined && !definesRoutes && Object.keys(raw).length > 0) {
+        warnings.push("this config defines no routes of its own (no `clis:` or `endpoints:` entries), so " +
+            "installed harness CLIs are still auto-detected and added. That is the old default " +
+            "and it still applies here; a config that DOES define routes is now authoritative " +
+            "and detection is off for it. Say `detect: true` to keep this explicit, or " +
+            "`detect: false` to run with no routes at all.");
+    }
+    const services = detect
+        ? await detectServices(disabled, apiKeys, overrides, whichFn)
+        : {};
+    if (!detect && (disabled.length > 0 || Object.keys(overrides).length > 0)) {
+        warnings.push("`disabled:` and `overrides:` apply to AUTO-DETECTED routes, and this config is " +
+            "authoritative (it defines its own routes), so detection is off and neither had any " +
+            "effect. Remove them, or add `detect: true` if you also want detected routes.");
+    }
     addClis(services, raw, apiKeys, warnings);
     addEndpoints(services, raw, apiKeys, warnings);
     warnUnknownSafetyEnums(raw, warnings);
@@ -758,6 +890,11 @@ export async function loadConfig(path, opts = {}) {
     const cfg = {
         services,
         disabled,
+        // Only when the file SAID so. Carrying the resolved value instead would
+        // make `configure` write `detect: true` into every config that merely
+        // omitted it, turning a default into a permanent declaration.
+        ...(detectRequested !== undefined ? { detect: detectRequested } : {}),
+        detectionRan: detect,
         ...topLevelSettings(raw, warnings),
         ...(envRefs.size > 0 ? { envRefs } : {}),
         ...(apiKeyRefs.size > 0 ? { apiKeyRefs } : {}),