audit-tools 0.32.68 → 0.33.1

package/dist/shared/providers/sharedProviderConfirmation.js

@@ -2,41 +2,51 @@
  * DC-2 — shared, session-scoped provider confirmation (Gate-0).
  *
  * The design wants ONE provider confirmation spanning an audit→remediate run:
- * the first tool to run writes the confirmed provider pool to a SHARED artifact
- * at `<root>/.audit-tools/provider-confirmation.json` (NOT the per-tool audit
- * artifacts dir); the second tool reads and honors it unless the roster has
- * since changed. "Session" = the shared `.audit-tools` dir for that repo+run, so
- * no new identity scheme is needed.
- *
- * Two invariants are in tension and are reconciled here by the CE-012 third
- * state:
- *   - INV-DC1-6 (never-block): remediate run standalone with no prior audit must
- *     resolve its provider independently, exactly as today — absence of the
- *     artifact is NOT an error.
- *   - INV-DC2-3 (roster-stale-re-confirm): a confirmation whose discovered roster
- *     no longer matches the current one must NOT be silently honored (it could
- *     pin a provider that has since disappeared) — it must re-confirm.
- * A single `null` return cannot carry both meanings (CE-012). So the accessor
- * returns a THREE-valued result: `null` for absent/malformed (never-block),
- * `{ status: 'confirmed' }` for a fresh honor, and the DISTINCT
- * `{ status: 'reconfirm' }` for roster-stale — so honoring INV-DC2-3 no longer
- * contradicts INV-DC1-6.
+ * the first tool to run writes the operator's confirmed route DECISION to a
+ * SHARED artifact at `<root>/.audit-tools/provider-confirmation.json` (NOT the
+ * per-tool audit artifacts dir); the second tool reads and honors it. "Session" =
+ * the shared `.audit-tools` dir for that repo+run, so no new identity scheme is
+ * needed.
+ *
+ * **What this artifact carries is POLICY, not reach (G3).** The operator's
+ * decision — exclusions, cost order, λ — is a set of *rules*, valid for any
+ * auditor. What is *reachable* is per-auditor capability and is re-resolved from
+ * live env/PATH at the moment of use, never inherited from whoever wrote this
+ * file. So every read here is reach-free: it returns the persisted decision and
+ * nothing else.
+ *
+ * INV-DC1-6 (never-block) is the only invariant left in tension, and it now
+ * resolves to a plain two-valued read: a remediate run standalone with no prior
+ * audit resolves its provider independently — absence or corruption of the
+ * artifact is NOT an error, it is `null`.
+ *
+ * The former roster-staleness check (and its CE-012 three-valued `reconfirm`
+ * state) is GONE. It compared the *writing* auditor's roster against the reader's
+ * — meaningless cross-auditor by construction — and answered a real event (a
+ * backend the operator never confirmed became reachable) by silently discarding
+ * the operator's cost order and λ, while reaching no obligation at all. The
+ * `autonomous_mode`-keyed reconciliation gate
+ * ({@link computeNewlyReachableBackends}) replaces it: it compares the operator's
+ * DECISION against *this* auditor's freshly-resolved reach, which is well-defined
+ * across auditors, and it actually fires.
  *
  * CE-003 (lockless read races the writer rename): writes go through the shared
  * atomic writer (temp + atomic rename) under `withFileLock`, so a lockless
  * reader always observes either the complete old file or the complete new file —
  * never a torn intermediate.
  *
- * PB-1 (opencode opt-in): the roster is derived from `discoverProviders`, which
- * already withholds a bare-PATH opencode unless it is explicitly configured, so
- * the shared confirmation inherits that opt-in for free.
+ * PB-1 (opencode opt-in): the confirmed pool is derived from `discoverProviders`,
+ * which already withholds a bare-PATH opencode unless it is explicitly
+ * configured, so the shared confirmation inherits that opt-in for free.
  */
-import { mkdir } from "node:fs/promises";
+import { mkdir, unlink } from "node:fs/promises";
 import { join } from "node:path";
+import { PROVIDER_NAMES } from "../types/sessionConfig.js";
+import { isSelfSpawnBlocked } from "./providerPathGuard.js";
 import { auditToolsDir } from "../io/auditToolsPaths.js";
 import { readJsonFile, writeJsonFile } from "../io/json.js";
 import { withFileLock } from "../quota/fileLock.js";
-import { discoverProviders, annotateConfirmedPool, } from "./providerConfirmation.js";
+import { discoverProviders, annotateConfirmedPool, representativeModelId, } from "./providerConfirmation.js";
 import { resolveConfirmedCostPositions } from "../dispatch/costRank.js";
 import { PROVIDER_CONFIRMATION_INPUT_VERSION } from "../types/providerConfirmation.js";
 // ---------------------------------------------------------------------------
