@event4u/agent-config 2.12.0 → 2.14.0

package/scripts/ai_council/orchestrator.py

@@ -20,7 +20,7 @@ CouncilResponse, never raise) is unchanged.
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Callable
+from typing import Any, Callable
 
 from scripts.ai_council.budget_guard import (
     record_spend as _record_daily_spend,
@@ -32,6 +32,18 @@ from scripts.ai_council.clients import (
     CouncilResponse,
     ExternalAIClient,
 )
+from scripts.ai_council.consensus import (
+    ConsensusBucket,
+    ConsensusMetadata,
+    Finding,
+    FindingScore,
+    aggregate_scores,
+    anonymize_findings,
+    anonymize_responses,
+    bucket_by_threshold,
+    parse_findings_response,
+    parse_scores_response,
+)
 from scripts.ai_council.pricing import (
     CostEstimate,
     PriceTable,
@@ -39,7 +51,16 @@ from scripts.ai_council.pricing import (
     estimate_input_tokens,
 )
 from scripts.ai_council.project_context import ProjectContext
-from scripts.ai_council.prompts import system_prompt_for
+from scripts.ai_council.advisors import AdvisorPlan
+from scripts.ai_council.prompts import (
+    advisor_system_prompt,
+    build_extraction_user_prompt,
+    build_peer_review_user_prompt,
+    build_scoring_user_prompt,
+    peer_review_synthesis_addendum,
+    synthesis_template,
+    system_prompt_for,
+)
 
 
 @dataclass
@@ -78,6 +99,99 @@ class OverrunEvent:
 OnOverrunCallback = Callable[[OverrunEvent], bool]
 
 
+@dataclass(frozen=True)
+class DebateCostEstimate:
+    """Pre-flight debate cost summary (Phase 8).
+
+    ``low_usd`` / ``expected_usd`` / ``high_usd`` are the rolled-up
+    spend bounds across every billable member × ``rounds``. The
+    expected estimate matches the per-round ``estimate()`` total
+    multiplied by rounds (worst-case ``max_output_tokens``). ``low_usd``
+    discounts output to 25% of the ceiling — most members do not hit
+    their token budget. ``high_usd`` adds a 20% over-run buffer per the
+    roadmap's ±20% accuracy target.
+
+    ``per_member`` carries one entry per billable member with the same
+    bound triple, plus the member's transport label (api / cli /
+    manual). ``subscription_members`` lists non-billable members so the
+    disclosure block can call out the "covered by subscription" rows
+    without summing them into USD totals.
+    """
+
+    rounds: int
+    low_usd: float
+    expected_usd: float
+    high_usd: float
+    per_member: list[dict[str, Any]]
+    subscription_members: list[dict[str, str]]
+
+
+def estimate_debate_cost(
+    question: CouncilQuestion,
+    members: list[ExternalAIClient],
+    table: PriceTable,
+    *,
+    rounds: int,
+    project: ProjectContext | None = None,
+    original_ask: str = "",
+    advisor_plans: dict[str, AdvisorPlan] | None = None,
+) -> DebateCostEstimate:
+    """Project total spend for an N-round debate across all members.
+
+    Mirrors :func:`estimate` per-member, then multiplies by ``rounds``
+    to account for the per-round preamble + critique pass. CLI / manual
+    members (``billable=False``) are excluded from USD totals and
+    surfaced separately in ``subscription_members`` so the disclosure
+    block can label them as covered by the user's flat-rate plan.
+    """
+    if rounds < 1:
+        raise ValueError(f"rounds must be >= 1 (got {rounds!r}).")
+    billable_members = [m for m in members if getattr(m, "billable", True)]
+    sub_members = [
+        {
+            "name": m.name,
+            "model": m.model,
+            "transport": getattr(m, "transport", "api"),
+            "subscription_label": getattr(m, "subscription_label", ""),
+        }
+        for m in members
+        if not getattr(m, "billable", True)
+    ]
+    per_round = estimate(
+        question, billable_members, table,
+        project=project, original_ask=original_ask,
+        advisor_plans=advisor_plans,
+    )
+    expected = sum(e.total_usd for e in per_round) * rounds
+    # Low bound: output tokens rarely reach `max_output_tokens` ceiling.
+    # Use input-only cost + 25% of the output ceiling — empirical floor
+    # from manual debate traces.
+    low = (
+        sum(e.input_usd + 0.25 * e.output_usd for e in per_round) * rounds
+    )
+    # High bound: +20% over-run buffer (roadmap ±20% accuracy target).
+    high = expected * 1.20
+    per_member: list[dict[str, Any]] = []
+    for member, est in zip(billable_members, per_round):
+        member_expected = est.total_usd * rounds
+        per_member.append({
+            "name": member.name,
+            "model": member.model,
+            "transport": getattr(member, "transport", "api"),
+            "low_usd": (est.input_usd + 0.25 * est.output_usd) * rounds,
+            "expected_usd": member_expected,
+            "high_usd": member_expected * 1.20,
+        })
+    return DebateCostEstimate(
+        rounds=rounds,
+        low_usd=low,
+        expected_usd=expected,
+        high_usd=high,
+        per_member=per_member,
+        subscription_members=sub_members,
+    )
+
+
 def estimate(
     question: CouncilQuestion,
     members: list[ExternalAIClient],
@@ -85,21 +199,41 @@ def estimate(
     *,
     project: ProjectContext | None = None,
     original_ask: str = "",
+    advisor_plans: dict[str, AdvisorPlan] | None = None,
 ) -> list[CostEstimate]:
     """Return a pre-call cost estimate per member, in input order.
 
     `project` and `original_ask` are passed through to
     `system_prompt_for()` so the estimate covers the handoff preamble
     bytes too. Both default to v1-shape (no preamble extension).
+
+    `advisor_plans` (Phase 6) — when a member's name has a plan, the
+    estimate uses the advisor persona system prompt (typically larger
+    than the bare mode addendum). The cost estimator must mirror
+    `_run_round` exactly so the pre-call preview never under-states
+    the advisor-mode bill.
     """
-    sys_prompt = system_prompt_for(
+    plans = advisor_plans or {}
+    base_user_tokens = estimate_input_tokens(question.user_prompt)
+    base_sys = system_prompt_for(
         question.mode, project=project, original_ask=original_ask,
     )
-    input_tokens = estimate_input_tokens(question.user_prompt) + estimate_input_tokens(sys_prompt)
-    return [
-        estimate_cost(m.name, m.model, input_tokens, question.max_tokens, table)
-        for m in members
-    ]
+    base_sys_tokens = estimate_input_tokens(base_sys)
+    estimates: list[CostEstimate] = []
+    for m in members:
+        plan = plans.get(m.name)
+        if plan is None:
+            sys_tokens = base_sys_tokens
+        else:
+            sys_prompt = advisor_system_prompt(
+                plan.persona_text, project=project, original_ask=original_ask,
+            )
+            sys_tokens = estimate_input_tokens(sys_prompt)
+        input_tokens = base_user_tokens + sys_tokens
+        estimates.append(
+            estimate_cost(m.name, m.model, input_tokens, question.max_tokens, table),
+        )
+    return estimates
 
 
 def consult(
@@ -113,6 +247,7 @@ def consult(
     original_ask: str = "",
     rounds: int = 1,
     on_round_complete: Callable[[int, list[CouncilResponse]], None] | None = None,
+    advisor_plans: dict[str, AdvisorPlan] | None = None,
 ) -> list[CouncilResponse]:
     """Sequentially fan out `question` to every enabled member.
 
@@ -133,6 +268,9 @@ def consult(
       accumulate across rounds. Returns the FINAL round's responses;
       use `on_round_complete(round_idx, responses)` to capture
       intermediate rounds.
+    - `advisor_plans` (Phase 6) keyed by provider name swaps the
+      member's system prompt for the advisor persona via
+      `advisor_system_prompt()`. Replace-mode: no extra calls.
     """
     if rounds < 1:
         raise ValueError(f"rounds must be >= 1 (got {rounds})")
@@ -162,6 +300,7 @@ def consult(
             members, round_question, budget, spent,
             table=table, on_overrun=on_overrun,
             project=project, original_ask=original_ask,
+            advisor_plans=advisor_plans,
         )
         if on_round_complete is not None:
             on_round_complete(round_idx, last_results)
@@ -183,14 +322,29 @@ def _run_round(
     on_overrun: OnOverrunCallback | None,
     project: ProjectContext | None,
     original_ask: str,
+    advisor_plans: dict[str, AdvisorPlan] | None = None,
 ) -> list[CouncilResponse]:
     """Run a single round; mutate `spent` with cumulative totals."""
-    system_prompt = system_prompt_for(
+    plans = advisor_plans or {}
+    base_system_prompt = system_prompt_for(
         question.mode, project=project, original_ask=original_ask,
     )
+
+    def _system_prompt_for_member(m: ExternalAIClient) -> str:
+        plan = plans.get(m.name)
+        if plan is None:
+            return base_system_prompt
+        return advisor_system_prompt(
+            plan.persona_text, project=project, original_ask=original_ask,
+        )
+
     results: list[CouncilResponse] = []
     estimates = (
-        estimate(question, members, table, project=project, original_ask=original_ask)
+        estimate(
+            question, members, table,
+            project=project, original_ask=original_ask,
+            advisor_plans=advisor_plans,
+        )
         if table is not None
         else None
     )
@@ -202,12 +356,16 @@ def _run_round(
         # observability, but no projection / budget breach can apply.
         if not getattr(member, "billable", True):
             try:
-                response = member.ask(system_prompt, question.user_prompt, question.max_tokens)
+                response = member.ask(
+                    _system_prompt_for_member(member),
+                    question.user_prompt, question.max_tokens,
+                )
             except Exception as exc:  # noqa: BLE001 - last-resort safety net
                 response = CouncilResponse(
                     provider=member.name, model=member.model, text="",
                     error=f"{type(exc).__name__}: {exc}",
                 )
+            _stamp_transport_metadata(response, member)
             results.append(response)
             spent["input"] += response.input_tokens
             spent["output"] += response.output_tokens
@@ -265,7 +423,10 @@ def _run_round(
 
         # ── actual call ──────────────────────────────────────────────
         try:
-            response = member.ask(system_prompt, question.user_prompt, question.max_tokens)
+            response = member.ask(
+                _system_prompt_for_member(member),
+                question.user_prompt, question.max_tokens,
+            )
         except Exception as exc:  # noqa: BLE001 - last-resort safety net
             response = CouncilResponse(
                 provider=member.name, model=member.model, text="",
@@ -274,6 +435,7 @@ def _run_round(
         results.append(response)
         spent["input"] += response.input_tokens
         spent["output"] += response.output_tokens
+        actual_usd: float | None = None
         if estimates is not None and table is not None:
             # Bill the actual output against the budget using the
             # member's per-1M output rate. Re-use estimate_cost with
@@ -282,6 +444,7 @@ def _run_round(
                 member.name, member.model,
                 response.input_tokens, response.output_tokens, table,
             )
+            actual_usd = actual.total_usd
             spent["usd"] += actual.total_usd
             # Persist to the rolling 24h ledger when the daily cap is
             # active. Errors are swallowed inside record_spend.
@@ -289,14 +452,44 @@ def _run_round(
                 _record_daily_spend(
                     actual.total_usd, member.name, member.model,
                 )
+        _stamp_transport_metadata(response, member, cost_usd=actual_usd)
 
     return results
 
 
 def _aborted(member: ExternalAIClient, reason: str) -> CouncilResponse:
-    return CouncilResponse(
+    response = CouncilResponse(
         provider=member.name, model=member.model, text="", error=reason,
     )
+    _stamp_transport_metadata(response, member)
+    return response
+
+
+def _stamp_transport_metadata(
+    response: CouncilResponse,
+    member: ExternalAIClient,
+    *,
+    cost_usd: float | None = None,
+) -> None:
+    """Annotate `response.metadata` with transport / billable / cost info.
+
+    Phase 5 / Step 1 — the session writer and orchestrator renderer key
+    off these fields to format the cost line as either
+    ``cost: subscription (claude-pro)`` (non-billable vendor CLI) or
+    ``cost: $0.NNNN (… in / … out)`` (billable api or community CLI).
+    Stamped here (and not in each client) so the writer stays decoupled
+    from the client class hierarchy.
+    """
+    meta = dict(response.metadata or {})
+    transport = getattr(member, "transport", "api")
+    meta.setdefault("transport", transport)
+    meta.setdefault("billable", bool(getattr(member, "billable", True)))
+    label = getattr(member, "subscription_label", "") or ""
+    if label and not meta.get("billable", True):
+        meta.setdefault("subscription_label", label)
+    if cost_usd is not None:
+        meta["cost_usd"] = float(cost_usd)
+    response.metadata = meta
 
 
 def _augment_for_next_round(
@@ -337,18 +530,677 @@ def _augment_for_next_round(
     )
 
 
-def render(responses: list[CouncilResponse]) -> str:
-    """Render stacked sections + a Convergence/Divergence summary slot."""
+@dataclass
+class DebateCheckpoint:
+    """Snapshot passed to the continue-prompt callback between rounds.
+
+    Phase 7 progressive-disclosure contract — the orchestrator pauses
+    after each completed round, builds this checkpoint, and asks the
+    caller whether to continue. Returning False stops the debate
+    gracefully (caller receives every completed round).
+    """
+
+    completed_round: int  # 1-based index of the round just finished
+    total_planned_rounds: int
+    cost_so_far_usd: float
+    next_round_estimate_usd: float
+    last_round_responses: list[CouncilResponse]
+
+
+class DebateCapExceeded(RuntimeError):
+    """Raised when projected next-round spend would breach the budget cap.
+
+    The CLI catches this *after* writing the partial artefact, so the
+    user always has a recoverable trail of the rounds that completed
+    before the cap fired.
+    """
+
+    def __init__(
+        self, *,
+        completed_round: int,
+        cost_so_far: float,
+        next_estimate: float,
+        cap: float,
+    ) -> None:
+        self.completed_round = completed_round
+        self.cost_so_far = cost_so_far
+        self.next_estimate = next_estimate
+        self.cap = cap
+        super().__init__(
+            f"Debate hard-cap: round {completed_round + 1} would push spend "
+            f"to ${cost_so_far + next_estimate:.4f} (cap=${cap:.4f}); "
+            f"stopping after round {completed_round}."
+        )
+
+
+# Continue-prompt callback. Receives a DebateCheckpoint, returns True to
+# proceed with the next round, False to stop gracefully.
+DebateContinuePrompt = Callable[[DebateCheckpoint], bool]
+
+
+def _augment_for_debate_round(
+    original_prompt: str,
+    prior_responses: list[CouncilResponse],
+    next_round_number: int,
+) -> str:
+    """Build the round-N user prompt for a debate — rebuttal framing.
+
+    Same anonymisation rules as `_augment_for_next_round` (Iron Law of
+    Neutrality § multi-round): provider/model identifiers stripped,
+    "Reviewer A / B / C…" labels assigned in input order, errors
+    skipped. The instruction block is debate-specific: each reviewer
+    is asked to identify the strongest opposing position and write a
+    rebuttal, NOT to find common ground.
+    """
     blocks: list[str] = []
+    label_idx = 0
+    for r in prior_responses:
+        if r.error or not r.text.strip():
+            continue
+        label = chr(ord("A") + label_idx)
+        label_idx += 1
+        blocks.append(f"### Reviewer {label}\n\n{r.text.strip()}")
+    if not blocks:
+        return original_prompt
+    prior_block = "\n\n".join(blocks)
+    return (
+        f"{original_prompt}\n\n"
+        f"---\n\n"
+        f"## Prior round positions (round {next_round_number - 1})\n\n"
+        f"You are now in round {next_round_number} of a structured\n"
+        f"debate. Below are anonymised positions from independent\n"
+        f"reviewers in the previous round. You do NOT know which model\n"
+        f"produced which position.\n\n"
+        f"Identify the SINGLE strongest opposing position and write a\n"
+        f"rebuttal addressed at its strongest steel-manned form. Do NOT\n"
+        f"search for common ground — name the load-bearing flaw the\n"
+        f"opposing reviewer missed and state the evidence behind your\n"
+        f"counter-position.\n\n"
+        f"{prior_block}"
+    )
+
+
+def run_debate(
+    members: list[ExternalAIClient],
+    question: CouncilQuestion,
+    *,
+    budget: CostBudget | None = None,
+    table: PriceTable | None = None,
+    on_overrun: OnOverrunCallback | None = None,
+    project: ProjectContext | None = None,
+    original_ask: str = "",
+    max_rounds: int = 2,
+    on_round_complete: Callable[[int, list[CouncilResponse]], None] | None = None,
+    on_continue: DebateContinuePrompt | None = None,
+    advisor_plans: dict[str, AdvisorPlan] | None = None,
+    seed_round_1: list[CouncilResponse] | None = None,
+) -> list[list[CouncilResponse]]:
+    """Run a structured multi-round debate with progressive disclosure.
+
+    Returns every completed round in order — caller persists each
+    round incrementally via `on_round_complete` for crash safety.
+
+    Round 1: each member produces an initial position. When
+    `seed_round_1` is provided, it is reused verbatim (no calls) so
+    `/council debate --continue-as-debate` can pivot from an existing
+    `/council default` session.
+
+    Round 2+: `_augment_for_debate_round` wraps the original prompt
+    with anonymised prior positions and asks each member for a
+    rebuttal addressed at the strongest opposing view.
+
+    Between rounds: `on_continue(checkpoint)` is consulted. Returning
+    False stops the debate; the caller receives every completed round.
+    `None` (the default) auto-continues — the CLI wires its
+    interactive y/N prompt here, `--auto-continue` passes `None`.
+
+    Hard cap: before kicking off round N+1, the orchestrator compares
+    `spent_usd + next_round_estimate` to `budget.max_total_usd`. A
+    projected breach raises `DebateCapExceeded`; the CLI catches it
+    after persisting the partial debate.
+    """
+    if max_rounds < 1:
+        raise ValueError(f"max_rounds must be >= 1 (got {max_rounds})")
+    if not members:
+        return []
+    budget = budget or CostBudget()
+    if len(members) > budget.max_calls:
+        raise ValueError(
+            f"Debate has {len(members)} members but budget caps at "
+            f"{budget.max_calls} calls."
+        )
+
+    spent: dict[str, float] = {"input": 0, "output": 0, "usd": 0.0}
+    all_rounds: list[list[CouncilResponse]] = []
+    current_user_prompt = question.user_prompt
+
+    for round_idx in range(max_rounds):
+        round_number = round_idx + 1
+        if round_idx == 0 and seed_round_1 is not None:
+            # Pivot from /council default — reuse the existing round 1
+            # verbatim. No calls billed; spend stays at $0 until round 2.
+            results = list(seed_round_1)
+        else:
+            round_question = (
+                question if round_idx == 0
+                else CouncilQuestion(
+                    mode=question.mode,
+                    user_prompt=current_user_prompt,
+                    max_tokens=question.max_tokens,
+                )
+            )
+            results = _run_round(
+                members, round_question, budget, spent,
+                table=table, on_overrun=on_overrun,
+                project=project, original_ask=original_ask,
+                advisor_plans=advisor_plans,
+            )
+
+        all_rounds.append(results)
+        if on_round_complete is not None:
+            on_round_complete(round_number, results)
+
+        # Prep the user-prompt for the next round so the cost estimate
+        # below covers the augmented bytes.
+        if round_idx + 1 < max_rounds:
+            current_user_prompt = _augment_for_debate_round(
+                question.user_prompt, results, round_number + 1,
+            )
+            # Hard-cap + continue-prompt gating before kicking off N+1.
+            if table is not None:
+                next_question = CouncilQuestion(
+                    mode=question.mode,
+                    user_prompt=current_user_prompt,
+                    max_tokens=question.max_tokens,
+                )
+                next_estimates = estimate(
+                    next_question, members, table,
+                    project=project, original_ask=original_ask,
+                    advisor_plans=advisor_plans,
+                )
+                next_round_usd = sum(e.total_usd for e in next_estimates)
+            else:
+                next_round_usd = 0.0
+
+            if (
+                budget.max_total_usd > 0
+                and spent["usd"] + next_round_usd > budget.max_total_usd
+            ):
+                raise DebateCapExceeded(
+                    completed_round=round_number,
+                    cost_so_far=spent["usd"],
+                    next_estimate=next_round_usd,
+                    cap=budget.max_total_usd,
+                )
+
+            if on_continue is not None:
+                checkpoint = DebateCheckpoint(
+                    completed_round=round_number,
+                    total_planned_rounds=max_rounds,
+                    cost_so_far_usd=spent["usd"],
+                    next_round_estimate_usd=next_round_usd,
+                    last_round_responses=results,
+                )
+                if not on_continue(checkpoint):
+                    return all_rounds
+
+    return all_rounds
+
+
+@dataclass
+class PeerReviewResult:
+    """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.
+    """
+
+    responses: list[CouncilResponse]
+    label_to_source: dict[str, str]
+    persona_labels: dict[str, str]
+
+
+def run_peer_review(
+    members: list[ExternalAIClient],
+    deliberation_responses: list[CouncilResponse],
+    *,
+    budget: CostBudget | None = None,
+    table: PriceTable | None = None,
+    on_overrun: OnOverrunCallback | None = None,
+    project: ProjectContext | None = None,
+    original_ask: str = "",
+    max_tokens: int = DEFAULT_MAX_TOKENS,
+    persona_labels: dict[str, str] | None = None,
+) -> PeerReviewResult:
+    """Karpathy peer-review pass (Phase 5 / F1).
+
+    After the final deliberation round, each member sees the OTHER
+    members' deliberation outputs under neutral `Response-A` labels
+    (provider identity stripped; advisor persona labels preserved per
+    Phase 6 Step 3a) and emits a Karpathy-style critique:
+    strongest / weakest blind spot / what all missed / refinement.
+
+    Members never see their own response — the orchestrator filters
+    self before building the anonymised prompt. Errors in one member's
+    pass tag that member but never abort the round.
+
+    Cost gates flow through `consult([member], ...)`, so the same
+    budget + daily-ledger semantics as deliberation apply.
+    """
+    if not members or not deliberation_responses:
+        return PeerReviewResult(
+            responses=[], label_to_source={}, persona_labels={},
+        )
+
+    member_by_name = {m.name: m for m in members}
+    # ── source map: deliberation responses keyed by `provider:model` ─
+    # Errors and empty bodies are skipped — they leak nothing useful
+    # and would clutter the anonymised prompt with blanks.
+    by_source: dict[str, CouncilResponse] = {}
+    for r in deliberation_responses:
+        if r.error or not r.text.strip():
+            continue
+        source = f"{r.provider}:{r.model}"
+        by_source[source] = r
+
+    if len(by_source) < 2:
+        # Peer-review needs ≥ 2 distinct deliberation outputs (a
+        # reviewer with nothing else to review is a no-op).
+        return PeerReviewResult(
+            responses=[], label_to_source={}, persona_labels={},
+        )
+
+    persona_labels = dict(persona_labels or {})
+    review_responses: list[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.
+    last_label_to_source: dict[str, str] = {}
+
+    for reviewer in members:
+        scorer = f"{reviewer.name}:{reviewer.model}"
+        if reviewer.name not in member_by_name:
+            continue
+        others_pairs = [
+            (src, resp.text) for src, resp in by_source.items() if src != scorer
+        ]
+        if len(others_pairs) == 0:
+            continue
+        anon_text, label_to_source = anonymize_responses(
+            others_pairs, persona_labels=persona_labels,
+        )
+        if not anon_text:
+            continue
+        last_label_to_source = label_to_source
+        question = CouncilQuestion(
+            mode="prompt",
+            user_prompt=build_peer_review_user_prompt(anon_text),
+            max_tokens=max_tokens,
+        )
+        reviewed = consult(
+            [reviewer], question,
+            budget=budget, table=table, on_overrun=on_overrun,
+            project=project, original_ask=original_ask,
+        )
+        review_responses.extend(reviewed)
+
+    return PeerReviewResult(
+        responses=review_responses,
+        label_to_source=last_label_to_source,
+        persona_labels=persona_labels,
+    )
+
+
+@dataclass
+class ConsensusResult:
+    """Bundle returned by `run_consensus_scoring()`.
+
+    `bucket` is renderer-ready; `findings`, `scores`, and `metadata`
+    are kept for audit-trail JSON (council-sessions/*.json).
+    """
+
+    bucket: ConsensusBucket
+    findings: list[Finding]
+    scores: list[FindingScore]
+    metadata: dict[str, ConsensusMetadata]
+    extraction_responses: list[CouncilResponse]
+    scoring_responses: list[CouncilResponse]
+
+
+def run_consensus_scoring(
+    members: list[ExternalAIClient],
+    deliberation_responses: list[CouncilResponse],
+    *,
+    budget: CostBudget | None = None,
+    table: PriceTable | None = None,
+    on_overrun: OnOverrunCallback | None = None,
+    project: ProjectContext | None = None,
+    original_ask: str = "",
+    max_tokens: int = DEFAULT_MAX_TOKENS,
+    strong_threshold: float = 0.7,
+    minority_threshold: float = 0.4,
+) -> ConsensusResult:
+    """Two-pass consensus round (Phase 4 / F3).
+
+    Pass 1 — extraction: each member re-emits its own deliberation as
+    a JSON array of `{id, text}` findings. Pass 2 — scoring: each
+    member sees the *other* members' findings under anonymous labels
+    and rates them 1-10 + agree/disagree + reason.
+
+    The cost budget is shared across both passes; the daily ledger
+    receives both. Errors in one member's extraction or scoring tag
+    that member but never abort the round.
+    """
+    if not members or not deliberation_responses:
+        return ConsensusResult(
+            bucket=ConsensusBucket(), findings=[], scores=[], metadata={},
+            extraction_responses=[], scoring_responses=[],
+        )
+
+    # ── Pass 1: extraction ──────────────────────────────────────────
+    member_by_name = {m.name: m for m in members}
+    extraction_responses: list[CouncilResponse] = []
+    all_findings: list[Finding] = []
+    for resp in deliberation_responses:
+        member = member_by_name.get(resp.provider)
+        if member is None or resp.error or not resp.text.strip():
+            continue
+        question = CouncilQuestion(
+            mode="prompt",
+            user_prompt=build_extraction_user_prompt(resp.text),
+            max_tokens=max_tokens,
+        )
+        extracted = consult(
+            [member], question,
+            budget=budget, table=table, on_overrun=on_overrun,
+            project=project, original_ask=original_ask,
+        )
+        extraction_responses.extend(extracted)
+        if not extracted or extracted[0].error:
+            continue
+        source = f"{member.name}:{member.model}"
+        all_findings.extend(
+            parse_findings_response(extracted[0].text, source=source),
+        )
+
+    if not all_findings:
+        return ConsensusResult(
+            bucket=ConsensusBucket(), findings=[], scores=[], metadata={},
+            extraction_responses=extraction_responses, scoring_responses=[],
+        )
+
+    # ── Pass 2: scoring (each member rates the OTHERS' findings) ────
+    scoring_responses: list[CouncilResponse] = []
+    all_scores: list[FindingScore] = []
+    for member in members:
+        scorer = f"{member.name}:{member.model}"
+        others = [f for f in all_findings if f.source != scorer]
+        if not others:
+            continue
+        anon = anonymize_findings(others)
+        label_to_id = {label: f.id for label, f in anon.items()}
+        anon_text = {label: f.text for label, f in anon.items()}
+        question = CouncilQuestion(
+            mode="prompt",
+            user_prompt=build_scoring_user_prompt(anon_text),
+            max_tokens=max_tokens,
+        )
+        scored = consult(
+            [member], question,
+            budget=budget, table=table, on_overrun=on_overrun,
+            project=project, original_ask=original_ask,
+        )
+        scoring_responses.extend(scored)
+        if not scored or scored[0].error:
+            continue
+        for s in parse_scores_response(scored[0].text, scorer=scorer):
+            real_id = label_to_id.get(s.finding_id)
+            if real_id is None:
+                continue
+            all_scores.append(FindingScore(
+                finding_id=real_id, scorer=s.scorer, score=s.score,
+                agree=s.agree, reason=s.reason,
+            ))
+
+    metadata = aggregate_scores(all_findings, all_scores)
+    bucket = bucket_by_threshold(
+        all_findings, metadata,
+        strong=strong_threshold, minority=minority_threshold,
+    )
+    return ConsensusResult(
+        bucket=bucket, findings=all_findings, scores=all_scores,
+        metadata=metadata, extraction_responses=extraction_responses,
+        scoring_responses=scoring_responses,
+    )
+
+
+def _render_response_meta(r: CouncilResponse) -> str:
+    """Format the per-member meta line — tokens, cost (or subscription), latency.
+
+    Phase 5 / Step 1 — non-billable vendor-CLI calls render
+    ``cost: subscription (<label>)`` with no token detail (the local
+    session counted them but the user is on a flat rate). Billable
+    calls (api or community CLI) render ``cost: $X.XXXX`` plus tokens.
+    Tokens marked ``estimated=True`` get a ``~`` prefix so the audit
+    trail flags heuristic counts.
+    """
+    meta_dict = r.metadata or {}
+    billable = bool(meta_dict.get("billable", True))
+    estimated = bool(meta_dict.get("tokens_estimated", False))
+    parts: list[str] = []
+    if not billable:
+        label = meta_dict.get("subscription_label") or "flat-rate"
+        parts.append(f"cost: subscription ({label})")
+    else:
+        cost_usd = meta_dict.get("cost_usd")
+        if isinstance(cost_usd, (int, float)):
+            parts.append(f"cost: ${cost_usd:.4f}")
+        prefix = "~" if estimated else ""
+        parts.append(
+            f"tokens: {prefix}{r.input_tokens} in / {prefix}{r.output_tokens} out"
+        )
+    parts.append(f"{r.latency_ms} ms")
+    return f"*{' · '.join(parts)}*"
+
+
+# Lens defaults for the Phase 9 confidence-explanation badge. The PR
+# lens stays terse so the existing "Must-fix / Nice-to-have" structure
+# isn't drowned in scorer prose; every other decision lens shows the
+# explanation by default. Creative lenses (design/optimize) never reach
+# this code path because they skip consensus scoring entirely.
+_DEFAULT_EXPLAIN_LENSES: frozenset[str] = frozenset({
+    "default", "analysis", "debate", "prompt", "roadmap", "diff", "files",
+})
+
+
+def _default_explain_confidence(mode: str | None) -> bool:
+    """Decide whether the confidence-explanation badge fires by default.
+
+    Pulled into a helper so the CLI ``--explain-confidence`` /
+    ``--no-explain-confidence`` flags and the lens override path share
+    one truth source.
+    """
+    if mode is None:
+        return True
+    return mode in _DEFAULT_EXPLAIN_LENSES
+
+
+def render(
+    responses: list[CouncilResponse],
+    *,
+    mode: str | None = None,
+    prose_synthesis: bool | None = None,
+    consensus: ConsensusResult | None = None,
+    peer_review: PeerReviewResult | None = None,
+    explain_confidence: bool | None = None,
+) -> str:
+    """Render stacked sections + a lens-aware synthesis prompt slot.
+
+    `mode` selects the synthesis template from `prompts.synthesis_template`.
+    `None` collapses to the default decision-lens template (back-compat).
+
+    `prose_synthesis` is the R4 Q4 escape hatch:
+      - `True`  → force creative-lens passthrough (bare slot) regardless of mode
+      - `False` → force decision-lens default template even on creative lenses
+      - `None`  → honour the lens default from the table
+
+    `consensus` (Phase 4 / F3) prepends Strong Consensus / Findings /
+    Minority Views sections when the analysis lens scored its findings.
+
+    `peer_review` (Phase 5 / F1) appends a Peer-Review block listing
+    each member's critique (under Reviewer-A / Reviewer-B labels, in
+    member input order so the audit trail is deterministic) and
+    extends the synthesis template with the
+    `Peer-Review-Surfaced Blind Spots` addendum.
+    """
+    blocks: list[str] = []
+    explain = (
+        explain_confidence
+        if explain_confidence is not None
+        else _default_explain_confidence(mode)
+    )
+    if consensus is not None and (
+        consensus.bucket.strong or consensus.bucket.findings or consensus.bucket.minority
+    ):
+        blocks.append(_render_consensus(consensus.bucket, explain=explain))
     for r in responses:
         header = f"## {r.provider} · {r.model}"
         if r.error:
             blocks.append(f"{header}\n\n*ERROR:* `{r.error}`")
             continue
-        meta = (
-            f"*tokens: {r.input_tokens} in / {r.output_tokens} out · "
-            f"{r.latency_ms} ms*"
-        )
+        meta = _render_response_meta(r)
         blocks.append(f"{header}\n\n{meta}\n\n{r.text}")
-    blocks.append("## Convergence / Divergence\n\n*to be summarised by the host agent*")
+    if peer_review is not None and peer_review.responses:
+        blocks.append(_render_peer_review(peer_review))
+    if prose_synthesis is True:
+        template = ""
+    elif prose_synthesis is False:
+        template = synthesis_template("default")
+    else:
+        template = synthesis_template(mode)
+    if peer_review is not None and peer_review.responses:
+        addendum = peer_review_synthesis_addendum()
+        template = f"{template}\n{addendum}" if template else addendum.lstrip()
+    if template:
+        body = template
+    else:
+        body = "*to be summarised by the host agent*"
+    blocks.append(f"## Convergence / Divergence\n\n{body}")
     return "\n\n---\n\n".join(blocks)
+
+
+def _render_peer_review(peer_review: PeerReviewResult) -> str:
+    """Render the peer-review block under deterministic Reviewer labels.
+
+    Each successful reviewer gets a `### Reviewer X` sub-section. Errors
+    keep their slot (so the audit trail still surfaces the breach) but
+    render `ERROR: <tag>` instead of the prompt body.
+    """
+    lines = ["## Peer-Review (Karpathy)"]
+    label_idx = 0
+    for r in peer_review.responses:
+        label = chr(ord("A") + label_idx)
+        label_idx += 1
+        if r.error:
+            lines.append(f"### Reviewer {label}\n\n*ERROR:* `{r.error}`")
+            continue
+        lines.append(f"### Reviewer {label}\n\n{r.text.strip()}")
+    return "\n\n".join(lines)
+
+
+def _render_consensus(bucket: ConsensusBucket, *, explain: bool = True) -> str:
+    """Render Strong / Findings / Minority sections in renderer order.
+
+    ``explain`` toggles the Phase 9 confidence-explanation badge — when
+    ``False`` the renderer falls back to the terse Phase 4 badge so the
+    PR lens (and any caller passing ``--no-explain-confidence``) keeps
+    its compact output.
+    """
+    parts: list[str] = []
+    if bucket.strong:
+        parts.append(
+            "## Strong Consensus\n\n"
+            + _render_bucket(bucket.strong, explain=explain),
+        )
+    if bucket.findings:
+        parts.append(
+            "## Findings\n\n"
+            + _render_bucket(bucket.findings, explain=explain),
+        )
+    if bucket.minority:
+        parts.append(
+            "## Minority Views\n\n"
+            "*Sub-threshold by consensus; kept for audit trail.*\n\n"
+            + _render_bucket(bucket.minority, explain=explain),
+        )
+    return "\n\n".join(parts)
+
+
+def _truncate_reason(reason: str, *, limit: int = 120) -> str:
+    """Collapse a multi-line scorer reason to a single ≤``limit``-char line.
+
+    Phase 9 — the dissent summary must fit on one line; we keep the
+    first sentence-ish chunk and add an ellipsis when truncating. Empty
+    reasons render as ``no rationale``.
+    """
+    flat = " ".join(reason.split()) if reason else ""
+    if not flat:
+        return "no rationale"
+    if len(flat) <= limit:
+        return flat
+    return flat[: limit - 1].rstrip() + "…"
+
+
+def _render_bucket(
+    items: list[tuple[Finding, ConsensusMetadata]],
+    *,
+    explain: bool = True,
+) -> str:
+    """Render one bucket of (finding, metadata) tuples.
+
+    The Phase 4 terse badge (``strength · mean · scorers · dissent``)
+    is preserved on the first line. Phase 9 adds a second
+    confidence-explanation line whenever ``explain`` is true *and* at
+    least one scorer rated the finding — the explanation needs scorer
+    data to be meaningful.
+    """
+    lines: list[str] = []
+    for f, m in items:
+        terse_badge = (
+            f"strength {m.consensus_strength:.2f} · "
+            f"mean {m.mean_score:.1f}/10 · "
+            f"{len(m.scorers)} scorers · "
+            f"{m.dissent_count} dissent"
+        )
+        block = f"- **{f.id}** — {f.text}  \n  _{terse_badge}_"
+        if explain and m.scorers:
+            total = m.concur_count + m.dissent_count
+            if total <= 0:
+                total = len(m.scorers)
+            parts: list[str] = [
+                f"{m.concur_count}/{total} members concur",
+            ]
+            if m.dissent_reasons:
+                first = m.dissent_reasons[0]
+                parts.append(
+                    f"{first[0]} dissented citing "
+                    f"{_truncate_reason(first[1])}",
+                )
+                extra = len(m.dissent_reasons) - 1
+                if extra > 0:
+                    parts.append(f"{extra} other dissent(s)")
+            else:
+                parts.append("no dissent")
+            parts.append(f"mean evidence-quality {m.evidence_quality}")
+            block += "  \n  _" + "; ".join(parts) + "_"
+        lines.append(block)
+    return "\n".join(lines)