syncade 0.6.2__py3-none-any.whl

syncade/synthesizer/validation.py

@@ -0,0 +1,421 @@
+"""Cross-input provenance validation for synthesizer output.
+
+The synthesizer's prompt can fabricate ``provenance`` entries that
+point at a non-existent ``reviewer_name`` or an out-of-range
+``original_index``. The pydantic schema can't catch this — it has no
+view of the input reviewer set — so this module owns the post-parse
+sanity check.
+
+Failures map to :class:`~syncade.synthesis.SynthesizerOutputError`,
+which the driver re-raises so the orchestrator's exit-code table
+turns it into exit 70 (parse failure). The error message identifies
+the specific consolidated finding + provenance entry so the persisted
+``synthesizer.error.txt`` tells the operator exactly which finding
+misattributed its source.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from syncade.dispatcher import ReviewerRunResult
+from syncade.findings import Severity
+from syncade.synthesis import SynthesizerOutput, SynthesizerOutputError
+
+
+@dataclass(frozen=True)
+class ProvenanceRepair:
+    """One provenance quotation corrected from the reviewer's own text.
+
+    Recorded rather than silent: the operator must be able to see that a synthesizer
+    miscopied a source, both because it is a signal about that model's fidelity and
+    because "we quietly rewrote the model's output" is not something to hide.
+    """
+
+    consolidated_index: int
+    provenance_index: int
+    reviewer_name: str
+    original_index: int
+    synthesizer_text: str
+    reviewer_text: str
+
+
+def _validate_provenance_against_reviewers(
+    output: SynthesizerOutput,
+    reviewer_results: list[ReviewerRunResult],
+) -> list[ProvenanceRepair]:
+    """Cross-input validation: every ``provenance`` entry must point
+    at a real reviewer + a real finding within that reviewer's
+    output.
+
+    Schema-level checks (``min_length=1`` on ``provenance``) prevent
+    zero-provenance findings, but the schema can't see the input
+    reviewer set, so it can't catch the model fabricating a
+    ``reviewer_name`` that doesn't correspond to a real reviewer, an
+    ``original_index`` outside the source reviewer's findings list, or
+    an ``original_severity`` that misreports what the source reviewer
+    actually assigned. All three shapes would render into
+    ``findings.md`` as if they had real attribution — exactly the
+    "cannot invent findings" invariant design set out to enforce. The
+    severity cross-check additionally closes the unanimous-blocker
+    bypass: a synth that records a genuinely-unanimous blocker as
+    ``"minor"`` for one reviewer would defeat the schema's all-blocker
+    dismissal guard (which keys on ``original_severity``); verifying
+    each entry's severity against its source reviewer makes that
+    impossible.
+
+    Args:
+        output: The parsed :class:`SynthesizerOutput`.
+        reviewer_results: The dispatcher's per-reviewer results.
+            Only successful reviewers contribute to the reviewer-name
+            and findings-length lookup tables.
+
+    Raises:
+        SynthesizerOutputError: When any provenance entry references
+            an unknown reviewer name, an out-of-range
+            ``original_index``, OR an ``original_severity`` that does
+            not match the source reviewer's actual finding severity.
+            The message names the specific violation so the persisted
+            ``synthesizer.error.txt`` tells the operator exactly which
+            finding misattributed its source. The error maps to exit
+            70 via the existing ``_compute_exit_code`` decision table.
+
+    ``original_description`` is also cross-checked: a synthesizer that may
+    restate the source can narrow a blocker into something it can then honestly
+    dismiss, and the operator reading ``findings.md`` would see the fabrication
+    quoted as the reviewer's verbatim framing. Provenance whose text the
+    synthesizer may author is not provenance.
+
+    The comparison normalizes runs of whitespace (so reflow and line-wrapping
+    survive) but preserves case and every character otherwise — a summarized,
+    truncated, or reworded quote is a hard exit 70.
+    """
+    # Build lookup: reviewer_name → number of original findings.
+    # Only successful reviewers contribute — failed reviewers have
+    # no findings list to reference, and the orchestrator's
+    # synth-skipped-on-any-reviewer-failure rule means we shouldn't
+    # see provenance pointing at a failed reviewer here anyway.
+    findings_count_by_name: dict[str, int] = {}
+    severities_by_name: dict[str, list[Severity]] = {}
+    texts_by_name: dict[str, list[str]] = {}
+    for r in reviewer_results:
+        if r.output is None:
+            continue
+        findings_count_by_name[r.reviewer_name] = len(r.output.findings)
+        severities_by_name[r.reviewer_name] = [f.severity for f in r.output.findings]
+        texts_by_name[r.reviewer_name] = [f.finding for f in r.output.findings]
+
+    repairs: list[ProvenanceRepair] = []
+    for consolidated_idx, finding in enumerate(output.consolidated_findings):
+        for prov_idx, prov in enumerate(finding.provenance):
+            # Unknown reviewer name → ghost provenance.
+            if prov.reviewer_name not in findings_count_by_name:
+                known = sorted(findings_count_by_name.keys())
+                raise SynthesizerOutputError(
+                    f"synthesizer provenance references unknown reviewer "
+                    f"{prov.reviewer_name!r} (consolidated_findings[{consolidated_idx}]"
+                    f".provenance[{prov_idx}]); known reviewer names from this "
+                    f"run: {known}. The synthesizer may have fabricated a "
+                    f"provenance entry; check synthesizer.stdout for the raw "
+                    f"output."
+                )
+            # Out-of-range original_index → ghost source finding. The
+            # zero-findings case needs a distinct message.
+            max_index = findings_count_by_name[prov.reviewer_name]
+            if max_index == 0:
+                raise SynthesizerOutputError(
+                    f"synthesizer provenance original_index "
+                    f"{prov.original_index} is invalid for reviewer "
+                    f"{prov.reviewer_name!r}: that reviewer produced 0 "
+                    f"findings, so no original_index value is valid. "
+                    f"consolidated_findings[{consolidated_idx}]"
+                    f".provenance[{prov_idx}]. The synthesizer may have "
+                    f"fabricated a provenance entry; check "
+                    f"synthesizer.stdout for the raw output."
+                )
+            if prov.original_index >= max_index:
+                raise SynthesizerOutputError(
+                    f"synthesizer provenance original_index "
+                    f"{prov.original_index} is out of range for reviewer "
+                    f"{prov.reviewer_name!r} (which produced {max_index} "
+                    f"finding(s); valid indices are 0..{max_index - 1}). "
+                    f"consolidated_findings[{consolidated_idx}]"
+                    f".provenance[{prov_idx}]. The synthesizer may have "
+                    f"fabricated a provenance entry; check "
+                    f"synthesizer.stdout for the raw output."
+                )
+            # original_severity must match the SOURCE reviewer's actual
+            # finding severity. The schema accepts any valid Severity
+            # enum value, so a synth could record a TRUTHFUL reviewer +
+            # in-range index but LIE about the severity (claim a
+            # genuinely-blocker finding was "minor") to slip a unanimous
+            # blocker past the schema's all-blocker dismissal guard.
+            # Cross-check it here so that bypass cannot pass.
+            actual_severity = severities_by_name[prov.reviewer_name][prov.original_index]
+            if prov.original_severity != actual_severity:
+                raise SynthesizerOutputError(
+                    f"synthesizer provenance original_severity "
+                    f"{prov.original_severity!r} does not match reviewer "
+                    f"{prov.reviewer_name!r}'s actual severity "
+                    f"{actual_severity!r} for finding {prov.original_index} "
+                    f"(consolidated_findings[{consolidated_idx}]"
+                    f".provenance[{prov_idx}]). The synthesizer may have "
+                    f"misreported a reviewer's severity to evade the "
+                    f"unanimous-blocker rule; check synthesizer.stdout for "
+                    f"the raw output."
+                )
+            # original_description must be the reviewer's OWN words. A
+            # synthesizer that may restate the source can narrow a blocker into
+            # something it can then honestly dismiss, and the operator sees the
+            # fabrication quoted as the reviewer's verbatim framing in
+            # findings.md. Whitespace runs are normalized so reflow survives;
+            # nothing else is.
+            actual_text = texts_by_name[prov.reviewer_name][prov.original_index]
+            if _normalize_whitespace(prov.original_description) != _normalize_whitespace(
+                actual_text
+            ):
+                # REPAIR, not abort (PR-h-field-01 item 5). Everything that could be an
+                # ATTRIBUTION attack has already been verified above: the reviewer exists,
+                # the index is in range, and the severity matches. What is left is a
+                # transcription error in a QUOTATION of a finding — and the ground truth is
+                # right here in `reviewer_results`, which is how we know it is wrong.
+                #
+                # This is strictly STRONGER than the abort it replaces. Before, the rendered
+                # text was verbatim only because the check happened to pass — we trusted the
+                # synthesizer's copy. Now it is verbatim BY CONSTRUCTION, copied from the
+                # source. Nothing a synthesizer writes in this field can reach findings.md.
+                #
+                # It cost a real run to learn: one dropped backtick in a finding about
+                # `style={{ backdropFilter: ... }}` aborted a run at exit 70 after 713
+                # seconds of reviewer wall-clock, discarding six valid findings and three
+                # unrun rounds. The exposure is proportional to reviewer verbosity, and
+                # findings that quote code are exactly the ones full of backticks and braces.
+                repairs.append(
+                    ProvenanceRepair(
+                        consolidated_index=consolidated_idx,
+                        provenance_index=prov_idx,
+                        reviewer_name=prov.reviewer_name,
+                        original_index=prov.original_index,
+                        synthesizer_text=prov.original_description,
+                        reviewer_text=actual_text,
+                    )
+                )
+                prov.original_description = actual_text
+
+    return repairs
+
+
+def _validate_reviewer_blockers_passed_through(
+    output: SynthesizerOutput,
+    reviewer_results: list[ReviewerRunResult],
+) -> None:
+    """Cross-input validation (finding R): every reviewer-surfaced BLOCKER
+    finding must appear in ``consolidated_findings`` — referenced by at least
+    one provenance entry, whether the synth kept it active OR dismissed it with
+    rationale.
+
+    This is the symmetric partner of
+    :func:`_validate_provenance_against_reviewers`. That function enforces
+    *cannot-invent* (every emitted provenance entry traces to a real reviewer
+    finding). This one enforces *cannot-omit* for blockers: anything substantive
+    that ships was either caught by no reviewer or dismissed with rationale. A
+    reviewer blocker must not silently vanish.
+
+    The pydantic schema deliberately allows ``consolidated_findings == []`` (it
+    means "the reviewers found nothing"), but the schema has no view of the input
+    reviewer set, so it cannot tell a legitimate empty set from a synth that
+    DROPPED two reviewers' blockers. With the blockers omitted,
+    ``has_active_blocker`` is False and the mechanical verdict returns exit 0
+    SHIP on a tree two reviewers blocked — a false ship (reproduced). This check
+    closes that hole.
+
+    Scope: BLOCKER findings only. An omitted advisory (minor/nit) finding is an
+    auditability loss but cannot cause a false ship — the mechanical verdict
+    reads only blockers — so enforcing pass-through for blockers is the
+    correctness-critical, false-positive-free subset of pass-through rule. Runs
+    after :func:`_validate_provenance_against_reviewers`, so every referenced
+    ``(reviewer_name, original_index)`` pair is already known-valid.
+
+    Args:
+        output: The parsed :class:`SynthesizerOutput`.
+        reviewer_results: The dispatcher's per-reviewer results. Only successful
+            reviewers contribute (a failed reviewer has no findings, and the
+            orchestrator skips synthesis on any reviewer failure).
+
+    Raises:
+        SynthesizerOutputError: when a reviewer blocker is referenced by no
+            consolidated finding's provenance. The message names the orphaned
+            reviewer finding(s) so the persisted ``synthesizer.error.txt`` points
+            the operator at the dropped blocker. Maps to exit 70.
+    """
+    # Required: every (reviewer_name, index) the reviewers themselves flagged at
+    # blocker — sourced from the reviewers' actual findings, not from what the
+    # synth claimed (the severity cross-check already proved any claim truthful).
+    required_blockers: set[tuple[str, int]] = set()
+    for r in reviewer_results:
+        if r.output is None:
+            continue
+        for i, finding in enumerate(r.output.findings):
+            if finding.severity == "blocker":
+                required_blockers.add((r.reviewer_name, i))
+
+    # Covered: every reviewer finding referenced by SOME consolidated finding
+    # (active or dismissed — a dismissed-with-rationale blocker is still a
+    # legitimate pass-through; the unanimous-blocker guard handles the rest).
+    covered: set[tuple[str, int]] = set()
+    for finding in output.consolidated_findings:
+        for prov in finding.provenance:
+            covered.add((prov.reviewer_name, prov.original_index))
+
+    missing = sorted(required_blockers - covered)
+    if missing:
+        detail = ", ".join(f"{name}#{idx}" for name, idx in missing)
+        raise SynthesizerOutputError(
+            f"synthesizer omitted reviewer-surfaced blocker finding(s) "
+            f"[{detail}] from consolidated_findings. Every reviewer blocker must "
+            f"be passed through (kept active OR dismissed with rationale), never "
+            f"dropped. The mechanical verdict reads only "
+            f"consolidated_findings, so a dropped blocker would falsely SHIP; "
+            f"check synthesizer.stdout for the raw output."
+        )
+
+
+def _normalize_whitespace(text: str) -> str:
+    """Collapse whitespace runs for provenance-quote comparison.
+
+    Deliberately case- and content-PRESERVING, unlike
+    :func:`_normalize_finding_text`: this one asks "did the synthesizer quote
+    the reviewer verbatim", where a case change is a rewrite. Only reflow and
+    line-wrapping are forgiven.
+    """
+    return " ".join(text.split())
+
+
+def _normalize_finding_text(text: str) -> str:
+    """Normalize reviewer finding text for exact duplicate split detection."""
+    return " ".join(text.casefold().split())
+
+
+def _validate_duplicate_blockers_not_split_deactivated(
+    output: SynthesizerOutput,
+    reviewer_results: list[ReviewerRunResult],
+) -> None:
+    """Defense-in-depth split guard for exact duplicate reviewer blockers.
+
+    The schema-level unanimous-blocker rule fires only when the synth merges two
+    reviewers' blocker findings into one consolidated finding. A malicious or
+    confused synth can otherwise split the same concern into separate
+    single-reviewer findings and downgrade/dismiss each one; pass-through is
+    satisfied, but the mechanical verdict sees no active blocker.
+
+    Full semantic concern matching is intentionally out of scope here. This guard
+    takes the narrow mechanically defensible case: two or more DISTINCT reviewers
+    emitted blocker findings with the same source ``file`` and normalized
+    ``finding`` text. That exact duplicate must be represented by at least one
+    ACTIVE consolidated blocker that carries provenance for two or more of those
+    source findings. Anything else is a split/deactivate shape and maps to exit
+    70.
+    """
+    duplicate_blockers: dict[tuple[str | None, str], set[tuple[str, int]]] = {}
+    for r in reviewer_results:
+        if r.output is None:
+            continue
+        for i, finding in enumerate(r.output.findings):
+            if finding.severity != "blocker":
+                continue
+            key = (finding.file, _normalize_finding_text(finding.finding))
+            duplicate_blockers.setdefault(key, set()).add((r.reviewer_name, i))
+
+    for (file, text), required_sources in duplicate_blockers.items():
+        distinct_reviewers = {name for name, _ in required_sources}
+        if len(distinct_reviewers) < 2:
+            continue
+
+        has_merged_active_blocker = False
+        for finding in output.consolidated_findings:
+            covered_here = {
+                (prov.reviewer_name, prov.original_index)
+                for prov in finding.provenance
+                if (prov.reviewer_name, prov.original_index) in required_sources
+            }
+            if (
+                len({name for name, _ in covered_here}) >= 2
+                and finding.severity == "blocker"
+                and not finding.dismissed
+            ):
+                has_merged_active_blocker = True
+                break
+
+        if not has_merged_active_blocker:
+            detail = ", ".join(f"{name}#{idx}" for name, idx in sorted(required_sources))
+            location = f"file={file!r}, " if file is not None else ""
+            raise SynthesizerOutputError(
+                f"synthesizer split/deactivated duplicate reviewer blocker "
+                f"({location}finding={text!r}) across [{detail}]. Exact duplicate "
+                f"blocker findings from two or more distinct reviewers must be "
+                f"merged into an active blocker, not split into single-reviewer "
+                f"downgrades/dismissals; check synthesizer.stdout for the raw output."
+            )
+
+
+def _validate_cluster_quotes_against_reviewers(
+    output: SynthesizerOutput,
+    reviewer_results: list[ReviewerRunResult],
+) -> None:
+    """Cross-input validation: every root-cause cluster's evidence
+    ``quote`` must be a VERBATIM substring of its member finding's
+    reviewer-original text.
+
+    Mirrors :func:`_validate_provenance_against_reviewers`' ``reviewer_results``
+    plumbing but deliberately sets a HIGHER bar. That function intentionally
+    does NOT substring-validate ``original_description`` — paraphrase is
+    legitimate there ("how each reviewer framed the same concern"). Cluster
+    quotes go the other way ON PURPOSE: verbatim grounding is exactly what makes
+    a cluster zero-invention (the synth groups + quotes; it authors no cause or
+    fix). Do not loosen this to match provenance's looser check.
+
+    For each cluster member, the quote must be a verbatim substring of at least
+    one of that member's source reviewer findings' ``finding`` text (located via
+    the member's ``provenance``). Runs after
+    :func:`_validate_provenance_against_reviewers` (so each provenance entry is
+    known-valid) and after
+    schema validation (so the cluster's member indices are in range and match
+    its evidence set).
+
+    Args:
+        output: The parsed :class:`SynthesizerOutput`.
+        reviewer_results: The dispatcher's per-reviewer results (same plumbing
+            as the provenance check). Only successful reviewers contribute.
+
+    Raises:
+        SynthesizerOutputError: when a quote is not a verbatim substring of any
+            of its member's reviewer-original finding texts. The message names
+            the cluster + finding so the persisted ``synthesizer.error.txt``
+            points the operator at the offending quote. Maps to exit 70.
+    """
+    # reviewer_name → list of original finding texts (the verbatim source).
+    findings_text_by_name: dict[str, list[str]] = {}
+    for r in reviewer_results:
+        if r.output is None:
+            continue
+        findings_text_by_name[r.reviewer_name] = [f.finding for f in r.output.findings]
+
+    for cluster_idx, cluster in enumerate(output.root_cause_clusters):
+        for ev in cluster.evidence:
+            member = output.consolidated_findings[ev.finding_index]
+            # Gather the reviewer-original texts this member traces to.
+            sources: list[str] = []
+            for prov in member.provenance:
+                texts = findings_text_by_name.get(prov.reviewer_name, [])
+                if 0 <= prov.original_index < len(texts):
+                    sources.append(texts[prov.original_index])
+            if not any(ev.quote in src for src in sources):
+                raise SynthesizerOutputError(
+                    f"root_cause_clusters[{cluster_idx}] evidence quote for "
+                    f"consolidated finding {ev.finding_index} is not a verbatim "
+                    f"substring of any of that finding's reviewer-original texts "
+                    f"(quote={ev.quote!r}). A cluster quote must be grounded in "
+                    f"the reviewers' own words (zero-invention); the synthesizer "
+                    f"may have paraphrased or fabricated it. Check "
+                    f"synthesizer.stdout for the raw output."
+                )

syncade/synthesizer/workspace.py

@@ -0,0 +1,208 @@
+"""Cold-synth workspace setup helpers.
+
+The load-bearing cold-synth invariant is that the subprocess cannot *read* the
+repo root: the workspace lives in a fresh tempdir, cwd/-C/--add-dir are scoped to
+it, and ``permissions=trusted-execute`` keeps the codex sandbox scoped there too
+(see :mod:`syncade.synthesizer.driver`). That holds independently of the env.
+
+The env scrub is defense-in-depth on top: it removes repo-root path references so
+the subprocess cannot even *discover* where the repo lives — with ONE deliberate
+exception, :data:`_AUTH_LOCATOR_KEYS` (``CODEX_HOME``). A credential-locator var
+must survive the scrub or the login the auth gate probed is not the login that
+runs (verified != runtime; see :mod:`syncade.auth_preflight`). So a *repo-local*
+``CODEX_HOME`` — an unusual config where the user parked codex's login dir inside
+the repo under review — does pass its path (which references repo_root) through to
+the cold subprocess. That weakens *discovery* only: the sandbox above still
+prevents the synth from reading anything under it, so blindness is intact. The
+alternative — stripping it — silently swaps the user's codex credential for
+whatever ``~/.codex`` holds, which is the worse failure.
+
+- :data:`_PATH_LIST_ENV_KEYS` — env keys whose values are path lists. Filtered
+  per segment so absolute repo-local entries get removed without dropping
+  unrelated sibling paths.
+- :func:`_path_is_relative_to` / :func:`_value_references_repo_path`
+  — boundary-aware path-match helpers used by :func:`_scrub_env_for_cold_synth`.
+  Both RESOLVE the candidate path before testing containment, so a symlink alias
+  of the repo root (macOS ``/tmp`` -> ``/private/tmp``) cannot slip through.
+- :func:`_scrub_env_for_cold_synth` — drops ``PWD`` / ``OLDPWD``,
+  filters path-list vars, and drops scalar vars whose value references
+  the repo root, EXCEPT the :data:`_AUTH_LOCATOR_KEYS` credential locators
+  (see the module note above on why they survive).
+- :func:`_init_workspace_git` — runs ``git init -q`` in the workspace
+  so codex's ``permissions=trusted-execute`` mode launches.
+
+The two underscore-prefixed names (``_scrub_env_for_cold_synth``,
+``_init_workspace_git``) are imported by tests and by :mod:`syncade.spec_audit`.
+The package ``__init__.py`` re-exports them so existing imports keep working.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+from syncade.process import SubprocessError, run_subprocess
+
+_AUTH_LOCATOR_KEYS = frozenset({"CODEX_HOME"})
+"""Vars that tell a provider CLI WHERE its stored credential lives. Kept through the cold
+scrub even when repo-local: stripping them re-auths the subprocess, so the mode the auth
+gate probed (parent env) would differ from the mode that runs (scrubbed env). CODEX_HOME is
+the codex login dir. Anthropic auth is a key VALUE (ANTHROPIC_API_KEY) or the OS keychain,
+not an env-var path, so it needs no entry here."""
+
+_PATH_LIST_ENV_KEYS = frozenset(
+    {
+        "PATH",
+        "PYTHONPATH",
+        "NODE_PATH",
+        "CDPATH",
+        "MANPATH",
+        "INFOPATH",
+        "LD_LIBRARY_PATH",
+        "DYLD_LIBRARY_PATH",
+        "PKG_CONFIG_PATH",
+    }
+)
+
+
+def _path_is_relative_to(path: Path, parent: Path) -> bool:
+    """Return whether ``path`` is within ``parent`` after resolution."""
+    try:
+        path.resolve(strict=False).relative_to(parent.resolve(strict=False))
+    except (OSError, RuntimeError, ValueError):
+        return False
+    return True
+
+
+_VALUE_TOKEN_SPLIT = re.compile(r"[\s'\"=" + re.escape(os.pathsep) + r"]+")
+
+
+def _value_references_repo_path(value: str, resolved_repo_root: Path) -> bool:
+    """Detect repo-root path references without sibling-prefix false positives.
+
+    Splits ``value`` into path-like tokens and RESOLVES each one before testing
+    containment, rather than string-matching spellings of the repo root.
+
+    Resolving the value, not the root, is the only way to catch symlink aliases:
+    on macOS ``/tmp`` is a symlink to ``/private/tmp``, so a parent process's
+    ``VIRTUAL_ENV=/tmp/<repo>/.venv`` refers to a repo root the orchestrator
+    knows as ``/private/tmp/<repo>``. Matching root spellings cannot see that —
+    you would have to enumerate every aliased spelling of the root, which is
+    unbounded. Resolving the token collapses both spellings to the same real
+    path and the containment test just works, in either direction.
+
+    This is also how the path-list branch of :func:`_scrub_env_for_cold_synth`
+    has always worked (via :func:`_path_is_relative_to`); the scalar branch was
+    the one doing string comparison, and it was the one that leaked.
+
+    Boundary correctness comes free: ``relative_to`` on resolved paths cannot
+    produce a sibling-prefix false positive the way a substring scan can
+    (``/private/tmp/repo-sibling`` is not within ``/private/tmp/repo``).
+    """
+    for token in _VALUE_TOKEN_SPLIT.split(value):
+        if not token:
+            continue
+        candidate = Path(token).expanduser()
+        if candidate.is_absolute() and _path_is_relative_to(candidate, resolved_repo_root):
+            return True
+    return False
+
+
+def _scrub_env_for_cold_synth(env: dict[str, str], repo_root: Path) -> dict[str, str]:
+    """Strip environment variables that would leak ``repo_root`` to
+    the synth subprocess.
+
+    Workspace-scoped cwd/``-C``/``--add-dir`` are one half of that; this is the
+    other. The parent process's env typically carries:
+
+    - ``PWD`` and ``OLDPWD`` from the shell — both contain the cwd
+      at invocation time, which is normally inside the repo
+      (``syncade`` is invoked from the repo or one of its
+      subdirs). Dropped unconditionally.
+    - Path-list vars like ``PATH`` and ``PYTHONPATH`` — split by
+      :data:`os.pathsep`; only absolute segments contained by ``repo_root`` are
+      removed. Sibling paths such as
+      ``/tmp/syncade-dev/bin`` and relative child-workspace segments
+      are preserved.
+    - Other vars like ``VIRTUAL_ENV`` or tool cache settings that may
+      reference a repo-local path. Dropped when their value contains
+      ``repo_root`` as a path-boundary-delimited reference, not as an
+      arbitrary substring.
+
+    What stays: non-repo ``PATH`` segments (codex needs them to find
+    its own binaries and any tools it shells out to), ``HOME`` (codex
+    auth state lives under ``~/.codex/``), and everything else that
+    doesn't reference the repo.
+
+    Args:
+        env: The parent invocation env.
+        repo_root: The git repo root whose path string should not
+            leak into the synth subprocess's environment.
+
+    Returns:
+        A new dict whose values do not expose paths inside
+        ``repo_root``.
+    """
+    resolved_repo_root = repo_root.resolve(strict=False)
+    scrubbed: dict[str, str] = {}
+    for key, value in env.items():
+        if key in {"PWD", "OLDPWD"}:
+            continue
+        if key in _AUTH_LOCATOR_KEYS:
+            # An auth-credential LOCATOR, kept even when it points inside the repo.
+            # Stripping CODEX_HOME because a user set it to a repo-local path silently
+            # changes which credential codex uses for the cold actor — so the mode the
+            # auth gate PROBED (with the parent env) is no longer the mode that RUNS. The
+            # guardrail's whole promise is "verified == runtime"; a scrub that re-auths the
+            # subprocess breaks it. CODEX_HOME is codex's own config dir, not the source
+            # under review, so preserving it does not weaken cold isolation (which is
+            # enforced by cwd / -C / --add-dir scope, not by hiding this path).
+            scrubbed[key] = value
+            continue
+        if key in _PATH_LIST_ENV_KEYS:
+            kept_segments = [
+                segment
+                for segment in value.split(os.pathsep)
+                if not segment
+                or not Path(segment).expanduser().is_absolute()
+                or not _path_is_relative_to(Path(segment).expanduser(), resolved_repo_root)
+            ]
+            if kept_segments:
+                scrubbed[key] = os.pathsep.join(kept_segments)
+            continue
+        if _value_references_repo_path(value, resolved_repo_root):
+            continue
+        scrubbed[key] = value
+    return scrubbed
+
+
+def _init_workspace_git(workspace: Path) -> None:
+    """Initialize ``workspace`` as an empty git working tree.
+
+    Codex with ``permissions=trusted-execute`` refuses to launch unless cwd is a
+    git working tree, failing with ``Not inside a trusted directory and
+    --skip-git-repo-check was not specified``.
+    The synth workspace is a fresh tempdir; this helper runs
+    ``git init -q`` in it before launching codex.
+
+    Failures surface as :class:`~syncade.process.SubprocessError`-bucket
+    exceptions that the caller maps to a SynthesizerResult failure.
+
+    No commits are made — the workspace stays as a fresh repo
+    with one untracked file (the copied PR doc). Codex's trusted-
+    mode check is satisfied by the ``.git/`` directory's presence.
+    """
+    git_init = run_subprocess(
+        ["git", "init", "-q"],
+        cwd=workspace,
+        env=None,
+        timeout=10.0,
+        input_text=None,
+    )
+    if git_init.returncode != 0:
+        raise SubprocessError(
+            f"synthesizer: failed to git-init the cold workspace at "
+            f"{workspace}: git init exited with code "
+            f"{git_init.returncode}; stderr: {git_init.stderr[:200]!r}"
+        )

