syncade 0.6.2__py3-none-any.whl

syncade/persistence/reviewer.py

@@ -0,0 +1,198 @@
+"""Reviewer subprocess persistence.
+
+Writes ``<round_dir>/<reviewer_name>.{stdout,stderr,parsed.json,error.txt}``
+and the matching round-manifest entry. Called once per reviewer in the
+fan-out (multiple per round).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+import traceback
+from pathlib import Path
+
+from syncade.dispatcher import ReviewerRunResult
+from syncade.process import SubprocessResult
+from syncade.usage import usage_fields
+
+from ._atomic import atomic_write_text
+from ._validation import _validate_reviewer_filename_basename
+
+
+def persist_reviewer_result(
+    round_dir: Path,
+    run_result: ReviewerRunResult,
+    raw_subprocess_result: SubprocessResult | None,
+) -> None:
+    """Write one reviewer's outputs to ``<round_dir>/<name>.*``.
+
+    Files written:
+
+    - ``<name>.stdout`` and ``<name>.stderr`` — always created.
+      Contain the captured subprocess streams when available;
+      empty when ``raw_subprocess_result`` is ``None`` (the failure
+      happened before the subprocess actually ran — e.g. unknown
+      provider, auth fail-fast, or build_invocation raising).
+    - ``<name>.parsed.json`` — written only when
+      ``run_result.output is not None``. Uses
+      :meth:`pydantic.BaseModel.model_dump_json(indent=2)` so the
+      file diffs cleanly across runs.
+    - ``<name>.error.txt`` — written only when
+      ``run_result.error is not None``. Contains the exception's
+      class name, message, and full traceback (when available).
+
+    Args:
+        round_dir: The round directory to write into. Must already
+            exist (the orchestrator creates it during run setup).
+        run_result: One :class:`ReviewerRunResult` from a
+            :class:`DispatchResult`. The ``reviewer_name`` field is
+            used as the filename basename and validated against
+            path traversal.
+        raw_subprocess_result: The :class:`SubprocessResult` from
+            the reviewer's subprocess, if one ran. ``None`` when
+            the failure happened before any subprocess launched.
+
+    Raises:
+        ValueError: If ``run_result.reviewer_name`` is not a safe
+            basename.
+        FileNotFoundError: If ``round_dir`` does not exist (caller
+            bug — orchestrator is responsible for creating it).
+    """
+    _validate_reviewer_filename_basename(run_result.reviewer_name)
+    if not round_dir.is_dir():
+        raise FileNotFoundError(f"round_dir does not exist: {round_dir}")
+
+    # Use name-append, not with_suffix: a reviewer named "team.a" must produce
+    # "team.a.stdout", not "team.stdout" (which would collide with "team.b").
+    base_name = run_result.reviewer_name
+
+    stdout_text = raw_subprocess_result.stdout if raw_subprocess_result is not None else ""
+    stderr_text = raw_subprocess_result.stderr if raw_subprocess_result is not None else ""
+    atomic_write_text(round_dir / (base_name + ".stdout"), stdout_text)
+    atomic_write_text(round_dir / (base_name + ".stderr"), stderr_text)
+
+    if run_result.output is not None:
+        atomic_write_text(
+            round_dir / (base_name + ".parsed.json"),
+            run_result.output.model_dump_json(indent=2),
+        )
+
+    if run_result.error is not None:
+        # Compose: class name, message, traceback. The class name is
+        # essential for downstream tooling that wants to bucket
+        # failures by type without parsing the message.
+        exc = run_result.error
+        lines = [
+            f"{type(exc).__name__}: {exc}",
+            "",
+        ]
+        # __traceback__ may be None when the exception was constructed
+        # (not raised) — e.g. ReviewerInvocationError that the adapter
+        # built defensively. Surface that distinction in the file.
+        tb = exc.__traceback__
+        if tb is not None:
+            lines.extend(traceback.format_exception(type(exc), exc, tb))
+        else:
+            lines.append("(no traceback available — exception was constructed, not raised)")
+        atomic_write_text(round_dir / (base_name + ".error.txt"), "\n".join(lines))
+
+
+def _reviewer_manifest_entry(run_result: ReviewerRunResult) -> dict[str, object]:
+    """Build the per-reviewer entry for the manifest's ``reviewers``
+    array. Pulls out the fields tooling cares about while keeping the
+    full raw output behind the .stdout / .parsed.json files."""
+    model = run_result.model or (run_result.usage.model if run_result.usage is not None else "")
+    if run_result.output is not None:
+        return {
+            "name": run_result.reviewer_name,
+            "provider": run_result.provider,
+            "model": model,
+            "verdict": run_result.output.verdict,
+            "finding_count": len(run_result.output.findings),
+            "duration_seconds": run_result.duration_seconds,
+            **usage_fields(run_result.usage),
+            "outcome": "success",
+            "error_type": None,
+        }
+    error_type = type(run_result.error).__name__ if run_result.error is not None else None
+    return {
+        "name": run_result.reviewer_name,
+        "provider": run_result.provider,
+        "model": model,
+        "verdict": None,
+        "finding_count": None,
+        "duration_seconds": run_result.duration_seconds,
+        **usage_fields(run_result.usage),
+        "outcome": "failure",
+        "error_type": error_type,
+    }
+
+
+def persist_dispatch_record(
+    round_dir: Path,
+    *,
+    round_index: int,
+    reviewers: list,
+    timeout_seconds: float,
+) -> None:
+    """Record that reviewers were DISPATCHED, before any of them returns (PR-h-field-02).
+
+    Every other artifact in a round is written after the panel completes, so a run that dies
+    mid-dispatch leaves the round directory EMPTY. Three field runs did exactly that — killed in
+    ``round-2: reviewing`` with nothing on disk — and the post-mortem had only a log line in a
+    terminal and a ``status.json`` phase to work from. The provider error, the child pids, even
+    the fact that dispatch had begun, were all unrecoverable.
+
+    This is the cheapest possible fix for that: one small file, written before the panel starts,
+    saying what was in flight and since when. It never changes a verdict and is never read by the
+    loop — it exists purely so the NEXT unexplained death is diagnosable.
+
+    Deliberately records the parent pid: cross-referenced with ``status.json``'s pid it tells a
+    reader whether the parent survived its children, which is the difference between "the
+    provider rejected us" and "something killed the process".
+    """
+    payload = {
+        "round": round_index,
+        "dispatched_at_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "parent_pid": os.getpid(),
+        "timeout_seconds": timeout_seconds,
+        "reviewers": [
+            {"name": r.name, "provider": r.provider, "model": r.model} for r in reviewers
+        ],
+    }
+    atomic_write_text(round_dir / "dispatch.json", json.dumps(payload, indent=2) + "\n")
+
+
+# Reviewers spawn in parallel threads, so two children can reach record_child_pid at once and
+# a plain read-modify-write would drop one of the pids. One process writes this file, so a
+# threading lock is the whole requirement — no file locking needed.
+_dispatch_record_lock = threading.Lock()
+
+
+def record_child_pid(round_dir: Path, reviewer_name: str, pid: int) -> None:
+    """Add a reviewer's child pid to ``dispatch.json``, once that child EXISTS.
+
+    The record is written before the panel starts, when no pid is knowable yet; this fills them
+    in as each ``Popen`` returns. That answers the question the PR-h-field-02 post-mortem could
+    not: whether the children outlived the parent — "something killed syncade and orphaned
+    them" — or died first and it followed. A reader can ``ps`` these, or observe their absence.
+
+    A RETRY overwrites: the previous attempt's child is already dead by construction (retry only
+    follows a failure), and the diagnostic question is about what was alive at the time of death.
+
+    Never raises. Every failure mode here — the file missing, half-written, unparseable, a name
+    that is not in it — costs a breadcrumb, and a breadcrumb is never worth failing a review for.
+    """
+    path = round_dir / "dispatch.json"
+    with _dispatch_record_lock:
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+            for entry in payload["reviewers"]:
+                if entry.get("name") == reviewer_name:
+                    entry["pid"] = pid
+            atomic_write_text(path, json.dumps(payload, indent=2) + "\n")
+        except (OSError, ValueError, KeyError, TypeError):
+            return

syncade/persistence/round_manifest.py

@@ -0,0 +1,238 @@
+"""Per-round manifest.json persistence.
+
+Writes ``<round_dir>/manifest.json`` — the round-level entry point for
+tooling that wants to know what happened without reading every
+reviewer's output. The schema includes reviewer, synthesizer, test,
+producer, and check sections, with ``round_exit_code`` aligned to
+``loop-manifest.json``.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from syncade import __version__
+from syncade.dispatcher import DispatchResult
+from syncade.producer import ProducerResult
+from syncade.snapshot import Snapshot
+from syncade.synthesizer import SynthesizerResult
+from syncade.test_runner import TestRunResult
+
+from ._atomic import atomic_write_json
+from .checks import _check_manifest_entry
+from .producer import _producer_manifest_entry
+from .reviewer import _reviewer_manifest_entry
+from .synth import _synthesizer_manifest_entry
+from .test_run import _test_run_manifest_entry
+
+
+def persist_round_manifest(
+    round_dir: Path,
+    snapshot: Snapshot,
+    dispatch_result: DispatchResult,
+    exit_code: int,
+    started_at: datetime,
+    synth_result: SynthesizerResult | None = None,
+    test_result: TestRunResult | None = None,
+    test_skip_reason: str | None = None,
+    *,
+    round_idx: int = 0,
+    producer_result: ProducerResult | None = None,
+    producer_provider: str | None = None,
+    producer_model: str | None = None,
+    check_results: list[TestRunResult] | None = None,
+    diff_filter_refusal_headers: list[str] | None = None,
+    filtered_diff_bytes: int | None = None,
+    raw_diff_bytes: int | None = None,
+    oversize_prompt_chars: int | None = None,
+    refusal_reason: str | None = None,
+) -> Path:
+    """Write ``<round_dir>/manifest.json`` summarizing the round.
+
+    The manifest is the round-level entry point for tooling that wants
+    to know what happened without reading every reviewer's output.
+    The loop and skill bridge read it to surface findings counts and round
+    status to the user.
+
+    Schema (matches PRD Appendix C usage):
+
+    .. code-block:: json
+
+       {
+         "syncade_version": "0.X.0",
+         "run_id": "2026-05-12T15-30-04",
+         "round": 0,
+         "started_at_utc": "2026-05-12T15:30:04Z",
+         "snapshot": {
+           "commit_sha": "...",
+           "branch": "main",
+           "base_ref": null,
+           "base_oid": null,
+           "diff_present": false
+         },
+         "reviewers": [
+           {
+             "name": "claude-reviewer",
+             "provider": "anthropic",
+             "verdict": "SHIP",
+             "finding_count": 0,
+             "duration_seconds": 12.4,
+             "outcome": "success",
+             "error_type": null
+           }
+         ],
+         "synthesizer": {
+           "outcome": "success",
+           "stdout_path": "synthesizer.stdout",
+           "stderr_path": "synthesizer.stderr",
+           "parsed_path": "synthesizer.parsed.json",
+           "error_path": null,
+           "duration_seconds": 12.4,
+           "dismissed_count": 1,
+           "active_blocker_count": 0,
+           "active_minor_count": 2,
+           "active_nit_count": 1
+         },
+         "test_run": {
+           "outcome": "passed",
+           "exit_code": 0,
+           "command": "pytest -q",
+           "duration_seconds": 8.3,
+           "stdout_path": "test-run.stdout",
+           "stderr_path": "test-run.stderr",
+           "exit_code_path": "test-run.exit-code.txt",
+           "error_type": null
+         },
+         "test_skip_reason": null,
+         "producer": null,
+         "retried": 0,
+         "round_exit_code": 0
+       }
+
+    The ``synthesizer`` section is ``null`` when the phase was
+    skipped (any reviewer failed). On synthesizer success the
+    consolidation counts populate. On synthesizer failure the
+    counts are ``null`` and ``error_path`` points at the
+    ``synthesizer.error.txt`` artifact.
+
+    The ``test_run`` section is ``null`` when the leg was skipped
+    (``[loop] test_command`` is not configured OR a prior phase
+    failed/produced blockers). When the leg ran, it carries the
+    ``outcome``, the operator-configured ``command`` echoed back
+    verbatim, and pointers to the three artifact files. On
+    ``subprocess_error``, ``error_type`` names the failure shape
+    (``SubprocessTimeoutError``, ``SubprocessNotFoundError``, or
+    other :class:`~syncade.process.SubprocessError` subclasses).
+
+    ``started_at`` is the run-start instant captured once by the
+    orchestrator and shared with :func:`persist_run_summary`, so the
+    two files agree on when the run *began* — not when each file
+    happened to be written (a long run finishes minutes after it
+    starts).
+
+    Returns the path of the written manifest.
+    """
+    if not round_dir.is_dir():
+        raise FileNotFoundError(f"round_dir does not exist: {round_dir}")
+
+    # Run id is the parent directory's name (orchestrator's layout
+    # convention). Decoupled here rather than passed in, so a future
+    # caller that reorganizes the run hierarchy doesn't have to remember
+    # to update this argument list — they only have to keep the
+    # parent.name convention.
+    run_id = round_dir.parent.name
+
+    manifest = {
+        "syncade_version": __version__,
+        "run_id": run_id,
+        # ``round`` is the per-round index (0-indexed). Top-level loop
+        # aggregation lives in <run-id>/loop-manifest.json.
+        "round": round_idx,
+        "started_at_utc": started_at.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "snapshot": {
+            "commit_sha": snapshot.commit_sha,
+            "branch": snapshot.branch,
+            "base_ref": snapshot.base_ref,
+            "base_oid": snapshot.base_oid,
+            "diff_present": bool(snapshot.diff_text),
+            # Size history for a future diff cap. There is no cap today, and picking a
+            # threshold without history would be a guess; recording costs nothing and cannot
+            # be backfilled, so every run from here on is a datapoint.
+            #
+            # Two numbers because they answer different questions: `diff_bytes` is what the
+            # repo produced, `diff_bytes_reviewed` is what a reviewer was actually handed
+            # AFTER repo-context stripping — and a cap must threshold on the latter, since
+            # that is what reaches the model's context.
+            #
+            # BOTH are supplied by the caller that MEASURED them, and this writer never
+            # infers one. Deriving `diff_bytes` from `snapshot.diff_text` looked free and was
+            # not: a resumed round's snapshot carries a SENTINEL rather than the real diff, so
+            # the derivation fabricated a byte count for a diff nobody had. `null` means "not
+            # measured on this path" and is honest; a fabricated integer is not.
+            "diff_bytes": raw_diff_bytes,
+            "diff_bytes_reviewed": filtered_diff_bytes,
+        },
+        "reviewers": [_reviewer_manifest_entry(r) for r in dispatch_result.results],
+        "synthesizer": _synthesizer_manifest_entry(synth_result),
+        "test_run": _test_run_manifest_entry(test_result),
+        # persist the test_skip_reason alongside test_run.
+        # Tooling that wants to know WHY the test leg didn't fire
+        # would otherwise have to infer from dispatch + synth
+        # state. Surfacing the explicit reason in the
+        # machine-readable manifest closes the loop: the CLI,
+        # the future update loop, and any external tooling all
+        # get the same signal the Logger emitted at run time.
+        # ``None`` when test_result is not None (the leg ran).
+        "test_skip_reason": test_skip_reason if test_result is None else None,
+        # per-round producer section. ``None`` when this round
+        # didn't run a producer (the round that SHIPped, or the
+        # final round under max-rounds-reached). Populated when the
+        # producer ran with outcome / starting_sha / ending_sha /
+        # provider + model echo.
+        "producer": _producer_manifest_entry(
+            producer_result,
+            producer_config_provider=producer_provider,
+            producer_config_model=producer_model,
+        ),
+        # Total EXTRA subprocess attempts consumed this round riding out
+        # transient provider errors (H5). A 429/5xx/dropped-socket blip in a
+        # reviewer, the synthesizer, OR the producer subprocess is retried with
+        # jittered backoff instead of aborting the loop at exit 40; surfacing the
+        # count makes a flaky run visible in the artifact. Sums the reviewer-dispatch
+        # retries, the synthesizer's own (SynthesizerResult.retries), and the
+        # producer's (ProducerResult.retries, PR-v2-22).
+        "retried": sum(r.retries for r in dispatch_result.results)
+        + (synth_result.retries if synth_result is not None else 0)
+        + (producer_result.retries if producer_result is not None else 0),
+        # Use ``round_exit_code`` for cross-surface consistency with
+        # ``loop-manifest.json``'s ``rounds[].round_exit_code``.
+        "round_exit_code": exit_code,
+    }
+
+    # append the checks array ONLY when checks ran, so a zero-config
+    # round's manifest stays byte-identical (no 'checks' key at all).
+    if check_results:
+        manifest["checks"] = [_check_manifest_entry(c) for c in check_results]
+
+    # present ONLY on a fail-closed diff-filter refusal (D2, PR-h-02d).
+    # Named "diff_filter_refusal_headers" so tooling can distinguish
+    # "reviewer worktree failed" from "diff section(s) were unidentifiable".
+    if diff_filter_refusal_headers is not None:
+        manifest["diff_filter_refusal_headers"] = diff_filter_refusal_headers
+
+    # present ONLY on a before-dispatch size refusal. Machine-readable discriminator
+    # for the resume planner and tooling: "diff_malformed", "diff_too_large", or
+    # "prompt_too_large". Distinct from diff_filter_refusal_headers (legacy field for
+    # diff_malformed only) so all three refusal reasons are uniformly detectable.
+    if refusal_reason is not None:
+        manifest["refusal_reason"] = refusal_reason
+
+    # present ONLY on a prompt_too_large refusal. Carries the measured assembled prompt
+    # size so tooling can tell the operator by how much and for which reviewer.
+    if oversize_prompt_chars is not None:
+        manifest["oversize_prompt_chars"] = oversize_prompt_chars
+
+    manifest_path = round_dir / "manifest.json"
+    atomic_write_json(manifest_path, manifest, sort_keys=False)
+    return manifest_path

