@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/ai_council/pricing.ts

@@ -116,6 +116,12 @@ export interface CostEstimate {
     output_tokens: number;
     input_usd: number;
     output_usd: number;
+    /**
+     * False when `lookup` found no row. The two amounts are then zero so
+     * arithmetic callers keep working, but zero is not the price: a ceiling
+     * that compared against it would let an unknown model through as free.
+     */
+    priced: boolean;
 }
 
 export function estimate_cost(
@@ -134,6 +140,7 @@ export function estimate_cost(
             output_tokens: maxOutputTokens,
             input_usd: 0.0,
             output_usd: 0.0,
+            priced: false,
         };
     }
     const inputUsd = (inputTokens / 1_000_000) * price.input_per_1m_usd;
@@ -145,6 +152,7 @@ export function estimate_cost(
         output_tokens: maxOutputTokens,
         input_usd: inputUsd,
         output_usd: outputUsd,
+        priced: true,
     };
 }
 
@@ -357,6 +365,7 @@ export function reprice_with_cache(
             output_tokens: tokens.output_tokens,
             input_usd: 0.0,
             output_usd: 0.0,
+            priced: false,
         };
     }
     const writeMult = ttl === '1h' ? CACHE_WRITE_MULTIPLIER_1H : CACHE_WRITE_MULTIPLIER_5M;
@@ -372,6 +381,7 @@ export function reprice_with_cache(
         output_tokens: tokens.output_tokens,
         input_usd: inputUsd,
         output_usd: outputUsd,
+        priced: true,
     };
 }
 

package/src/scripts/ai_council/redact_low_impact_entry.ts

@@ -43,6 +43,7 @@
  * module guarantees its callers.
  */
 
+import { API_KEY_ASSIGNMENT_KEYWORD } from '../_lib/egress_prefixes.js';
 import { _RAW_KEY_PREFIXES } from './config.js';
 
 /**
@@ -189,9 +190,11 @@ const _MONEY_RE = new RegExp(
     'gu',
 );
 
-// Python: (?i)\bapi[_-]?key\b\s*[:=]\s*[A-Za-z0-9+/=_\-]{12,}
+// The keyword is the rule table's, read through its bundled projection (this
+// module rides in the dispatch bundle); the Unicode word boundary and the
+// 12-character value are this redactor's threshold.
 const _API_KEY_RE = new RegExp(
-    `${_UNB_BEFORE}api[_-]?key${_UNB_AFTER}\\s*[:=]\\s*[A-Za-z0-9+/=_\\-]{12,}`,
+    `${_UNB_BEFORE}${API_KEY_ASSIGNMENT_KEYWORD}${_UNB_AFTER}\\s*[:=]\\s*[A-Za-z0-9+/=_\\-]{12,}`,
     'giu',
 );
 

package/src/scripts/ai_council/response_render.ts

@@ -9,6 +9,7 @@
  */
 
 import { CouncilResponse, type ExternalAIClient } from './clients.js';