@@ -45,8 +55,8 @@ import { PROVIDER_CONFIRMATION_INPUT_VERSION } from "../types/providerConfirmati
 /**
  * Schema version for the shared confirmation artifact. Bumped independently of
  * the per-tool seam contract (PROVIDER_CONFIRMATION_RESULT_VERSION) — this is
- * the cross-tool session artifact, a distinct shape that also carries the
- * roster snapshot used for staleness.
+ * the cross-tool session artifact carrying the operator's route DECISION
+ * (exclusions, cost order, λ), a distinct shape from the seam's pool snapshot.
  */
 export const SHARED_PROVIDER_CONFIRMATION_VERSION = "1.0.0";
 /**
@@ -65,33 +75,37 @@ export const SHARED_PROVIDER_CONFIRMATION_FILENAME = "provider-confirmation.json
 export function sharedProviderConfirmationPath(root) {
     return join(auditToolsDir(root), SHARED_PROVIDER_CONFIRMATION_FILENAME);
 }
-// ---------------------------------------------------------------------------
-// Roster derivation
-// ---------------------------------------------------------------------------
 /**
- * The current discovered provider roster: the sorted set of provider names
- * `discoverProviders` surfaces for this session config + environment. PB-1's
- * opencode opt-in is inherited from `discoverProviders` (a bare-PATH opencode is
- * not surfaced unless explicitly configured), so it never spuriously perturbs
- * the roster.
+ * Project the render DTO down to what actually gets PERSISTED: the operator's
+ * decision, with this auditor's reach assessment dropped (G3 B+D).
+ *
+ * The PRODUCER is split — not the write site. `writeSharedProviderConfirmation`
+ * receives an already-typed value, so projecting THERE would leave the reach fields
+ * representable on the persisted type and a future caller could put them back.
+ * Projecting here makes the persisted shape carry no reach BY CONSTRUCTION.
  */
