@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/ai_council/free_route.ts

@@ -0,0 +1,216 @@
+/**
+ * A council member reached over an OpenAI-compatible `base_url` — a route the
+ * package does not pay for by default.
+ *
+ * Kept out of `config.ts` and `clients.ts`, which both sit far past the source
+ * ceiling. Imports no client code: `config.ts` loads this and is itself in the
+ * hook bundle. The client is `free_route_client.ts`.
+ *
+ * The rules, each failing toward the metered or restricted side:
+ *
+ * - billing is `free-quota` only with a dated proof (keyless endpoint or a
+ *   documented free tier); without one the route is `per-token` and stays
+ *   inside the USD gate;
+ * - an HTTP 402 is `policy_unproven_cost` — the route asked for money, so its
+ *   free claim is void for the pass, and no other route is tried in its place;
+ * - every route sits at the `public-artifact` ceiling; only a loopback route
+ *   whose per-model probe shows local weights and no outbound connection may
+ *   carry its declared ceiling (`self-hosted`). Loopback alone proves nothing:
+ *   a local proxy forwards upstream;
+ * - identity is derived from the served id, and a route serving another model
+ *   than the one requested is absent with `policy_model_mismatch`;
+ * - random or auto routers are refused at config time: their family is unknown
+ *   until after the call.
+ */
+
+import { admitsContent, classifyContentClass, DEFAULT_CONTENT_CLASS, type ContentClass } from './content_ceiling.js';
+import type { BillingClass } from '../_lib/environment_detector.js';
+import type { ResolvedTransport } from './transport_resolver.js';
+
+export type RouteBilling = Extract<BillingClass, 'free-quota' | 'per-token' | 'self-hosted'>;
+
+export const BILLING_PROOF_KINDS = ['keyless', 'free-tier'] as const;
+export type BillingProofKind = (typeof BILLING_PROOF_KINDS)[number];
+
+export interface BillingProof {
+    readonly kind: BillingProofKind;
+    readonly url: string;
+    /** `YYYY-MM-DD` — the day someone read the documented free terms. */
+    readonly checked: string;
+}
+
+export interface RouteSpec {
+    readonly base_url: string;
+    readonly keyless: boolean;
+    readonly proof: BillingProof | null;
+    readonly loopback: boolean;
+    /** The configured ceiling; effective only for a probed self-hosted route. */
+    readonly declared_ceiling: ContentClass;
+}
+
+/** What a self-hosted probe observed for one model. */
+export interface SelfHostedProbeResult {
+    readonly weights: 'local' | 'remote' | 'unknown';
+    /** True when an outbound connection was seen during the probe call; null when unmeasured. */
+    readonly outbound: boolean | null;
+}
+
+export type SelfHostedProbe = (route: RouteSpec, model: string) => SelfHostedProbeResult;
+
+/** Nothing measured, nothing proven: the default, so production never raises a ceiling by omission. */
+export const UNPROVEN_PROBE: SelfHostedProbe = () => ({ weights: 'unknown', outbound: null });
+
+const _ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+export function isRealDate(s: unknown): s is string {
+    if (typeof s !== 'string' || !_ISO_DATE.test(s)) return false;
+    const [y, m, d] = s.split('-').map(Number) as [number, number, number];
+    const probe = new Date(Date.UTC(y, m - 1, d));
+    return probe.getUTCFullYear() === y && probe.getUTCMonth() + 1 === m && probe.getUTCDate() === d;
+}
+
+/** `localhost`, `127.0.0.0/8` and `::1`. A name that merely resolves locally does not count. */
+export function isLoopbackUrl(raw: string): boolean {
+    let host: string;
+    try {
+        host = new URL(raw).hostname.toLowerCase();
+    } catch {
+        return false;
+    }
+    if (host === 'localhost' || host === '[::1]' || host === '::1') return true;
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+
+/** A model id that asks the route to pick for us (K2). */
+export function isRandomRouter(model: string): boolean {
+    return /^(?:.*\/)?(?:auto|random|free|router)(?::.*)?$/i.test(model.trim());
+}
+
+function _parseProof(name: string, raw: unknown, keyless: boolean): BillingProof | { error: string } | null {
+    if (raw === undefined || raw === null) return null;
+    const where = `members.${name}.billing_proof`;
+    if (typeof raw !== 'object' || Array.isArray(raw)) return { error: `${where} must be a mapping with kind, url and checked.` };
+    const p = raw as Record<string, unknown>;
+    if (!BILLING_PROOF_KINDS.includes(p['kind'] as BillingProofKind)) {
+        return { error: `${where}.kind must be one of ${BILLING_PROOF_KINDS.join(', ')}.` };
+    }
+    if (typeof p['url'] !== 'string' || !/^https:\/\/\S+$/.test(p['url'])) {
+        return { error: `${where}.url must be the https URL documenting the free terms.` };
+    }
+    // An unquoted YAML date is a Date object and may have rolled an impossible value over.
+    if (!isRealDate(p['checked'])) {
+        return { error: `${where}.checked must be a quoted 'YYYY-MM-DD' date — an undated proof proves nothing.` };
+    }
+    if (p['kind'] === 'keyless' && !keyless) {
+        return { error: `${where}.kind is 'keyless' but the member carries an api_key_ref.` };
+    }
+    return { kind: p['kind'] as BillingProofKind, url: p['url'], checked: p['checked'] };
+}
+
+/**
+ * The route half of a member's config. `{ route: null }` for a member without
+ * `base_url`; an error message (the loader raises it) for a malformed one.
+ */
+export function parseRouteFields(
+    name: string,
+    raw: Record<string, unknown>,
+    knownProvider: boolean,
+): { route: RouteSpec | null } | { error: string } {
+    const base = raw['base_url'];
+    if (base === undefined || base === null) {
+        return raw['billing_proof'] === undefined ? { route: null } : { error: `members.${name}.billing_proof needs base_url.` };
+    }
+    if (knownProvider) {
+        return { error: `members.${name}: base_url names a route, so the member needs its own name, not a provider's.` };
+    }
+    let url: URL;
+    try {
+        url = new URL(String(base));
+    } catch {
+        return { error: `members.${name}.base_url is not a URL (got ${JSON.stringify(base)}).` };
+    }
+    const loopback = isLoopbackUrl(url.href);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+        return { error: `members.${name}.base_url must use https unless it is a loopback address.` };
+    }
+    const model = raw['model'];
+    if (typeof model === 'string' && isRandomRouter(model)) {
+        return { error: `members.${name}.model ${JSON.stringify(model)} is a random/auto router; its identity is unknown before the call.` };
+    }
+    const ref = raw['api_key_ref'];
+    const keyless = ref === undefined || ref === null || ref === '';
+    const proof = _parseProof(name, raw['billing_proof'], keyless);
+    if (proof !== null && 'error' in proof) return proof;
+    return {
+        route: {
+            base_url: String(base).replace(/\/+$/, ''),
+            keyless,
+            proof,
+            loopback,
+            declared_ceiling: classifyContentClass(raw['content_ceiling']),
+        },
+    };
+}
+
+function _provenLocal(route: RouteSpec, probe: SelfHostedProbeResult): boolean {
+    return route.loopback && probe.weights === 'local' && probe.outbound === false;
+}
+
+export function routeBilling(route: RouteSpec, probe: SelfHostedProbeResult = UNPROVEN_PROBE(route, '')): RouteBilling {
+    if (_provenLocal(route, probe)) return 'self-hosted';
+    return route.proof === null ? 'per-token' : 'free-quota';
+}
+
+/** `public-artifact` for every route, except a proven self-hosted one. */
+export function routeCeiling(route: RouteSpec, probe: SelfHostedProbeResult = UNPROVEN_PROBE(route, '')): ContentClass {
+    return _provenLocal(route, probe) ? route.declared_ceiling : 'public-artifact';
+}
+
+export interface ResolveRouteOptions {
+    readonly name: string;
+    readonly route: RouteSpec;
+    readonly model: string;
+    readonly contentClass?: ContentClass | null;
+    /** Whether the member's `api_key_ref` resolves; ignored for a keyless route. */
+    readonly keyPresent?: boolean;
+    readonly probe?: SelfHostedProbe;
+}
+
+export function resolveRouteTransport(opts: ResolveRouteOptions): ResolvedTransport {
+    const result = (opts.probe ?? UNPROVEN_PROBE)(opts.route, opts.model);
+    const billing = routeBilling(opts.route, result);
+    const absent = (reason: string, absentReason: ResolvedTransport['absentReason']): ResolvedTransport => ({
+        available: false, transport: null, billing, authSource: null, makesProviderCall: false, reason, absentReason,
+    });
+    const verdict = admitsContent(routeCeiling(opts.route, result), opts.contentClass ?? DEFAULT_CONTENT_CLASS);
+    if (!verdict.admitted) {
+        return absent(`${opts.name}: ${verdict.reason ?? 'content ceiling refused the payload'}`, 'policy_content_ceiling');
+    }
+    if (!opts.route.keyless && opts.keyPresent !== true) {
+        return absent(`${opts.name}: the route's api_key_ref does not resolve`, 'no_auth');
+    }
+    return {
+        available: true,
+        transport: 'api',
+        billing,
+        authSource: opts.route.keyless ? null : 'env-key',
+        makesProviderCall: true,
+        reason: null,
+        absentReason: null,
+    };
+}
+
+/** The family a served id belongs to: the leading word of its last path segment. */
+export function familyOf(servedId: string): string {
+    const last = servedId.trim().split('/').pop() ?? '';
+    return (last.split(/[^a-zA-Z]+/).find((t) => t !== '') ?? '').toLowerCase();
+}
+
+/** Same model, allowing only a vendor prefix and a dated or variant suffix of the requested id. */
+export function servedMatches(requested: string, served: string): boolean {
+    const norm = (s: string): string => (s.trim().split('/').pop() ?? '').toLowerCase();
+    const r = norm(requested);
+    const s = norm(served);
+    if (r === '' || s === '') return false;
+    return s === r || (s.startsWith(`${r}-`) && familyOf(s) === familyOf(r));
+}

