@event4u/agent-config 14.20.0 → 14.21.0

package/src/scripts/ai_council/api_transport.ts

@@ -0,0 +1,163 @@
+/**
+ * The council's synchronous HTTP transport, and the per-provider shims that
+ * turn it into the SDK-shaped callables `clients.ts::ask()` reads.
+ *
+ * Extracted from `clients.ts` (road-to-admissible-council-seats 1.1). Two
+ * reasons, and only the first is about tidiness:
+ *
+ * 1. `clients.ts` is ~1,370 lines past the 1,500-line ceiling
+ *    `check_source_size_budget` ratchets, so every line added there costs one
+ *    excess line. The three shims below are new code; putting them in a file
+ *    UNDER the ceiling is what lets 1.1 land without raising a baseline.
+ * 2. Before 1.1 exactly one provider (OpenAI) had a live transport and the
+ *    other four constructors threw `… package not installed. pip install …`
+ *    after the api-key check — so `mode: api` was dead for gemini, xai and
+ *    perplexity. A shared shim module is the honest home for "how this
+ *    package actually reaches a provider over HTTP", rather than four
+ *    copies of the same curl call inside four constructors.
+ *
+ * The injectable seam. Every shim takes a `JsonPost` rather than calling `curlJsonPost` directly.
+ * A test can then construct a REAL client with a REAL api_key — exercising
+ * the shim-building path a mock `client:` object skips entirely — and still
+ * make no network call. That is the difference between testing the transport
+ * and testing around it.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+/** The one network primitive. Swappable so tests never reach the network. */
+export type JsonPost = (url: string, extraHeaders: string[], body: unknown) => unknown;
+
+export const GEMINI_BASE_URL = 'https://generativelanguage.googleapis.com/v1beta';
+
+/**
+ * Synchronous JSON POST via `curl` (no Node SDK, no Python). Matches the
+ * council's `spawnSync` transport model so the live-call clients stay
+ * synchronous. Returns the parsed response JSON (the provider HTTP APIs return
+ * exactly the SDK response shape `ask()` reads). Throws on transport failure or
+ * a non-2xx status so `ask()`'s catch surfaces it as a member error.
+ */
+export function curlJsonPost(url: string, extraHeaders: string[], body: unknown): unknown {
+    const args = ['-sS', '-X', 'POST', url, '-H', 'content-type: application/json'];
+    for (const h of extraHeaders) {
+        args.push('-H', h);
+    }
+    // `--connect-timeout` fast-fails a dead host; `--max-time` lets curl abort
+    // itself cleanly (surfacing a real `curl exited` error with stderr) ~10s
+    // before the `spawnSync` timeout would kill it with an opaque ETIMEDOUT.
+    // A full 16k-token generation legitimately runs several minutes, so the
+    // ceiling is 300s, not 120s (the old value timed out long Anthropic calls).
+    args.push('--connect-timeout', '30', '--max-time', '290');
+    args.push('-w', '\n%{http_code}', '--data-binary', '@-');
+    const r = spawnSync('curl', args, {
+        input: JSON.stringify(body),
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+        timeout: 300_000,
+    });
+    if (r.error) {
+        throw new Error(`curl spawn failed: ${(r.error as Error).message}`);
+    }
+    if (r.status !== 0) {
+        throw new Error(
+            `curl exited ${r.status ?? 'null'}: ${(r.stderr ?? '').toString().slice(0, 500)}`,
+        );
+    }
+    const out = (r.stdout ?? '').toString();
+    const nl = out.lastIndexOf('\n');
+    const httpCode = (nl >= 0 ? out.slice(nl + 1) : out).trim();
+    const bodyText = nl >= 0 ? out.slice(0, nl) : out;
+    if (!/^2\d\d$/.test(httpCode)) {
+        throw new Error(`HTTP ${httpCode}: ${bodyText.slice(0, 500)}`);
+    }
+    return JSON.parse(bodyText);
+}
+
+/**
+ * `chat.completions.create` over any OpenAI-compatible `/v1/chat/completions`.
+ * Used by OpenAI itself and by the two OpenAI-compatible vendors (xAI,
+ * Perplexity), whose only difference is the base URL.
+ *
+ * `baseUrl` is passed rather than read off `this.base_url`: a subclass field
+ * initializer (`override base_url = XAI_BASE_URL`) runs AFTER the base
+ * constructor, so reading the field during construction would silently build
+ * every compatible client against the empty string.
+ */
+export function openAiCompatibleClient(
+    baseUrl: string,
+    apiKey: string,
+    post: JsonPost = curlJsonPost,
+): unknown {
+    const url = `${baseUrl.replace(/\/+$/, '')}/chat/completions`;
+    return {
+        chat: {
+            completions: {
+                create: (kwargs: Record<string, unknown>): unknown =>
+                    post(url, [`authorization: Bearer ${apiKey}`], kwargs),
+            },
+        },
+    };
+}
+
+/**
+ * `models.generate_content` over the Gemini REST API, normalised to the
+ * `google-genai` SDK response shape `GeminiClient.ask()` reads.
+ *
+ * The normalisation is the whole point and is not cosmetic: REST answers with
+ * `candidates[0].content.parts[*].text` and `usageMetadata.promptTokenCount`,
+ * while `ask()` reads `.text`, `.model_version` and
+ * `.usage_metadata.{prompt_token_count, candidates_token_count}`. Rewriting
+ * `ask()` to read REST instead would break every injected SDK-shaped mock in
+ * the existing tests, so the adapter lives here, at the transport boundary,
+ * where a shape mismatch is a transport concern.
+ */
+export function geminiRestClient(
+    apiKey: string,
+    post: JsonPost = curlJsonPost,
+    baseUrl: string = GEMINI_BASE_URL,
+): unknown {
+    return {
+        models: {
+            generate_content: (kwargs: Record<string, unknown>): unknown => {
+                const model = String(kwargs['model'] ?? '');
+                const cfg = (kwargs['config'] ?? {}) as Record<string, unknown>;
+                const url = `${baseUrl.replace(/\/+$/, '')}/models/${model}:generateContent`;
+                const raw = post(
+                    url,
+                    [`x-goog-api-key: ${apiKey}`],
+                    {
+                        contents: [{ role: 'user', parts: [{ text: String(kwargs['contents'] ?? '') }] }],
+                        generationConfig: { maxOutputTokens: cfg['max_output_tokens'] ?? null },
+                    },
+                );
+                return normaliseGeminiRest(raw);
+            },
+        },
+    };
+}
+
+/** REST envelope → the `google-genai` SDK response shape. Exported for tests. */
+export function normaliseGeminiRest(raw: unknown): {
+    text: string;
+    model_version: string;
+    usage_metadata: { prompt_token_count: number; candidates_token_count: number };
+} {
+    const env = (raw ?? {}) as Record<string, unknown>;
+    const candidates = Array.isArray(env['candidates']) ? (env['candidates'] as unknown[]) : [];
+    const first = (candidates[0] ?? {}) as Record<string, unknown>;
+    const content = (first['content'] ?? {}) as Record<string, unknown>;
+    const parts = Array.isArray(content['parts']) ? (content['parts'] as unknown[]) : [];
+    const text = parts
+        .map((p) => String(((p ?? {}) as Record<string, unknown>)['text'] ?? ''))
+        .join('');
+    const usage = (env['usageMetadata'] ?? {}) as Record<string, unknown>;
+    const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+    return {
+        text,
+        model_version: String(env['modelVersion'] ?? ''),
+        usage_metadata: {
+            prompt_token_count: num(usage['promptTokenCount']),
+            candidates_token_count: num(usage['candidatesTokenCount']),
+        },
+    };
+}