syncade/templates/presets/balanced.toml

@@ -0,0 +1,13 @@
+# Preset: balanced (PR-v2-9) — the proven, shipped defaults.
+#
+# Behaviourally identical to a zero-config run: `--preset balanced` changes nothing on its own.
+# It exists as the honest starting point — copy it, then deviate ONE knob at a time. The values
+# below are pinned to the shipped defaults by a drift test (test_presets.py), so this file can
+# never quietly diverge from what a plain `syncade <pr-doc>` does.
+#
+# Presets vary ONLY loop dimensions (rounds / timeout). They NEVER touch the reviewer model or
+# effort tier — a cheaper panel that audits leniently is the pr-29 hazard, and a preset must not
+# reintroduce it. Set `[[reviewers]]` yourself in .syncade/config.toml if you truly want that.
+[loop]
+max_rounds = 5          # full loop: reviewers -> synthesizer -> optional test -> producer-if-NO-SHIP
+timeout_seconds = 1800  # 30 min per subprocess (the default)

syncade/templates/presets/cheap.toml

@@ -0,0 +1,12 @@
+# Preset: cheap (PR-v2-9) — a fast, low-cost single-pass check.
+#
+# Trades ROUNDS for cost: one round of reviewers -> synthesizer, with NO producer loop. That is the
+# structurally cheapest honest config — a single review pass at the SAME proven reviewer model and
+# effort tier. It deliberately does NOT lower the effort tier or swap in a cheaper model (the pr-29
+# leniency hazard), and it sets no ADDITIONAL token/dollar budget beyond the default ceiling
+# (budget_tokens = 50,000,000 from the global default; set budget_tokens = 0 in your
+# .syncade/config.toml to disable it).
+#
+# Layer your own knobs on top in .syncade/config.toml — the user file always wins over the preset.
+[loop]
+max_rounds = 1  # single pass: no producer subprocess, no second round

syncade/templates/presets/thorough.toml

@@ -0,0 +1,9 @@
+# Preset: thorough (PR-v2-9) — full rounds plus extra per-subprocess wall-clock for large diffs.
+#
+# Trades TIME for depth: the full producer loop (max_rounds = 5, the default) and double
+# the per-subprocess timeout, so a heavy reviewer working a large diff is not SIGKILLed mid-review. It
+# holds the reviewer model + effort tier at the SAME proven level as balanced — "thorough" buys more
+# rounds and more time, never a different (or more expensive) panel.
+[loop]
+max_rounds = 5          # the full producer loop (5 is the default; ceiling is 10)
+timeout_seconds = 3600  # 60 min per subprocess — double the default, for big diffs