@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/ai_council/provider_leakage_bench.ts

@@ -0,0 +1,327 @@
+/**
+ * Provider-recognition leakage bench — does anonymisation actually anonymise?
+ *
+ * `road-to-inbox-harvest-2026-08-e-council-topology-evidence` Phase 3, step 3.3:
+ * "ask reviewers and judges to guess the provider family from anonymized
+ * answers; measure recognition against chance. **Measurement first** — not a
+ * justification for rewriting anything." Verified by "recognition rate and
+ * chance baseline are both published".
+ *
+ * The council already strips provider identity from a peer-review or chairman
+ * transcript (`consensus.anonymize_responses`, `blind_review.build_blind_labels`).
+ * Stripping the LABEL is not the same as removing the SIGNAL: models have house
+ * styles, and a reviewer that can name the author of `Response-B` is not blind,
+ * whatever the header says. Nothing in this tree had ever measured that, so
+ * "the council is blind" was an assumption with a mechanism behind it rather
+ * than a result.
+ *
+ * ── This module measures; it does not decide ────────────────────────────────
+ * Step 3.4 (style normalization) is gated on this bench's result, and the gate
+ * lives here as `normalizationGateVerdict` so the gate cannot be satisfied by
+ * prose. Its default with no data is `unrun`, which is NOT `below-bar`: the
+ * difference is the whole point of the step. A null is what a measurement
+ * returns; `unrun` is what you have before one.
+ *
+ * ── Why the transport is injected ───────────────────────────────────────────
+ * Everything here is a pure function over data plus one `RaterFn` seam, the
+ * same LIBRARY/RUNNER split `check_quality_regression.ts:19-24` uses: the
+ * library is unit-tested against a scripted rater at zero cost, and the live
+ * pass — which is a paid council call per item per rater — is the operator
+ * step. A bench that could only be exercised by spending is a bench nobody
+ * regression-tests.
+ */
+
+/** Provider families a rater may name. Closed set: an open guess is ungradeable. */
+export interface LeakageOptions {
+    /** The closed option list shown to every rater, in a fixed order. */
+    readonly families: readonly string[];
+}
+
+/** One anonymised answer whose true author is known to the scorer, never to the rater. */
+export interface LeakageItem {
+    readonly id: string;
+    /** The anonymised body exactly as a reviewer or judge would receive it. */
+    readonly text: string;
+    /** Ground truth. MUST be a member of `LeakageOptions.families`. */
+    readonly true_family: string;
+}
+
+/** What a rater answered for one item. `null` = declined or unparseable. */
+export interface LeakageGuess {
+    readonly rater: string;
+    readonly item_id: string;
+    readonly guess: string | null;
+}
+
+/**
+ * The paid seam. Given the closed option list and one anonymised body, return
+ * the rater's guess, or `null` when it declined or its answer did not parse.
+ */
+export type RaterFn = (rater: string, item: LeakageItem, options: LeakageOptions) => string | null;
+
+/**
+ * The prompt a rater sees. Deliberately narrow: it asks ONLY for a family name
+ * from the closed list, so a rater cannot pass by hedging and the answer is
+ * gradeable without an LLM in the scoring loop.
+ *
+ * The body is NOT fenced here even though it is untrusted, and that is a
+ * deliberate difference from `build_peer_review_user_prompt`. Fencing a body
+ * inserts a nonce and a security preamble around it; this bench measures how
+ * recognisable a body is, so anything the bench adds to the body is a confound
+ * the live path does not have. The rater is asked for one word from a closed
+ * list and its answer is matched against that list, so an injected instruction
+ * has no schema to alter — the risk fencing buys back is absent by construction.
+ */
+export function buildRecognitionPrompt(item: LeakageItem, options: LeakageOptions): string {
+    return [
+        'Below is one anonymised answer produced by an AI model. Its provider',
+        'identity has been stripped. Guess which provider family wrote it.',
+        '',
+        `Answer with EXACTLY one of: ${options.families.join(', ')}`,
+        'Answer `unknown` if you genuinely cannot tell. Do not explain.',
+        '',
+        '---',
+        '',
+        item.text,
+    ].join('\n');
+}
+
+/** Run the bench over `items` for each rater, via the injected paid seam. */
+export function collectGuesses(
+    raters: readonly string[],
+    items: readonly LeakageItem[],
+    options: LeakageOptions,
+    ask: RaterFn,
+): LeakageGuess[] {
+    const out: LeakageGuess[] = [];
+    for (const rater of raters) {
+        for (const item of items) {
+            const raw = ask(rater, item, options);
+            const guess = raw !== null && options.families.includes(raw) ? raw : null;
+            out.push({ rater, item_id: item.id, guess });
+        }
+    }
+    return out;
+}
+
+export interface RecognitionResult {
+    readonly rater: string;
+    /** Guesses attempted, gradeable or not. */
+    readonly attempted: number;
+    /** Guesses that named a family in the closed list. */
+    readonly gradeable: number;
+    readonly correct: number;
+    /** `correct / gradeable`, or `null` when nothing was gradeable. */
+    readonly recognition_rate: number | null;
+    /**
+     * Chance under uniform guessing over the closed list — `1 / families`.
+     */
+    readonly chance_uniform: number;
+    /**
+     * Chance for the best CONSTANT guesser: the largest share any single family
+     * holds in the graded items. Published beside the uniform baseline because
+     * a skewed corpus makes uniform chance the wrong bar — a rater that always
+     * says the majority family beats `1/k` while recognising nothing.
+     */
+    readonly chance_majority: number;
+    /**
+     * One-sided exact binomial tail: P(at least `correct` successes in
+     * `gradeable` trials at the STRICTER of the two baselines). `null` when
+     * nothing was gradeable.
+     */
+    readonly p_value: number | null;
+}
+
+/** Score one rater's guesses against ground truth. */
+export function scoreRecognition(
+    rater: string,
+    guesses: readonly LeakageGuess[],
+    items: readonly LeakageItem[],
+    options: LeakageOptions,
+): RecognitionResult {
+    const truth = new Map(items.map((i) => [i.id, i.true_family]));
+    const mine = guesses.filter((g) => g.rater === rater);
+    let gradeable = 0;
+    let correct = 0;
+    const gradedFamilies: string[] = [];
+    for (const g of mine) {
+        if (g.guess === null) {
+            continue;
+        }
+        const t = truth.get(g.item_id);
+        if (t === undefined) {
+            continue;
+        }
+        gradeable += 1;
+        gradedFamilies.push(t);
+        if (g.guess === t) {
+            correct += 1;
+        }
+    }
+    const k = options.families.length;
+    const chance_uniform = k > 0 ? 1 / k : 0;
+    const counts = new Map<string, number>();
+    for (const f of gradedFamilies) {
+        counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+    const chance_majority = gradeable > 0 ? Math.max(...counts.values()) / gradeable : 0;
+    const bar = Math.max(chance_uniform, chance_majority);
+    return {
+        rater,
+        attempted: mine.length,
+        gradeable,
+        correct,
+        recognition_rate: gradeable > 0 ? correct / gradeable : null,
+        chance_uniform,
+        chance_majority,
+        p_value: gradeable > 0 ? binomialUpperTail(correct, gradeable, bar) : null,
+    };
+}
+
+/**
+ * P(X >= k) for X ~ Binomial(n, p), computed exactly.
+ *
+ * Exact rather than normal-approximated because this bench's honest sample size
+ * is small — a few dozen graded items — and a normal approximation at n=20 is
+ * the kind of shortcut that turns a null into a finding.
+ */
+export function binomialUpperTail(k: number, n: number, p: number): number {
+    if (n <= 0) {
+        return 1;
+    }
+    if (k <= 0) {
+        return 1;
+    }
+    if (p <= 0) {
+        return k > 0 ? 0 : 1;
+    }
+    if (p >= 1) {
+        return k <= n ? 1 : 0;
+    }
+    let total = 0;
+    for (let i = k; i <= n; i += 1) {
+        total += Math.exp(_logChoose(n, i) + i * Math.log(p) + (n - i) * Math.log1p(-p));
+    }
+    return Math.min(1, Math.max(0, total));
+}
+
+function _logChoose(n: number, k: number): number {
+    return _logGamma(n + 1) - _logGamma(k + 1) - _logGamma(n - k + 1);
+}
+
+/** Lanczos log-gamma — enough precision for the small n this bench grades. */
+function _logGamma(x: number): number {
+    const g = [
+        76.18009172947146, -86.5053203294167, 24.01409824083091, -1.231739572450155, 0.1208650973866179e-2,
+        -0.5395239384953e-5,
+    ];
+    let y = x;
+    let tmp = x + 5.5;
+    tmp -= (x + 0.5) * Math.log(tmp);
+    let ser = 1.000000000190015;
+    for (let j = 0; j < 6; j += 1) {
+        y += 1;
+        ser += (g[j] as number) / y;
+    }
+    return -tmp + Math.log((2.5066282746310005 * ser) / x);
+}
+
+// ── Step 3.4 — the gate style normalization has to clear ────────────────────
+
+/**
+ * The step's two conditions, verbatim: normalization lands only if this tree's
+ * own leakage bench shows "materially above-chance recognition **and** that
+ * recognition correlates with judgment distortion".
+ */
+export interface NormalizationGateInput {
+    /** Per-rater recognition results. Empty = the bench has not been run. */
+    readonly recognition: readonly RecognitionResult[];
+    /**
+     * Whether a SEPARATE measurement established that recognition correlates
+     * with judgment distortion. `null` when that arm has not been run — which is
+     * not the same as "measured and found absent", and is why this is
+     * three-valued rather than a boolean.
+     */
+    readonly distortion_correlated: boolean | null;
+    /** Significance bar for "materially above chance". */
+    readonly alpha?: number;
+}
+
+export type NormalizationVerdict =
+    /** The bench has not produced data. Not a null — nothing was measured. */
+    | 'unrun'
+    /** Measured, and at least one condition failed. Normalization must NOT land. */
+    | 'below-bar'
+    /** Both conditions recorded met. Normalization is permitted, still not required. */
+    | 'bar-cleared';
+
+export interface NormalizationGateResult {
+    readonly verdict: NormalizationVerdict;
+    /** Why, in one clause, printable beside the verdict. */
+    readonly reason: string;
+}
+
+/**
+ * Decide whether step 3.4 may proceed.
+ *
+ * Fails CLOSED in every ambiguous direction: no gradeable data, or a distortion
+ * arm that was never run, returns `unrun` and not `below-bar` — because
+ * "measured and found harmless" is a claim, and this function must never make
+ * one on behalf of a measurement nobody took.
+ */
+export function normalizationGateVerdict(input: NormalizationGateInput): NormalizationGateResult {
+    const alpha = input.alpha ?? 0.05;
+    const graded = input.recognition.filter((r) => r.gradeable > 0);
+    if (graded.length === 0) {
+        return {
+            verdict: 'unrun',
+            reason: 'no gradeable recognition data — the leakage bench has not been run',
+        };
+    }
+    const significant = graded.filter((r) => r.p_value !== null && r.p_value < alpha);
+    if (significant.length === 0) {
+        return {
+            verdict: 'below-bar',
+            reason:
+                `no rater recognised the provider above chance at alpha=${String(alpha)} ` +
+                `(${String(graded.length)} rater(s) graded) — condition 1 not met`,
+        };
+    }
+    if (input.distortion_correlated === null) {
+        return {
+            verdict: 'unrun',
+            reason:
+                `${String(significant.length)} rater(s) recognise above chance, but the ` +
+                'recognition-to-distortion correlation arm has not been run — condition 2 unmeasured',
+        };
+    }
+    if (!input.distortion_correlated) {
+        return {
+            verdict: 'below-bar',
+            reason: 'recognition is above chance but does not correlate with judgment distortion — condition 2 not met',
+        };
+    }
+    return {
+        verdict: 'bar-cleared',
+        reason:
+            `${String(significant.length)} rater(s) recognise above chance AND recognition correlates ` +
+            'with judgment distortion — both conditions recorded met',
+    };
+}
+
+/** The publishable block: recognition rate AND chance baseline, per the step's verify. */
+export function renderRecognitionReport(rows: readonly RecognitionResult[]): string {
+    if (rows.length === 0) {
+        return 'provider-recognition leakage: NOT RUN — no rater produced a guess.';
+    }
+    const pct = (v: number | null): string => (v === null ? 'n/a' : `${(v * 100).toFixed(1)}%`);
+    return rows
+        .map(
+            (r) =>
+                `recognition · ${r.rater}: ${pct(r.recognition_rate)} ` +
+                `(${String(r.correct)}/${String(r.gradeable)} gradeable of ${String(r.attempted)} attempted) · ` +
+                `chance uniform ${pct(r.chance_uniform)} · chance majority-class ${pct(r.chance_majority)} · ` +
+                `p=${r.p_value === null ? 'n/a' : r.p_value.toFixed(4)}`,
+        )
+        .join('\n');
+}

package/src/scripts/ai_council/py_format.ts

@@ -1,9 +1,20 @@
 /**
  * Python-format helpers, extracted from `config.ts`.
  *
- * Every error string this package emits is byte-faithful to the Python original
- * it replaced, which is why `repr()`, `type().__name__` and `oct()` are
- * reimplemented here instead of being approximated with template literals.
+ * THE LIVE CONTRACT, stated instead of a fidelity claim: `config.ts` and
+ * `clients.ts` raise `ValueError` / `TypeError` whose messages are built from
+ * these helpers — `invalid literal for int() with base 10: <repr>`, `could not
+ * convert string to float: <repr>`, `'<typeName>'`. That exact wording is what
+ * makes a malformed `.ai-council.yml` diagnosable, so the helpers reimplement
+ * `repr()`, `type().__name__` and `oct()` rather than approximating them with
+ * template literals.
+ *
+ * WHAT PINS IT TODAY: nothing. Searched 2026-08-26 — no test in `tests/` asserts
+ * any of those three strings, and the only other occurrences in the tree are
+ * independent copies in the work-engine templates. So this docstring records an
+ * INTENDED contract with no gate behind it; a refactor that changed the wording
+ * would pass every check in this repository. Naming the gap is the honest form,
+ * and it is cheaper than a fidelity claim to a deleted file nobody can consult.
  *
  * Pure and self-contained: these functions call only each other, which is what
  * made the section safe to move out whole. Extracted because config.ts is

package/src/scripts/ai_council/recouncil_guard.ts

@@ -0,0 +1,293 @@
+/**
+ * The re-council guard — warn before paying twice for one deliberation.
+ *
+ * `road-to-inbox-harvest-2026-08-e-council-topology-evidence` Phase 1A. The
+ * phase's own framing is the design constraint: *"the cheapest quality
+ * improvement is not paying twice for the same deliberation"*, and it sits
+ * before any sophisticated routing on purpose.
+ *
+ * FOUR CONSTRAINTS FROM THE STEPS, EACH LOAD-BEARING:
+ *
+ *   1A.1 Reuse the EXISTING question hash. `_sha256_hex` is imported from
+ *        `blind_review.ts`, not reimplemented — two hashes of one question are
+ *        two answers to "is this the same question", and the second is the one
+ *        nobody updates.
+ *   1A.2 WARN, NEVER PROHIBIT. {@link RecouncilVerdict} carries no field a
+ *        caller could read as a block, which is stronger than a documented
+ *        promise not to block: there is nothing to misread.
+ *   1A.3 Near-duplicate detection on the ALREADY-IMPORTED similarity
+ *        mechanism — `trigrams` from `_lib/lexical_index.ts`, the BM25 core
+ *        ADR-061 already sanctions. No embeddings, no new infrastructure. The
+ *        threshold is PRE-REGISTERED below, before any tuning on the retained
+ *        corpus.
+ *   1A.4 Three states, distinguishable: exact + same config, exact + stale
+ *        config, near-duplicate.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { jaccardSimilarity, MERGE_THRESHOLD } from '../_lib/text_similarity.js';
+import { _sha256_hex } from './blind_review.js';
+
+/**
+ * The near-duplicate threshold — and it is REUSED, not chosen.
+ *
+ * Step 1A.3 asks for the threshold to be pre-registered before any tuning on
+ * the retained local corpus. `MERGE_THRESHOLD` in `_lib/text_similarity.ts` is
+ * already that: fixed by an AI-council verdict of 2026-07-05 as the point at
+ * which two texts are treated as duplicates, long before this guard existed and
+ * with no knowledge of the council-question corpus it is now applied to. A
+ * number nobody could have tuned against this corpus is the strongest form of
+ * pre-registration available, and re-declaring `0.8` here would fork it — the
+ * same defect 1A.1 forbids for the hash.
+ *
+ * `revisit-if`: the retained corpus produces a false positive at this value
+ * (two questions a human calls different, scored at or above it), or a
+ * one-sentence rewrite of a real question scores below it. Either falsifies the
+ * number, and the fix then belongs in `text_similarity.ts` where its other
+ * consumers can see it move.
+ */
+export const NEAR_DUPLICATE_THRESHOLD = MERGE_THRESHOLD;
+
+/** The three states step 1A.4 requires the warning to distinguish. */
+export type RepeatState =
+    /** Same question text, and the configuration that would run it is unchanged. */
+    | 'exact-same-config'
+    /** Same question text, but the members or round count have moved since. */
+    | 'exact-stale-config'
+    /** Not the same text, but above the pre-registered similarity threshold. */
+    | 'near-duplicate';
+
+/** One prior run, as read from a retained response artefact. */
+export interface PriorRun {
+    /** Path of the retained artefact. */
+    readonly artifactPath: string;
+    /** The question file it ran over, as the artefact recorded it. */
+    readonly questionPath: string;
+    /** ISO date of the artefact, for the warning's "prior run date". */
+    readonly ranAt: string;
+    /** Sorted member ids + round count — the "relevant configuration". */
+    readonly configFingerprint: string;
+    /** `_sha256_hex` of the question text, when the question file still exists. */
+    readonly questionHash: string | null;
+    /** The question text, for the near-duplicate pass. `null` when the file is gone. */
+    readonly questionText: string | null;
+}
+
+/**
+ * A finding. There is DELIBERATELY no `block`, `refuse` or `severity` field:
+ * step 1A.2 requires that no code path can turn this into an unconditional
+ * block, and a type that cannot express one is the strongest available form of
+ * that guarantee.
+ */
+export interface RecouncilVerdict {
+    readonly state: RepeatState;
+    readonly prior: PriorRun;
+    /** Token Jaccard against the prior question, 0..1. Exactly 1 on an exact repeat. */
+    readonly similarity: number;
+}
+
+/** Sorted members plus rounds — what 1A.4 calls the relevant configuration. */
+export function configFingerprint(members: readonly string[], rounds: number): string {
+    return `${[...members].sort().join(',')}|rounds=${String(rounds)}`;
+}
+
+/**
+ * Read the retained response artefacts into prior runs.
+ *
+ * Tolerant of every read failure by design: a malformed or half-written
+ * artefact must not break a council run. The guard is an advisory, and an
+ * advisory that can throw is worse than one that stays quiet.
+ */
+export function readPriorRuns(responsesDir: string, repoRoot: string): PriorRun[] {
+    let names: string[];
+    try {
+        names = fs.readdirSync(responsesDir).filter((f) => f.endsWith('.md'));
+    } catch {
+        return [];
+    }
+    const out: PriorRun[] = [];
+    for (const name of names) {
+        const abs = path.join(responsesDir, name);
+        let head: Record<string, unknown>;
+        let stat: fs.Stats;
+        try {
+            stat = fs.statSync(abs);
+            const text = fs.readFileSync(abs, 'utf8');
+            const json = _leadingJson(text);
+            // A file with no leading object is not a council artefact at all —
+            // skipped rather than admitted as a prior run with empty fields,
+            // which would put noise in a warning whose whole value is that it
+            // is rare enough to read.
+            if (json === null) continue;
+            head = JSON.parse(json) as Record<string, unknown>;
+        } catch {
+            continue;
+        }
+        const questionPath = typeof head['artefact'] === 'string' ? head['artefact'] : '';
+        const members = Array.isArray(head['members']) ? (head['members'] as string[]) : [];
+        const rounds = typeof head['rounds'] === 'number' ? head['rounds'] : 0;
+        let questionHash: string | null = null;
+        let questionText: string | null = null;
+        if (questionPath !== '') {
+            try {
+                const q = fs.readFileSync(path.join(repoRoot, questionPath), 'utf8');
+                questionHash = _sha256_hex(q);
+                questionText = q;
+            } catch {
+                // The question file was moved or pruned. The run is still a
+                // prior run; it simply cannot be compared by text, and saying
+                // that is better than dropping the record.
+            }
+        }
+        out.push({
+            artifactPath: abs,
+            questionPath,
+            ranAt: stat.mtime.toISOString().slice(0, 10),
+            configFingerprint: configFingerprint(members, rounds),
+            questionHash,
+            questionText,
+        });
+    }
+    return out;
+}
+
+/** The leading `{...}` object of an artefact, brace-balanced, or `null`. */
+function _leadingJson(text: string): string | null {
+    const start = text.indexOf('{');
+    if (start === -1) return null;
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = start; i < text.length; i++) {
+        const c = text[i] as string;
+        if (inStr) {
+            if (esc) esc = false;
+            else if (c === '\\') esc = true;
+            else if (c === '"') inStr = false;
+            continue;
+        }
+        if (c === '"') inStr = true;
+        else if (c === '{') depth += 1;
+        else if (c === '}') {
+            depth -= 1;
+            if (depth === 0) return text.slice(start, i + 1);
+        }
+    }
+    return null;
+}
+
+/**
+ * Is this question already deliberated?
+ *
+ * Returns the STRONGEST finding, or `null`. Exact beats near-duplicate, and a
+ * stale-config exact beats a near-duplicate: a caller shown two findings reads
+ * neither, and the exact one carries more information.
+ */
+export function checkRecouncil(
+    questionText: string,
+    currentConfig: string,
+    priors: readonly PriorRun[],
+    threshold: number = NEAR_DUPLICATE_THRESHOLD,
+): RecouncilVerdict | null {
+    const hash = _sha256_hex(questionText);
+
+    for (const p of priors) {
+        if (p.questionHash === hash) {
+            return {
+                state: p.configFingerprint === currentConfig ? 'exact-same-config' : 'exact-stale-config',
+                prior: p,
+                similarity: 1,
+            };
+        }
+    }
+    let best: RecouncilVerdict | null = null;
+    for (const p of priors) {
+        if (p.questionText === null) continue;
+        const s = jaccardSimilarity(questionText, p.questionText);
+        if (s >= threshold && (best === null || s > best.similarity)) {
+            best = { state: 'near-duplicate', prior: p, similarity: s };
+        }
+    }
+    return best;
+}
+
+/**
+ * The warning text.
+ *
+ * Every line step 1A.2 names is present — prior run date, prior artifact path,
+ * the fact that the question appears already deliberated, and the path to
+ * re-run — and 1A.3 requires the SCORE to be printed, so it is, on every state
+ * rather than only the near-duplicate one. A score of 1.00 on an exact repeat
+ * tells the reader which comparison fired.
+ */
+export function renderRecouncilWarning(v: RecouncilVerdict): string {
+    const what: Record<RepeatState, string> = {
+        'exact-same-config':
+            'this exact question has already been deliberated, and the configuration that would run it is unchanged',
+        'exact-stale-config':
+            'this exact question has already been deliberated, but the members or round count have moved since — the prior verdict may rest on evidence this configuration would not produce',
+        'near-duplicate':
+            'a question above the pre-registered similarity threshold has already been deliberated',
+    };
+    return [
+        `⚠️  council:re-council — ${what[v.state]}.`,
+        `    prior run    ${v.prior.ranAt}`,
+        `    prior answer ${v.prior.artifactPath}`,
+        `    question     ${v.prior.questionPath || '(not recorded)'}`,
+        `    similarity   ${v.similarity.toFixed(2)} (threshold ${String(NEAR_DUPLICATE_THRESHOLD)}, pre-registered)`,
+        '    This is a WARNING, never a refusal. Re-run with --confirm to deliberate again.',
+        '',
+    ].join('\n');
+}
+
+/**
+ * The whole call site, in one function.
+ *
+ * Lives here rather than in `council_cli.ts` for a reason the source-size
+ * ratchet made concrete: that file is already 2,525 lines over the 1,500-line
+ * ceiling, so every line added to it is a line the ratchet counts, and a
+ * twenty-line comment explaining a guard belongs beside the guard anyway.
+ *
+ * IT CANNOT REFUSE, and the signature is where that is guaranteed: it returns
+ * `void`. Step 1A.2 requires that no code path turn the warning into an
+ * unconditional block, and a function with nothing to return gives a caller
+ * nothing to branch on.
+ *
+ * Every read is wrapped: an advisory that throws is worse than one that stays
+ * quiet, because the guard exists to save a duplicate run and never to prevent
+ * a legitimate one.
+ *
+ * `questionFile` is the RAW question file, not the built prompt. Measured on
+ * the first live run: the built prompt hashes differently from the file the
+ * prior artefact recorded, so the exact-repeat states were unreachable in
+ * production and every true repeat reported as a near-duplicate at similarity
+ * 1.00. `fallbackText` covers a question that arrived on stdin and has no file.
+ */
+export function warnIfRecounciled(
+    repoRoot: string,
+    questionFile: string,
+    fallbackText: string,
+    members: readonly { name: string; model: string }[],
+    rounds: number,
+    write: (s: string) => void,
+): void {
+    try {
+        let text = fallbackText;
+        try {
+            text = fs.readFileSync(path.resolve(repoRoot, questionFile), 'utf8');
+        } catch {
+            // No file behind this question; the built prompt is the best text
+            // available, and a near-duplicate finding is still useful.
+        }
+        const v = checkRecouncil(
+            text,
+            // `name/model` — the SAME shape the artefact writer records.
+            configFingerprint(members.map((m) => `${m.name}/${m.model}`), rounds),
+            readPriorRuns(path.join(repoRoot, 'agents/runtime/council/responses'), repoRoot),
+        );
+        if (v !== null) write(renderRecouncilWarning(v));
+    } catch {
+        // See the docstring: quiet beats loud-and-broken for an advisory.
+    }
+}