package/src/scripts/ai_council/clients.ts

@@ -47,6 +47,12 @@ import * as path from 'node:path';
 
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
 import { boundFor } from './cli_agency_bounds.js';
+import {
+    curlJsonPost as _curlJsonPost,
+    geminiRestClient,
+    openAiCompatibleClient,
+    type JsonPost,
+} from './api_transport.js';
 import { SESSION_ROLE_ENV } from '../_lib/session_role.js';
 import { load_agent_settings } from '../_lib/agent_settings.js';
 
@@ -163,9 +169,8 @@ export const DEFAULT_OPENAI_CLI_MODEL = OPENAI_CLI_VENDOR_DEFAULT;
 export const DEFAULT_ANTHROPIC_CLI_MODEL = 'sonnet';
 export const DEFAULT_GEMINI_CLI_MODEL = 'gemini-2.5-pro';
 
-// OpenAI-API-compatible endpoints. xAI and Perplexity both expose the
-// `/v1/chat/completions` shape, so their clients reuse the `openai` SDK with a
-// custom `base_url`. Gemini has its own SDK (`google-genai`).
+// OpenAI-API-compatible endpoints — xAI and Perplexity both expose the
+// `/v1/chat/completions` shape, reached by one curl shim in `api_transport.ts`.
 export const XAI_BASE_URL = 'https://api.x.ai/v1';
 export const PERPLEXITY_BASE_URL = 'https://api.perplexity.ai';
 
