syncade 0.6.2__py3-none-any.whl

syncade/orchestrator/loop_dispatch_check.py

@@ -0,0 +1,112 @@
+"""Pre-dispatch classifier for the review loop.
+
+Split out of :mod:`syncade.orchestrator.loop` to keep that module under the LOC cap;
+re-exported from there so existing imports remain stable.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from syncade.config import SyncadeConfig
+from syncade.diff_filter import (
+    concealed_destinations,
+    elide_binary_hunks,
+    filter_diff_for_reviewer,
+    unidentifiable_sections,
+)
+
+if TYPE_CHECKING:
+    from syncade.snapshot import Snapshot
+
+
+def _diff_will_dispatch(
+    snapshot: Snapshot,
+    config: SyncadeConfig,
+    repo_root: Path | None = None,
+    pr_doc_path: Path | None = None,
+) -> bool:
+    """Return False when the round will terminate before dispatching any subprocess.
+
+    A False result means no reviewer, judge, or producer will run, so commit-safety
+    guards (dirty-tree refusal, default-branch guard) are irrelevant for this run.
+    Four cases: diff is malformed (diff_malformed, exit 60), reviewer-facing diff
+    exceeds the size ceiling (diff_too_large, exit 60), diff is known-empty
+    (no_changes_to_review, exit 0), or an assembled reviewer prompt exceeds the provider
+    character ceiling (prompt_too_large, exit 60). All are pre-dispatch terminal decisions
+    in _run_one_round; classifying here avoids the dirty/default-branch guards firing
+    before the prompt-size refusal for runs that will never dispatch any reviewer.
+
+    The prompt_too_large check renders the full round-0 prompt and requires repo_root to load
+    the reviewer templates. When repo_root is None the check is skipped and the exact check
+    inside _run_one_round catches it instead (though only after commit-safety guards have
+    already run). pr_doc_path is the resolved PR doc path; when provided it is converted to
+    the worktree-local reference the real reviewer sees (relative path inside the repo, or a
+    collision-free .syncade-inputs/ path for out-of-repo docs). When omitted the placeholder
+    "<pr-doc>" is used, which can undercount prompt size if the template repeats {pr_doc_path}.
+    """
+    # Only refuse on unidentifiable headers when there are strip targets: with an empty
+    # strip list filter_diff_for_reviewer keeps every section byte-for-byte, so an
+    # undecodable header is not a security concern (nothing is being hidden).
+    if config.review.strip_repo_context_files and unidentifiable_sections(snapshot.diff_text):
+        return False  # diff_malformed path — refuses at exit 60, no producer runs
+    filtered = filter_diff_for_reviewer(snapshot.diff_text, config.review.strip_repo_context_files)
+    filtered_elided, _ = elide_binary_hunks(filtered)
+    if len(filtered_elided.encode("utf-8")) > config.loop.max_diff_bytes:
+        return False  # diff_too_large path — refuses at exit 60, no producer runs
+    if (
+        snapshot.base_oid is not None
+        and not filtered_elided
+        # A boundary rename empties the filtered diff while concealing a reviewable
+        # destination; that run DOES dispatch, so the commit guards still apply.
+        and not concealed_destinations(snapshot.diff_text, config.review.strip_repo_context_files)
+    ):
+        return False  # no_changes_to_review path — exits 0, no producer runs
+    # Exact assembled-prompt check: render the full round-0 prompt and measure it directly.
+    # The former template+diff estimate omitted the JSON schema (~517 chars), adversarial-lens
+    # block (~3,316 chars), and prior-round sentinel — a lower bound that let the real rendered
+    # prompt exceed the provider ceiling (1,048,576 chars) while this predicate returned True,
+    # causing commit-safety guards to fire first (dirty-tree or default-branch refusal) instead
+    # of the intended prompt_too_large refusal. Fails open on template-load or render errors —
+    # the exact check in _run_one_round catches them (though only after commit-safety guards run).
+    if repo_root is not None:
+        from syncade.findings import get_findings_schema_string
+        from syncade.orchestrator.round import _NO_DIFF_SENTINEL
+        from syncade.orchestrator.round_no_changes import _CODEX_CHAR_CEILING
+        from syncade.prompts import load_reviewer_template_for, render_reviewer_prompt
+
+        # Compute the worktree-local PR doc reference the same way _build_reviewer_prompt
+        # does. Using the real path matters when the template repeats {pr_doc_path} — with
+        # the placeholder "<pr-doc>" (8 chars) the rendered size is always lower than the
+        # real prompt, so the guard can false-green for a prompt that later refuses.
+        if pr_doc_path is not None:
+            try:
+                _pr_doc_ref = str(pr_doc_path.relative_to(repo_root))
+            except ValueError:
+                _digest = hashlib.sha256(str(pr_doc_path).encode("utf-8")).hexdigest()[:16]
+                _pr_doc_ref = f".syncade-inputs/pr-doc-{_digest}-{pr_doc_path.name}"
+        else:
+            _pr_doc_ref = "<pr-doc>"
+        _diff_text = filtered_elided if filtered_elided else _NO_DIFF_SENTINEL
+        _json_schema = get_findings_schema_string()
+        for reviewer in config.reviewers:
+            try:
+                template = load_reviewer_template_for(
+                    repo_root, provider=reviewer.provider, template=reviewer.template
+                )
+                rendered = render_reviewer_prompt(
+                    template,
+                    pr_doc_path=_pr_doc_ref,
+                    diff=_diff_text,
+                    master_plan_path=None,
+                    json_schema=_json_schema,
+                    adversarial_lens=reviewer.adversarial_lens,
+                    bug_class_sweep=reviewer.bug_class_sweep,
+                )
+            except Exception:  # noqa: BLE001 — fail open; exact check runs inside round
+                continue
+            if len(rendered) > _CODEX_CHAR_CEILING:
+                return False  # prompt_too_large path — refuses at exit 60, no producer runs
+    return True

syncade/orchestrator/loop_finalize.py

@@ -0,0 +1,404 @@
+"""Loop finalization.
+
+``_finalize_run`` is the post-loop tail of ``run_review``: it writes the
+loop-level artifacts (loop-summary.md / loop-manifest.json / handoff.md),
+records the per-branch last-reviewed SHA, emits the working-tree-not-synced
+note, performs the terminal worktree cleanup-vs-preserve decision, builds the
+aggregate :class:`RunResult`, and returns it.
+
+``completed_at`` is computed by the caller and passed in.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from syncade import run_status as _run_status
+from syncade.exit_codes import (
+    CLARIFICATION_NEEDED,
+    FINDINGS_PRESENT,
+    MAX_ROUNDS_REACHED,
+    SUCCESS,
+)
+from syncade.git_object_id import is_full_git_object_id
+from syncade.persistence import (
+    ProducerArtifactPaths,
+    persist_handoff,
+    persist_loop_manifest,
+    persist_loop_summary,
+)
+
+from .results import RunArtifacts, RunResult
+
+
+def _warn_branch_advanced(*, branch: str, repo_root, logger) -> None:
+    """Emit the working-tree-not-synced warning after a branch advance.
+
+    Shared by the normal finalize tail and the early ``test_worktree_error``
+    re-raise path so the operator hears the identical message on both (N3).
+
+    Uses ``logger.safety``, not ``logger.warning``: under ``--quiet`` this was suppressed
+    entirely (PR-h-13), and it is the ONLY thing standing between an operator and a
+    ``git commit`` that silently reverts the producer's work — the tree still holds the
+    pre-advance content, so `git status` shows a fully staged revert.
+    """
+    logger.safety(
+        f"orchestrator: branch refs/heads/{branch} "
+        f"has been advanced to the latest producer commit, "
+        f"but your working tree at {repo_root} is NOT "
+        f"automatically synced. To pick up the producer's fix in your "
+        f"working tree: `git reset --hard HEAD` (discards "
+        f"any local edits) or `git stash && git reset "
+        f"--hard HEAD && git stash pop` (preserves them). "
+        f"See loop-summary.md for the commit series and "
+        f"per-round artifacts."
+    )
+
+
+def _cleanup_prior_round_managers(managers, *, current_round_dir) -> None:
+    """Best-effort ``cleanup_all`` of every manager whose worktrees are NOT
+    under ``current_round_dir`` (N4).
+
+    The current round's worktrees are deliberately preserved for diagnostics
+    on the ``test_worktree_error`` early-raise path; only the now-superseded
+    prior-round reviewer/producer worktrees are reclaimed.
+    """
+    for manager in managers:
+        run_dir = manager.run_dir
+        if run_dir == current_round_dir or current_round_dir in run_dir.parents:
+            continue
+        try:
+            manager.cleanup_all()
+        except Exception:
+            # Best-effort: one manager's failure must not block the others
+            # or the re-raise of the captured WorktreeError.
+            pass
+
+
+def _finalize_run(
+    *,
+    run_dir,
+    run_id,
+    repo_root,
+    snapshot,
+    config,
+    pr_doc_path,
+    round_results,
+    round_artifacts_list,
+    final_exit_code,
+    termination_reason,
+    started_at,
+    completed_at,
+    branch_advanced_during_run,
+    managers_to_cleanup,
+    effective_worktree_base,
+    logger,
+    run_usages=None,
+    budget_ceiling=None,
+) -> RunResult:
+    """Write loop-level artifacts, build the aggregate :class:`RunResult`,
+    handle last-reviewed recording + worktree cleanup, and return the result.
+
+    ``completed_at`` is supplied by the caller (``run_review``) so the patched
+    ``datetime.now`` lookup stays in the rebound caller body.
+    """
+    # --- Loop terminated --------------------------------------------
+    final_round_idx = len(round_results) - 1
+    last_round = round_results[-1]
+
+    # write the loop-level artifacts (top-level
+    # loop-summary.md + loop-manifest.json). Always written —
+    # operators inspecting a multi-round run want the aggregate
+    # view, and even single-pass runs benefit from a top-level
+    # summary that doesn't require traversing into round-0/.
+    #
+    # ``termination_reason`` is always set by here — every break
+    # path above assigns it. Defensive default just in case a
+    # future code path forgets to.
+    safe_termination_reason: str = termination_reason or "unknown"
+    try:
+        loop_summary_path = persist_loop_summary(
+            run_dir,
+            final_exit_code=final_exit_code,
+            final_round=final_round_idx,
+            termination_reason=safe_termination_reason,
+            rounds=round_results,
+            max_rounds=config.loop.max_rounds,
+            started_at=started_at,
+            completed_at=completed_at,
+            # pass repo_root so the loop-summary
+            # commit series can look up producer commit subjects via
+            # ``git log -1 --pretty=format:%s <ending_sha>``.
+            repo_root=repo_root,
+            # PR-v2-11: the configured ceiling(s), so the Budget section on a
+            # budget_exceeded run can name them alongside the tally.
+            budget_tokens=config.loop.budget_tokens,
+            budget_usd=config.loop.budget_usd,
+            # The ENFORCEMENT tally itself — fresh on --resume, so the reported Budget number
+            # is exactly what tripped, not original+resume re-summed from rehydrated rounds.
+            budget_usages=run_usages,
+            # Which ceiling crossed, so the Budget section names it (both set → first-to-trip).
+            budget_ceiling=budget_ceiling,
+        )
+        persist_loop_manifest(
+            run_dir,
+            final_exit_code=final_exit_code,
+            final_round=final_round_idx,
+            termination_reason=safe_termination_reason,
+            rounds=round_results,
+            max_rounds=config.loop.max_rounds,
+            started_at=started_at,
+            producer_provider=config.producer.provider,
+            producer_model=config.producer.model,
+        )
+        # structured operator handoff on exit 20 / exit 30
+        # paths. persist_handoff gates internally on exit code +
+        # active-blocker count so the call is safe to make
+        # unconditionally; returns None when the gate skips.
+        persist_handoff(
+            run_dir,
+            final_exit_code=final_exit_code,
+            final_round=final_round_idx,
+            termination_reason=safe_termination_reason,
+            rounds=round_results,
+            max_rounds=config.loop.max_rounds,
+            pr_doc_path=pr_doc_path,
+            repo_root=repo_root,
+        )
+    except Exception:
+        # Loop-level persistence failures shouldn't mask the
+        # actual exit code — the per-round artifacts are already
+        # on disk. Log via the existing channel and continue.
+        loop_summary_path = None
+        logger.warning(
+            "orchestrator: loop-level persistence failed (per-round "
+            "artifacts are still on disk; the top-level "
+            "loop-summary.md / loop-manifest.json / handoff.md may be "
+            "missing or partial)"
+        )
+
+    # Build the aggregate RunArtifacts pointing flat fields at the
+    # LAST round (back-compat with single-pass RunArtifacts shape).
+    # producer_paths is the brief-documented flat list
+    # parallel to rounds[] — one entry per round, None when the
+    # round didn't run a producer (SHIP rounds + the final round
+    # under max_rounds_reached).
+    producer_paths_list: list[ProducerArtifactPaths | None] = [
+        r.producer_paths for r in round_artifacts_list
+    ]
+    # the run-root findings.md (if it was written) lives
+    # at <run_dir>/findings.md regardless of round count.
+    run_root_findings = run_dir / "findings.md"
+    run_root_findings_path: Path | None = run_root_findings if run_root_findings.is_file() else None
+    artifacts = RunArtifacts(
+        run_dir=run_dir,
+        round_dir=last_round.artifacts.round_dir,
+        manifest_path=last_round.artifacts.manifest_path,
+        summary_path=last_round.artifacts.summary_path,
+        findings_md_path=last_round.artifacts.findings_md_path,
+        synthesizer_paths=last_round.artifacts.synthesizer_paths,
+        test_run_paths=last_round.artifacts.test_run_paths,
+        rounds=round_artifacts_list,
+        loop_summary_path=loop_summary_path,
+        producer_paths=producer_paths_list,
+        run_root_findings_md_path=run_root_findings_path,
+    )
+
+    result = RunResult(
+        artifacts=artifacts,
+        snapshot=last_round.snapshot,
+        dispatch_result=last_round.dispatch_result,
+        exit_code=final_exit_code,
+        synth_result=last_round.synth_result,
+        test_result=last_round.test_result,
+        test_skip_reason=last_round.test_skip_reason,
+        test_worktree_error=last_round.test_worktree_error,
+        rounds=round_results,
+        final_round=final_round_idx,
+        termination_reason=termination_reason,
+        # Same values persist_loop_summary renders, so the terminal notice and the artifact
+        # cannot disagree about what was spent (PR-h-field-06).
+        budget_usages=list(run_usages or []),
+        budget_ceiling=budget_ceiling,
+        budget_tokens=config.loop.budget_tokens,
+        budget_usd=config.loop.budget_usd,
+    )
+
+    # When the final round had a test-leg worktree provisioning failure, that
+    # WorktreeError must be re-raised so the CLI maps to exit 60. The per-round
+    # persistence already wrote everything; this is just the bubble-up.
+    if last_round.test_worktree_error is not None:
+        # The branch-advance warning and the prior-round cleanup both live
+        # BELOW this raise, so replay the parts that still apply here:
+        # N3 — an earlier round's producer may have advanced the branch; the
+        # operator must hear that even on this exit-60 path.
+        if snapshot.branch is not None and branch_advanced_during_run:
+            _warn_branch_advanced(branch=snapshot.branch, repo_root=repo_root, logger=logger)
+        # N4 — the terminal cleanup below would otherwise reclaim every prior
+        # round's reviewer/producer worktrees. Do that here, preserving only
+        # the current (failed) round's worktrees for diagnostics.
+        _cleanup_prior_round_managers(
+            managers_to_cleanup,
+            current_round_dir=effective_worktree_base / run_id / f"round-{final_round_idx}",
+        )
+        logger.summary(result)
+        # Finalize with the mechanical reason before re-raising so the CLI's
+        # typed WorktreeError handler sees _active=None and is a no-op.
+        # Without this, status.json would be overwritten as
+        # exception:WorktreeError even though loop-manifest already recorded
+        # the mechanical termination_reason (worktree_error).
+        _run_status.finalize_active(safe_termination_reason, final_exit_code)
+        raise last_round.test_worktree_error
+
+    # --- record the per-branch last-reviewed SHA --------------
+    # On a COMPLETED verdict where reviewers actually ran (exits 0/20/30, but NOT
+    # no_changes_to_review or producer_emptied_diff which are exit-0 with zero reviewers
+    # dispatched), record the SHA a reviewer saw so `--scope since-last-review` bounds its
+    # diff to new work. Skipped on phase failures (40/50/60/70), decision_needed (10,
+    # resume-pending), detached HEAD (no branch), and empty-diff terminals where no
+    # reviewer actually ran (recording an unreviewed anchor would silently skip real work
+    # on the next since-last-review diff).
+    _skip_reasons = ("no_changes_to_review", "producer_emptied_diff")
+    if (
+        snapshot.branch is not None
+        and final_exit_code in (SUCCESS, MAX_ROUNDS_REACHED, FINDINGS_PRESENT)
+        and termination_reason not in _skip_reasons
+    ):
+        # Record the SHA a reviewer ACTUALLY saw, not a re-read of the branch (R6).
+        # `last_round.snapshot` is the final round's — NOT the `snapshot` parameter, which
+        # is round 0's and differs on any multi-round run.
+        #
+        # Re-reading `refs/heads/<branch>` returned whatever the ref pointed at when the
+        # run ended, which is the reviewed SHA only because the TERMINAL round never runs a
+        # producer (loop_round_step.py special-cases `round_idx == max_rounds - 1`). When
+        # the ref moved anyway — a `producer_stalled` run whose fast-forward was refused, or
+        # an external commit landing mid-run — it recorded a SHA nobody reviewed, and
+        # `--scope since-last-review` then SKIPS that unreviewed work. Reading the value
+        # already in hand cannot drift.
+        _reviewed_sha = last_round.snapshot.commit_sha
+        if is_full_git_object_id(_reviewed_sha):
+            from syncade.persistence import persist_last_reviewed as _persist_last_reviewed
+
+            try:
+                _persist_last_reviewed(
+                    repo_root,
+                    branch=snapshot.branch,
+                    sha=_reviewed_sha,
+                    run_id=run_id,
+                    recorded_at_utc=completed_at.isoformat(),
+                )
+            except OSError as exc:
+                # Narrowed from `except Exception: pass` (audit rank 17). Only a real I/O
+                # failure is tolerable here — losing last-reviewed costs a wider next diff,
+                # never a wrong verdict, so it must not abort a completed run. Anything
+                # else (a bug in the writer, a bad SHA) is a defect and must surface.
+                #
+                # Printed directly to stderr, NOT via logger.warning, which is suppressed
+                # in --quiet mode. A persistence failure must be visible regardless of
+                # verbosity — the operator needs to know the anchor was not updated.
+                print(
+                    f"[syncade] warning: could not record last-reviewed SHA for "
+                    f"{snapshot.branch}: {exc}",
+                    file=sys.stderr,
+                    flush=True,
+                )
+
+    # --- Do NOT touch the operator's working tree -----
+    # The design is explicit ("Notes for the implementing agent"):
+    #
+    #   > do not use `git checkout` in the user's working tree
+    #   > (don't touch their checkout). The worktree's shared
+    #   > `.git` is the contract surface.
+    #
+    # Branch advance moves the ref; the operator syncs their working tree
+    # themselves using the documented command in the loop summary.
+    #
+    # The remaining UX gap (operator runs ``cat foo.py`` post-loop
+    # and sees old content) is addressed via documentation:
+    # loop-summary.md's "Next steps" block names the sync command
+    # explicitly on every SHIP termination. Operators handle the
+    # checkout themselves — same contract as a remote ``git push``
+    # to their branch from elsewhere.
+    if snapshot.branch is not None and branch_advanced_during_run:
+        _warn_branch_advanced(branch=snapshot.branch, repo_root=repo_root, logger=logger)
+
+    # terminal cleanup decision. Per the PRD,
+    # exits 10/20/30 keep worktrees for inspection; exit 0 +
+    # environmental failures (40/50/60/70) clean up. Each
+    # WorktreeManager was constructed with defer_cleanup=True so
+    # the per-round + per-producer ``with`` blocks didn't
+    # auto-clean; the orchestrator now decides based on
+    # final_exit_code.
+    preserve_worktrees = final_exit_code in (
+        CLARIFICATION_NEEDED,
+        MAX_ROUNDS_REACHED,
+        FINDINGS_PRESENT,
+    )
+    if not preserve_worktrees:
+        for manager in managers_to_cleanup:
+            try:
+                manager.cleanup_all()
+            except Exception:
+                # Best-effort: a cleanup failure on one manager
+                # doesn't block the others or block the final
+                # ``rmdir(<base>/<run_id>/)``. Surface via a
+                # generic warning rather than the per-manager
+                # stderr the WorktreeManager.cleanup_all already
+                # writes; we don't want to double-warn.
+                pass
+    else:
+        # Surface the preservation in the operator's terminal
+        # log so they know where to look.
+        if managers_to_cleanup:
+            logger.warning(
+                f"orchestrator: worktrees PRESERVED on disk for "
+                f"inspection (exit {final_exit_code} keeps them per "
+                f"PRD). Inspect at {effective_worktree_base / run_id}/."
+            )
+
+    # final cleanup of the per-run worktree-base parent. The
+    # per-round WorktreeManagers each cleaned up their round-N
+    # subdirs, but the shared ``<worktree_base>/<run_id>/`` parent
+    # they were nested under is still on disk.
+    #
+    # the per-round managers' cleanup_all rmdirs
+    # their own ``round-N/`` subdirs, BUT on a NO-SHIP round where
+    # the producer also ran, the reviewer-manager's cleanup_all
+    # tries to rmdir ``round-N/`` BEFORE the producer-manager
+    # cleans up its own ``round-N/producer-worktree/`` — the rmdir
+    # fails silently (dir not empty), the producer phase runs and
+    # cleans its subdir, but nothing goes back to retry the
+    # ``round-N/`` rmdir. Result: empty ``round-N/`` directories
+    # accumulate under ``<base>/<run_id>/`` even on successful
+    # runs, and the post-loop ``rmdir(<base>/<run_id>/)`` fails
+    # because of the empty children.
+    #
+    # Fix: walk the run_dir bottom-up and rmdir every empty subdir
+    # before the final ``rmdir(run_dir)``. Best-effort: any OSError
+    # is swallowed (caller may have left intentional state).
+    #
+    # skipped when ``preserve_worktrees`` is True — the
+    # whole point is to leave the dirs on disk for inspection.
+    shared_run_dir = effective_worktree_base / run_id
+    if not preserve_worktrees and shared_run_dir.exists():
+        # Walk bottom-up so deeper empty dirs get rmdir'd first,
+        # making their parents potentially empty for the next step.
+        for child_dir in sorted(
+            (p for p in shared_run_dir.rglob("*") if p.is_dir()),
+            key=lambda p: len(p.parts),
+            reverse=True,
+        ):
+            try:
+                child_dir.rmdir()
+            except OSError:
+                # Not empty (operator left something) — skip.
+                pass
+        try:
+            shared_run_dir.rmdir()
+        except OSError:
+            # Not empty; leave it for inspection.
+            pass
+
+    logger.summary(result)
+    return result