package/src/scripts/ai_council/free_route_catalog.ts

@@ -0,0 +1,173 @@
+// egress-content: fixed-corpus — a GET of the route's /models listing with no request body, never session content
+/**
+ * What the package ships about `base_url` routes: endpoints and dated data-use
+ * attestations, never model ids. Catalogues lose and gain rows within weeks,
+ * so a committed id is stale by the time it is read; the ids a route serves
+ * are discovered from its own `/models` and kept in gitignored runtime state.
+ *
+ * An attestation records what someone read in the route's terms on a date. It
+ * enforces nothing — every free route stays at the `public-artifact` ceiling
+ * whatever it says. It decides one thing: whether a route may be offered to
+ * consumers by default. A row without an attestation, or without the
+ * EEA/Switzerland/UK client-distribution field, is for the maintainer's own
+ * runs only: some free tiers require paid service once a client distributed
+ * to users in those regions exists.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { isRealDate } from './free_route.js';
+
+export interface RouteAttestation {
+    /** `YYYY-MM-DD` the terms were read. */
+    readonly checked: string;
+    readonly source_url: string;
+    readonly trains_on_prompts: boolean;
+    /** Whether the terms permit use inside a client distributed to users in the EEA, Switzerland and the UK. */
+    readonly client_distribution_eea_ch_uk?: 'permitted' | 'forbidden';
+}
+
+export interface CatalogRoute {
+    readonly id: string;
+    readonly base_url: string;
+    readonly keyless: boolean;
+    /** `null` until someone reads the terms and dates what they say. */
+    readonly attestation: RouteAttestation | null;
+}
+
+/**
+ * Base URLs only. No row carries an attestation yet: none has been read and
+ * dated, so every row is maintainer-only until one is.
+ */
+export const ROUTE_CATALOG: readonly CatalogRoute[] = [
+    { id: 'groq', base_url: 'https://api.groq.com/openai/v1', keyless: false, attestation: null },
+    { id: 'cerebras', base_url: 'https://api.cerebras.ai/v1', keyless: false, attestation: null },
+    { id: 'openrouter', base_url: 'https://openrouter.ai/api/v1', keyless: false, attestation: null },
+    { id: 'huggingface', base_url: 'https://router.huggingface.co/v1', keyless: false, attestation: null },
+    { id: 'nvidia', base_url: 'https://integrate.api.nvidia.com/v1', keyless: false, attestation: null },
+];
+
+/** Terms drift; an attestation older than this no longer speaks for the route. */
+export const ATTESTATION_MAX_AGE_DAYS = 90;
+
+export interface ConsumerDefaultVerdict {
+    readonly admissible: boolean;
+    readonly reason: string;
+}
+
+export function consumerDefaultVerdict(route: CatalogRoute, now: Date = new Date()): ConsumerDefaultVerdict {
+    const a = route.attestation;
+    if (a === null) return { admissible: false, reason: `${route.id}: unattested — maintainer runs only` };
+    if (!isRealDate(a.checked)) return { admissible: false, reason: `${route.id}: attestation is undated — maintainer runs only` };
+    const ageDays = (now.getTime() - Date.parse(`${a.checked}T00:00:00Z`)) / 86_400_000;
+    if (ageDays > ATTESTATION_MAX_AGE_DAYS) {
+        return { admissible: false, reason: `${route.id}: attestation from ${a.checked} is older than ${ATTESTATION_MAX_AGE_DAYS} days` };
+    }
+    if (a.client_distribution_eea_ch_uk === undefined) {
+        return { admissible: false, reason: `${route.id}: attestation records no EEA/CH/UK distribution term — maintainer runs only` };
+    }
+    if (a.client_distribution_eea_ch_uk === 'forbidden') {
+        return { admissible: false, reason: `${route.id}: terms forbid use in a client distributed to EEA/CH/UK users` };
+    }
+    return { admissible: true, reason: `${route.id}: attested ${a.checked}` };
+}
+
+export function consumerDefaultRoutes(now: Date = new Date()): CatalogRoute[] {
+    return ROUTE_CATALOG.filter((r) => consumerDefaultVerdict(r, now).admissible);
+}
+
+/** Runtime state beside `council-probes.json`; gitignored, never committed. */
+export const ROUTE_MODELS_RELPATH = path.join('agents', 'runtime', 'state', 'council-route-models.json');
+
+export type RouteRoster =
+    | { readonly status: 'known'; readonly models: readonly string[]; readonly observed_at: string }
+    | { readonly status: 'unknown'; readonly reason: string };
+
+interface StoredRoster {
+    readonly base_url: string;
+    readonly models: readonly string[];
+    readonly observed_at: string;
+}
+
+function _storePath(repoRoot: string): string {
+    return path.join(repoRoot, ROUTE_MODELS_RELPATH);
+}
+
+/** Corrupt or missing state reads as "nothing observed". */
+function _readStore(repoRoot: string): Record<string, StoredRoster> {
+    try {
+        const raw = JSON.parse(fs.readFileSync(_storePath(repoRoot), 'utf8')) as unknown;
+        return raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, StoredRoster>) : {};
+    } catch {
+        return {};
+    }
+}
+
+function _writeStore(repoRoot: string, store: Record<string, StoredRoster>): 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);
+}
+
+export function readRouteRoster(repoRoot: string, routeKey: string): RouteRoster {
+    const row = _readStore(repoRoot)[routeKey];
+    if (row === undefined || !Array.isArray(row.models)) return { status: 'unknown', reason: 'never discovered' };
+    return { status: 'known', models: row.models, observed_at: row.observed_at };
+}
+
+/**
+ * Drop one model from a route's discovered roster; the next discovery that
+ * serves it brings it back. False when the roster does not list it.
+ */
+export function retireRouteModel(repoRoot: string, routeKey: string, model: string): boolean {
+    const store = _readStore(repoRoot);
+    const row = store[routeKey];
+    if (row === undefined || !Array.isArray(row.models) || !row.models.includes(model)) return false;
+    store[routeKey] = { ...row, models: row.models.filter((m) => m !== model) };
+    _writeStore(repoRoot, store);
+    return true;
+}
+
+export interface DiscoverOptions {
+    readonly repoRoot: string;
+    readonly apiKey?: string | null;
+    readonly fetchImpl?: typeof fetch;
+    readonly now?: Date;
+    readonly timeoutMs?: number;
+}
+
+/**
+ * One GET of `<base_url>/models`. A failure clears the stored entry, so an
+ * offline route reads `unknown` rather than the list it served last time.
+ */
+export async function discoverRouteModels(routeKey: string, baseUrl: string, opts: DiscoverOptions): Promise<RouteRoster> {
+    const store = _readStore(opts.repoRoot);
+    let models: string[];
+    try {
+        const headers: Record<string, string> = { accept: 'application/json' };
+        if (opts.apiKey) headers['authorization'] = `Bearer ${opts.apiKey}`;
+        const res = await (opts.fetchImpl ?? fetch)(`${baseUrl.replace(/\/+$/, '')}/models`, {
+            headers,
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
+        });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const body = (await res.json()) as { data?: unknown };
+        if (!Array.isArray(body.data)) throw new Error('no data array in the /models answer');
+        models = body.data
+            .map((m) => (m !== null && typeof m === 'object' ? (m as Record<string, unknown>)['id'] : undefined))
+            .filter((id): id is string => typeof id === 'string' && id !== '');
+    } catch (exc) {
+        if (routeKey in store) {
+            delete store[routeKey];
+            _writeStore(opts.repoRoot, store);
+        }
+        return { status: 'unknown', reason: exc instanceof Error ? exc.message : String(exc) };
+    }
+    const observed_at = (opts.now ?? new Date()).toISOString();
+    store[routeKey] = { base_url: baseUrl, models, observed_at };
+    _writeStore(opts.repoRoot, store);
+    return { status: 'known', models, observed_at };
+}