@@ -461,6 +466,12 @@ interface ApiClientOptions {
     // Phase 4). Default '5m' when omitted — see `DEFAULT_PROMPT_CACHE_TTL`.
     // Only meaningful when `enable_prompt_cache` is true.
     prompt_cache_ttl?: PromptCacheTtl | undefined;
+    /**
+     * HTTP seam. Omitted → the live `curl` post. A test passes a double
+     * TOGETHER with a real `api_key`, which exercises the shim-building
+     * path that an injected `client:` object skips entirely.
+     */
+    transport?: JsonPost | undefined;
 }
 
 /** Shared ctor-options shape for the CLI clients. */
@@ -479,47 +490,6 @@ interface CliClientOptions {
     consumer?: string | undefined;
 }
 
-/**
- * Synchronous JSON POST via `curl` (no Node SDK, no Python). Matches the
- * council's `spawnSync` transport model so the live-call clients stay
- * synchronous. Returns the parsed response JSON (the provider HTTP APIs return
- * exactly the SDK response shape `ask()` reads). Throws on transport failure or
- * a non-2xx status so `ask()`'s catch surfaces it as a member error.
- */
-function _curlJsonPost(url: string, extraHeaders: string[], body: unknown): unknown {
-    const args = ['-sS', '-X', 'POST', url, '-H', 'content-type: application/json'];
-    for (const h of extraHeaders) {
-        args.push('-H', h);
-    }
-    // `--connect-timeout` fast-fails a dead host; `--max-time` lets curl abort
-    // itself cleanly (surfacing a real `curl exited` error with stderr) ~10s
-    // before the `spawnSync` timeout would kill it with an opaque ETIMEDOUT.
-    // A full 16k-token generation legitimately runs several minutes, so the
-    // ceiling is 300s, not 120s (the old value timed out long Anthropic calls).
-    args.push('--connect-timeout', '30', '--max-time', '290');
-    args.push('-w', '\n%{http_code}', '--data-binary', '@-');
-    const r = spawnSync('curl', args, {
-        input: JSON.stringify(body),
-        encoding: 'utf8',
-        maxBuffer: 64 * 1024 * 1024,
-        timeout: 300_000,
-    });
-    if (r.error) {
-        throw new Error(`curl spawn failed: ${(r.error as Error).message}`);
-    }
-    if (r.status !== 0) {
-        throw new Error(`curl exited ${r.status ?? 'null'}: ${(r.stderr ?? '').toString().slice(0, 500)}`);
-    }
-    const out = (r.stdout ?? '').toString();
-    const nl = out.lastIndexOf('\n');
-    const httpCode = (nl >= 0 ? out.slice(nl + 1) : out).trim();
-    const bodyText = nl >= 0 ? out.slice(0, nl) : out;
-    if (!/^2\d\d$/.test(httpCode)) {
-        throw new Error(`HTTP ${httpCode}: ${bodyText.slice(0, 500)}`);
-    }
-    return JSON.parse(bodyText);
-}
-
 export class AnthropicClient extends ExternalAIClient {
     override name = 'anthropic';
     override billable = true;
@@ -824,13 +794,12 @@ export class OpenAIClient extends ExternalAIClient {
 // ── Gemini / xAI / Perplexity (Phase 0 — Step 6) ─────────────────────
 
 /**
- * Google Gemini via the `google-genai` SDK.
- *
- * Lazy-imports `google.genai` on first `ask()` so disabled members do not
- * require the SDK to be installed. Tests inject a mock client shaped like
- * `genai.Client(api_key=...)` — `self._client.models.generate_content(...)`
- * returns an object with `.text` and
- * `.usage_metadata.{prompt_token_count, candidates_token_count}`.
+ * Google Gemini over the REST API (1.1 — there is no SDK dependency; the old
+ * `google-genai` lazy-import never existed in the TS port and the constructor
+ * simply threw). `ask()` still reads the SDK RESPONSE shape — `.text`,
+ * `.model_version`, `.usage_metadata.{prompt_token_count,
+ * candidates_token_count}` — which `geminiRestClient` normalises to, so every
+ * injected-mock test is unaffected.
  */
 export class GeminiClient extends ExternalAIClient {
     override name = 'gemini';
@@ -851,7 +820,12 @@ export class GeminiClient extends ExternalAIClient {
                     'Use `api_key_ref: env:GEMINI_API_KEY` in ~/.event4u/agent-config/settings/.ai-council.yml.',
             );
         }
-        throw new Error('google-genai package not installed. `pip install google-genai`.');
+        // Live transport (1.1). Was an unconditional `pip install google-genai`
+        // throw, which made `mode: api` dead for this provider however the key
+        // was configured. `geminiRestClient` normalises the REST envelope into
+        // the SDK shape `ask()` below already reads, so `ask()` is untouched
+        // and every existing injected-mock test keeps passing.
+        this._client = geminiRestClient(api_key, opts.transport ?? _curlJsonPost);
     }
 
     override ask(
@@ -901,19 +875,26 @@ export class GeminiClient extends ExternalAIClient {
 }
 
 /**
- * Shared shape for OpenAI-API-compatible providers (xAI, Perplexity).
- *
- * Both vendors implement `/v1/chat/completions` and accept the `openai` Python
- * SDK with a custom `base_url`. The reasoning-model branch from `OpenAIClient`
- * is intentionally omitted — neither xAI nor Perplexity ships a reasoning model
- * that requires `max_completion_tokens` as of 2026-05-14.
+ * Shared shape for OpenAI-API-compatible providers (xAI, Perplexity): both
+ * implement `/v1/chat/completions`, so 1.1 reaches them with one curl shim and
+ * a base URL. The reasoning-model branch from `OpenAIClient` is intentionally
+ * omitted — neither ships a reasoning model that requires
+ * `max_completion_tokens` as of 2026-05-14.
  */
 export class _OpenAICompatibleClient extends ExternalAIClient {
     override billable = true;
     base_url = '';
     protected _client: unknown;
 
-    constructor(opts: { model: string; client?: unknown; api_key?: string | null | undefined }) {
+    constructor(opts: {
+        model: string;
+        client?: unknown;
+        api_key?: string | null | undefined;
+        transport?: JsonPost | undefined;
+        // Passed, never read off `this.base_url`: a subclass field initializer
+        // runs AFTER this constructor, so the field is still '' right here.
+        base_url: string;
+    }) {
         super();
         this.model = opts.model;
         if (opts.client !== undefined && opts.client !== null) {
@@ -926,7 +907,13 @@ export class _OpenAICompatibleClient extends ExternalAIClient {
                 `${this.constructor.name} requires explicit api_key or injected client.`,
             );
         }
-        throw new Error('openai package not installed. `pip install openai`.');
+        // Live transport (1.1) — replaces an unconditional `pip install openai`
+        // throw that made `mode: api` dead for xai and perplexity.
+        this._client = openAiCompatibleClient(
+            opts.base_url,
+            api_key,
+            opts.transport ?? _curlJsonPost,
+        );
     }
 
     override ask(
@@ -989,7 +976,13 @@ export class XAIClient extends _OpenAICompatibleClient {
     override base_url = XAI_BASE_URL;
 
     constructor(opts: ApiClientOptions = {}) {
-        super({ model: opts.model ?? DEFAULT_XAI_MODEL, client: opts.client, api_key: opts.api_key });
+        super({
+            model: opts.model ?? DEFAULT_XAI_MODEL,
+            client: opts.client,
+            api_key: opts.api_key,
+            transport: opts.transport,
+            base_url: XAI_BASE_URL,
+        });
     }
 }
 
@@ -1003,6 +996,8 @@ export class PerplexityClient extends _OpenAICompatibleClient {
             model: opts.model ?? DEFAULT_PERPLEXITY_MODEL,
             client: opts.client,
             api_key: opts.api_key,
+            transport: opts.transport,
+            base_url: PERPLEXITY_BASE_URL,
         });
     }
 }
@@ -1028,8 +1023,8 @@ export {
 //
 // Raised 120 → 300 (2026-08-13) to match the API transport, which has carried
 // `--max-time 290` / `timeout: 300_000` since the 2026-06-24 repair of the same
-// symptom. That repair landed in `_curlJsonPost` only, so when a member resolves
-// to `cli · subscription` the old cap was still live — and a deep design run
+// symptom. That repair landed in `api_transport.ts::curlJsonPost` only, so with
+// a member on `cli · subscription` the old cap was still live — a deep run
 // reproduced it exactly: both members returned `error: timeout` at
 // `latency_ms: 122921` with `timeout_seconds: 120`, and the run reported
 // `0/2 present — INCONCLUSIVE`.

package/src/scripts/ai_council/config.ts

@@ -83,6 +83,8 @@ import * as budget from './cli_call_budget.js';
 // Converting it to a value import — or adding any other runtime import from
 // quorum into config — creates a real ESM cycle in the loader's init path.
 import { OPENAI_CLI_VENDOR_DEFAULT } from './clients.js';
+import { parseSeatFields, type PolicyExclusion } from './seat_policy.js';
+import type { ContentClass } from './content_ceiling.js';
 import { SOLO_FLOOR_MIN_PRESENT } from './quorum.js';
 
 const _VALID_PROVIDERS: ReadonlySet<string> = new Set([
@@ -330,6 +332,12 @@ export interface MemberConfig {
      * demanding a date nobody would refresh.
      */
     readonly verified_at: string | null;
+    /** Seat policy — parsed and documented by `seat_policy.ts::parseSeatFields`.
+     *  All three are NOTES or REFUSALS: none can make a seat available that was
+     *  not already available. */
+    readonly disabled_reason: string | null;
+    readonly policy_exclusion: PolicyExclusion | null;
+    readonly content_ceiling: ContentClass;
 }
 
 /**
@@ -1875,6 +1883,10 @@ function _build_member(
         }
         verified_at = coerced;
     }
+    const seat = parseSeatFields(name, cfg as Record<string, unknown>);
+    if ('error' in seat) {
+        throw new CouncilConfigError(seat.error);
+    }
     const prompt_cache_raw = _get(cfg, 'prompt_cache', null);
     let prompt_cache_ttl: '5m' | '1h' = '5m';
     if (prompt_cache_raw !== null && prompt_cache_raw !== undefined && !_isBool(prompt_cache_raw)) {
@@ -1907,6 +1919,7 @@ function _build_member(
         tier,
         prompt_cache_ttl,
         verified_at,
+        ...seat.fields,
     };
 }
 

package/src/scripts/ai_council/content_ceiling.ts

@@ -0,0 +1,79 @@
+/**
+ * One binary content ceiling per seat — road-to-admissible-council-seats 2.2.
+ *
+ * Redaction today is a SECRETS floor and says so
+ * (`src/skills/ai-council/references/cost-and-redaction.md`). Nothing above it
+ * could express "this project's diff may not go to that seat", which is a
+ * different question with a different answer: a diff carrying no secret at all
+ * is still the consumer's private source.
+ *
+ * Deliberately BINARY. A graded scale invites a middle value nobody can define
+ * and every caller reads differently; two values force the decision at
+ * authoring time, where it belongs.
+ *
+ *   public-artifact  — repo-owned artefacts: skill descriptions, the trigger
+ *                      corpus, rule text, bench fixtures. Already public.
+ *   project-content  — everything a consumer supplies. The DEFAULT, so an
+ *                      unclassified payload is treated as private rather than
+ *                      as publishable.
+ *
+ * A seat's ceiling is the most sensitive class it may receive. `public-artifact`
+ * is therefore the NARROWER seat: it admits public artefacts only.
+ */
+
+export const CONTENT_CLASSES = ['public-artifact', 'project-content'] as const;
+export type ContentClass = (typeof CONTENT_CLASSES)[number];
+
+/** The default for anything not explicitly classified: private, not public. */
+export const DEFAULT_CONTENT_CLASS: ContentClass = 'project-content';
+
+/** The default seat ceiling: unchanged behaviour for every existing seat. */
+export const DEFAULT_SEAT_CEILING: ContentClass = 'project-content';
+
+const _SET: ReadonlySet<string> = new Set<string>(CONTENT_CLASSES);
+
+/**
+ * Any configured value → a content class. Unrecognised input becomes
+ * `project-content`, the RESTRICTIVE value: a typo must narrow what a seat may
+ * receive, never widen it.
+ */
+export function classifyContentClass(raw: unknown, fallback: ContentClass = DEFAULT_CONTENT_CLASS): ContentClass {
+    if (typeof raw === 'string' && _SET.has(raw)) {
+        return raw as ContentClass;
+    }
+    return fallback;
+}
+
+export interface CeilingVerdict {
+    readonly admitted: boolean;
+    /** Non-null exactly when `admitted` is false. */
+    readonly reason: string | null;
+}
+
+/**
+ * Does a seat whose ceiling is `seatCeiling` admit a payload of `contentClass`?
+ *
+ * The one refusal is `project-content` into a `public-artifact` seat. Every
+ * other pairing is admitted, including public artefacts into a
+ * `project-content` seat — a seat cleared for private content is trivially
+ * cleared for public content, and refusing that would be a nonsense that
+ * disables the default seat for its own repo's fixtures.
+ *
+ * Refusal is a GREEN path (this roadmap's 2.2 verify): the caller drops the
+ * seat and the run continues. It is not an error, because a policy working as
+ * designed is not a failure.
+ */
+export function admitsContent(
+    seatCeiling: ContentClass,
+    contentClass: ContentClass,
+): CeilingVerdict {
+    if (seatCeiling === 'public-artifact' && contentClass === 'project-content') {
+        return {
+            admitted: false,
+            reason:
+                "seat ceiling is 'public-artifact'; the payload is classified " +
+                "'project-content' (consumer-supplied)",
+        };
+    }
+    return { admitted: true, reason: null };
+}

package/src/scripts/ai_council/jury_aggregate.ts

@@ -0,0 +1,178 @@
+/**
+ * Jury aggregation — road-to-admissible-council-seats 3.2.
+ *
+ * BESIDE `consensus.ts`, not inside it, and the separation is the design.
+ * `consensus.ts` aggregates a COUNCIL, whose members carry verdicts.
+ * A jury does not: per ADR-257 a route this package did not pay for may propose
+ * and may score, never decide. Folding jury scoring into the consensus path
+ * would put a scorer on the code path that produces verdicts, which is the
+ * exact transition this roadmap's Risk 5 names — "scoring quietly becomes
+ * deciding".
+ *
+ * Two rules, and both are refusals.
+ *
+ * 1. **At least two model families, or the panel is ABSENT.** Not a warning, a
+ *    refusal: `docs/CLAIMS.md` records that a same-posture second vendor's
+ *    catches were a strict SUBSET of the first's. A same-family panel therefore
+ *    measures redundancy, and reporting redundancy as agreement is the failure
+ *    a diversity requirement exists to prevent.
+ * 2. **The aggregate is a trimmed statistic, never a vote count.** For the same
+ *    reason: counting agreeing voices rewards a panel for being correlated.
+ *
+ * What "trimmed" means here, exactly: with n >= 3 the single lowest and single highest score are dropped and the
+ * rest averaged — which at n = 3 IS the median, and is why one corrupted score
+ * in a three-judge panel cannot move the result the way it moves an arithmetic
+ * mean. With n = 2 there is nothing to trim; the mean is returned with
+ * `trimmed: 0` so a reader can see that no robustness was available rather than
+ * inferring it from a method name.
+ */
+
+import {
+    judgeBothOrders,
+    positionConsistency,
+    type JudgeConsistency,
+    type PairResolution,
+    type PairwiseJudge,
+    type SwapObservation,
+} from './judge_position_bias.js';
+
+/** One judge's score for one item. `family` is the MODEL family, not the seat. */
+export interface JuryScore {
+    readonly judge: string;
+    readonly family: string;
+    /** Any finite number. The aggregator does not impose a scale. */
+    readonly score: number;
+}
+
+/** Why a panel produced no aggregate. Each value is a REFUSAL, not an error. */
+export type JuryAbsentReason = 'no_scores' | 'single_family' | 'non_finite_score';
+
+export type JuryResult =
+    | {
+          readonly present: false;
+          readonly absentReason: JuryAbsentReason;
+          readonly reason: string;
+      }
+    | {
+          readonly present: true;
+          readonly aggregate: number;
+          readonly method: 'trimmed-mean';
+          /** How many scores the trim discarded. 0 when n < 3. */
+          readonly trimmed: number;
+          readonly judges: number;
+          readonly families: readonly string[];
+      };
+
+/**
+ * Aggregate one item's jury scores.
+ *
+ * Never throws on panel composition: a refused panel is a VERDICT the caller
+ * reads, the same shape the transport resolver uses for a refused seat. An
+ * exception would make "this panel does not qualify" indistinguishable from a
+ * bug at every call site.
+ */
+export function juryAggregate(scores: readonly JuryScore[]): JuryResult {
+    if (scores.length === 0) {
+        return { present: false, absentReason: 'no_scores', reason: 'no jury scores supplied' };
+    }
+    for (const s of scores) {
+        if (!Number.isFinite(s.score)) {
+            return {
+                present: false,
+                absentReason: 'non_finite_score',
+                reason: `judge ${s.judge} returned a non-finite score; the panel is refused rather than silently dropping it`,
+            };
+        }
+    }
+    const families = [...new Set(scores.map((s) => s.family))].sort();
+    if (families.length < 2) {
+        return {
+            present: false,
+            absentReason: 'single_family',
+            reason:
+                `panel spans ${families.length} model family (${families.join(', ') || 'none'}); ` +
+                'at least two are required — a same-family panel measures redundancy, not agreement',
+        };
+    }
+    const sorted = [...scores.map((s) => s.score)].sort((a, b) => a - b);
+    const trimmed = sorted.length >= 3 ? 2 : 0;
+    const kept = trimmed === 0 ? sorted : sorted.slice(1, sorted.length - 1);
+    const aggregate = kept.reduce((acc, v) => acc + v, 0) / kept.length;
+    return {
+        present: true,
+        aggregate,
+        method: 'trimmed-mean',
+        trimmed,
+        judges: scores.length,
+        families,
+    };
+}
+
+/** One judge's swapped observation plus the family it belongs to. */
+export interface JuryPairwiseJudge {
+    readonly judge: string;
+    readonly family: string;
+    readonly fn: PairwiseJudge;
+}
+
+export interface JuryPairwiseResult {
+    readonly present: boolean;
+    readonly absentReason: JuryAbsentReason | null;
+    readonly reason: string | null;
+    /** Panel resolution, or `null` when the panel is absent. */
+    readonly resolution: PairResolution | null;
+    readonly observations: readonly SwapObservation[];
+    readonly consistency: readonly JudgeConsistency[];
+}
+
+/**
+ * Run a pairwise jury with the position swap applied PER JUDGE.
+ *
+ * Reuses `judge_position_bias.ts` rather than re-implementing the swap: a
+ * second implementation of "show both orders and reconcile" is a second place
+ * for the reconciliation to be subtly wrong, and that module already resolves a
+ * verdict that does not survive the swap to `inconsistent` rather than to a
+ * winner.
+ *
+ * The panel resolution is the strict majority of the judges' own resolutions,
+ * and `inconsistent` judges are counted in the DENOMINATOR — a judge that
+ * flipped has an opinion about nothing, and dropping it from the denominator
+ * would let two stable judges out of five look unanimous.
+ */
+export function juryPairwise(
+    id: string,
+    a: string,
+    b: string,
+    judges: readonly JuryPairwiseJudge[],
+): JuryPairwiseResult {
+    const families = [...new Set(judges.map((j) => j.family))].sort();
+    if (judges.length === 0 || families.length < 2) {
+        return {
+            present: false,
+            absentReason: judges.length === 0 ? 'no_scores' : 'single_family',
+            reason:
+                judges.length === 0
+                    ? 'no judges supplied'
+                    : `panel spans ${families.length} model family; at least two are required`,
+            resolution: null,
+            observations: [],
+            consistency: [],
+        };
+    }
+    const observations: SwapObservation[] = [];
+    const consistency: JudgeConsistency[] = [];
+    const tally = new Map<PairResolution, number>();
+    for (const j of judges) {
+        const obs = judgeBothOrders(id, a, b, j.fn);
+        observations.push(obs);
+        consistency.push(positionConsistency(j.judge, [obs]));
+        tally.set(obs.resolution, (tally.get(obs.resolution) ?? 0) + 1);
+    }
+    let resolution: PairResolution = 'inconsistent';
+    for (const [k, v] of tally) {
+        if (v * 2 > judges.length) {
+            resolution = k;
+        }
+    }
+    return { present: true, absentReason: null, reason: null, resolution, observations, consistency };
+}