syncade/orchestrator/loop_preflight.py

@@ -0,0 +1,131 @@
+"""Run-level commit-safety gates: everything a RUN passes before the loop may spend.
+
+The run-level twin of :mod:`syncade.orchestrator.round_predispatch`, split out of ``loop`` in
+PR-h-field-06 after three consecutive dogfoods flagged that module's size while budget state
+was being threaded into it. It was 481 of a 500 code-LOC cap — passing, with 19 lines of
+headroom, which is the position ``producer.py`` was in when the next change broke the gate.
+
+**The ORDER is load-bearing**, exactly as it is for the round-level gates: the diff is
+classified FIRST, because a run that cannot dispatch must not be refused for being on the
+default branch or for a dirty tree — there is nothing for it to commit. The block is moved
+intact rather than reassembled for that reason.
+
+Refusals RAISE (``WorktreeError``); nothing returns early, which is what makes the extraction
+faithful. The four values the loop needs come back on :class:`RunPreflight`.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from syncade.worktree import WorktreeError
+
+from .branch_guard import guard_default_branch
+from .loop_dispatch_check import _diff_will_dispatch
+
+
+def run_preflight(
+    *,
+    config,
+    repo_root,
+    pr_doc_path,
+    snapshot,
+    state,
+    branch,
+    resume_plan,
+    logger,
+    force_dirty: bool,
+    allow_default_branch: bool,
+) -> None:
+    """Run every run-level gate, in order. Returns nothing; refusals RAISE.
+
+    Measured during the extraction: every value this block computes
+    (``_will_dispatch``, ``_dirty_state``, ``effective_max_rounds``, ``will_commit``,
+    ``short_sha``) is used only by the gates themselves — the loop needs none of them
+    afterwards. That is what makes this a seam rather than a cut: nothing has to be threaded
+    back, so there is no carrier object and no chance of the two halves disagreeing.
+    """
+    short_sha = snapshot.commit_sha[:12]
+    # --- Pre-classify diff before commit-safety guards (PR-h-02d) ---
+    # A known-empty or malformed diff terminates before any subprocess — no producer
+    # runs, so commit-only guards are irrelevant and must not refuse valid no-change runs.
+    _will_dispatch = _diff_will_dispatch(
+        snapshot, config, repo_root=repo_root, pr_doc_path=pr_doc_path
+    )
+
+    # --- Pre-flight dirty-tree refusal in loop mode -----------------
+    # max_rounds > 1 → the loop will run a producer that commits to
+    # the operator's branch. A tracked-modified WIP would race
+    # against the producer's writes (the operator's working tree
+    # would interleave with new commits in confusing ways).
+    # Untracked-only is fine — those files don't enter any
+    # worktree, so they're invisible to both reviewers and the
+    # producer. The --force-dirty escape hatch is for operators
+    # who understand the consequences.
+    #
+    # max_rounds == 1 is warning-only because it runs reviewers + synth and
+    # exits; nothing writes to the operator branch.
+    #
+    # Resumed loop-mode runs are refused on the same grounds: a resume
+    # still runs the producer and commits to the branch, so a dirty WIP
+    # races just as it would on a fresh run. --force-dirty is the only
+    # escape (resume does not exempt itself).
+    # The refusal must use the EFFECTIVE cap: a resume rehydrates
+    # max_rounds to max(config, resume_plan.max_rounds) later (see
+    # loop_resume._rehydrate_resume_state), so reading the un-bumped config
+    # here would let `--resume --max-rounds 1` — or a config drifted to
+    # max_rounds=1 — on a multi-round run slip the gate and then race the
+    # producer's commit against the dirty WIP (H3).
+    effective_max_rounds = config.loop.max_rounds
+    if resume_plan is not None:
+        effective_max_rounds = max(effective_max_rounds, resume_plan.max_rounds)
+    _dirty_state = state in ("tracked", "both")
+    if _will_dispatch and effective_max_rounds > 1 and _dirty_state and not force_dirty:
+        raise WorktreeError(
+            f"uncommitted tracked changes (dirty_state={state!r}); "
+            f"loop mode (max_rounds={effective_max_rounds}) "
+            f"commits to your branch and would race against this "
+            f"WIP. Commit, stash, or pass --force-dirty to override. "
+            f"To run single-pass with warning-only tracked changes, set max_rounds=1 in "
+            f"[loop] or pass --max-rounds 1."
+        )
+
+    # --- Default-branch commit guard (PR-v2-26) ---------------------
+    # A committing run (loop mode) fast-forwards the CURRENT branch, so refuse the
+    # default branch unless the operator opted in, and announce the target branch
+    # BEFORE any dispatch. Placed at the run-entry choke so a direct run_review call
+    # and a --resume are covered too, not only the CLI wrapper.
+    # will_commit is False when no dispatch will happen: no producer runs on a no-change
+    # or malformed-diff run, so the default-branch guard and commit announcement are moot.
+    will_commit = _will_dispatch and effective_max_rounds > 1
+    guard_default_branch(
+        repo_root, snapshot.branch, allow=allow_default_branch, will_commit=will_commit
+    )
+    if will_commit:
+        # Printed directly to stderr, NOT via logger.event, so it survives --quiet — the
+        # same reason the auth block bypasses quiet. Which branch receives commits is a
+        # safety disclosure, and it matters MOST under `--quiet --allow-default-branch`.
+        print(
+            f"[syncade] producer commits will land on: {snapshot.branch or '(detached HEAD)'}",
+            file=sys.stderr,
+        )
+
+    # Dirty-tree warnings fire on every round-0 snapshot regardless of
+    # max_rounds; the loop-mode refusal above is additive.
+    if state in ("tracked", "both"):
+        logger.warning(
+            f"working tree has uncommitted modifications to tracked "
+            f"files — reviewers will only see HEAD ({short_sha}); "
+            f"your local changes are invisible to them. Commit "
+            f"before running syncade if you want them reviewed."
+        )
+    if state in ("untracked", "both"):
+        count = snapshot.untracked_count
+        plural = "files" if count != 1 else "file"
+        logger.warning(
+            f"working tree has untracked files (not reviewed): "
+            f"{count} {plural}. These are invisible to reviewers, "
+            f"which is usually intentional. Run 'git status' to see them."
+        )
+
+    # --- Run-directory layout ---------------------------------------