+import { councilEgress } from './council_egress.js';
 import { _metaGet } from './py_parity.js';
 
 /**
@@ -62,14 +63,25 @@ export function renderResponseMeta(r: CouncilResponse, deps: MetaRenderDeps): st
                 : `transport: api (fell back from ${fallback_from}${why})`,
         );
     }
+    // Same reasoning for a size-fit downgrade: the model that answered is not
+    // the one configured, and only the artefact outlives the stdout line.
+    const configured = _metaGet(meta_dict, 'configured_model', null);
+    if (typeof configured === 'string' && configured !== '' && configured !== r.model) {
+        const reason = _metaGet(meta_dict, 'size_fit_reason', null);
+        const why = typeof reason === 'string' && reason !== '' ? `: ${reason}` : '';
+        parts.push(`model: ${r.model} (downgraded from ${configured}${why})`);
+    }
     return `*${parts.join(' · ')}*`;
 }
 
 
-/** Error-tagged member call — the split/ask branch is one shape, not three. */
 /**
  * One member call, error-tagged rather than throwing — the split/ask branch
- * appeared three times before this and is one shape, not three.
+ * appeared three times before this and is one shape, not three. It is also the
+ * council channel's final egress check: immediately before the request is
+ * written, the whole body is rescanned for every value this run replaced and
+ * every high-confidence finding, and a hit refuses the send — the member is
+ * never called and the response carries only the reason.
  */
 export function callMember(
     client: ExternalAIClient,
@@ -79,14 +91,25 @@ export function callMember(
     excTag: (e: unknown) => string,
 ): CouncilResponse {
     try {
+        const system = systemFor(client);
+        const body = opts.split ? `${system}\n${opts.split.stable}${opts.split.suffix}` : `${system}\n${question.user_prompt}`;
+        const refusal = councilEgress().check(body);
+        if (refusal !== null) {
+            return new CouncilResponse({
+                provider: client.name,
+                model: client.model,
+                text: '',
+                error: `egress refused: ${refusal.reason} (${refusal.what}); nothing was sent`,
+            });
+        }
         return opts.split
             ? client.ask_split(
-                  systemFor(client),
+                  system,
                   opts.split.stable,
                   opts.split.suffix,
                   question.max_tokens,
               )
-            : client.ask(systemFor(client), question.user_prompt, question.max_tokens);
+            : client.ask(system, question.user_prompt, question.max_tokens);
     } catch (exc) {
         return new CouncilResponse({
             provider: client.name,

package/src/scripts/ai_council/round_reservations.ts

@@ -0,0 +1,119 @@
+/**
+ * round_reservations — reserve-then-reconcile for one council round
+ * (road-to-unknowns-that-say-so Phase 3).
+ *
+ * Extracted rather than written into `orchestrator.ts`, which sits over the
+ * source-size ceiling; the orchestrator calls three methods and nothing else.
+ *
+ * Inert unless a daily ceiling is set: `reserve` returns `null` without
+ * touching the ledger, and `settle` records exactly what the orchestrator
+ * recorded before this existed, so with every ceiling at zero the ledger is
+ * byte-identical (ADR-279).
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import {
+    close_reservation,
+    record_spend,
+    reserve_spend,
+} from './budget_guard.js';
+import { DEFAULT_CLI_TIMEOUT_SECONDS, type CouncilResponse, type ExternalAIClient } from './clients.js';
+import { type CostEstimate } from './pricing.js';
+import { _total_usd, type CostBudget } from './spend_gate.js';
+
+/** One hour past the call's own timeout (D8). */
+const HOLD_PAST_TIMEOUT_MS = 3_600_000;
+
+/**
+ * An error whose outcome nobody knows: the provider may have generated and
+ * billed before the connection died. Anything else that fails with no tokens
+ * failed before the provider accepted the request — auth, a missing key, a
+ * refused connection — and releases its reservation. `parse_failed` is an
+ * answer that arrived unreadable, so it was billed. A 5xx counts only where it
+ * is named as a status, so `line 500` or `500 ms` in a message is not one.
+ */
+const UNKNOWN_OUTCOME =
+    /time[sd]?\s*out|timeout|deadline exceeded|ETIMEDOUT|ECONNRESET|socket hang up|server[_ ]error|overloaded|parse_failed|(?:\bHTTP\s*|\bstatus(?:\s+code)?\s*:?\s*|\bexit_|\berror\s+)5\d\d\b/iu;
+
+export function outcomeIsUnknown(error: string): boolean {
+    return UNKNOWN_OUTCOME.test(error);
+}
+
+export class RoundReservations {
+    readonly run_id = randomUUID();
+    private current: string | null = null;
+    private readonly unknown: string[] = [];
+
+    constructor(
+        private readonly budget: CostBudget,
+        private readonly ledgerPath: string | null = null,
+    ) {}
+
+    /**
+     * Claim the seat's estimate under the ledger lock. Returns `'daily'` when
+     * the ceiling cannot hold it (or the lock cannot be taken — an unchecked
+     * ceiling is not that ceiling), `null` when the call may go ahead.
+     */
+    reserve(est: CostEstimate | null, member: ExternalAIClient): 'daily' | null {
+        this.current = null;
+        if (this.budget.daily_limit_usd <= 0 || est === null || !est.priced) {
+            return null;
+        }
+        const timeout = (member as { timeout_seconds?: number }).timeout_seconds ?? DEFAULT_CLI_TIMEOUT_SECONDS;
+        const res = reserve_spend(this.budget.daily_limit_usd, _total_usd(est), member.name, member.model, {
+            path: this.ledgerPath,
+            run_id: this.run_id,
+            hold_ms: timeout * 1000 + HOLD_PAST_TIMEOUT_MS,
+        });
+        if (!res.ok) return 'daily';
+        this.current = res.id;
+        return null;
+    }
+
+    /**
+     * Reconcile the seat's call. Without a reservation this is the ledger write
+     * the orchestrator always made. With one: `completed` at the actual amount
+     * when tokens came back or no error was raised; `released` when it failed
+     * before the provider accepted it; an unknown outcome waits for `finish`.
+     */
+    settle(response: CouncilResponse, effective: ExternalAIClient, actual: CostEstimate): void {
+        const id = this.current;
+        this.current = null;
+        if (id === null) {
+            if (!response.error) {
+                record_spend(_total_usd(actual), effective.name, effective.model, {
+                    path: this.ledgerPath,
+                    cache_read_input_tokens: response.cache_read_input_tokens,
+                    cache_creation_input_tokens: response.cache_creation_input_tokens,
+                    cache_ttl: '5m',
+                    ...(actual.priced ? {} : { unpriced: true, input_tokens: actual.input_tokens, output_tokens: actual.output_tokens }),
+                });
+            }
+            return;
+        }
+        const tokens = response.input_tokens + response.output_tokens;
+        if (!response.error || tokens > 0) {
+            close_reservation(id, 'completed', {
+                path: this.ledgerPath,
+                usd: _total_usd(actual),
+                provider: effective.name,
+                model: effective.model,
+            });
+        } else if (outcomeIsUnknown(String(response.error))) {
+            this.unknown.push(id);
+        } else {
+            close_reservation(id, 'released', { path: this.ledgerPath });
+        }
+    }
+
+    /** Run end: every reservation still waiting on an outcome closes at its estimate, never zero. */
+    finish<T>(passthrough: T): T {
+        if (this.current !== null) this.unknown.push(this.current);
+        this.current = null;
+        for (const id of this.unknown.splice(0)) {
+            close_reservation(id, 'unreconciled', { path: this.ledgerPath });
+        }
+        return passthrough;
+    }
+}

package/src/scripts/ai_council/route_chooser.ts

@@ -0,0 +1,161 @@
+/**
+ * Which route serves one rung-0.5 call. Replaces "the first configured member":
+ * list order says nothing about cost, content ceiling, quota or liveness.
+ *
+ * Order: an admissible unpaid route, else a paid fallback, else an honest ∅.
+ * Head-only work (plan, decide, chair, final review, anything that writes) is
+ * refused here before any candidate is looked at, and an untyped ask may only
+ * use a paid route: a free hand is defined by its typed, schema-checked return.
+ */
+
+import type { ExternalAIClient } from './clients.js';
+import { EXPOSURE_SHARE_CAP } from './exposure_ledger.js';
+import { admitsContent, classifyContentClass, DEFAULT_SEAT_CEILING, type ContentClass } from './content_ceiling.js';
+import {
+    isHeadOnlyKind,
+    isUnpaid,
+    ROUTE_BILLINGS,
+    type HandKind,
+    type HeadOnlyKind,
+    type RouteBilling,
+} from '../_lib/hand_kinds.js';
+
+export { isUnpaid, ROUTE_BILLINGS, type RouteBilling };
+
+/** The route shape the chooser reads; built from a council member by {@link routeCandidateFromMember}. */
+export interface RouteCandidate {
+    readonly name: string;
+    readonly billing: RouteBilling;
+    readonly ceiling: ContentClass;
+    /** Calls left in the current quota window; null when unknown or unmetered. */
+    readonly remainingQuota: number | null;
+    readonly live: boolean;
+}
+
+export type RouteRefusalReason =
+    | 'not-live'
+    | 'quota-exhausted'
+    | 'content-ceiling'
+    | 'untyped-call'
+    | 'kind-not-flipped'
+    | 'exposure-cap'
+    | 'exposure-unknown';
+
+export interface RouteRefusal {
+    readonly name: string;
+    readonly reason: RouteRefusalReason;
+}
+
+export interface ChooseInput {
+    readonly kind: HandKind | HeadOnlyKind | null;
+    readonly contentClass: ContentClass;
+    readonly candidates: readonly RouteCandidate[];
+    /**
+     * Each route's share of tracked files after this call; null when the share
+     * cannot be computed. Absent means exposure is not tracked for this call.
+     */
+    readonly exposureShare?: (route: string) => number | null;
+    /** Default {@link EXPOSURE_SHARE_CAP}. */
+    readonly exposureCap?: number;
+    /**
+     * False when the kind has not cleared the shadow bars (free-hands 6.3):
+     * every unpaid route is then refused. Absent keeps the chooser's own order.
+     */
+    readonly unpaidAllowed?: boolean;
+}
+
+export type RouteChoice =
+    | { readonly route: RouteCandidate; readonly reason: 'unpaid-route' | 'paid-fallback'; readonly refused: RouteRefusal[] }
+    | { readonly route: null; readonly reason: 'head-only' | 'no-admissible-route'; readonly refused: RouteRefusal[] };
+
+function refusalOf(c: RouteCandidate, input: ChooseInput): RouteRefusalReason | null {
+    if (!c.live) return 'not-live';
+    if (c.remainingQuota !== null && c.remainingQuota <= 0) return 'quota-exhausted';
+    if (!admitsContent(c.ceiling, input.contentClass).admitted) return 'content-ceiling';
+    if (isUnpaid(c.billing) && input.kind === null) return 'untyped-call';
+    if (isUnpaid(c.billing) && input.unpaidAllowed === false) return 'kind-not-flipped';
+    if (input.exposureShare !== undefined) {
+        const share = input.exposureShare(c.name);
+        // Unknown exposure fails closed for an unpaid route only; a paid route
+        // stays usable so an untracked project still has a fallback.
+        if (share === null) return isUnpaid(c.billing) ? 'exposure-unknown' : null;
+        if (share > (input.exposureCap ?? EXPOSURE_SHARE_CAP)) return 'exposure-cap';
+    }
+    return null;
+}
+
+/** A known positive quota before an unknown one, more before less; list order breaks ties. */
+function byQuota(a: RouteCandidate, b: RouteCandidate): number {
+    if (a.remainingQuota === b.remainingQuota) return 0;
+    if (a.remainingQuota === null) return 1;
+    if (b.remainingQuota === null) return -1;
+    return b.remainingQuota - a.remainingQuota;
+}
+
+export interface RouteChain {
+    /** Every admissible route, in the order a failed call walks them. */
+    readonly chain: RouteCandidate[];
+    readonly headOnly: boolean;
+    readonly refused: RouteRefusal[];
+}
+
+export function chooseRouteChain(input: ChooseInput): RouteChain {
+    const refused: RouteRefusal[] = [];
+    if (isHeadOnlyKind(input.kind)) return { chain: [], headOnly: true, refused };
+    const admissible: RouteCandidate[] = [];
+    for (const c of input.candidates) {
+        const why = refusalOf(c, input);
+        if (why === null) admissible.push(c);
+        else refused.push({ name: c.name, reason: why });
+    }
+    const share = (c: RouteCandidate): number => input.exposureShare?.(c.name) ?? 0;
+    const order = (a: RouteCandidate, b: RouteCandidate): number => share(a) - share(b) || byQuota(a, b);
+    const unpaid = admissible.filter((c) => isUnpaid(c.billing)).sort(order);
+    const paid = admissible.filter((c) => !isUnpaid(c.billing)).sort(order);
+    return { chain: [...unpaid, ...paid], headOnly: false, refused };
+}
+
+export function chooseRoute(input: ChooseInput): RouteChoice {
+    const { chain, headOnly, refused } = chooseRouteChain(input);
+    if (headOnly) return { route: null, reason: 'head-only', refused };
+    const first = chain[0];
+    if (first === undefined) return { route: null, reason: 'no-admissible-route', refused };
+    return { route: first, reason: isUnpaid(first.billing) ? 'unpaid-route' : 'paid-fallback', refused };
+}
+
+const _BILLINGS: ReadonlySet<string> = new Set<string>(ROUTE_BILLINGS);
+
+/**
+ * A council member as a route. Members built today carry none of the route
+ * fields, so they map to a paid, project-content, live route — exactly the seat
+ * they were. A member whose billing is `free-quota` is pinned to
+ * `public-artifact` whatever ceiling it declares: every free route stays there.
+ * A `self-hosted` member that declares no ceiling gets `public-artifact` too;
+ * only a declared, probed `content_ceiling` raises it.
+ */
+export function routeCandidateFromMember(member: ExternalAIClient): RouteCandidate {
+    const m = member as unknown as Record<string, unknown>;
+    const name = (typeof m['name'] === 'string' && m['name']) || (typeof m['provider'] === 'string' && m['provider']) || 'unknown';
+    // A base_url route member names its class `billing`; other members may say `billing_class`.
+    const declared = m['billing_class'] ?? m['billing'];
+    const billing: RouteBilling =
+        typeof declared === 'string' && _BILLINGS.has(declared)
+            ? (declared as RouteBilling)
+            : m['billable'] === false
+              ? 'subscription'
+              : 'per-token';
+    // An unpaid route that names no ceiling gets the narrow one; only a member
+    // that predates route fields keeps the default seat ceiling.
+    const ceiling: ContentClass =
+        billing === 'free-quota'
+            ? 'public-artifact'
+            : classifyContentClass(m['content_ceiling'], isUnpaid(billing) ? 'public-artifact' : DEFAULT_SEAT_CEILING);
+    const quota = m['remaining_quota'];
+    return {
+        name,
+        billing,
+        ceiling,
+        remainingQuota: typeof quota === 'number' && Number.isFinite(quota) ? quota : null,
+        live: m['live'] !== false,
+    };
+}

package/src/scripts/ai_council/route_liveness.ts

@@ -0,0 +1,152 @@
+/**
+ * Liveness of a `base_url` route, per route and model: streaks, not last
+ * outcomes (gateway M9).
+ *
+ * The outcome names are the closed failure vocabulary of
+ * road-to-seats-that-know-why-they-failed — `rate_limited`,
+ * `quota_exhausted`, `model_unservable`, `server_error`, `billing` — read here
+ * from the route's own HTTP answer by a small local classifier, so the two
+ * converge when that roadmap's shared table lands instead of meeting a second
+ * vocabulary.
+ *
+ * Only `model_unservable` speaks about the model: a throttle, an empty quota or
+ * a server fault says the route is busy or down for this pass, never that the
+ * model is gone, so they never count against liveness and never break a streak.
+ * An answered call resets it. Three consecutive unservable answers retire the
+ * model from the discovered roster until a later discovery serves it again.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readRouteRoster, retireRouteModel } from './free_route_catalog.js';
+import type { CliFailureClass } from './transport_resolver.js';
+
+export const ROUTE_OUTCOMES = [
+    'ok',
+    'rate_limited',
+    'quota_exhausted',
+    'model_unservable',
+    'server_error',
+    'billing',
+    'other',
+] as const;
+export type RouteOutcome = (typeof ROUTE_OUTCOMES)[number];
+
+export const RETIRE_STREAK = 3;
+
+/** Runtime state beside `council-route-models.json`; gitignored, never committed. */
+export const ROUTE_LIVENESS_RELPATH = path.join('agents', 'runtime', 'state', 'council-route-liveness.json');
+
+const _QUOTA_TEXT = /insufficient_quota|quota exceeded|exceeded your current quota|usage limit/i;
+
+/** The route's answer as one vocabulary name; `null` / empty means it answered. */
+export function classifyRouteOutcome(error: string | null | undefined): RouteOutcome {
+    if (error === null || error === undefined || error.trim() === '') return 'ok';
+    const s = error.trim();
+    if (s.startsWith('policy_unproven_cost')) return 'billing';
+    const m = /^HTTP (\d{3})\b:?\s*([\s\S]*)$/.exec(s);
+    if (m === null) return 'other';
+    const status = Number(m[1]);
+    const body = m[2] ?? '';
+    if (status === 402) return 'billing';
+    if (status === 429) return _QUOTA_TEXT.test(body) ? 'quota_exhausted' : 'rate_limited';
+    if (status === 410) return 'model_unservable';
+    if (status === 404) return /\bmodel\b/i.test(body) ? 'model_unservable' : 'other';
+    // 501 and 505 say the route cannot do this at all; retrying is pointless.
+    if (status >= 500 && status <= 599 && status !== 501 && status !== 505) return 'server_error';
+    return 'other';
+}
+
+/** Absent for this pass only: busy or down, never evidence about the model. */
+export function isAbsentForPass(outcome: RouteOutcome): boolean {
+    return outcome === 'rate_limited' || outcome === 'quota_exhausted' || outcome === 'server_error';
+}
+
+/** The outcome as the class `MidFlightFallback` gates on. */
+export function routeFailureClass(outcome: RouteOutcome): CliFailureClass {
+    switch (outcome) {
+        case 'rate_limited':
+        case 'quota_exhausted':
+            return 'quota_exhausted';
+        case 'model_unservable':
+            return 'model_unservable';
+        case 'server_error':
+            return 'server_error';
+        default:
+            return 'other';
+    }
+}
+
+interface LivenessEntry {
+    readonly streak: number;
+    readonly last: RouteOutcome;
+    readonly observed_at: string;
+    readonly retired_at?: string;
+}
+
+type Store = Record<string, Record<string, LivenessEntry>>;
+
+function _storePath(repoRoot: string): string {
+    return path.join(repoRoot, ROUTE_LIVENESS_RELPATH);
+}
+
+function _readStore(repoRoot: string): Store {
+    try {
+        const raw = JSON.parse(fs.readFileSync(_storePath(repoRoot), 'utf8')) as unknown;
+        return raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Store) : {};
+    } catch {
+        return {};
+    }
+}
+
+function _writeStore(repoRoot: string, store: Store): void {
+    const target = _storePath(repoRoot);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
+    fs.renameSync(tmp, target);
+}
+
+/** A retirement stands until the roster is re-discovered after it. */
+function _retirementStands(repoRoot: string, routeKey: string, entry: LivenessEntry | undefined): boolean {
+    if (entry?.retired_at === undefined) return false;
+    const roster = readRouteRoster(repoRoot, routeKey);
+    return roster.status !== 'known' || roster.observed_at <= entry.retired_at;
+}
+
+export function isRouteModelLive(repoRoot: string, routeKey: string, model: string): boolean {
+    return !_retirementStands(repoRoot, routeKey, _readStore(repoRoot)[routeKey]?.[model]);
+}
+
+export interface RecordedOutcome {
+    readonly streak: number;
+    readonly retired: boolean;
+    readonly absentForPass: boolean;
+}
+
+export function recordRouteOutcome(
+    repoRoot: string,
+    routeKey: string,
+    model: string,
+    outcome: RouteOutcome,
+    now: Date = new Date(),
+): RecordedOutcome {
+    const store = _readStore(repoRoot);
+    const route = store[routeKey] ?? {};
+    let prev = route[model];
+    if (prev?.retired_at !== undefined && !_retirementStands(repoRoot, routeKey, prev)) prev = undefined;
+    const before = prev?.streak ?? 0;
+    const streak = outcome === 'ok' ? 0 : outcome === 'model_unservable' ? before + 1 : before;
+    const observed_at = now.toISOString();
+    let retiredAt = prev?.retired_at;
+    if (retiredAt === undefined && streak >= RETIRE_STREAK) {
+        retiredAt = observed_at;
+        retireRouteModel(repoRoot, routeKey, model);
+    }
+    route[model] = { streak, last: outcome, observed_at, ...(retiredAt !== undefined ? { retired_at: retiredAt } : {}) };
+    store[routeKey] = route;
+    _writeStore(repoRoot, store);
+    return { streak, retired: retiredAt !== undefined, absentForPass: isAbsentForPass(outcome) };
+}
+

package/src/scripts/ai_council/route_member.ts

@@ -0,0 +1,52 @@
+/**
+ * Construct a `base_url` route member for a council pass, or say why it is
+ * absent. Lives apart from `council_cli.ts`, which is far past the source
+ * ceiling, and apart from `free_route.ts`, which `config.ts` imports and which
+ * therefore must not import the loader back.
+ */
+
+import { PROVIDER_TABLE } from '../_lib/environment_detector.js';
+import { resolve_api_key } from './config.js';
+import type { ContentClass } from './content_ceiling.js';
+import { FreeRouteClient } from './free_route_client.js';
+import {
+    parseRouteFields,
+    resolveRouteTransport,
+    UNPROVEN_PROBE,
+    type RouteBilling,
+    type SelfHostedProbe,
+} from './free_route.js';
+import { keyResolves } from './status_surface.js';
+
+export type RouteMemberResult =
+    | { readonly client: FreeRouteClient }
+    | { readonly absent: { member: string; reason: string; detail: string } };
+
+/** `null` for a provider member; otherwise the constructed client or its absence. */
+export function routeMemberFor(
+    name: string,
+    cfg: Record<string, unknown>,
+    contentClass: ContentClass,
+    modelOverride?: string,
+    probe: SelfHostedProbe = UNPROVEN_PROBE,
+): RouteMemberResult | null {
+    const parsed = parseRouteFields(name, cfg, Object.hasOwn(PROVIDER_TABLE, name));
+    if ('error' in parsed) return { absent: { member: name, reason: 'policy_unknown', detail: parsed.error } };
+    const route = parsed.route;
+    if (route === null) return null;
+    const model = modelOverride || (typeof cfg['model'] === 'string' ? cfg['model'] : '');
+    const ref = typeof cfg['api_key_ref'] === 'string' ? cfg['api_key_ref'] : null;
+    const t = resolveRouteTransport({ name, route, model, contentClass, keyPresent: keyResolves(ref), probe });
+    if (!t.available) {
+        return { absent: { member: name, reason: t.absentReason ?? 'unavailable', detail: t.reason ?? 'route unavailable' } };
+    }
+    return {
+        client: new FreeRouteClient({
+            name,
+            model,
+            base_url: route.base_url,
+            api_key: ref === null ? null : resolve_api_key(ref, `ai_council.members.${name}`),
+            billing: t.billing as RouteBilling,
+        }),
+    };
+}

package/src/scripts/ai_council/seat_policy.ts

@@ -135,3 +135,43 @@ export function parseSeatFields(
         },
     };
 }
+
+/**
+ * Council roles, and the three a route this package does not pay for may never
+ * hold (ADR-257: an unpaid route may propose and score, never decide). Kept
+ * apart from `PolicyExclusion`: that union makes a seat ABSENT for the whole
+ * run, while a role refusal leaves the seat free to propose or judge.
+ */
+export const COUNCIL_ROLES = ['proposer', 'juror', 'chair', 'synthesis', 'verdict'] as const;
+export type CouncilRole = (typeof COUNCIL_ROLES)[number];
+export const HEAD_ROLES: ReadonlySet<CouncilRole> = new Set<CouncilRole>(['chair', 'synthesis', 'verdict']);
+
+const _PAID_BILLING: ReadonlySet<string> = new Set(['subscription', 'per-token']);
+/** The classes positively known to cost the package nothing per call. */
+export const UNPAID_BILLING_CLASSES: readonly string[] = ['free-quota', 'self-hosted'];
+
+/**
+ * True unless the billing class is a paid one. Absent means a seat configured
+ * before billing classes existed, all of them paid; any other unrecognised
+ * value fails closed, so a typo cannot hand a free route the chair.
+ */
+export function isUnpaidBilling(billing: string | null | undefined): boolean {
+    return billing !== undefined && billing !== null && !_PAID_BILLING.has(billing);
+}
+
+export interface RoleRefusal {
+    readonly reason: 'unpaid_head_role';
+    readonly message: string;
+}
+
+export function seatRoleRefusal(
+    role: CouncilRole,
+    billing: string | null | undefined,
+    seat = 'this seat',
+): RoleRefusal | null {
+    if (!HEAD_ROLES.has(role) || !isUnpaidBilling(billing)) return null;
+    return {
+        reason: 'unpaid_head_role',
+        message: `${seat} (billing ${String(billing)}) may not hold the ${role} role: an unpaid route proposes and scores, never decides (ADR-257)`,
+    };
+}