@event4u/agent-config 14.9.0 → 14.11.0

package/src/scripts/ai_council/orchestrator.ts

@@ -21,6 +21,10 @@
 // Failure normalisation (one member's exception → `error`-set
 // CouncilResponse, never raise) is unchanged.
 
+import { ConsensusResult, CouncilQuestion, PeerReviewResult } from './orchestrator_results.js';
+import type { RunConsensusScoringOptions, RunPeerReviewOptions } from './orchestrator_results.js';
+export { ConsensusResult, CouncilQuestion, PeerReviewResult } from './orchestrator_results.js';
+export type { RunConsensusScoringOptions, RunPeerReviewOptions } from './orchestrator_results.js';
 import {
     record_spend as _record_daily_spend,
     today_spend_usd as _today_spend_usd,
@@ -42,7 +46,7 @@ import {
     anonymize_findings,
     anonymize_responses,
     bucket_by_threshold,
-    parse_findings_response,
+    parse_findings_outcome,
     parse_scores_response,
 } from './consensus.js';
 import type {
@@ -119,9 +123,9 @@ import {
     _setdefault,
 } from './py_parity.js';
 
-import { CHAIRMAN_FIELDS_ADDENDUM, render_deanonymization_block } from './blind_review.js';
+import { CHAIRMAN_FIELDS_ADDENDUM, render_deanonymization_block, deterministic_shuffle_indices } from './blind_review.js';
 import type { AbsentReason } from './transport_resolver.js';
-import { isSoloConcluded, type QuorumResult } from './quorum.js';
+import { formatAttendanceCaveats, isSoloConcluded, type QuorumResult } from './quorum.js';
 import { isEmptyHandoff, type HandoffEnvelope } from './handoff.js';
 
 
@@ -150,17 +154,6 @@ function _label(idx: number): string {
 
 // ── dataclasses ───────────────────────────────────────────────────────
 
-export class CouncilQuestion {
-    mode: string; // one of: prompt, roadmap, diff, files
-    user_prompt: string; // bundled artefact text
-    max_tokens: number;
-
-    constructor(args: { mode: string; user_prompt: string; max_tokens?: number }) {
-        this.mode = args.mode;
-        this.user_prompt = args.user_prompt;
-        this.max_tokens = args.max_tokens ?? DEFAULT_MAX_TOKENS;
-    }
-}
 
 // Callback signature: receive event → return True (proceed) or False (skip + tag error).
 export type OnOverrunCallback = (event: OverrunEvent) => boolean;
@@ -1434,44 +1427,7 @@ export function run_debate(
     return all_rounds;
 }
 
-/**
- * Bundle returned by `run_peer_review()` (Phase 5 / F1).
- *
- * `responses` carries the per-reviewer critiques. `label_to_source`
- * is the anonymisation map captured server-side so the audit-trail
- * JSON can rehydrate it without leaking provider identity to the
- * member at prompt time.
- *
- * `persona_labels` is the (optional) Phase 6 / Step 3a wiring: when
- * the deliberation was an advisor-mode run, the source → persona
- * map flows through to the renderer so peer-review output can render
- * as `Response A (Contrarian)`. Plain-member runs leave it empty.
- */
-export class PeerReviewResult {
-    responses: CouncilResponse[];
-    label_to_source: Map<string, string>;
-    persona_labels: Map<string, string>;
 
-    constructor(args: {
-        responses: CouncilResponse[];
-        label_to_source: Map<string, string>;
-        persona_labels: Map<string, string>;
-    }) {
-        this.responses = args.responses;
-        this.label_to_source = args.label_to_source;
-        this.persona_labels = args.persona_labels;
-    }
-}
-
-export interface RunPeerReviewOptions {
-    budget?: CostBudget | null;
-    table?: PriceTable | null;
-    on_overrun?: OnOverrunCallback | null;
-    project?: ProjectContext | null;
-    original_ask?: string;
-    max_tokens?: number;
-    persona_labels?: Map<string, string> | null;
-}
 
 /**
  * Karpathy peer-review pass (Phase 5 / F1).
@@ -1537,12 +1493,23 @@ export function run_peer_review(
 
     const persona_labels = new Map<string, string>(opts.persona_labels ?? []);
     const review_responses: CouncilResponse[] = [];
-    // ── final label_to_source map captured from the LAST member call
-    // so the renderer / JSON dump has the deterministic A/B mapping.
-    // Each member sees a different N-1 subset (self filtered), but the
-    // ordering of `by_source` stays stable, so the label assignment is
-    // deterministic per artefact run.
-    let last_label_to_source = new Map<string, string>();
+    // ── What is deterministic here, and what is NOT — corrected 2026-08-23 (step 1.3).
+    //
+    // DETERMINISTIC: the iteration order of `by_source`, and therefore the input order
+    // handed to `anonymize_responses`. Two runs over the same config produce the same
+    // per-reviewer mapping.
+    //
+    // NOT deterministic ACROSS REVIEWERS, and this is what the old comment got wrong by
+    // calling it "the deterministic A/B mapping": every reviewer receives a different
+    // self-filtered subset, and `anonymize_responses` restarts its label counter on each
+    // call (`consensus.ts:437`). So `Response-A` denotes a DIFFERENT member for every
+    // reviewer, by construction. A single map cannot express that, and the one that used
+    // to live here was overwritten per reviewer — so the artefact carried the last
+    // reviewer's mapping for every quote in it.
+    //
+    // `by_reviewer` is the authoritative structure. `last_label_to_source` survives only
+    // as the serialised compatibility field (`council_cli.ts:1480`/`:1492`).
+    const label_to_source_by_reviewer = new Map<string, Map<string, string>>();
 
     for (const reviewer of members) {
         const scorer = `${reviewer.name}:${reviewer.model}`;
@@ -1558,13 +1525,31 @@ export function run_peer_review(
         if (others_pairs.length === 0) {
             continue;
         }
-        const [anon_text, label_to_source] = anonymize_responses(others_pairs, {
+        // Step 1.5 — SEEDED order, not input order.
+        //
+        // Before this, `others_pairs` reached `anonymize_responses` in `by_source`
+        // iteration order, so which member became `Response-A` was a pure function of
+        // config order: identical across runs AND inferable from position. That is the
+        // leak `blind_review.ts:52-54` already argues against for its own path ("which
+        // pair becomes `Response-A` is not simply input order, so position alone leaks
+        // nothing") — the two paths contradicted each other in code until now.
+        //
+        // Seed = the original ask plus the deliberation bodies. Run-scoped and
+        // REPLAYABLE from the artefact's own contents; never `Math.random`, never
+        // `Date`, because a label order nobody can reproduce makes the de-anonymization
+        // block unverifiable. The reviewer is deliberately NOT in the seed: one shuffle
+        // per run, so a reader comparing two reviewers' critiques of the same member is
+        // comparing the same label.
+        const shuffle_seed = [opts.original_ask ?? '', ...[...by_source.values()].map((r) => r.text)].join('\0');
+        const order = deterministic_shuffle_indices(shuffle_seed, others_pairs.length);
+        const shuffled_pairs = order.map((i) => others_pairs[i]!);
+        const [anon_text, label_to_source] = anonymize_responses(shuffled_pairs, {
             persona_labels,
         });
         if (anon_text.size === 0) {
             continue;
         }
-        last_label_to_source = label_to_source;
+        label_to_source_by_reviewer.set(scorer, label_to_source);
         const question = new CouncilQuestion({
             mode: 'prompt',
             user_prompt: build_peer_review_user_prompt(anon_text),
@@ -1579,54 +1564,22 @@ export function run_peer_review(
         review_responses.push(...reviewed);
     }
 
+    // DERIVED after the loop, never assigned inside it (step 1.2's verify is a grep for
+    // exactly that). The compatibility field is the last reviewer's mapping, and deriving
+    // it here rather than accumulating it makes that explicit: nothing in the loop
+    // pretends to maintain a run-wide map.
+    const reviewer_maps = [...label_to_source_by_reviewer.values()];
+    const flat_compat = reviewer_maps.length === 0 ? new Map<string, string>() : reviewer_maps[reviewer_maps.length - 1]!;
+
     return new PeerReviewResult({
         responses: review_responses,
-        label_to_source: last_label_to_source,
+        label_to_source_by_reviewer,
+        label_to_source: flat_compat,
         persona_labels,
     });
 }
 
-/**
- * Bundle returned by `run_consensus_scoring()`.
- *
- * `bucket` is renderer-ready; `findings`, `scores`, and `metadata`
- * are kept for audit-trail JSON (council-sessions/*.json).
- */
-export class ConsensusResult {
-    bucket: ConsensusBucket;
-    findings: Finding[];
-    scores: FindingScore[];
-    metadata: Map<string, ConsensusMetadata>;
-    extraction_responses: CouncilResponse[];
-    scoring_responses: CouncilResponse[];
 
-    constructor(args: {
-        bucket: ConsensusBucket;
-        findings: Finding[];
-        scores: FindingScore[];
-        metadata: Map<string, ConsensusMetadata>;
-        extraction_responses: CouncilResponse[];
-        scoring_responses: CouncilResponse[];
-    }) {
-        this.bucket = args.bucket;
-        this.findings = args.findings;
-        this.scores = args.scores;
-        this.metadata = args.metadata;
-        this.extraction_responses = args.extraction_responses;
-        this.scoring_responses = args.scoring_responses;
-    }
-}
-
-export interface RunConsensusScoringOptions {
-    budget?: CostBudget | null;
-    table?: PriceTable | null;
-    on_overrun?: OnOverrunCallback | null;
-    project?: ProjectContext | null;
-    original_ask?: string;
-    max_tokens?: number;
-    strong_threshold?: number;
-    minority_threshold?: number;
-}
 
 /**
  * Two-pass consensus round (Phase 4 / F3).
@@ -1672,6 +1625,13 @@ export function run_consensus_scoring(
     }
     const extraction_responses: CouncilResponse[] = [];
     const all_findings: Finding[] = [];
+    // Per-member extraction outcome — step 2.2. Recorded rather than derived from the
+    // findings count, because "zero findings" and "could not be read" are different facts
+    // and the count cannot tell them apart. `parsed-after-reask` is kept distinct from
+    // `parsed`: a member that needed a second ask is a signal about the prompt or the
+    // member, and collapsing it into `parsed` would hide the only evidence that the
+    // re-ask is doing anything.
+    const parse_outcomes = new Map<string, string>();
     for (const resp of deliberation_responses) {
         const member = member_by_name.get(resp.provider);
         if (member === undefined || resp.error || !_pyStrip(resp.text)) {
@@ -1693,9 +1653,45 @@ export function run_consensus_scoring(
             continue;
         }
         const source = `${member.name}:${member.model}`;
-        all_findings.push(
-            ...parse_findings_response(extracted[0]!.text, { source }),
-        );
+        let ex = parse_findings_outcome(extracted[0]!.text, { source });
+
+        // Step 2.2 — ONE bounded re-ask on `parse_failed`, and one only.
+        //
+        // A member that said something no parser could read used to be indistinguishable
+        // from a member that found nothing: `parse_findings_response` returned `[]` for
+        // both, and this loop pushed the empty array with no branch. So an unparseable
+        // answer counted as a clean zero-findings review.
+        //
+        // ONE re-ask, not a loop. A re-ask is a paid call, and an unbounded retry turns
+        // one unparseable answer into open-ended spend — the failure mode the N=3
+        // validation budget exists for, reached here by a different road. `empty` is NOT
+        // re-asked: a member that said nothing has nothing to restate, and re-asking it
+        // buys a second silence.
+        if (ex.outcome === 'parse_failed') {
+            const retry_q = new CouncilQuestion({
+                mode: 'prompt',
+                user_prompt:
+                    build_extraction_user_prompt(resp.text) +
+                    '\n\nYour previous answer could not be parsed. Reply with ONLY a JSON ' +
+                    'array of {"id": string, "text": string} objects, no prose before or ' +
+                    'after it. An empty array [] is a valid answer meaning you found nothing.',
+                max_tokens,
+            });
+            const retried = consult([member], retry_q, budget, {
+                table,
+                on_overrun,
+                project,
+                original_ask,
+            });
+            extraction_responses.push(...retried);
+            if (retried.length > 0 && !retried[0]!.error) {
+                ex = parse_findings_outcome(retried[0]!.text, { source });
+            }
+            parse_outcomes.set(source, ex.outcome === 'parsed' ? 'parsed-after-reask' : 'parse_failed');
+        } else {
+            parse_outcomes.set(source, ex.outcome);
+        }
+        all_findings.push(...ex.findings);
     }
 
     if (all_findings.length === 0) {
@@ -1704,6 +1700,7 @@ export function run_consensus_scoring(
             findings: [],
             scores: [],
             metadata: new Map(),
+            parse_outcomes,
             extraction_responses,
             scoring_responses: [],
         });
@@ -1761,6 +1758,7 @@ export function run_consensus_scoring(
         findings: all_findings,
         scores: all_scores,
         metadata,
+        parse_outcomes,
         extraction_responses,
         scoring_responses,
     });
@@ -2061,11 +2059,8 @@ function _render_quorum_line(q: QuorumResult): string {
     // so 2-of-4 rendered as plain "concluded" with nothing to stop a reader
     // inferring convergence. Same sentence as stdout on purpose — one wording,
     // so neither surface can drift into being the softer one again.
-    const degraded =
-        q.present < q.total
-            ? `  ⚠️  DEGRADED — ${String(q.total - q.present)} member(s) did not answer; this is not convergence.`
-            : '';
-    return `**Quorum:** ${q.present}/${q.total} present, needed ${q.threshold} — ${verdict}.${solo}${degraded}`;
+    // Wording shared with the stdout mirror; `formatAttendanceCaveats` owns it.
+    return `**Quorum:** ${q.present}/${q.total} present, needed ${q.threshold} — ${verdict}.${solo}${formatAttendanceCaveats(q)}`;
 }
 
 /**

package/src/scripts/ai_council/orchestrator_results.ts

@@ -0,0 +1,166 @@
+/**
+ * The two result bundles `orchestrator.ts` returns — extracted, a PURE MOVE.
+ *
+ * The reason is arithmetic. `orchestrator.ts` sits ~850 lines above the 1,500-line
+ * ceiling, so `check_source_size_budget` refuses ANY net growth in it: Phases 1 and 2 of
+ * `road-to-council-evidence-integrity` added 122 lines and the gate said so, correctly.
+ * Raising the baseline is what that gate's own message calls a defect rather than a fix.
+ *
+ * These two classes are the cleanest movable unit in the file: they are data carriers with
+ * no logic and no dependency on anything else in the orchestrator, so moving them changes
+ * no behaviour. `orchestrator.ts` re-exports both, so every existing import path keeps
+ * resolving.
+ *
+ * Extracting a data carrier rather than shaving the new documentation was the choice: the
+ * alternative was compressing comments that explain WHY a per-reviewer map exists and why
+ * the re-ask is bounded at one, which buys the same green from worse code.
+ */
+import type { CouncilResponse } from './clients.js';
+import { DEFAULT_MAX_TOKENS } from './clients.js';
+import type { CostBudget } from './spend_gate.js';
+import type { PriceTable } from './pricing.js';
+import type { ProjectContext } from './project_context.js';
+// TYPE-ONLY back-import. `OnOverrunCallback` is declared in orchestrator.ts, which also
+// imports types from here — legal and runtime-free, because both directions are erased.
+// The alternative was leaving the two options interfaces behind, which would have meant
+// finding 19 lines elsewhere for no design reason.
+import type { OnOverrunCallback } from './orchestrator.js';
+import type { ConsensusBucket, ConsensusMetadata, Finding, FindingScore } from './consensus.js';
+
+/**
+ * Bundle returned by `run_peer_review()` (Phase 5 / F1).
+ *
+ * `responses` carries the per-reviewer critiques. `label_to_source`
+ * is the anonymisation map captured server-side so the audit-trail
+ * JSON can rehydrate it without leaking provider identity to the
+ * member at prompt time.
+ *
+ * `persona_labels` is the (optional) Phase 6 / Step 3a wiring: when
+ * the deliberation was an advisor-mode run, the source → persona
+ * map flows through to the renderer so peer-review output can render
+ * as `Response A (Contrarian)`. Plain-member runs leave it empty.
+ */
+/**
+ * One question put to the council. Moved here with the result bundles: it is the same
+ * kind of thing — a data carrier with no logic — and `orchestrator.ts` re-exports it, so
+ * every import path is unchanged.
+ */
+export class CouncilQuestion {
+    mode: string; // one of: prompt, roadmap, diff, files
+    user_prompt: string; // bundled artefact text
+    max_tokens: number;
+
+    constructor(args: { mode: string; user_prompt: string; max_tokens?: number }) {
+        this.mode = args.mode;
+        this.user_prompt = args.user_prompt;
+        this.max_tokens = args.max_tokens ?? DEFAULT_MAX_TOKENS;
+    }
+}
+
+export class PeerReviewResult {
+    responses: CouncilResponse[];
+    /**
+     * PER-REVIEWER label→source attribution — the authoritative mapping.
+     *
+     * Keyed by `provider:model`, because that is the identity `by_source` uses and the
+     * identity a quote in the artefact has to resolve against. Added by step 1.2 of
+     * `road-to-council-evidence-integrity`: each reviewer sees a DIFFERENT
+     * self-filtered subset, and `anonymize_responses` restarts its label counter per
+     * call, so `Response-A` means a different member for every reviewer. One map
+     * cannot express that.
+     */
+    label_to_source_by_reviewer: Map<string, Map<string, string>>;
+    /**
+     * Flat compatibility view — the LAST reviewer's mapping, kept only because
+     * `council_cli.ts:1480` serialises this field and `:1492` reads it back.
+     *
+     * It is wrong for any reviewer but the last, and it is retained rather than
+     * removed so the serialisation contract does not break in the same change that
+     * fixes the attribution. Read `label_to_source_by_reviewer` for anything that
+     * resolves a quote.
+     */
+    label_to_source: Map<string, string>;
+    persona_labels: Map<string, string>;
+
+    constructor(args: {
+        responses: CouncilResponse[];
+        label_to_source_by_reviewer?: Map<string, Map<string, string>>;
+        label_to_source: Map<string, string>;
+        persona_labels: Map<string, string>;
+    }) {
+        this.responses = args.responses;
+        this.label_to_source_by_reviewer = args.label_to_source_by_reviewer ?? new Map();
+        this.label_to_source = args.label_to_source;
+        this.persona_labels = args.persona_labels;
+    }
+}
+
+/**
+ * Bundle returned by `run_consensus_scoring()`.
+ *
+ * `bucket` is renderer-ready; `findings`, `scores`, and `metadata`
+ * are kept for audit-trail JSON (council-sessions/*.json).
+ */
+export class ConsensusResult {
+    bucket: ConsensusBucket;
+    findings: Finding[];
+    scores: FindingScore[];
+    metadata: Map<string, ConsensusMetadata>;
+    /**
+     * Per-member extraction outcome, keyed by `provider:model` — step 2.2 of
+     * `road-to-council-evidence-integrity`.
+     *
+     * `parsed` · `parsed-after-reask` · `empty` · `parse_failed`. Recorded rather than
+     * derived from the findings count, because "found nothing" and "could not be read"
+     * are different facts and a count cannot tell them apart — which is exactly how an
+     * unparseable answer used to read as a clean zero-findings review.
+     *
+     * `parsed-after-reask` is deliberately distinct from `parsed`: a member needing a
+     * second ask is a signal about the prompt or the member, and folding it into `parsed`
+     * would hide the only evidence that the re-ask does anything.
+     *
+     * Additive and optional, so no existing constructor call changes.
+     */
+    parse_outcomes: Map<string, string>;
+    extraction_responses: CouncilResponse[];
+    scoring_responses: CouncilResponse[];
+
+    constructor(args: {
+        bucket: ConsensusBucket;
+        findings: Finding[];
+        scores: FindingScore[];
+        metadata: Map<string, ConsensusMetadata>;
+        parse_outcomes?: Map<string, string>;
+        extraction_responses: CouncilResponse[];
+        scoring_responses: CouncilResponse[];
+    }) {
+        this.bucket = args.bucket;
+        this.findings = args.findings;
+        this.scores = args.scores;
+        this.metadata = args.metadata;
+        this.parse_outcomes = args.parse_outcomes ?? new Map();
+        this.extraction_responses = args.extraction_responses;
+        this.scoring_responses = args.scoring_responses;
+    }
+}
+
+export interface RunPeerReviewOptions {
+    budget?: CostBudget | null;
+    table?: PriceTable | null;
+    on_overrun?: OnOverrunCallback | null;
+    project?: ProjectContext | null;
+    original_ask?: string;
+    max_tokens?: number;
+    persona_labels?: Map<string, string> | null;
+}
+
+export interface RunConsensusScoringOptions {
+    budget?: CostBudget | null;
+    table?: PriceTable | null;
+    on_overrun?: OnOverrunCallback | null;
+    project?: ProjectContext | null;
+    original_ask?: string;
+    max_tokens?: number;
+    strong_threshold?: number;
+    minority_threshold?: number;
+}

package/src/scripts/ai_council/prompts.ts

@@ -120,9 +120,11 @@ MUST:
    suggestion. No hand-wave "this is probably slow".
 3. State at least one suggestion you explicitly REJECT as
    low-leverage, so the user does not over-engineer.
-4. Mark at least one suggestion as hypothesis (requires measurement
-   before committing) versus confirmed (already supported by the
-   evidence in the artefact).`;
+4. Mark at least one suggestion \`evidence: speculative\` (requires
+   measurement before committing) against at least one marked
+   \`evidence: confirmed\` (already supported by the artefact). Use the
+   same three-term scale as every other lens — \`confirmed\` |
+   \`inferred\` | \`speculative\` — never a lens-local synonym.`;
 
 export const ANALYSIS_MODE = `The artefact is a local analysis output (from a project analyzer,
 audit script, or codebase scan). Critique the **analysis itself**, not
@@ -315,8 +317,13 @@ metadata shape as Top-10.
 
 ### Outliers
 Single-reviewer findings the others did not engage with. Keep them
-— they are signal for a future deeper analysis pass — but mark each
-as \`unverified-by-council\`.
+— they are signal for a future deeper analysis pass — and give each
+the SAME metadata shape as Top-10, including its \`evidence:\` term.
+The heading is the corroboration statement: everything under it was
+raised by one reviewer and engaged with by none. Do not invent a
+separate certainty word for that; \`evidence:\` measures how well a
+finding is supported, and being alone in raising it is a different
+property the section already carries.
 
 ### Kill criteria
 Observable conditions that would falsify the analysis's leading finding

package/src/scripts/ai_council/quorum.ts

@@ -37,6 +37,23 @@ export interface QuorumResult {
     readonly total: number;
     /** Members that actually produced a usable response. */
     readonly present: number;
+    /**
+     * Members that answered with something no parser could read.
+     *
+     * Deliberately OPTIONAL and omitted when zero, never defaulted to `0`. Every
+     * assertion over a `QuorumResult` in this tree is an exact-shape `toEqual`,
+     * and the field also rides into `payload['quorum']`, so a defaulted key would
+     * be a silent breaking change to a serialized surface for the overwhelmingly
+     * common case where nothing was unparseable.
+     *
+     * Such a member is NOT in `present`: the byte check that admits it
+     * (`text.trim() !== ''`) is true of a prose refusal, which is exactly the
+     * "looked more settled than the run was" shape the empty-body fix already
+     * closed one case of. It is not plainly absent either — it answered, and the
+     * distinction is what a reader needs to tell "found nothing" from
+     * "said something unreadable".
+     */
+    readonly unparsed?: number;
 }
 
 /**
@@ -76,11 +93,75 @@ export function evaluateQuorum(
     total: number,
     present: number,
     setting: QuorumSetting = 'majority',
+    unparsed = 0,
 ): QuorumResult {
     const threshold = resolveQuorumThreshold(total, setting);
     const clampedPresent = Math.min(Math.max(present, 0), total);
     const status: QuorumStatus = clampedPresent >= threshold ? 'concluded' : 'inconclusive';
-    return { status, threshold, total, present: clampedPresent };
+    const clampedUnparsed = Math.min(Math.max(unparsed, 0), total - clampedPresent);
+    // Spread-on-condition rather than a defaulted key — see `QuorumResult.unparsed`.
+    return { status, threshold, total, present: clampedPresent, ...(clampedUnparsed > 0 ? { unparsed: clampedUnparsed } : {}) };
+}
+
+/**
+ * Move `n` members out of `present` and into the unparsed bucket.
+ *
+ * The run path derives findings-parse outcomes only AFTER `_postRunQuorum` has
+ * emitted the post-run attendance event, and that ordering is deliberate: the
+ * event is a TRANSPORT-level reading and stays one, so a consumer computing an
+ * attendance rate over the log keeps the denominator it has always had. The
+ * rendered artefact is where AC-2 asks for the distinction, and this is how it
+ * gets there — the same reading, re-derived once the parser has spoken.
+ *
+ * `threshold` is not recomputed: it resolves from `total` and the configured
+ * setting, neither of which this function touches. `status` IS recomputed,
+ * because moving a member out of `present` can legitimately turn a concluded
+ * pass inconclusive — which is the whole point, and the same consequence the
+ * empty-body fix already accepted.
+ */
+export function withUnparsed(q: QuorumResult, unparsed: number): QuorumResult {
+    if (unparsed <= 0) {
+        return q;
+    }
+    const present = Math.max(0, q.present - unparsed);
+    const moved = q.present - present;
+    return {
+        status: present >= q.threshold ? 'concluded' : 'inconclusive',
+        threshold: q.threshold,
+        total: q.total,
+        present,
+        ...(moved > 0 ? { unparsed: moved } : {}),
+    };
+}
+
+/**
+ * The attendance caveats both banners append — ONE wording, one place.
+ *
+ * `orchestrator.ts::_render_quorum_line` and `quorum_wiring.ts::_format_quorum_line`
+ * are deliberate mirrors, and the DEGRADED sentence carries a note explaining
+ * that they must stay byte-identical "so neither surface can drift into being
+ * the softer one again". Two copies of a sentence with that requirement is a
+ * drift waiting to happen, so Step 2.3 extracted it here rather than adding a
+ * third clause to each copy by hand.
+ *
+ * Two caveats, and they are disjoint on purpose:
+ *
+ * - `did not answer` counts only the SILENT members. An unparsed member
+ *   answered, so counting it here would make the line contradict itself — the
+ *   exact "says something the run did not establish" failure this roadmap is
+ *   about, in the sentence written to prevent it.
+ * - `present-unparsed` counts the members whose answer no parser could read.
+ */
+export function formatAttendanceCaveats(q: QuorumResult): string {
+    const unparsed = q.unparsed ?? 0;
+    const silent = q.total - q.present - unparsed;
+    const degraded =
+        silent > 0 ? `  ⚠️  DEGRADED — ${String(silent)} member(s) did not answer; this is not convergence.` : '';
+    const unreadable =
+        unparsed > 0
+            ? `  ⚠️  ${String(unparsed)} present-unparsed — answered, and no parser could read it; not counted toward attendance.`
+            : '';
+    return `${degraded}${unreadable}`;
 }
 
 /**