@event4u/agent-config 6.0.0 → 7.0.0

package/src/scripts/ai_council/redact_low_impact_entry.py

@@ -1,155 +0,0 @@
-"""Privacy floor for `agents/decisions/low-impact-decisions.md` (Phase 12).
-
-Non-bypassable redactor invoked on intake (write-side) AND on
-upstream (`/learn-low-impact`, leave-the-repo side). Both gates call
-:func:`redact_low_impact_entry` and refuse to proceed when a forbidden
-pattern fires.
-
-Iron Law: nothing leaves the project repo until this redactor clears
-the entry. See ``.augment/rules/low-impact-corpus-privacy-floor.md``.
-
-Forbidden-content classes (per Phase 12 § Step 4):
-
-1. Secrets — raw-key prefixes mirrored from
-   :data:`scripts.ai_council.config._RAW_KEY_PREFIXES`, plus a
-   generic ``api[-_]?key:\\s*<token>`` shape.
-2. Emails — RFC-5322-ish shape, deliberately permissive.
-3. Project-rooted paths — anything starting ``/Users/``, ``/home/``,
-   ``/opt/``, ``/private/``, drive letters (``C:\\``), or the
-   configured repo root from ``.agent-settings.yml`` when supplied.
-4. Customer / tenant names — caller passes a name list (project
-   policy); generic placeholders ``<customer>``, ``<tenant>``,
-   ``<account>``, ``<user>`` survive.
-5. Internal hostnames — ``*.internal``, ``*.local``, plus any
-   project-private domain the caller supplies.
-6. Monetary amounts — ``$1,234`` / ``€500`` / ``USD 1000`` shapes
-   that look like business figures (lone ``$0.05`` cap mentions in
-   curly-brace context are skipped via the call-site, not here).
-7. Business-context SQL identifiers — caller-supplied table /
-   column allow-list. Default empty.
-8. Inline code excerpts > 40 chars — any backtick-fenced run > 40.
-"""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Iterable
-
-from scripts.ai_council.config import _RAW_KEY_PREFIXES
-
-
-@dataclass(frozen=True)
-class RedactionViolation:
-    """Single forbidden-pattern hit."""
-
-    category: str
-    snippet: str
-    note: str = ""
-
-
-@dataclass(frozen=True)
-class RedactionResult:
-    """Outcome of one redaction pass."""
-
-    ok: bool
-    violations: tuple[RedactionViolation, ...] = ()
-
-    def summary(self) -> str:
-        if self.ok:
-            return "redaction: clean"
-        parts = [f"{v.category}: {v.snippet!r}" for v in self.violations]
-        return "redaction REFUSED — " + "; ".join(parts)
-
-
-_EMAIL_RE = re.compile(r"\b[\w.+-]+@[\w-]+\.[\w.-]+\b")
-_PATH_RE = re.compile(
-    r"(?:^|[\s\"'(])"
-    r"(?:/Users/|/home/|/opt/|/private/|[A-Z]:\\)"
-    r"[\w.\-/\\]+"
-)
-_INTERNAL_HOST_RE = re.compile(
-    r"\b[a-zA-Z0-9][\w.-]*\.(?:internal|local)\b",
-    re.IGNORECASE,
-)
-_MONEY_RE = re.compile(
-    r"(?:[\$€£¥]\s?\d{1,3}(?:[,.]\d{3})*(?:\.\d+)?"
-    r"|\b(?:USD|EUR|GBP|JPY)\s?\d+(?:[,.]\d+)?)"
-)
-_API_KEY_RE = re.compile(
-    r"(?i)\bapi[_-]?key\b\s*[:=]\s*[A-Za-z0-9+/=_\-]{12,}"
-)
-_CODE_FENCE_RE = re.compile(r"`([^`]{41,})`")
-
-
-def _check_secrets(text: str) -> list[RedactionViolation]:
-    hits: list[RedactionViolation] = []
-    for prefix in _RAW_KEY_PREFIXES:
-        pat = re.compile(re.escape(prefix) + r"[A-Za-z0-9_\-]{6,}")
-        m = pat.search(text)
-        if m:
-            hits.append(RedactionViolation(
-                "secret", m.group(0)[:8] + "…",
-                f"raw-key prefix {prefix!r}",
-            ))
-    m = _API_KEY_RE.search(text)
-    if m:
-        hits.append(RedactionViolation("secret", m.group(0)[:20] + "…",
-                                       "inline api_key"))
-    return hits
-
-
-def _check_patterns(text: str, repo_root: str | None,
-                    private_domains: Iterable[str],
-                    customer_names: Iterable[str],
-                    sql_identifiers: Iterable[str]) -> list[RedactionViolation]:
-    hits: list[RedactionViolation] = []
-    for m in _EMAIL_RE.finditer(text):
-        hits.append(RedactionViolation("email", m.group(0)))
-    for m in _PATH_RE.finditer(text):
-        hits.append(RedactionViolation("project_path", m.group(0).strip()))
-    if repo_root and repo_root in text:
-        hits.append(RedactionViolation("project_path", repo_root,
-                                       "configured repo root"))
-    for m in _INTERNAL_HOST_RE.finditer(text):
-        hits.append(RedactionViolation("internal_hostname", m.group(0)))
-    for dom in private_domains:
-        if dom and dom in text:
-            hits.append(RedactionViolation("internal_hostname", dom,
-                                           "configured private domain"))
-    for m in _MONEY_RE.finditer(text):
-        hits.append(RedactionViolation("monetary_amount", m.group(0)))
-    for name in customer_names:
-        if name and re.search(rf"\b{re.escape(name)}\b", text, re.IGNORECASE):
-            hits.append(RedactionViolation("customer_name", name))
-    for ident in sql_identifiers:
-        if ident and re.search(rf"\b{re.escape(ident)}\b", text):
-            hits.append(RedactionViolation("sql_identifier", ident))
-    for m in _CODE_FENCE_RE.finditer(text):
-        hits.append(RedactionViolation("long_code_excerpt",
-                                       m.group(1)[:40] + "…",
-                                       f"{len(m.group(1))} chars"))
-    return hits
-
-
-def redact_low_impact_entry(
-    text: str,
-    *,
-    repo_root: str | None = None,
-    private_domains: Iterable[str] = (),
-    customer_names: Iterable[str] = (),
-    sql_identifiers: Iterable[str] = (),
-) -> RedactionResult:
-    """Run the privacy floor over ``text``. Returns clean or refused.
-
-    The redactor never auto-rewrites the entry — that would be a soft
-    privacy gate. It refuses + surfaces what to rephrase, which keeps
-    the user in the loop and the audit trail honest.
-    """
-    violations: list[RedactionViolation] = []
-    violations.extend(_check_secrets(text))
-    violations.extend(_check_patterns(
-        text, repo_root, private_domains, customer_names, sql_identifiers,
-    ))
-    return RedactionResult(ok=not violations, violations=tuple(violations))