package/src/scripts/ai_council/free_route_client.ts

@@ -0,0 +1,95 @@
+/**
+ * The `chat/completions` client for a `base_url` route. Separate from
+ * `free_route.ts` so the config loader, which sits in the hook bundle, does not
+ * pull the client layer in.
+ */
+
+import { curlJsonPost, type JsonPost } from './api_transport.js';
+import { CouncilResponse, ExternalAIClient } from './clients.js';
+import { familyOf, servedMatches, type RouteBilling } from './free_route.js';
+import { policyExclusionReason, type PolicyExclusion } from './seat_policy.js';
+
+export interface FreeRouteClientOptions {
+    readonly name: string;
+    readonly model: string;
+    readonly base_url: string;
+    readonly api_key: string | null;
+    readonly billing: RouteBilling;
+    readonly post?: JsonPost;
+}
+
+/**
+ * `chat/completions` against a route. Distinct from `_OpenAICompatibleClient`
+ * because a keyless route must send no Authorization header at all, and
+ * because its answer is only kept when the served model is the requested one.
+ * Paid provider clients keep `model_served` as attribution only.
+ */
+export class FreeRouteClient extends ExternalAIClient {
+    readonly base_url: string;
+    readonly billing: RouteBilling;
+    private readonly _apiKey: string | null;
+    private readonly _post: JsonPost;
+
+    constructor(opts: FreeRouteClientOptions) {
+        super();
+        this.name = opts.name;
+        this.model = opts.model;
+        this.base_url = opts.base_url.replace(/\/+$/, '');
+        this.billing = opts.billing;
+        this.billable = opts.billing === 'per-token';
+        this._apiKey = opts.api_key;
+        this._post = opts.post ?? curlJsonPost;
+    }
+
+    private _refused(exclusion: PolicyExclusion, detail: string, latency_ms: number, served = ''): CouncilResponse {
+        return new CouncilResponse({
+            provider: this.name,
+            model: this.model,
+            model_served: served,
+            text: '',
+            latency_ms,
+            error: `${exclusion}: ${policyExclusionReason(exclusion, this.name)} — ${detail}`,
+            metadata: { absent_reason: exclusion, billing: this.billing, route: this.base_url },
+        });
+    }
+
+    override ask(system_prompt: string, user_prompt: string, max_tokens = 2048): CouncilResponse {
+        const t0 = performance.now();
+        const headers = this._apiKey === null ? [] : [`authorization: Bearer ${this._apiKey}`];
+        let response: Record<string, unknown>;
+        try {
+            response = (this._post(`${this.base_url}/chat/completions`, headers, {
+                model: this.model,
+                max_tokens,
+                messages: [
+                    { role: 'system', content: system_prompt },
+                    { role: 'user', content: user_prompt },
+                ],
+            }) ?? {}) as Record<string, unknown>;
+        } catch (exc) {
+            const msg = exc instanceof Error ? exc.message : String(exc);
+            const ms = Math.trunc(performance.now() - t0);
+            if (/^HTTP 402\b/.test(msg)) return this._refused('policy_unproven_cost', 'the route answered 402; no paid fallback is tried', ms);
+            return new CouncilResponse({ provider: this.name, model: this.model, text: '', latency_ms: ms, error: msg });
+        }
+        const ms = Math.trunc(performance.now() - t0);
+        const served = typeof response['model'] === 'string' ? response['model'] : '';
+        if (!servedMatches(this.model, served)) {
+            return this._refused('policy_model_mismatch', `requested ${this.model}, served ${served || '(none reported)'}`, ms, served);
+        }
+        const choices = Array.isArray(response['choices']) ? (response['choices'] as Record<string, unknown>[]) : [];
+        const message = (choices[0]?.['message'] ?? {}) as Record<string, unknown>;
+        const usage = (response['usage'] ?? {}) as Record<string, unknown>;
+        const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+        return new CouncilResponse({
+            provider: this.name,
+            model: this.model,
+            model_served: served,
+            text: typeof message['content'] === 'string' ? message['content'] : '',
+            input_tokens: num(usage['prompt_tokens']),
+            output_tokens: num(usage['completion_tokens']),
+            latency_ms: ms,
+            metadata: { family: familyOf(served), billing: this.billing, route: this.base_url, billable: this.billable },
+        });
+    }
+}