-export function currentProviderRoster(sessionConfig, env = process.env, detectCommand) {
-    const names = discoverProviders(sessionConfig, env, detectCommand).map((p) => p.name);
-    return sortRoster(names);
+export function buildSharedProviderConfirmation(...args) {
+    const rendered = buildProviderConfirmationRender(...args);
+    return {
+        ...rendered,
+        provider_pool: rendered.provider_pool.map(toPersistedPoolEntry),
+    };
 }
-function sortRoster(names) {
-    // Deduplicate + sort so the snapshot is order-insensitive and comparison is a
-    // plain stringified equality.
+/** The decision half of one pool entry. Reach is dropped, never persisted. */
+function toPersistedPoolEntry(entry) {
+    return {
+        name: entry.name,
+        ...(entry.model_id !== undefined ? { model_id: entry.model_id } : {}),
+        ...(entry.cost_order !== undefined ? { cost_order: entry.cost_order } : {}),
+    };
+}
+function sortNames(names) {
+    // Deduplicate + sort so a persisted list is order-insensitive and stable.
     return [...new Set(names)].sort();
 }
-function rostersEqual(a, b) {
-    if (a.length !== b.length)
-        return false;
-    for (let i = 0; i < a.length; i++) {
-        if (a[i] !== b[i])
-            return false;
-    }
-    return true;
+function sortStrings(values) {
+    // Deduplicate + sort so a persisted list is order-insensitive and stable.
+    return [...new Set(values)].sort();
 }
 // ---------------------------------------------------------------------------
 // Build
@@ -113,7 +127,10 @@ function rostersEqual(a, b) {
  *
  * @param sessionConfig - Current session config; may be an empty `{}`.
  * @param env           - Process env snapshot; defaults to `process.env`.
- * @param exclude       - Provider names to pre-exclude (from a prior gate).
+ * @param exclude       - {@link DispatchExclusionPattern}s to pre-exclude (from a
+ *   prior gate). A `provider:model` pattern marks a pool entry excluded only when
+ *   that entry's `representativeModelId` IS that model — the same key the routing
+ *   filter matches on, so display and dispatch cannot disagree.
  * @param include       - Provider names the operator explicitly opts back IN,
  *   overriding the default self-spawn-blocked exclusion for those names.
  * @param detectCommand - Injectable PATH-detection hook, forwarded to
@@ -126,10 +143,26 @@ function rostersEqual(a, b) {
  *   passed via the dedicated params above (the executor forwards them from the
  *   same input), so this arg governs ordering + host roster only.
  */
-export function buildSharedProviderConfirmation(sessionConfig = {}, env = process.env, exclude = [], include = [], detectCommand, input, sources = []) {
+export function buildProviderConfirmationRender(sessionConfig = {}, env = process.env, exclude = [], include = [], detectCommand, input, sources = []) {
     const discovered = discoverProviders(sessionConfig, env, detectCommand);
-    const excludeSet = new Set(exclude);
+    const operatorExcluded = buildExclusion(exclude);
     const includeSet = new Set(include);
+    // Evaluate a pool entry against the operator's rules at the SAME key the routing
+    // filter uses — `representativeModelId` is what `computeNewlyReachableBackends`
+    // and `annotateConfirmedPool` key a provider by, so a `provider:model` rule marks
+    // exactly the entry it will later filter.
+    //
+    // ⚠ The provider + model tiers ONLY. `provider_pool` is provider-granular and an
+    // entry has no endpoint, so an endpoint-host rule can never mark one — that tier
+    // addresses SOURCES, which this pool does not enumerate. The direction is safe
+    // (the rule is still honored at `buildSourcePools`; the Gate-0 table merely
+    // under-reports it as "included"), but it is a real display/routing gap and it is
+    // NOT closed here. Backlog: the Gate-0 sources table carries no status column at
+    // all, so no tier is reflected for a source today.
+    const ruledOut = (name) => operatorExcluded.excludes({
+        provider: name,
+        model: representativeModelId(name, sessionConfig),
+    });
     const pool = [];
     // Always include worker-command as a fallback — it's always available and is
     // never surfaced by PATH discovery (it blocks auto-dispatch by design).
@@ -137,24 +170,21 @@ export function buildSharedProviderConfirmation(sessionConfig = {}, env = proces
         pool.push({
             name: "worker-command",
             capability_tier: "unknown",
-            excluded: excludeSet.has("worker-command"),
-            reason: "always-available fallback; no PATH detection required",
+            excluded: ruledOut("worker-command"),
         });
     }
     for (const provider of discovered) {
         // Self-spawn-blocked providers are excluded from the dispatchable pool by
         // default; the operator can opt one back in via `include`. An operator-named
-        // `exclude` always wins. The machine-readable flag rides along so downstream
-        // consumers never have to parse `reason`.
+        // `exclude` always wins.
         const blocked = provider.selfSpawnBlocked === true;
         const operatorIncluded = includeSet.has(provider.name);
-        const excluded = excludeSet.has(provider.name) || (blocked && !operatorIncluded);
+        const excluded = ruledOut(provider.name) || (blocked && !operatorIncluded);
         pool.push({
             name: provider.name,
             capability_tier: provider.capabilityTier,
             excluded,
             ...(blocked ? { self_spawn_blocked: true } : {}),
-            reason: provider.reason,
         });
     }
     // Cost-first routing: annotate with representative model price + cost_order,
@@ -166,6 +196,8 @@ export function buildSharedProviderConfirmation(sessionConfig = {}, env = proces
         session_level: true,
         confirmed_at: new Date().toISOString(),
         provider_pool: annotated.provider_pool,
+        // NOTE: the FULL entries. This is the render DTO; `buildSharedProviderConfirmation`
+        // projects them to `PersistedPoolEntry[]` on the way to disk.
         ...(annotated.host_model_cost_order.length > 0
             ? { host_model_cost_order: annotated.host_model_cost_order }
             : {}),
@@ -175,9 +207,309 @@ export function buildSharedProviderConfirmation(sessionConfig = {}, env = proces
         ...(clampDispatchBias(input?.dispatch_bias) != null
             ? { dispatch_bias: clampDispatchBias(input?.dispatch_bias) }
             : {}),
-        roster: sortRoster(discovered.map((p) => p.name)),
+        ...(buildConfirmedDispatchPolicy(exclude, include) ?? {}),
     };
 }
+/**
+ * Lift the operator's explicit route decision out of their Gate-0 input into the
+ * persisted policy half. Returns `undefined` when the operator named neither list
+ * (so the field stays absent rather than persisting an empty shell).
+ */
+function buildConfirmedDispatchPolicy(exclude, include) {
+    if (exclude.length === 0 && include.length === 0)
+        return undefined;
+    return {
+        policy: {
+            ...(exclude.length > 0 ? { exclude: sortStrings(exclude) } : {}),
+            ...(include.length > 0 ? { include: sortNames(include) } : {}),
+        },
+    };
+}
+/**
+ * Keep every non-empty pattern verbatim — **no membership check.** Unlike
+ * {@link parseProviderNameList}, this list is an open grammar: a pattern whose head
+ * is not a provider name is a legitimate endpoint-host rule, so "unknown ⇒ drop"
+ * would silently delete the operator's endpoint tier. An unmatchable pattern is
+ * inert (it simply matches nothing), which is the safe direction for a filter.
+ *
+ * Returns `undefined` for a non-array or an all-empty array, so the field stays
+ * absent rather than persisting an empty shell.
+ */
+function parseExclusionPatterns(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const patterns = value.filter((v) => typeof v === "string" && v.trim().length > 0);
+    return patterns.length > 0 ? patterns.map((p) => p.trim()) : undefined;
+}
+/**
+ * Keep only real provider names, dropping anything unknown. Returns `undefined` for a
+ * non-array or an array with no recognizable name, so an unknown entry degrades that
+ * entry — never the whole list.
+ *
+ * Retained for `include` ONLY: that list opts a *self-spawn-blocked provider* back in,
+ * and self-spawn-blockedness is a property of a provider (`isSelfSpawnBlocked` keys on
+ * the provider name), so its keyspace is genuinely the closed name set — not the open
+ * exclusion grammar.
+ */
+function parseProviderNameList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const names = value.filter((v) => typeof v === "string" && RESOLVED_PROVIDER_NAMES.includes(v));
+    return names.length > 0 ? names : undefined;
+}
+/** Every concrete provider name — `auto` is a resolution directive, not a backend. */
+const RESOLVED_PROVIDER_NAMES = PROVIDER_NAMES.filter((name) => name !== "auto");
+// ---------------------------------------------------------------------------
+// The reconciliation gate (G3): operator DECISION vs THIS auditor's reach
+// ---------------------------------------------------------------------------
+/**
+ * The gate's comparison key for one backend: **the model where it is knowable,
+ * else the coarse provider name.**
+ *
+ * This is the operator-facing exclusion grammar's own provision (`provider:model`,
+ * with `provider` as the coarser pattern — spec/unified-dispatch-worker-model.md).
+ * Model granularity is the POINT, not a refinement: the operator confirms *model*
+ * choices, so a second model under an already-confirmed `openai-compatible` is a
+ * new choice even though it introduces no new provider.
+ *
+ * But a bare-`model_id` key would be worse than useless: `representativeModelId`
+ * knows a model only for `openai-compatible` and `codex` — for claude-code / agy /
+ * opencode / worker-command a CLI backend's model arrives only at the dispatch
+ * handshake. Such a backend would contribute NO key, so installing `agy` on PATH
+ * would leave the delta empty and the gate would silently dispatch it — re-opening
+ * the exact PATH-appearance case the gate exists to catch, blind rather than loud.
+ *
+ * ⚠ This is a THIRD keyspace, deliberately distinct from the quota-ledger pool
+ * identity (`provider[#account]/model`, `buildProviderModelKey`) — an account is
+ * irrelevant to a rule about a backend. Do not unify them.
+ */
+function backendGateKey(modelId, providerName) {
+    return modelId ?? providerName;
+}
+/**
+ * The keys of the operator's persisted DECISION — the CONFIRMED half of the gate.
+ *
+ * All three pools contribute, and each is load-bearing: `annotateConfirmedPool`
+ * folds a source away when its model is already claimed by a provider entry, so a
+ * source can be represented ONLY by `provider_pool[].model_id`; and a host tier
+ * appears only in `host_model_cost_order`. Reading fewer than all three would
+ * manufacture a phantom delta for an already-confirmed backend.
+ */
+export function confirmedBackendKeys(confirmation) {
+    const keys = new Set();
+    for (const entry of confirmation.provider_pool) {
+        keys.add(backendGateKey(entry.model_id, entry.name));
+    }
+    for (const entry of confirmation.source_pool_cost_order ?? []) {
+        keys.add(backendGateKey(entry.model_id, entry.provider));
+    }
+    for (const entry of confirmation.host_model_cost_order ?? []) {
+        keys.add(entry.model_id);
+    }
+    return keys;
+}
+/**
+ * The pattern that rules out one backend at the finest granularity its model is
+ * knowable at. The inverse of {@link backendGateKey}, and deliberately adjacent to
+ * it: a `provider:model` rule matches only when the routing filter sees that exact
+ * model, so a backend whose model arrives at the dispatch handshake (a CLI) must be
+ * ruled out at the coarse `provider` tier or the rule would never match.
+ */
+function backendExclusionPattern(modelId, providerName) {
+    return modelId ? `${providerName}:${modelId}` : providerName;
+}
+/**
+ * DELTA = **REACH-NOW \ CONFIRMED**: the backends this auditor can reach *right
+ * now* that the operator's persisted decision never mentions. Sorted by key, so the
+ * result is stable for prompt rendering + comparison.
+ *
+ * This is a **set difference — a FILTER over fresh reach, never additive.** The
+ * opposite direction (CONFIRMED \ REACH-NOW: a backend the operator confirmed that
+ * this auditor cannot reach) is the harmless *subset* case and is deliberately
+ * silent — it is also why the synthetic `worker-command` entry and
+ * `host_model_cost_order` need no special-casing here.
+ *
+ * @param confirmation - The persisted decision (CONFIRMED).
+ * @param sessionConfig - The EFFECTIVE config, so `representativeModelId` derives
+ *   keys identically to the write side.
+ * @param sources - REACH-NOW's source half. MUST come from the
+ *   `gatherDispatchableSources` chokepoint — the single async source-gather point
+ *   both `buildSourcePools` and the Gate-0 surface consume, so what the operator
+ *   confirms is exactly what routes. Re-deriving it from `resolveAmbientSources`
+ *   would reintroduce the display/dispatch drift that invariant forbids, and is
+ *   structurally blind to descriptor-supplied sources, the demoted primary, and the
+ *   legacy `openai_compatible` fold.
+ * @param env - Process env, for `discoverProviders` (REACH-NOW's provider half).
+ * @param detectCommand - Injectable PATH-detection hook so tests drive discovery
+ *   deterministically instead of shelling out.
+ */
+export function computeNewlyReachableBackends(confirmation, sessionConfig, sources = [], env = process.env, detectCommand) {
+    const confirmed = confirmedBackendKeys(confirmation);
+    const reachNow = new Map();
+    const record = (modelId, provider) => {
+        reachNow.set(backendGateKey(modelId, provider), {
+            key: backendGateKey(modelId, provider),
+            provider,
+            exclusion_pattern: backendExclusionPattern(modelId, provider),
+        });
+    };
+    for (const provider of discoverProviders(sessionConfig, env, detectCommand)) {
+        record(representativeModelId(provider.name, sessionConfig), provider.name);
+    }
+    for (const source of sources) {
+        record(source.model, source.provider);
+    }
+    return [...reachNow.values()]
+        .filter((backend) => !confirmed.has(backend.key))
+        .sort((a, b) => a.key.localeCompare(b.key));
+}
+/**
+ * The dispatchable-pool exclusion rules for THIS process: the operator's explicit
+ * {@link DispatchExclusionPattern}s, plus every provider that is self-spawn-blocked
+ * *in this process's env* and was not explicitly opted back in.
+ *
+ * Reach is recomputed here rather than read from the artifact's derived `excluded`
+ * flag — that flag encodes the WRITING auditor's env, and an auditor for whom a
+ * provider is perfectly spawnable must not inherit another's block. The operator's
+ * decision is inherited (it is a rule); the reach assessment is not.
+ *
+ * ⚠ **These rules are only safe to apply to SOURCE pools.** Inside any agent session
+ * the self-spawn half ALWAYS names that agent (`CLAUDECODE` ⇒ `claude-code`, `CODEX`
+ * ⇒ `codex`) — i.e. the conversation host itself. Applying them to HOST pools would
+ * zero out dispatch entirely: the driver would exclude itself. It is harmless at
+ * `buildSourcePools` only because a host can never BE a source — `claude-code` is
+ * structurally absent from `DISPATCHABLE_SOURCE_PROVIDERS`, so in a Claude Code
+ * session the filter is a no-op. Honoring an operator exclusion of the host/primary
+ * provider therefore is NOT a matter of passing these rules to the host-pool builder;
+ * it needs a separate decision about what excluding your own driver should even mean.
+ */
+export function resolveDispatchExclusion(policy, env = process.env) {
+    const included = new Set(policy?.include ?? []);
+    // The local reach half: a self-spawn-blocked provider is ruled out at PROVIDER
+    // granularity (blockedness is a property of the provider, not of one of its
+    // models), recomputed against THIS process's env rather than inherited.
+    const blocked = RESOLVED_PROVIDER_NAMES.filter((name) => !included.has(name) && isSelfSpawnBlocked(name, env));
+    return buildExclusion([...(policy?.exclude ?? []), ...blocked]);
+}
+/**
+ * The pure-policy matcher: the operator's patterns and nothing else. Split out
+ * because the Gate-0 pool BUILDER must evaluate the operator's rules WITHOUT the
+ * local self-spawn fold — it derives `self_spawn_blocked` from `discoverProviders`
+ * on its own and would otherwise conflate the two into one indistinguishable
+ * `excluded` verdict.
+ */
+function buildExclusion(patterns) {
+    const rules = patterns.map(parseExclusionRule);
+    return { excludes: (backend) => rules.some((rule) => ruleMatches(rule, backend)) };
+}
+function parseExclusionRule(pattern) {
+    const colon = pattern.indexOf(":");
+    if (colon === -1) {
+        return isResolvedProviderName(pattern)
+            ? { kind: "provider", provider: pattern }
+            : { kind: "endpoint", host: pattern.toLowerCase() };
+    }
+    const head = pattern.slice(0, colon);
+    const tail = pattern.slice(colon + 1);
+    if (!isResolvedProviderName(head)) {
+        return { kind: "endpoint", host: pattern.toLowerCase() };
+    }
+    // The head decides the tier — an empty tail does NOT demote a provider-name head
+    // to the endpoint tier. `codex:` reads as "codex, every model"; classifying it as
+    // an (unmatchable) endpoint rule would silently drop the operator's intent, and
+    // the head-decides rule this type documents would not actually hold.
+    return tail.length > 0
+        ? { kind: "provider_model", provider: head, model: tail }
+        : { kind: "provider", provider: head };
+}
+function isResolvedProviderName(value) {
+    return RESOLVED_PROVIDER_NAMES.includes(value);
+}
+function ruleMatches(rule, backend) {
+    switch (rule.kind) {
+        case "provider":
+            return backend.provider === rule.provider;
+        case "provider_model":
+            // A model-granular rule matches ONLY that model. A backend of the same
+            // provider carrying no model (a CLI whose model arrives at the dispatch
+            // handshake) is NOT matched: the operator ruled out one model, not the
+            // backend — the coarse `provider` tier is how they rule out the backend.
+            return backend.provider === rule.provider && backend.model === rule.model;
+        case "endpoint":
+            return endpointHosts(backend.endpoint).includes(rule.host);
+    }
+}
+/**
+ * The forms of a source endpoint an operator pattern may name: `hostname` (port-
+ * agnostic — `integrate.api.nvidia.com` rules out that host on any port) and
+ * `host:port` (port-specific — `localhost:8000` rules out one of several local
+ * endpoints). Both are offered so the pattern's own specificity decides.
+ *
+ * An endpoint that is not a URL (a CLI launcher command) degrades to the raw
+ * lowercased string, which then only ever matches an identical literal pattern —
+ * never a false positive against a real host.
+ *
+ * ⚠ The authority check is load-bearing, not defensive: `new URL()` accepts ANY
+ * scheme-shaped string, so it does NOT throw on `localhost:8000` (protocol
+ * `localhost:`) or on a Windows command path like `C:\tools\codex.cmd` (protocol
+ * `c:`) — both parse to an EMPTY hostname. Relying on the `catch` alone would
+ * therefore silently yield no hosts for exactly those endpoints, making an
+ * operator's literal-identical rule match nothing.
+ */
+function endpointHosts(endpoint) {
+    if (!endpoint)
+        return [];
+    const raw = endpoint.toLowerCase();
+    if (endpoint.includes("//")) {
+        try {
+            const url = new URL(endpoint);
+            if (url.hostname.length > 0) {
+                return [url.hostname.toLowerCase(), url.host.toLowerCase()];
+            }
+        }
+        catch {
+            // Not a URL after all — fall through to the raw literal.
+        }
+    }
+    return [raw];
+}
+/**
+ * Read the operator's confirmed route policy from the shared Gate-0 confirmation.
+ *
+ * Deliberately reads the artifact DIRECTLY rather than going through
+ * {@link readSharedProviderConfirmation}, so that **a corrupt sibling field cannot
+ * discard the decision**: `parseSharedProviderConfirmation` returns `null` wholesale
+ * on any malformed required field or a `schema_version` mismatch. Routing policy
+ * through it would make an unrelated corruption (or a future version bump) silently
+ * lift the operator's exclusions — failing OPEN on the one field that must fail
+ * closed. Parsing `policy` on its own keeps that blast radius out.
+ *
+ * (Before G3 this bypass carried a second rationale — dodging the roster-freshness
+ * gate. That gate is gone: no read of this artifact is reach-gated any more, so the
+ * remaining reason is blast radius alone.)
+ *
+ * **Honest limit — this is not absolutely fail-closed.** An absent or unparseable
+ * artifact yields `null` (no operator policy). That residue is irreducible here: with
+ * no readable decision on disk there is nothing to fail closed ON. Self-spawn-blocked
+ * providers are still excluded locally by {@link resolveDispatchExclusion}, which
+ * needs no artifact.
+ */
+export async function readConfirmedDispatchPolicy(root) {
+    if (!root)
+        return null;
+    let raw;
+    try {
+        raw = await readJsonFile(sharedProviderConfirmationPath(root));
+    }
+    catch {
+        // Absent (ENOENT) / unreadable / invalid JSON — never-block, same contract as
+        // every other read of this artifact.
+        return null;
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    return parseConfirmedDispatchPolicy(raw.policy) ?? null;
+}
 // ---------------------------------------------------------------------------
 // Write (audit writes it)
 // ---------------------------------------------------------------------------
@@ -203,17 +535,21 @@ export async function writeSharedProviderConfirmation(root, confirmation, logger
 // ---------------------------------------------------------------------------
 // Validation
 // ---------------------------------------------------------------------------
-function isResolvedProviderNameArray(value) {
-    return Array.isArray(value) && value.every((v) => typeof v === "string");
-}
-function isConfirmedPoolEntry(value) {
+/**
+ * The persisted pool entry's gate: `name` ONLY.
+ *
+ * B+D: this gate previously hard-required `capability_tier` AND `excluded` — the
+ * exact reach fields B removes from the persisted shape. That coupling is why B and
+ * D are ONE commit: a post-B artifact failing a pre-B gate parses to `null`, which
+ * degrades SILENTLY to empty cost positions and λ=0. Requiring only `name` also
+ * makes the gate forward-tolerant of a confirmation written before B (its extra
+ * reach fields are simply ignored on read, never re-persisted).
+ */
+function isPersistedPoolEntry(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         return false;
     }
-    const obj = value;
-    return (typeof obj.name === "string" &&
-        typeof obj.capability_tier === "string" &&
-        typeof obj.excluded === "boolean");
+    return typeof value.name === "string";
 }
 function isHostModelCostEntry(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
@@ -254,11 +590,9 @@ function parseSharedProviderConfirmation(value) {
     if (typeof obj.confirmed_at !== "string")
         return null;
     if (!Array.isArray(obj.provider_pool) ||
-        !obj.provider_pool.every(isConfirmedPoolEntry)) {
+        !obj.provider_pool.every(isPersistedPoolEntry)) {
         return null;
     }
-    if (!isResolvedProviderNameArray(obj.roster))
-        return null;
     // host_model_cost_order is optional + additive; a malformed value degrades to
     // absent (the field never blocks parsing — INV-DC1-6 never-block spirit).
     const hostModels = Array.isArray(obj.host_model_cost_order) &&
@@ -273,6 +607,11 @@ function parseSharedProviderConfirmation(value) {
     // dispatch_bias is optional + additive; a malformed/out-of-range value degrades to
     // the cost-first default (clamp → undefined only when non-finite), never blocking.
     const dispatchBias = clampDispatchBias(obj.dispatch_bias);
+    // policy is optional + additive; a malformed value degrades to absent. Note the
+    // asymmetry with the fields above: degrading policy to absent fails OPEN (the
+    // operator's exclusions stop applying), so each list is validated independently —
+    // a malformed `include` must not silently discard a well-formed `exclude`.
+    const policy = parseConfirmedDispatchPolicy(obj.policy);
     return {
         schema_version: SHARED_PROVIDER_CONFIRMATION_VERSION,
         session_level: true,
@@ -285,79 +624,132 @@ function parseSharedProviderConfirmation(value) {
             ? { source_pool_cost_order: sourcePools }
             : {}),
         ...(dispatchBias != null ? { dispatch_bias: dispatchBias } : {}),
-        roster: obj.roster,
+        ...(policy ? { policy } : {}),
+    };
+}
+/**
+ * Parse the optional policy half. Each list is validated on its own so one
+ * malformed list cannot discard the other — degrading a well-formed `exclude` to
+ * absent would fail OPEN and route to a backend the operator ruled out.
+ */
+function parseConfirmedDispatchPolicy(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const obj = value;
+    // `exclude` is the OPEN exclusion grammar (a pattern's head need not be a provider
+    // name — the endpoint tier's never is), so it is kept verbatim; an unmatchable
+    // pattern is inert, which is the safe direction for a filter. `include` is the
+    // CLOSED provider-name set and stays membership-checked, so an unknown name cannot
+    // type-assert its way into overriding a self-spawn block.
+    const exclude = parseExclusionPatterns(obj.exclude);
+    const include = parseProviderNameList(obj.include);
+    if (!exclude?.length && !include?.length)
+        return undefined;
+    return {
+        ...(exclude?.length ? { exclude } : {}),
+        ...(include?.length ? { include } : {}),
     };
 }
 // ---------------------------------------------------------------------------
 // Read (remediate gains this)
 // ---------------------------------------------------------------------------
 /**
- * Read + interpret the shared confirmation for `root`. THREE-valued (CE-012):
+ * Read + parse the shared confirmation for `root`. TWO-valued:
  *
  *   - returns `null` when the artifact is ABSENT or MALFORMED — the caller then
  *     resolves its provider independently, exactly as today (INV-DC1-6
  *     never-block). Absence is the standalone-remediate case and is not an error.
- *   - returns `{ status: 'confirmed', confirmation }` when the artifact is valid
- *     AND the stamped roster still matches the currently-discovered roster — the
- *     caller honors the recorded pool.
- *   - returns `{ status: 'reconfirm', confirmation, reason }` when the artifact
- *     is valid but the roster has CHANGED since it was written (a provider
- *     appeared or disappeared) — a DISTINCT signal so the caller re-confirms
- *     rather than pinning a stale pool (INV-DC2-3). This is the CE-012 third
- *     state that keeps INV-DC2-3 from collapsing into the never-block `null`.
+ *   - returns the parsed confirmation otherwise — the operator's persisted route
+ *     DECISION, honored as-is.
+ *
+ * **Reach-free by construction (G3).** This read does NOT check whether the
+ * reachable backend set still matches whatever the writing auditor saw. It cannot
+ * meaningfully: a *different* auditor legitimately has different reach, so that
+ * comparison was noise cross-auditor — and answering it by discarding the
+ * operator's decision fails OPEN on a policy question. A backend becoming newly
+ * reachable is a real event, handled by the reconciliation gate
+ * ({@link computeNewlyReachableBackends}), which compares the DECISION against
+ * *this* auditor's reach and is keyed on `autonomous_mode`.
  *
  * Never throws: a read/parse failure is treated as absent/malformed → `null`.
  * The read is lockless (no lock needed: the writer's atomic rename guarantees a
  * complete file either way — CE-003) and so cannot deadlock against a writer.
  */
-export async function readSharedProviderConfirmation(root, sessionConfig = {}, env = process.env) {
-    const path = sharedProviderConfirmationPath(root);
+export async function readSharedProviderConfirmation(root) {
     let raw;
     try {
-        raw = await readJsonFile(path);
+        raw = await readJsonFile(sharedProviderConfirmationPath(root));
     }
     catch {
         // Absent (ENOENT) OR unreadable / invalid-JSON both degrade to the
         // never-block path — a missing or corrupt artifact is never an error here.
         return null;
     }
-    const confirmation = parseSharedProviderConfirmation(raw);
-    if (confirmation === null) {
-        // Malformed (wrong shape / version drift) → never-block.
-        return null;
-    }
-    const current = currentProviderRoster(sessionConfig, env);
-    if (!rostersEqual(confirmation.roster, current)) {
-        return {
-            status: "reconfirm",
-            confirmation,
-            reason: `discovered provider roster changed since confirmation ` +
-                `(was [${confirmation.roster.join(", ")}], now [${current.join(", ")}])`,
-        };
-    }
-    return { status: "confirmed", confirmation };
+    // Malformed (wrong shape / version drift) → never-block, but never SILENT (D).
+    const parsed = parseSharedProviderConfirmation(raw);
+    if (parsed === null)
+        warnConfirmationRejected(raw, root);
+    return parsed;
+}
+/**
+ * D — loud rejection. `null` from the parser is indistinguishable at the call sites
+ * from "no confirmation exists", and every consumer treats that as "no operator
+ * decision": empty cost positions, λ=0, no exclusions. So a `schema_version` bump —
+ * or any shape drift — would SILENTLY discard the operator's whole route decision
+ * and quietly re-route the run. Absence is legitimately silent; a file that EXISTS
+ * and was rejected is not.
+ *
+ * A warning, not a throw: INV-DC1-6 (never-block) is the standing invariant here —
+ * the same loud-degrade shape as `readQuotaStateOrDegrade` and the blind-dispatch
+ * warning. Reached only on the rejection path, so it cannot become hot.
+ */
+function warnConfirmationRejected(raw, root) {
+    const version = raw !== null && typeof raw === "object" && !Array.isArray(raw)
+        ? raw.schema_version
+        : undefined;
+    const why = version !== undefined && version !== SHARED_PROVIDER_CONFIRMATION_VERSION
+        ? `schema_version "${String(version)}" != expected "${SHARED_PROVIDER_CONFIRMATION_VERSION}"`
+        : "malformed shape";
+    // Scoped to what the rejection ACTUALLY discards. Exclusions deliberately survive:
+    // `readConfirmedDispatchPolicy` bypasses this parser (and its version check) and reads
+    // `policy` straight off the raw JSON, so an exclusion keeps failing CLOSED through a
+    // schema drift — the correct direction, and the reason this message must NOT claim the
+    // pool is unfiltered. Saying otherwise sends the operator hunting a routing change that
+    // did not happen.
+    process.stderr.write(`WARNING: ignoring the provider confirmation at ${sharedProviderConfirmationPath(root)} ` +
+        `(${why}). The operator's confirmed COST ORDER and DISPATCH BIAS are NOT being applied ` +
+        `to this run — dispatch falls back to price-then-tier at the default bias. ` +
+        `(Exclusions are read separately and still apply.) Re-run the provider-confirmation ` +
+        `gate to rewrite it.
+`);
 }
 /**
  * Read the operator-confirmed cost ordering (rung 1 of costRank; see
  * spec/cost-first-routing.md) from the shared Gate-0 confirmation as a model-keyed
  * `Map<model_id, cost_order>` for the dispatch build sites. Single-sourced so audit
  * and remediate honor it identically. Best-effort and never throws: an absent
- * `root`, a missing/malformed confirmation, or a roster that has since changed
- * (`reconfirm`) all yield an empty map — dispatch then falls to real price then
- * tier. Only a `confirmed` (roster-fresh) confirmation contributes positions.
+ * `root` or a missing/malformed confirmation yields an empty map — dispatch then
+ * falls to real price then tier.
+ *
+ * **Not gated on reach (G3 step 1).** The cost order is the operator's POLICY —
+ * "the operator may reorder" — so a shift in what happens to be reachable must not
+ * silently discard it. The former roster-freshness gate did exactly that, on the
+ * false premise that these positions are reach-derived; they are not, and it was
+ * the live defect this fixes.
  */
-export async function readConfirmedCostPositions(root, sessionConfig = {}, env = process.env) {
+export async function readConfirmedCostPositions(root) {
     if (!root)
         return new Map();
-    const read = await readSharedProviderConfirmation(root, sessionConfig, env);
-    if (!read || read.status !== "confirmed")
+    const confirmation = await readSharedProviderConfirmation(root);
+    if (!confirmation)
         return new Map();
     // Provider-pool positions (configured models) PLUS any host-native tiers the
     // operator confirmed at Gate-0 (follow-up c). Both are model-keyed; a host tier
     // and a configured pool thread to dispatch identically. Host entries are already
     // in the single unified cost order, so a plain merge preserves the total order.
-    const positions = resolveConfirmedCostPositions(read.confirmation.provider_pool);
-    for (const entry of read.confirmation.host_model_cost_order ?? []) {
+    const positions = resolveConfirmedCostPositions(confirmation.provider_pool);
+    for (const entry of confirmation.host_model_cost_order ?? []) {
         if (entry.model_id &&
             Number.isFinite(entry.cost_order) &&
             entry.cost_order >= 0) {
@@ -368,7 +760,7 @@ export async function readConfirmedCostPositions(root, sessionConfig = {}, env =
     // position keyed on the source's model id — the SAME model-keyed lookup a repair-proxy
     // dispatch pool resolves against (pool.model = the namespaced `provider/model`). An entry
     // without a model_id is display-only and contributes no dispatch position.
-    for (const entry of read.confirmation.source_pool_cost_order ?? []) {
+    for (const entry of confirmation.source_pool_cost_order ?? []) {
         if (entry.model_id &&
             Number.isFinite(entry.cost_order) &&
             entry.cost_order >= 0) {
@@ -381,17 +773,20 @@ export async function readConfirmedCostPositions(root, sessionConfig = {}, env =
  * Read the operator-confirmed cost↔speed dispatch bias (λ ∈ [0,1]) from the shared
  * Gate-0 confirmation for the dispatch build sites (spec/dispatch-cost-speed-dial.md).
  * Single-sourced so audit and remediate apply the identical operating point.
- * Best-effort and never throws: an absent `root`, a missing/malformed confirmation, a
- * roster that has since changed (`reconfirm`), or an absent field all yield the
- * cost-first default `0`. Only a `confirmed` (roster-fresh) confirmation contributes.
+ * Best-effort and never throws: an absent `root`, a missing/malformed confirmation,
+ * or an absent field all yield the cost-first default `0`.
+ *
+ * **Not gated on reach (G3 step 1)** — λ is the operator's durable operating point
+ * on the cost-vs-throughput frontier, i.e. POLICY. See
+ * {@link readConfirmedCostPositions}.
  */
-export async function readConfirmedDispatchBias(root, sessionConfig = {}, env = process.env) {
+export async function readConfirmedDispatchBias(root) {
     if (!root)
         return 0;
-    const read = await readSharedProviderConfirmation(root, sessionConfig, env);
-    if (!read || read.status !== "confirmed")
+    const confirmation = await readSharedProviderConfirmation(root);
+    if (!confirmation)
         return 0;
-    return clampDispatchBias(read.confirmation.dispatch_bias) ?? 0;
+    return clampDispatchBias(confirmation.dispatch_bias) ?? 0;
 }
 // ---------------------------------------------------------------------------
 // Interactive Gate-0 operator input (spec/cost-first-routing.md — Gate-0)
@@ -416,6 +811,9 @@ export function parseProviderConfirmationInput(value) {
         ? v
         : undefined;
     const costOrder = stringArray(obj.cost_order);
+    // No cast: `exclude` is the OPEN exclusion grammar, so asserting the operator's
+    // raw strings into the closed provider-name union would be a lie — and the exact
+    // type-assert-your-way-in move the policy parser refuses for `include`.
     const exclude = stringArray(obj.exclude);
     const include = stringArray(obj.include);
     const dispatchBias = clampDispatchBias(obj.dispatch_bias);
@@ -456,4 +854,27 @@ export async function readProviderConfirmationInput(artifactsDir) {
     }
     return parseProviderConfirmationInput(raw);
 }
+/**
+ * Invalidate a CONSUMED Gate-0 input by deleting it — the second half of
+ * consume-and-invalidate, paired here with {@link readProviderConfirmationInput} so
+ * the two cannot drift apart.
+ *
+ * The input's presence is the "operator has acted" signal the gate reads to decide
+ * emit-vs-consume. Once promoted into the canonical artifacts it is SPENT: leaving it
+ * on disk means a later reconciliation delta silently re-consumes a submission that
+ * answered an older question, auto-satisfying the gate instead of asking the
+ * operator. Deleting it is what makes the gate able to fire a second time at all.
+ *
+ * Best-effort and never throws: an already-absent file is the desired end state, and
+ * a failed unlink must not break the in-flight obligation (the promotion itself
+ * already succeeded).
+ */
+export async function unlinkProviderConfirmationInput(artifactsDir) {
+    try {
+        await unlink(join(artifactsDir, PROVIDER_CONFIRMATION_INPUT_FILENAME));
+    }
+    catch {
+        // Absent / locked / read-only — nothing to invalidate, or nothing we can do.
+    }
+}
 //# sourceMappingURL=sharedProviderConfirmation.js.map