package/src/scripts/ai_council/replay.py

@@ -1,155 +0,0 @@
-"""Decision-replay artefact for council sessions (Phase 9).
-
-Produces a per-session ``decision-replay.md`` that surfaces the audit
-trail GPT review of PR #148 called out as missing: for each top
-finding, the consensus_strength, agreeing-members with their key
-argument, dissenting-members with their counter-argument, the
-evidence-quality verdict, and a final synthesis verdict line.
-
-The artefact is a pure projection of the consensus data plus the
-per-member deliberation texts — no extra model calls. Schema is
-documented in ``docs/contracts/ai-council-config.md`` under
-"Decision-replay schema".
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Iterable, Sequence
-
-from scripts.ai_council.clients import CouncilResponse
-from scripts.ai_council.consensus import (
-    ConsensusMetadata,
-    Finding,
-    FindingScore,
-)
-
-
-@dataclass(frozen=True)
-class DecisionReplayInputs:
-    """Bundle accepted by :func:`render_decision_replay`.
-
-    ``include_member_arguments`` toggles the redacted-vs-full output.
-    When ``False`` the artefact emits consensus + dissent COUNT only —
-    no per-member arguments — for sharing without leaking which model
-    framed which point.
-    """
-
-    findings: Sequence[Finding]
-    scores: Sequence[FindingScore]
-    metadata: dict[str, ConsensusMetadata]
-    deliberation: Sequence[CouncilResponse]  # last-round per-member texts
-    original_ask: str = ""
-    include_member_arguments: bool = True
-
-
-def _verdict(strength: float) -> str:
-    """Single-word verdict band for a consensus_strength."""
-    if strength > 0.7:
-        return "Strong"
-    if strength > 0.4:
-        return "Moderate"
-    return "Weak"
-
-
-def _scorer_argument(
-    scorer: str,
-    member_texts: dict[str, str],
-    score: FindingScore | None,
-) -> str:
-    """Return the one-line key argument for ``scorer`` on a finding.
-
-    Prefers the scorer's ``reason`` field (rich, contextual) and falls
-    back to the truncated deliberation snippet so the audit trail never
-    surfaces an empty argument.
-    """
-    if score and score.reason:
-        flat = " ".join(score.reason.split())
-        if len(flat) > 200:
-            flat = flat[:199].rstrip() + "…"
-        return flat
-    snippet = member_texts.get(scorer, "")
-    flat = " ".join(snippet.split())
-    if not flat:
-        return "no argument captured"
-    if len(flat) > 200:
-        flat = flat[:199].rstrip() + "…"
-    return flat
-
-
-def _scores_for_finding(
-    fid: str, scores: Iterable[FindingScore],
-) -> dict[str, FindingScore]:
-    return {s.scorer: s for s in scores if s.finding_id == fid}
-
-
-def render_decision_replay(inputs: DecisionReplayInputs) -> str:
-    """Render the ``decision-replay.md`` body.
-
-    Sections (in order): a leading H1 plus the original ask blockquote,
-    one ``## <finding-id> — <truncated text>`` block per finding (ranked
-    by consensus_strength desc), and a trailing footer with the toggle
-    state so consumers can tell at a glance whether arguments were
-    redacted.
-    """
-    member_texts = {f"{r.provider}:{r.model}": r.text or "" for r in inputs.deliberation}
-    ranked = sorted(
-        inputs.findings,
-        key=lambda f: inputs.metadata.get(
-            f.id,
-            ConsensusMetadata(
-                finding_id=f.id, consensus_strength=0.0, dissent_count=0,
-                scorers=(), mean_score=0.0,
-            ),
-        ).consensus_strength,
-        reverse=True,
-    )
-    lines: list[str] = ["# Decision Replay\n"]
-    if inputs.original_ask.strip():
-        ask = " ".join(inputs.original_ask.split())
-        if len(ask) > 400:
-            ask = ask[:399].rstrip() + "…"
-        lines.append(f"> {ask}\n")
-    if not ranked:
-        lines.append("*No findings were extracted for this session.*\n")
-        return "\n".join(lines).rstrip() + "\n"
-    for f in ranked:
-        m = inputs.metadata.get(f.id)
-        if m is None:
-            m = ConsensusMetadata(
-                finding_id=f.id, consensus_strength=0.0, dissent_count=0,
-                scorers=(), mean_score=0.0,
-            )
-        title = " ".join(f.text.split())
-        if len(title) > 120:
-            title = title[:119].rstrip() + "…"
-        verdict = _verdict(m.consensus_strength)
-        lines.append(f"## {f.id} — {title}\n")
-        lines.append(
-            f"- **Consensus**: {verdict} ({m.consensus_strength:.2f})\n"
-            f"- **Evidence quality**: {m.evidence_quality} "
-            f"(mean {m.mean_score:.1f}/10)\n"
-            f"- **Agreement**: {m.concur_count}/"
-            f"{m.concur_count + m.dissent_count} members concur, "
-            f"{m.dissent_count} dissent\n",
-        )
-        if inputs.include_member_arguments:
-            score_map = _scores_for_finding(f.id, inputs.scores)
-            agreeing = [s for s in m.scorers if score_map.get(s) and score_map[s].agree]
-            dissent = [pair for pair in m.dissent_reasons]
-            if agreeing:
-                lines.append("**Agreeing members**:")
-                for scorer in agreeing:
-                    arg = _scorer_argument(scorer, member_texts, score_map.get(scorer))
-                    lines.append(f"- _{scorer}_ — {arg}")
-                lines.append("")
-            if dissent:
-                lines.append("**Dissenting members**:")
-                for scorer, reason in dissent:
-                    arg = _scorer_argument(scorer, member_texts, score_map.get(scorer))
-                    lines.append(f"- _{scorer}_ — {arg}")
-                lines.append("")
-        lines.append(f"**Synthesis verdict**: {verdict} consensus — {f.source} sourced.\n")
-    mode_label = "full" if inputs.include_member_arguments else "redacted (counts only)"
-    lines.append(f"---\n\n_artefact mode: {mode_label}_\n")
-    return "\n".join(lines).rstrip() + "\n"

package/src/scripts/ai_council/session.py

@@ -1,366 +0,0 @@
-"""Session persistence for council consultations (D2).
-
-Every `/council` call that completes (success or partial) writes an
-audit artefact under `agents/runtime/council/sessions/<UTC-timestamp>/`:
-
-- `manifest.json` — input mode, members, token + USD totals, original
-  ask, neutrality preamble fingerprint.
-- `response.md`   — `orchestrator.render()` output (per-member
-  sections + Convergence/Divergence slot).
-- `raw-text.md`   — concatenated raw text per member, separated by
-  ASCII rules so a later `grep` is trivial.
-
-Hard rules:
-- Never raises on the project — disk write failures are logged and
-  swallowed; the council is text-only and the report is the contract.
-- Never writes secrets. The bundle has already been redacted by
-  `bundler.py` before the orchestrator receives it.
-- Never writes outside `agents/runtime/council/sessions/`. Path traversal in
-  the timestamp is impossible (we generate it from `datetime.utcnow`).
-"""
-
-from __future__ import annotations
-
-import datetime as _dt
-import json
-import re
-import shutil
-import sys
-from dataclasses import dataclass, field
-from pathlib import Path
-try:  # invocation-agnostic import (repo-root-on-path vs scripts-on-path)
-    from scripts._lib.agent_settings import project_settings_path
-except ModuleNotFoundError:  # pragma: no cover
-    from _lib.agent_settings import project_settings_path
-from typing import Iterable
-
-from scripts.ai_council.clients import CouncilResponse
-from scripts.ai_council.orchestrator import render
-
-REPO_ROOT = Path(__file__).resolve().parents[3]
-SESSIONS_DIR = REPO_ROOT / "agents" / "runtime" / "council" / "sessions"
-QUESTIONS_DIR = REPO_ROOT / "agents" / "runtime" / "council" / "questions"
-RESPONSES_DIR = REPO_ROOT / "agents" / "runtime" / "council" / "responses"
-SETTINGS_FILE = project_settings_path(REPO_ROOT)
-
-# Default retention for all council artefacts (questions, responses,
-# sessions). Overridden by `ai_council.session_retention_days`
-# in `.agent-settings.yml`. Council files are local-only scratch — short
-# retention keeps the working tree from accumulating dead weight.
-DEFAULT_RETENTION_DAYS = 7
-_TS_RE = re.compile(r"^(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})Z$")
-
-
-@dataclass
-class SessionManifest:
-    """Structured record of a single council call.
-
-    Round 2+ debate calls (D1) pass `rounds > 1`; each round's
-    per-member response is appended in `responses_per_round`.
-    """
-
-    mode: str  # bundle mode: prompt|roadmap|diff|files
-    artefact: str  # human-readable artefact descriptor (path or "<inline>")
-    original_ask: str
-    members: list[str]  # "provider/model" pairs
-    rounds: int = 1
-    cost_usd_estimated: float = 0.0
-    cost_usd_actual: float = 0.0
-    extra: dict[str, object] = field(default_factory=dict)
-
-
-def _utc_timestamp() -> str:
-    """UTC timestamp safe for filesystem use (Z suffix preserved)."""
-    return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H-%M-%SZ")
-
-
-def _serialise_response(r: CouncilResponse) -> dict[str, object]:
-    """Project a `CouncilResponse` into the manifest schema.
-
-    Phase 5 / Step 1 — surface ``transport``, ``billable``,
-    ``subscription_label``, ``cost_usd``, and ``tokens_estimated`` so
-    the audit trail can distinguish flat-rate CLI calls from billable
-    api / community-CLI calls. When ``tokens_estimated`` is true the
-    token counts are kept (heuristic) but flagged so consumers can
-    null or disclaim them.
-    """
-    meta = r.metadata or {}
-    payload: dict[str, object] = {
-        "provider": r.provider,
-        "model": r.model,
-        "input_tokens": r.input_tokens,
-        "output_tokens": r.output_tokens,
-        "latency_ms": r.latency_ms,
-        "error": r.error,
-        "transport": meta.get("transport", "api"),
-        "billable": bool(meta.get("billable", True)),
-        "tokens_estimated": bool(meta.get("tokens_estimated", False)),
-    }
-    if meta.get("subscription_label"):
-        payload["subscription_label"] = meta["subscription_label"]
-    if "cost_usd" in meta:
-        payload["cost_usd"] = meta["cost_usd"]
-    return payload
-
-
-def _load_retention_days(settings_path: Path | None = None) -> int:
-    """Read `ai_council.session_retention_days` from `.agent-settings.yml`.
-
-    Returns `DEFAULT_RETENTION_DAYS` on any read/parse failure (missing
-    file, invalid YAML, missing key, non-int value). Pruning never
-    blocks the council on a settings error.
-    """
-    # Centralized loader (road-to-portable-dev-preferences P3): tolerance
-    # contract handles missing file / malformed YAML / no PyYAML uniformly.
-    # ``ai_council.session_retention_days`` is not whitelisted, so the
-    # user-global file cannot override the project value.
-    try:
-        from scripts._lib.agent_settings import load_agent_settings
-    except ImportError:  # pragma: no cover — script-style invocation
-        import sys as _sys
-        from pathlib import Path as _Path
-        _sys.path.insert(0, str(_Path(__file__).resolve().parent.parent))
-        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
-
-    path = settings_path or SETTINGS_FILE
-    data = load_agent_settings(project_path=path)
-    ai = data.get("ai_council")
-    if not isinstance(ai, dict):
-        return DEFAULT_RETENTION_DAYS
-    raw = ai.get("session_retention_days", DEFAULT_RETENTION_DAYS)
-    try:
-        return int(raw)
-    except (TypeError, ValueError):
-        return DEFAULT_RETENTION_DAYS
-
-
-def _parse_session_timestamp(name: str) -> _dt.datetime | None:
-    """Parse `YYYY-MM-DDTHH-MM-SSZ` directory name to a UTC datetime."""
-    m = _TS_RE.match(name)
-    if not m:
-        return None
-    try:
-        y, mo, d, h, mi, s = (int(g) for g in m.groups())
-        return _dt.datetime(y, mo, d, h, mi, s, tzinfo=_dt.timezone.utc)
-    except ValueError:
-        return None
-
-
-def prune_old_sessions(
-    sessions_dir: Path,
-    retention_days: int,
-    *,
-    now: _dt.datetime | None = None,
-) -> list[Path]:
-    """Delete session subdirectories older than `retention_days`.
-
-    A session is "old" when its directory-name timestamp predates
-    `now - retention_days`. Non-matching names (e.g. JSON reports at
-    the root, custom folders) are skipped. Never raises — disk
-    failures are logged to stderr.
-
-    Returns the list of deleted directories. `retention_days <= 0`
-    disables pruning and returns an empty list.
-    """
-    if retention_days <= 0 or not sessions_dir.exists():
-        return []
-    cutoff = (now or _dt.datetime.now(_dt.timezone.utc)) - _dt.timedelta(days=retention_days)
-    removed: list[Path] = []
-    try:
-        entries = list(sessions_dir.iterdir())
-    except OSError as exc:  # noqa: BLE001 - never block the report
-        print(f"[council:session] prune iterdir failed: {exc}", file=sys.stderr)
-        return removed
-    for entry in entries:
-        if not entry.is_dir():
-            continue
-        ts = _parse_session_timestamp(entry.name)
-        if ts is None or ts >= cutoff:
-            continue
-        try:
-            shutil.rmtree(entry)
-            removed.append(entry)
-        except OSError as exc:  # noqa: BLE001 - never block the report
-            print(f"[council:session] prune rmtree failed for {entry}: {exc}",
-                  file=sys.stderr)
-    return removed
-
-
-def prune_old_artifacts(
-    artifact_dir: Path,
-    retention_days: int,
-    *,
-    now: _dt.datetime | None = None,
-) -> list[Path]:
-    """Delete files and timestamp-less directories older than `retention_days`.
-
-    mtime-based — used for `agents/runtime/council/questions/`,
-    `agents/runtime/council/responses/`, and root-level files in
-    `agents/runtime/council/sessions/` that don't match the
-    timestamp-subdir convention handled by `prune_old_sessions`.
-
-    Walks the directory non-recursively. For files: deletes when
-    mtime predates the cutoff. For sub-directories without a
-    timestamp name: deletes recursively when mtime predates the
-    cutoff. Never raises — disk failures log to stderr.
-
-    Returns the list of deleted paths. `retention_days <= 0`
-    disables pruning and returns an empty list.
-    """
-    if retention_days <= 0 or not artifact_dir.exists():
-        return []
-    cutoff = (now or _dt.datetime.now(_dt.timezone.utc)) - _dt.timedelta(days=retention_days)
-    cutoff_ts = cutoff.timestamp()
-    removed: list[Path] = []
-    try:
-        entries = list(artifact_dir.iterdir())
-    except OSError as exc:  # noqa: BLE001 - never block the report
-        print(f"[council:session] artifact iterdir failed: {exc}", file=sys.stderr)
-        return removed
-    for entry in entries:
-        # Timestamp subdirs are owned by prune_old_sessions; skip them
-        # so the two pruners don't race.
-        if entry.is_dir() and _parse_session_timestamp(entry.name) is not None:
-            continue
-        try:
-            mtime = entry.stat().st_mtime
-        except OSError as exc:  # noqa: BLE001 - never block the report
-            print(f"[council:session] artifact stat failed for {entry}: {exc}",
-                  file=sys.stderr)
-            continue
-        if mtime >= cutoff_ts:
-            continue
-        try:
-            if entry.is_dir():
-                shutil.rmtree(entry)
-            else:
-                entry.unlink()
-            removed.append(entry)
-        except OSError as exc:  # noqa: BLE001 - never block the report
-            print(f"[council:session] artifact remove failed for {entry}: {exc}",
-                  file=sys.stderr)
-    return removed
-
-
-def prune_all_council_artifacts(
-    retention_days: int | None = None,
-    *,
-    repo_root: Path | None = None,
-    now: _dt.datetime | None = None,
-) -> dict[str, list[Path]]:
-    """Prune every council artefact dir under `repo_root` in one pass.
-
-    Reads `retention_days` from settings if not supplied. Used by the
-    `task council-prune` target and by `save()`. Never raises.
-
-    Returns a dict keyed by directory label — `sessions`,
-    `questions`, `responses` — each mapped to the list of
-    paths actually removed.
-    """
-    root = repo_root or REPO_ROOT
-    days = _load_retention_days() if retention_days is None else retention_days
-    sessions = root / "agents" / "runtime" / "council" / "sessions"
-    questions = root / "agents" / "runtime" / "council" / "questions"
-    responses = root / "agents" / "runtime" / "council" / "responses"
-    return {
-        "sessions": (
-            prune_old_sessions(sessions, days, now=now)
-            + prune_old_artifacts(sessions, days, now=now)
-        ),
-        "questions": prune_old_artifacts(questions, days, now=now),
-        "responses": prune_old_artifacts(responses, days, now=now),
-    }
-
-
-def save(
-    *,
-    manifest: SessionManifest,
-    responses: list[CouncilResponse] | Iterable[list[CouncilResponse]],
-    sessions_dir: Path | None = None,
-    timestamp: str | None = None,
-    retention_days: int | None = None,
-) -> Path:
-    """Persist a council call. Returns the session directory.
-
-    `responses` accepts either:
-    - `list[CouncilResponse]` — single round (round 1 only).
-    - `Iterable[list[CouncilResponse]]` — multi-round, one list per
-      round in execution order.
-
-    `retention_days` controls auto-pruning of older council artefacts
-    after the new one is written — sibling sessions plus, when
-    `sessions_dir` is not overridden, files in `runtime/council/questions/`
-    and `runtime/council/responses/`. `None` reads the value
-    from `.agent-settings.yml` (`ai_council.session_retention_days`,
-    default `7`); `0` disables pruning.
-
-    Disk-write failures are surfaced via a stderr line but do not
-    raise; the caller's text report is the source of truth.
-    """
-    rounds_data: list[list[CouncilResponse]]
-    if responses and isinstance(responses, list) and isinstance(responses[0], CouncilResponse):
-        rounds_data = [responses]  # type: ignore[list-item]
-    else:
-        rounds_data = list(responses)  # type: ignore[arg-type]
-
-    base = sessions_dir or SESSIONS_DIR
-    ts = timestamp or _utc_timestamp()
-    session_dir = base / ts
-
-    try:
-        session_dir.mkdir(parents=True, exist_ok=True)
-    except OSError as exc:  # noqa: BLE001 - never block the report
-        print(f"[council:session] mkdir failed: {exc}", file=sys.stderr)
-        return session_dir
-
-    manifest_payload = {
-        "timestamp_utc": ts,
-        "mode": manifest.mode,
-        "artefact": manifest.artefact,
-        "original_ask": manifest.original_ask,
-        "members": manifest.members,
-        "rounds": manifest.rounds,
-        "cost_usd_estimated": round(manifest.cost_usd_estimated, 6),
-        "cost_usd_actual": round(manifest.cost_usd_actual, 6),
-        "responses_per_round": [
-            [_serialise_response(r) for r in round_responses]
-            for round_responses in rounds_data
-        ],
-        **manifest.extra,
-    }
-
-    try:
-        (session_dir / "manifest.json").write_text(
-            json.dumps(manifest_payload, indent=2) + "\n", encoding="utf-8",
-        )
-        # Render uses the LAST round (the moderator-facing summary).
-        last_round = rounds_data[-1] if rounds_data else []
-        (session_dir / "response.md").write_text(
-            render(last_round) + "\n", encoding="utf-8",
-        )
-        raw_blocks: list[str] = []
-        for round_idx, round_responses in enumerate(rounds_data, start=1):
-            for r in round_responses:
-                raw_blocks.append(
-                    f"=== round {round_idx} · {r.provider}/{r.model} ===\n\n"
-                    f"{r.text}\n",
-                )
-        (session_dir / "raw-text.md").write_text(
-            "\n".join(raw_blocks) + ("\n" if raw_blocks else ""),
-            encoding="utf-8",
-        )
-    except OSError as exc:  # noqa: BLE001 - never block the report
-        print(f"[council:session] write failed: {exc}", file=sys.stderr)
-
-    days = _load_retention_days() if retention_days is None else retention_days
-    prune_old_sessions(base, days)
-    prune_old_artifacts(base, days)
-    # In production (no sessions_dir override), also prune the sibling
-    # council artefact dirs so questions/responses aren't left as dead
-    # weight. Tests that pass an explicit sessions_dir stay isolated
-    # from the wider tree.
-    if sessions_dir is None:
-        prune_old_artifacts(QUESTIONS_DIR, days)
-        prune_old_artifacts(RESPONSES_DIR, days)
-
-    return session_dir