syncade/persistence/run_init.py

@@ -0,0 +1,153 @@
+"""Run-init persistence.
+
+Writes ``<run_dir>/run-init.json`` — the top-level "what was this run
+about" record, captured at the very start of every fresh ``syncade
+<pr-doc>`` invocation (before round 0's directory exists).
+
+The file exists so ``--resume <run-id>`` can
+reconstruct enough of the original invocation's context to decide
+eligibility (was the operator on this branch? did the original run
+start from this SHA?) and to validate against tree drift between
+abort and resume.
+
+Schema:
+
+.. code-block:: json
+
+   {
+     "syncade_version": "0.1.0",
+     "started_at_utc": "2026-05-28T16:43:59Z",
+     "pr_doc_path": "design docs",
+     "base_ref": "1dbbca3",
+     "base_oid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
+     "starting_sha": "3442e72ab60b43153cdbee83f3187203b289f14a",
+     "operator_branch": "main",
+     "max_rounds": 3,
+     "config_snapshot": { ... }
+   }
+
+The ``config_snapshot`` is informational only — the resumed loop
+reads the CURRENT ``.syncade/config.toml`` from disk; the snapshot
+exists so the operator (or a future agent) inspecting an aborted run
+knows what config produced it.
+
+It is a ``model_dump`` of :class:`SyncadeConfig` echoing every field at
+its serialized value, with ONE carve-out: a
+default-empty ``checks`` list is omitted, so a zero-config run-init.json does
+not carry an empty optional section. A configured ``[[checks]]`` list is still
+echoed; only the empty default is dropped.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from syncade.config import SyncadeConfig
+
+from ._atomic import atomic_write_json
+
+RUN_INIT_FILENAME: str = "run-init.json"
+"""Filename used for the run-init artifact. Single source of
+truth so the persistence writer, the resume detector, and any future
+tooling all agree on the path."""
+
+
+def _config_snapshot(config: SyncadeConfig) -> dict:
+    """Serialize the config for the diagnostic ``config_snapshot`` block.
+
+    A default-empty ``checks`` list is omitted so zero-config runs do not carry
+    an empty optional section. A configured ``[[checks]]`` list is still echoed
+    for diagnostics. Every other field is echoed verbatim.
+    """
+    snapshot = config.model_dump(mode="json")
+    if snapshot.get("checks") == []:
+        del snapshot["checks"]
+    return snapshot
+
+
+def persist_run_init(
+    run_dir: Path,
+    *,
+    syncade_version: str,
+    started_at: datetime,
+    pr_doc_path: Path,
+    base_ref: str | None,
+    base_oid: str | None,
+    starting_sha: str,
+    operator_branch: str | None,
+    max_rounds: int,
+    config: SyncadeConfig,
+) -> Path:
+    """Write ``<run_dir>/run-init.json`` capturing the run's initial
+    state.
+
+    Called ONCE per run, at the very start of
+    :func:`syncade.orchestrator.loop.run_review` (after the run directory
+    exists, before round 0's directory is created). A
+    resumed run does NOT rewrite this file — the snapshot captured
+    at the original run start is the authoritative record across
+    resume boundaries.
+
+    Args:
+        run_dir: Top-level run directory (``<repo>/.syncade/runs/<id>/``).
+            Must already exist; the run-id mkdir happens before this
+            call in ``run_review``.
+        syncade_version: The :data:`syncade.__version__` at run start.
+            Recorded so a resume across a syncade upgrade can emit a
+            stderr warning.
+        started_at: The :func:`datetime.now(tz=UTC)` instant captured
+            at run start. Same value threaded into manifest /
+            loop-manifest / summary so they all agree on when the
+            run began.
+        pr_doc_path: Path to the PR doc the run was invoked against.
+            Serialized as the ``str(...)`` of the path so the file
+            stays JSON-safe.
+        base_ref: The ``--base`` value the CLI received, or ``None``
+            if no diff was requested. Distinct from ``starting_sha``
+            (the resolved HEAD SHA at run start).
+        base_oid: The resolved full object ID of ``base_ref`` at
+            snapshot time, or ``None`` when ``base_ref`` is ``None``.
+            Unlike ``base_ref``, this is immutable even if the ref
+            moves after the run starts.
+        starting_sha: The full HEAD object ID the orchestrator
+            snapshotted at round 0. The authoritative tree state
+            the run began against.
+        operator_branch: The branch the operator was on at run
+            start (``Snapshot.branch``). ``None`` for detached
+            HEAD. Captured so resume can validate the operator
+            hasn't switched branches between abort and resume.
+        max_rounds: The ``config.loop.max_rounds`` cap the run was
+            launched with. Captured because a future ``--resume
+            --max-rounds N`` may override the original cap; the
+            original is preserved here for diagnostic comparison.
+        config: The :class:`SyncadeConfig` instance loaded at run
+            start. Serialized via :meth:`pydantic.BaseModel.model_dump`
+            with ``mode="json"`` so enums + paths flatten to
+            JSON-safe primitives.
+
+    Returns:
+        Path of the written ``run-init.json``.
+
+    Raises:
+        FileNotFoundError: If ``run_dir`` does not exist.
+    """
+    if not run_dir.is_dir():
+        raise FileNotFoundError(f"run_dir does not exist: {run_dir}")
+
+    record = {
+        "syncade_version": syncade_version,
+        "started_at_utc": started_at.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "pr_doc_path": str(pr_doc_path),
+        "base_ref": base_ref,
+        "base_oid": base_oid,
+        "starting_sha": starting_sha,
+        "operator_branch": operator_branch,
+        "max_rounds": max_rounds,
+        # Full config echo. See module docstring.
+        "config_snapshot": _config_snapshot(config),
+    }
+
+    run_init_path = run_dir / RUN_INIT_FILENAME
+    atomic_write_json(run_init_path, record, sort_keys=False)
+    return run_init_path