package/src/scripts/ai_council/free_rung.ts

@@ -0,0 +1,61 @@
+/**
+ * Whether the council config declares an unpaid route a hand could reach —
+ * the question the per-prompt delegation nudge asks before naming the free
+ * rung. Kept apart from `route_member.ts` and `config.ts`, whose import graph
+ * would put the whole council loader into the hook bundle.
+ *
+ * It is a pointer check, not the admission: `ask_transport`'s route chooser
+ * still decides per call. A key reference other than `env:` cannot be resolved
+ * here cheaply, so it answers false rather than name a rung it cannot verify.
+ */
+import * as fs from 'node:fs';
+
+import { parse as parseYaml } from 'yaml';
+
+import { resolve_with_fallback } from '../_lib/user_global_paths.js';
+import type { HandKind } from '../_lib/hand_kinds.js';
+import { parseRouteFields, resolveRouteTransport } from './free_route.js';
+import { isKindFlipped } from './kind_flip_state.js';
+
+const COUNCIL_CONFIG_ENV = 'AI_COUNCIL_CONFIG';
+const COUNCIL_CONFIG_REL = 'settings/.ai-council.yml';
+
+function keyPresent(ref: unknown): boolean {
+    if (ref === undefined || ref === null) return true;
+    if (typeof ref !== 'string' || !ref.startsWith('env:')) return false;
+    return (process.env[ref.slice(4)] ?? '') !== '';
+}
+
+export function freeRouteAvailable(configPath: string): boolean {
+    let raw: unknown;
+    try {
+        raw = parseYaml(fs.readFileSync(configPath, 'utf-8'), { version: '1.1' });
+    } catch {
+        return false;
+    }
+    const members = (raw as { members?: unknown } | null)?.members;
+    if (members === null || typeof members !== 'object') return false;
+    for (const [name, value] of Object.entries(members as Record<string, unknown>)) {
+        if (value === null || typeof value !== 'object') continue;
+        const cfg = value as Record<string, unknown>;
+        if (cfg['enabled'] !== true) continue;
+        const parsed = parseRouteFields(name, cfg, false);
+        if ('error' in parsed || parsed.route === null) continue;
+        const model = typeof cfg['model'] === 'string' ? cfg['model'] : '';
+        const t = resolveRouteTransport({ name, route: parsed.route, model, contentClass: 'public-artifact', keyPresent: keyPresent(cfg['api_key_ref']) });
+        if (t.available && t.billing !== 'per-token') return true;
+    }
+    return false;
+}
+
+/** The user-global council config path, honouring the explicit override (ADR-104). */
+export function councilConfigPath(): string | null {
+    const override = process.env[COUNCIL_CONFIG_ENV];
+    if (override) return override.startsWith('~/') ? `${process.env['HOME'] ?? ''}${override.slice(1)}` : override;
+    return resolve_with_fallback(COUNCIL_CONFIG_REL, { env: null });
+}
+
+/** The free rung exists for `kind` only once the kind has flipped (6.3) and a route is declared. */
+export function freeRungFor(stateRoot: string, kind: HandKind, configPath: string | null): boolean {
+    return isKindFlipped(stateRoot, kind) && configPath !== null && freeRouteAvailable(configPath);
+}