syncade 0.6.2__py3-none-any.whl

syncade/orchestrator/resume_target.py

@@ -0,0 +1,215 @@
+"""Resume-target resolution.
+
+``find_resumable_runs`` lists eligible run-ids; ``resolve_resume_target`` turns
+a CLI ``--resume`` target ("latest" or a concrete id) into a validated run-id.
+Pure read-from-disk; raises :class:`ResumeError` on a non-resolvable target.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from syncade.persistence import RUN_INIT_FILENAME
+from syncade.persistence.decision_needed import DECISION_NEEDED_FILENAME
+
+from .resume_types import _RESUMABLE_EXIT_CODES, LOOP_MANIFEST_FILENAME, ResumeError
+
+# Unique heading written only by persist_deactivated_blockers_decision_needed,
+# never by the producer-escalation persist_decision_needed. When loop-manifest.json
+# is missing (partial-finalization window: decision-needed.md written before manifest),
+# this marker lets us identify the non-resumable shape without the manifest.
+_DEACTIVATED_BLOCKERS_MARKER = "## What each reviewer actually said"
+
+
+def _decision_needed_is_deactivated_shape(run_dir: Path) -> bool:
+    """Return True when ``decision-needed.md`` exists and carries the
+    blockers-all-deactivated marker (meaning the run is NOT resumable).
+
+    Used when ``loop-manifest.json`` is missing — the normal eligibility
+    predicate — to close the partial-finalization window where
+    ``decision-needed.md`` is written before ``loop-manifest.json`` is.
+    """
+    dn_path = run_dir / DECISION_NEEDED_FILENAME
+    try:
+        text = dn_path.read_text(encoding="utf-8")
+    except OSError:
+        return False
+    return _DEACTIVATED_BLOCKERS_MARKER in text
+
+
+def find_resumable_runs(runs_root: Path) -> list[str]:
+    """Return run-ids under ``runs_root`` that are eligible to resume.
+
+    Newest first (sort by run-id string descending — run-id is a
+    UTC timestamp so lexical order matches chronological order).
+
+    Eligibility (per the design's "resume mental model" table):
+
+    - ``run-init.json`` present AND ``loop-manifest.json`` missing
+      → ELIGIBLE (interrupted: operator Ctrl-C / crash / SIGTERM).
+    - ``run-init.json`` present AND ``loop-manifest.json`` malformed/unreadable
+      → ELIGIBLE enough to surface during resume-target resolution; the later
+      planning path reports the specific corruption instead of silently hiding
+      the run.
+    - ``run-init.json`` present AND ``loop-manifest.json::final_exit_code``
+      in ``{10, 25, 40, 60, 70}`` → ELIGIBLE (decision-needed checkpoint, a
+      budget-or-quota stop (25), or environment failure mid-loop).
+    - Any other state → NOT eligible.
+
+    Args:
+        runs_root: The ``<repo>/.syncade/runs/`` directory.
+
+    Returns:
+        Sorted list of eligible run-ids, newest first. Empty list
+        when ``runs_root`` doesn't exist or contains no eligible
+        runs.
+
+    Does NOT raise on a malformed ``loop-manifest.json`` — that run is returned
+    as eligible enough to protect it from GC and let the resume planner surface
+    the specific corruption. The intent is that this function never surfaces an
+    error path the CLI has to handle directly; it just returns what's available.
+    The specific-id resume path (:func:`resolve_resume_target`) is responsible
+    for surfacing "run-id not eligible" with the SPECIFIC reason.
+    """
+    if not runs_root.is_dir():
+        return []
+
+    eligible: list[str] = []
+    for entry in runs_root.iterdir():
+        if not entry.is_dir():
+            continue
+        if not (entry / RUN_INIT_FILENAME).is_file():
+            # Not a syncade run, or missing the required resume artifact.
+            continue
+        loop_manifest_path = entry / LOOP_MANIFEST_FILENAME
+        if not loop_manifest_path.is_file():
+            # Missing manifest: usually an interrupted run — eligible, UNLESS
+            # decision-needed.md already carries the blockers-all-deactivated
+            # shape (written before the manifest in that path). That shape is
+            # non-resumable even without the manifest to confirm it.
+            if _decision_needed_is_deactivated_shape(entry):
+                continue
+            eligible.append(entry.name)
+            continue
+        try:
+            data = json.loads(loop_manifest_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            # Malformed/unreadable loop-manifest — protect and surface rather
+            # than silently skipping. A later specific-plan path names the
+            # concrete failure.
+            eligible.append(entry.name)
+            continue
+        exit_code = data.get("final_exit_code")
+        if not (isinstance(exit_code, int) and exit_code in _RESUMABLE_EXIT_CODES):
+            continue
+        # Exit 10 with blockers_all_deactivated is not resumable: no producer
+        # ran, no blocker is active, and resume would re-review unchanged code.
+        # plan_resume also refuses this shape, but excluding it here prevents
+        # it from shadowing an older decision_needed run in --resume latest.
+        if exit_code == 10 and data.get("termination_reason") == "blockers_all_deactivated":
+            continue
+        eligible.append(entry.name)
+
+    eligible.sort(reverse=True)
+    return eligible
+
+
+def _read_operator_branch(run_dir: Path) -> str | None:
+    """Best-effort read of ``run-init.json::operator_branch``."""
+    run_init = run_dir / RUN_INIT_FILENAME
+    try:
+        data = json.loads(run_init.read_text(encoding="utf-8"))
+        return data.get("operator_branch")
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def resolve_resume_target(
+    runs_root: Path,
+    target: str,
+    current_branch: str | None = None,
+) -> str:
+    """Resolve a CLI ``--resume`` target to a concrete run-id.
+
+    Two target shapes:
+
+    - ``"latest"`` → return the newest eligible run on
+      ``current_branch`` (when supplied) or the absolute newest
+      eligible run (when ``current_branch`` is ``None``, e.g.
+      detached HEAD).
+    - Any other string → treat as a concrete run-id and validate
+      its eligibility. The specific run-id's branch is NOT checked
+      here — that's the tree-drift check's job in T3.
+
+    Args:
+        runs_root: The ``<repo>/.syncade/runs/`` directory.
+        target: ``"latest"`` or a concrete run-id.
+        current_branch: The branch the operator is currently on.
+            When supplied, ``"latest"`` resolution filters by
+            ``operator_branch == current_branch``. When ``None``
+            (detached HEAD or no branch info), the absolute newest
+            eligible run is returned.
+
+    Returns:
+        The concrete run-id to resume.
+
+    Raises:
+        ResumeError: On any non-resolvable state. The message is
+            operator-facing and names the specific reason (no
+            eligible runs, run-id not found, completed normally,
+            etc.).
+    """
+    if target == "latest":
+        eligible = find_resumable_runs(runs_root)
+        if current_branch is not None:
+            eligible = [
+                r for r in eligible if _read_operator_branch(runs_root / r) == current_branch
+            ]
+        if not eligible:
+            if current_branch is not None:
+                raise ResumeError(
+                    f"no eligible runs to resume on branch {current_branch!r} under {runs_root}"
+                )
+            raise ResumeError(f"no eligible runs to resume under {runs_root}")
+        return eligible[0]
+
+    # Specific run-id — validate eligibility with a helpful message.
+    run_dir = runs_root / target
+    if not run_dir.is_dir():
+        raise ResumeError(f"run-id {target!r} not found under {runs_root} (directory missing)")
+    if not (run_dir / RUN_INIT_FILENAME).is_file():
+        raise ResumeError(
+            f"run-id {target!r} is not a syncade run "
+            f"(no {RUN_INIT_FILENAME}). The directory is corrupted "
+            f"or missing the required resume artifact."
+        )
+    loop_manifest_path = run_dir / LOOP_MANIFEST_FILENAME
+    if loop_manifest_path.is_file():
+        try:
+            data = json.loads(loop_manifest_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as e:
+            raise ResumeError(
+                f"run-id {target!r} has a malformed {LOOP_MANIFEST_FILENAME}: "
+                f"{e}. Investigate manually before resuming."
+            ) from e
+        exit_code = data.get("final_exit_code")
+        # Mirror find_resumable_runs's concrete-exit-code predicate: require an
+        # int in the resumable set.
+        # Without the isinstance guard a JSON float like 40.0 would slip through
+        # here (40.0 in {10,40,60,70} is True via numeric ==) while
+        # find_resumable_runs would treat it as NOT eligible
+        # (isinstance(40.0, int) is False). (bool is an int subclass but no bool
+        # is in the set.)
+        if not (isinstance(exit_code, int) and exit_code in _RESUMABLE_EXIT_CODES):
+            raise ResumeError(
+                f"run-id {target!r} completed normally "
+                f"(final_exit_code={exit_code}); resume only applies "
+                f"to runs paused for a decision (exit 10), stopped at a budget "
+                f"ceiling or a provider usage limit (exit 25), aborted by "
+                f"environment failure (exit 40 / 60 / 70), or interrupted "
+                f"before the loop terminator wrote {LOOP_MANIFEST_FILENAME}. "
+                f"Start a fresh run."
+            )
+    # loop-manifest missing → interrupted run → eligible. Fall through.
+    return target

syncade/orchestrator/resume_types.py

@@ -0,0 +1,182 @@
+"""Shared types + constants for the resume layer.
+
+Leaf module: the filename constants, the resumable-exit-code set, the git
+timeout, and the three public types (:class:`ResumeError`, :class:`ResumePlan`,
+:class:`TreeDriftError`). Imported by the ``resume_*`` siblings; re-exported by
+the ``resume.py`` shim so ``syncade.orchestrator.resume.<name>`` import paths are
+unchanged.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from syncade.exit_codes import (
+    BUDGET_EXCEEDED,
+    CLARIFICATION_NEEDED,
+    REVIEWER_FAILURE,
+    REVIEWER_OUTPUT_UNPARSEABLE,
+    WORKTREE_ERROR,
+)
+
+LOOP_MANIFEST_FILENAME: str = "loop-manifest.json"
+"""The top-level loop-manifest filename. Lockstep with
+:mod:`syncade.persistence.loop_manifest`."""
+
+ROUND_MANIFEST_FILENAME: str = "manifest.json"
+"""The per-round manifest filename. Lockstep with
+:mod:`syncade.persistence.round_manifest`."""
+
+# Final exit codes the loop can RESUME from. Reviewer/worktree/parse failures are
+# environment/subprocess failures mid-loop (restart the errored round).
+# 10 (CLARIFICATION_NEEDED): a producer escalation checkpoint — resume re-runs the
+# escalated round with the operator's recorded decision.
+# 25 (BUDGET_EXCEEDED, PR-v2-11): a deliberate cost-ceiling stop at a phase boundary.
+# A before-producer stop's review bundle is persisted whole; plan_resume detects this
+# case via the loop-manifest's termination_reason and sets budget_aborted_before_producer_round
+# so the loop rehydrates the review bundle and dispatches only the producer on the fresh tally.
+# Everything else (0, 20, 30) is a clean completion / NO-SHIP and the operator's next
+# move is a fresh run.
+_RESUMABLE_EXIT_CODES: frozenset[int] = frozenset(
+    {
+        CLARIFICATION_NEEDED,
+        BUDGET_EXCEEDED,
+        REVIEWER_FAILURE,
+        WORKTREE_ERROR,
+        REVIEWER_OUTPUT_UNPARSEABLE,
+    }
+)
+
+# Wall-clock ceiling for the git rev-parse calls in check_tree_drift.
+# Sub-second on every reasonable repo; 5s is generous and bounded.
+_GIT_TIMEOUT_SECONDS: float = 5.0
+
+
+class ResumeError(Exception):
+    """Raised when a target run-id is not eligible to resume or its
+    on-disk state is malformed.
+
+    The CLI maps this to exit 60 (worktree/environment error class)
+    on the failing-resume path. The message is operator-facing and
+    should name the specific reason: not found, completed normally,
+    malformed run-init, etc.
+    """
+
+
+@dataclass(frozen=True)
+class ResumePlan:
+    """The orchestrator's input contract for a resumed run.
+
+    Built by :func:`plan_resume` from on-disk artifacts. Carries
+    everything ``run_review`` needs to skip the original-run setup
+    steps (run-id generation, run-init.json write) and pick up at
+    ``resumed_round`` with the right snapshot SHA.
+
+    Attributes:
+        run_id: The original run's id. The orchestrator reuses
+            this instead of generating a fresh one — that's the
+            point of resume.
+        run_dir: ``<repo>/.syncade/runs/<run_id>/``. Must exist.
+        pr_doc_path: PR doc the original run was invoked against.
+            Resumed reviewers see the CURRENT content of this file
+            (no diff/refuse on brief edits — operator's
+            responsibility).
+        operator_branch: Branch the original run was started on.
+            Read from ``run-init.json``. ``None`` for detached HEAD.
+        expected_sha: The full object ID the resumed round should
+            snapshot from. For round 0, the original run's
+            ``starting_sha``; for round N>0, the prior round's
+            advancement target (producer ending SHA, or snapshot
+            SHA if the producer didn't commit).
+        expected_branch: The branch the operator should still be on
+            at resume time. Identical to ``operator_branch``;
+            duplicated for symmetry with the tree-drift API.
+        resumed_round: 0-indexed round the resumed loop will run
+            FIRST. The orchestrator's for-loop enters at
+            ``range(resumed_round, max_rounds)``.
+        completed_rounds: 0-indexed list of rounds that completed
+            cleanly. Used by ``run_review`` (T4) to rehydrate
+            their ``RoundResult`` state via
+            :func:`load_completed_round`. Always
+            ``[0, 1, ..., resumed_round - 1]`` in v1 — the resume
+            walk is contiguous.
+        max_rounds: The original run's max_rounds. The CLI may
+            override this via ``--resume --max-rounds N``; that
+            override applies to the orchestrator's loop bound,
+            not to this field (which remains the original value
+            for diagnostic purposes).
+        syncade_version: The syncade version the original run was
+            launched with. Compared against the current
+            :data:`syncade.__version__` to emit a stderr warning
+            on mismatch (NOT a hard refusal — see brief's
+            "Out of scope").
+        config_snapshot_path: Path to the original ``run-init.json``.
+            Used by T4 for the "config drift" diagnostic
+            annotation on the new round's ``summary.md``.
+        budget_aborted_before_producer_round: When not None, the run was
+            budget-aborted (exit 25) before this round's producer ran.
+            The round's review bundle is complete and in ``completed_rounds``
+            for rehydration; the loop skips ``_run_one_round`` for this index
+            and dispatches only the producer under the fresh budget tally.
+    """
+
+    run_id: str
+    run_dir: Path
+    pr_doc_path: Path
+    operator_branch: str | None
+    expected_sha: str
+    expected_branch: str | None
+    resumed_round: int
+    completed_rounds: list[int] = field(default_factory=list)
+    max_rounds: int = 1
+    syncade_version: str = ""
+    config_snapshot_path: Path | None = None
+    base_ref: str | None = None
+    base_oid: str | None = None
+    budget_aborted_before_producer_round: int | None = None
+
+
+class TreeDriftError(Exception):
+    """Raised by :func:`check_tree_drift` when the operator's current
+    HEAD or branch differs from the expected resume target.
+
+    The CLI maps this to exit 60 (worktree/environment error class)
+    unless the operator passed ``--force-drift``. The message names
+    BOTH the expected and actual values so the operator can see what
+    moved without consulting another tool.
+
+    Attributes:
+        kind: ``"branch"`` (branch mismatch — operator switched
+            branches between abort and resume) or ``"sha"`` (same
+            branch, different HEAD — operator committed or reset
+            between abort and resume).
+        expected: The expected branch name or SHA.
+        actual: The current branch name or SHA at resume time.
+    """
+
+    kind: Literal["branch", "sha"]
+    expected: str
+    actual: str
+
+    def __init__(self, kind: Literal["branch", "sha"], expected: str, actual: str) -> None:
+        self.kind = kind
+        self.expected = expected
+        self.actual = actual
+        if kind == "branch":
+            msg = (
+                f"branch drift: expected {expected!r} (the branch the "
+                f"original run was started on), got {actual!r} at resume "
+                f"time. Switch back to {expected!r} or pass --force-drift "
+                f"to accept the drift."
+            )
+        else:
+            msg = (
+                f"HEAD drift: expected {expected} (the SHA the resumed "
+                f"round was supposed to snapshot from), got {actual} at "
+                f"resume time. Reset / check out {expected} or pass "
+                f"--force-drift to accept the drift (the resumed round "
+                f"will snapshot from the new HEAD)."
+            )
+        super().__init__(msg)

syncade/orchestrator/reviewer_template_failure.py

@@ -0,0 +1,99 @@
+"""Artifact builder for reviewer-template render failures."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from syncade.config import SyncadeConfig
+from syncade.dispatcher import DispatchResult, ReviewerRunResult
+from syncade.exit_codes import REVIEWER_FAILURE
+from syncade.persistence import persist_round_manifest, persist_run_summary
+from syncade.process import SubprocessError
+from syncade.snapshot import Snapshot
+
+from .results import RoundArtifacts, RoundResult
+
+
+def _reviewer_template_failure_result(
+    *,
+    round_idx: int,
+    snapshot: Snapshot,
+    round_dir: Path,
+    config: SyncadeConfig,
+    started_at: datetime,
+    resumed_under_drift: bool,
+    error: Exception,
+    filtered_diff_bytes: int | None = None,
+    raw_diff_bytes: int | None = None,
+) -> RoundResult:
+    """Build a phase-failure result for reviewer-template load/render errors."""
+    message = f"reviewer template render failed: {error}"
+    dispatch_result = DispatchResult(
+        results=[
+            ReviewerRunResult(
+                reviewer_name=reviewer.name,
+                provider=reviewer.provider,
+                output=None,
+                error=SubprocessError(message),
+                duration_seconds=0.0,
+                raw_subprocess_result=None,
+            )
+            for reviewer in config.reviewers
+        ],
+        total_duration_seconds=0.0,
+    )
+    persist_round_manifest(
+        round_dir,
+        snapshot,
+        dispatch_result,
+        REVIEWER_FAILURE,
+        started_at,
+        None,
+        None,
+        None,
+        round_idx=round_idx,
+        producer_result=None,
+        producer_provider=config.producer.provider,
+        producer_model=config.producer.model,
+        check_results=[],
+        filtered_diff_bytes=filtered_diff_bytes,
+        raw_diff_bytes=raw_diff_bytes,
+    )
+    persist_run_summary(
+        round_dir,
+        snapshot,
+        dispatch_result,
+        REVIEWER_FAILURE,
+        started_at,
+        None,
+        None,
+        None,
+        resumed_under_drift=resumed_under_drift,
+        check_results=[],
+    )
+    artifacts = RoundArtifacts(
+        round_idx=round_idx,
+        round_dir=round_dir,
+        manifest_path=round_dir / "manifest.json",
+        summary_path=round_dir / "summary.md",
+        findings_md_path=None,
+        synthesizer_paths=None,
+        test_run_paths=None,
+        producer_paths=None,
+    )
+    return RoundResult(
+        round_idx=round_idx,
+        snapshot=snapshot,
+        dispatch_result=dispatch_result,
+        synth_result=None,
+        test_result=None,
+        test_skip_reason=None,
+        test_worktree_error=None,
+        producer_result=None,
+        round_exit_code=REVIEWER_FAILURE,
+        artifacts=artifacts,
+        check_results=[],
+        filtered_diff_bytes=filtered_diff_bytes,
+        raw_diff_bytes=raw_diff_bytes,
+    )