syncade 0.6.2__py3-none-any.whl

syncade/prompts_loader.py

@@ -0,0 +1,238 @@
+"""Prompt template loader + the reviewer prompt blocks.
+
+``load_template`` (the per-repo-override-then-packaged-default resolver with the
+symlink-containment guard), ``ADVERSARIAL_LENS_BLOCK`` (the opt-in reviewer
+edge-enumeration text), and ``BUG_CLASS_BLOCK`` (the opt-in directed
+bug-class sweep). All are free of any dependency on ``prompts`` itself —
+stdlib + importlib only — so they extract without a circular import. Re-exported
+from ``prompts`` so the ``syncade.prompts.<name>`` import paths are unchanged.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+
+ADVERSARIAL_LENS_BLOCK = """
+## Adversarial edge enumeration (before any SHIP)
+
+Confirming the code does what the brief says is NOT enough — that is exactly how
+real defects survive review, and it is the specific failure this instruction
+exists to stop. The brief's acceptance criteria are the FLOOR of your review,
+never the ceiling: ticking off "each AC is implemented" is the confirmatory trap
+that ships bugs. Before any SHIP, treat the implementation as guilty until proven
+innocent and do all three of the following — your `summary` must show you did.
+
+1. **Enumerate the spec-omitted combinations, in writing.** List the cases the
+   brief does NOT discuss — flag interactions (e.g. a verbosity/quiet flag
+   crossed with the feature), empty / missing / malformed / unrelated inputs,
+   absent state (no record, no upstream, no config), ordering / concurrency
+   edges. This list is SEPARATE from the acceptance criteria; if your enumeration
+   just restates the ACs, you have not done it.
+2. **Falsify every invariant the brief asserts — do not confirm the mechanism.**
+   For each absolute claim the brief makes ("byte-identical", "unchanged",
+   "always …", "never silently …", "exactly one", "only X"), construct and RUN
+   the comparison that would DISPROVE it, then cite the command and its output.
+   Confirming the relevant code path exists or executes is NOT verifying the
+   claim: "byte-identical" means you diff the actual bytes of both outputs, not
+   that a branch is taken; "never silently" means you run the silent mode and
+   inspect the channel, not that a log line exists in source. An asserted
+   invariant you did not try to break is unverified.
+3. **Run each enumerated edge in your worktree.** A probed edge that misbehaves
+   is a finding (cite the reproduction). An edge you could NOT probe is a
+   `coverage_gap`. SHIP is permitted ONLY when your `summary` shows the
+   enumeration (1) AND a falsification attempt for each asserted invariant (2);
+   without those you have not finished reviewing — emit NO-SHIP or coverage_gaps,
+   never a silent clean SHIP.
+4. **Verify the END-TO-END journey, and a real defect is a blocker — do not
+   downgrade it to a nit to justify SHIP.** Two failure modes this stops, both
+   seen in validation:
+   - *Unit verified, journey not.* Trace each feature from invocation to its
+     FINAL output / printed message / side-effect, and check every brief
+     invariant holds at EVERY surface — not just the first. A `--base` correctly
+     passed to one function but DROPPED from the printed next-step is a real
+     blocker; the running test suite passing is not the journey.
+   - *Happy path verified, consequence-of-bad-input not.* For each parse / IO /
+     input operation, feed the corrupt / missing / malformed case and ask what
+     the user GETS: a loud error, or a plausible-but-WRONG result? A
+     silently-wrong result (a partial draft from a corrupt input that looks
+     complete; a value silently defaulted) is a blocker, not an edge note.
+   When you find a defect that loses data, changes behavior, or contradicts a
+   brief invariant, your verdict is **NO-SHIP and the finding is a `blocker`** —
+   however small the fix looks. Do not downgrade a genuine defect to a `nit` or
+   `minor` so you can SHIP; "the fix is one line" is not a reason to ship the bug.
+"""
+"""The adversarial edge-enumeration block.
+
+Substituted into ``reviewer.md``'s ``{adversarial_lens_block}`` placeholder
+only for reviewers configured ``adversarial_lens=True`` (see
+:class:`~syncade.config.ReviewerConfig`); other reviewers render the placeholder
+as the empty string.
+"""
+
+BUG_CLASS_BLOCK = """## Directed bug-class sweep (before any SHIP)
+
+The adversarial disposition above tells you to attack the change; this tells you
+WHERE to aim, so recall does not depend on inspiration. Work each angle below
+against the diff AND the enclosing functions, and surface every candidate with a
+nameable failure — as a *candidate*. This is find-phase guidance: raising one here
+does NOT relax the rule that a `blocker` needs reproduction, and a candidate you
+drop silently is never verified — the single largest source of missed defects.
+
+Severity follows verification state, not your confidence:
+- A candidate you REPRODUCE (cite `evidence_cmd` / `evidence_output`) takes the
+  severity its consequence warrants — `blocker` if it loses or corrupts data,
+  breaks a user path, or violates an invariant the brief asserts. Do NOT downgrade
+  a reproduced defect so you can SHIP (see the adversarial block above).
+- A candidate whose mechanism is real but whose trigger you could not reproduce is
+  a `minor`, or goes in `coverage_gaps` — surfaced, never dropped, and never an
+  unreproduced `blocker`. This keeps recall high without spending a producer round
+  on a maybe-bug.
+
+Your `summary` must name which of these angles you ran.
+
+- **Removed-behavior audit.** For every line the diff DELETES or replaces —
+  including a rewritten docstring or comment that stated an invariant — name the
+  guard, validation, error path, or invariant it enforced, then find where the new
+  code re-establishes it. If you cannot, that is a candidate. Watch especially for
+  an invariant only PARTIALLY re-established: a new code path that reaches the same
+  sink (a delete, a write, a network call) without the guard the old path carried.
+- **Caller/callee trace.** For every function the diff changes, grep its callers
+  and check each call site against the NEW contract: a new precondition, a changed
+  return shape or nullability, a new exception, a new empty/zero case the caller
+  does not handle. Then check the callees the diff adds: does a new call feed a
+  value into an existing sink (sweep / delete / overwrite / commit) whose guard
+  assumed the old path's guarantees? A *success* that now carries an empty or
+  absent result into a destructive sink is the highest-value find here. (Distinct
+  from the consistency-class rule above: that rule is the same fact restated in
+  many places; this is a changed contract breaking a call site.)
+- **Language / framework pitfall.** Flag the classic footguns the diff introduces
+  for its language: falsy-zero and `==` coercion (JS); mutable-default-arg and
+  late-binding closures (Python); nil-map write and range-var capture (Go);
+  unanchored regex; float equality; timezone/DST drift; SQL injection.
+- **Wrapper / proxy correctness.** When the change adds or edits a type that wraps
+  another (cache, proxy, decorator, adapter), check every method routes to the
+  wrapped instance and not back through a registry/session/global (which re-enters
+  or recurses), and that it forwards every method its callers actually use.
+"""
+"""The directed bug-class sweep block.
+
+Substituted into every reviewer template's ``{bug_class_block}`` placeholder for
+reviewers configured ``bug_class_sweep=True``. OPT-IN, like
+:data:`ADVERSARIAL_LENS_BLOCK` (see :class:`~syncade.config.ReviewerConfig`): a reviewer that
+does not ask for it renders the placeholder as the empty string. The contributed design
+defaulted this ON; it is held opt-in until an ablation measures whether the checklist raises
+recall or narrows the search.
+"""
+
+
+def load_template(repo_root: Path, template_name: str) -> str:
+    """Load a prompt template by basename.
+
+    Resolution order:
+
+    1. ``<repo_root>/.syncade/templates/<template_name>`` — per-repo
+       override. If this file exists, its contents are returned. Any
+       read failure (permissions, encoding) raises ``OSError`` and is
+       NOT silently swallowed — a broken override is a config bug, not
+       a fall-through-to-default condition.
+    2. Packaged default at ``syncade/templates/<template_name>``,
+       loaded via :func:`importlib.resources.files` so it works both
+       for installed wheels and ``pip install -e .`` editable
+       installs.
+
+    Args:
+        repo_root: The git repo root to check for an override under
+            ``.syncade/templates/``.
+        template_name: The template's basename (e.g. ``"reviewer.md"``,
+            ``"synthesizer.md"``). Must be a plain basename — no path
+            separators, no parent references, no leading ``.``. The
+            check is intentionally strict: a template loader that
+            accepts arbitrary paths could be tricked into reading
+            anywhere on the filesystem by a malicious config.
+
+    Returns:
+        The raw template string with ``{placeholder}`` tokens
+        unsubstituted. Substitution is the per-template renderer's
+        concern.
+
+    Raises:
+        ValueError: If ``template_name`` is not a safe basename OR if
+            the override file (or any parent directory) is a symlink
+            that escapes ``<repo_root>/.syncade/templates/``. The
+            containment guard prevents a malicious or
+            accidental symlink (e.g. ``.syncade/templates/reviewer.md``
+            pointing at ``/etc/passwd``) from making the template
+            loader read arbitrary files.
+        FileNotFoundError: If neither the override nor the packaged
+            default exists. The packaged default should always be
+            present for templates syncade ships; a missing default is
+            a packaging bug, not a runtime condition.
+    """
+    if (
+        not template_name
+        or "/" in template_name
+        or "\\" in template_name
+        or template_name in (".", "..")
+        or Path(template_name).is_absolute()
+    ):
+        raise ValueError(
+            f"template_name {template_name!r} must be a plain basename "
+            "(no separators, parent refs, or absolute paths). The "
+            "loader resolves against `.syncade/templates/` or the "
+            "packaged default; an arbitrary path is unsafe."
+        )
+    override = repo_root / ".syncade" / "templates" / template_name
+    if override.is_file():
+        # Template override containment guard. Three layered
+        # checks against symlink-based escape:
+        #
+        # 1. Parent directories must be REAL dirs, not symlinks.
+        #    Without this, ``<repo>/.syncade/templates`` could be a
+        #    symlink to e.g. ``/etc/``, and the file-level
+        #    ``relative_to`` check below would pass because both
+        #    resolve to the same target.
+        #
+        # 2. The override path itself (if a symlink) must resolve
+        #    to a target inside the REAL template dir. This is the
+        #    file-level containment check.
+        #
+        # 3. The template-dir resolution uses ``strict=False`` so
+        #    we don't follow symlinks on the parent components;
+        #    they should NOT be symlinks per (1).
+        syncade_dir = repo_root / ".syncade"
+        template_dir = syncade_dir / "templates"
+        for parent in (syncade_dir, template_dir):
+            if parent.is_symlink():
+                raise ValueError(
+                    f"template override path contains a symlinked parent "
+                    f"directory ({parent} is a symlink). Symlinks on the "
+                    "parent components of the template directory are "
+                    "refused: a symlink at <repo>/.syncade or "
+                    "<repo>/.syncade/templates can redirect template "
+                    "loading to arbitrary filesystem locations. Make "
+                    "the parent components real directories."
+                )
+        # File-level containment check: the override (which
+        # MAY itself be a file-level symlink) must resolve to a path
+        # inside the now-confirmed-real template directory.
+        resolved = override.resolve()
+        try:
+            # template_dir.resolve() is safe now — we verified above
+            # that neither it nor its parent .syncade is a symlink.
+            resolved.relative_to(template_dir.resolve())
+        except ValueError as exc:
+            raise ValueError(
+                f"template override at {override} resolves to "
+                f"{resolved}, which is outside the template directory "
+                f"{template_dir}. Symlinks that escape the template "
+                "directory are refused — the override path must be a "
+                "real file (or a symlink to a real file inside the "
+                "template directory)."
+            ) from exc
+        return override.read_text(encoding="utf-8")
+    # `files("syncade")` resolves to the package root; `/ "templates" /
+    # <name>` is the bundled template. Works for both editable and
+    # installed-wheel layouts because importlib.resources abstracts
+    # over them.
+    return (files("syncade") / "templates" / template_name).read_text(encoding="utf-8")

syncade/retry.py

@@ -0,0 +1,159 @@
+"""Bounded retry on transient reviewer / synthesizer / producer API errors (H5).
+
+A single transient provider blip — an HTTP 429, a 5xx, or a dropped socket —
+in a reviewer, the synthesizer, or the producer subprocess otherwise aborts
+the whole review loop at exit 40 with no second attempt, which makes
+real-provider runs non-deterministic (the H5 finding: a transient anthropic
+reviewer error in round 1 took down an entire run). This module is the ONE
+place that decides (a) whether a failure is transient enough to retry and
+(b) how long to wait between attempts, so the per-reviewer dispatch
+(:mod:`syncade.dispatcher`), the cold-synth driver
+(:mod:`syncade.synthesizer.driver`), and the producer (:mod:`syncade.producer`
+— its retry is SIDE-EFFECT-safe, PR-v2-22) cannot drift apart on that definition.
+
+Classification — deliberately minimal (H5 scope guard). The taxonomy is a
+*whitelist*: when in doubt, do NOT retry.
+
+- ONLY a :class:`~syncade.adapters.base.ReviewerInvocationError` is ever
+  retried, and only when it wraps a recognizable transient API/network
+  condition. That is the single exception type both the reviewer adapter's
+  ``parse_output`` and the synthesizer adapter's
+  ``extract_final_text`` raise to wrap a *subprocess-side*
+  provider failure (auth, model-unavailable, rate-limit, network).
+- Transient ⇔ HTTP status 429 or 5xx, OR — when the adapter could not surface
+  a status — a stderr/message substring in :data:`_TRANSIENT_MARKERS`.
+- EVERYTHING else is permanent and never retried: parse/contract failures
+  (:class:`~syncade.findings.ReviewerOutputError`,
+  :class:`~syncade.synthesis.SynthesizerOutputError`), a missing CLI binary
+  (:class:`~syncade.process.SubprocessNotFoundError`), a wall-clock timeout
+  (:class:`~syncade.process.SubprocessTimeoutError` — that is the budget, not
+  a blip; note its message contains "timed out", so the type gate below MUST
+  fire before the substring scan), bad config, and any programming bug.
+  Retrying a deterministic failure only burns budget on an outcome that
+  cannot change.
+- A status-bearing error that is NOT 429/5xx (400/401/403/404) is permanent:
+  bad-request / auth / permission / missing-model do not get better on a
+  second identical attempt.
+
+ASSUMPTION / open question: the no-status path leans on substring markers,
+which is heuristic. It only applies when an adapter raised a
+``ReviewerInvocationError`` without an ``api_error_status`` — today the real
+adapters set the status when they have one, so the markers are a fallback for
+network-layer failures (dropped sockets) that never reached an HTTP status.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+
+from syncade.adapters.base import ReviewerInvocationError
+
+# Extra attempts AFTER the first try, i.e. up to 3 subprocess attempts total.
+# Bounded so a hard provider outage still fails the leg promptly rather than
+# looping indefinitely.
+MAX_RETRIES = 2
+
+# Lowercased substrings checked ONLY when a ReviewerInvocationError carries no
+# api_error_status. Kept small and high-signal: a marker that also matched a
+# deterministic provider verdict would wrongly trigger retries.
+_TRANSIENT_MARKERS = (
+    "429",
+    "rate limit",
+    "rate_limit",
+    "temporarily unavailable",
+    "temporary failure",
+    "connection reset",
+    "connection aborted",
+    "connection refused",
+    "socket",
+    "network",
+    "timed out",
+    "timeout",
+    "econnreset",
+    "etimedout",
+    # A provider dropping the response stream mid-flight. Empirically the most
+    # common real transient we hit, and it matched NONE of the markers above:
+    # codex reports it as `stream disconnected before completion: error sending
+    # request for url (...)` with no HTTP status, so the status gate cannot
+    # catch it either. Two dogfood runs died at exit 40 — losing every
+    # remaining round — because the retry that exists for exactly this case
+    # never fired.
+    "stream disconnected",
+    "error sending request",
+)
+
+
+# Provider QUOTA EXHAUSTION — deliberately NOT in _TRANSIENT_MARKERS (PR-h-field-02).
+#
+# The two need opposite handling and merging them would be worse than the bug. Retrying a
+# usage limit is pointless — the window has not moved — so folding these into the transient
+# list would fire MAX_RETRIES more doomed reviewer pairs against an exhausted quota before
+# dying anyway. Classifying it permanent (today's behaviour, by omission) is also wrong: the
+# run is resumable and the operator only has to wait.
+#
+# Read out of the shipped codex binary (codex-cli 0.145.0): its error enum carries
+# `UsageLimitReached` and `QuotaExceeded`, and the user-facing text is
+# "You've hit your usage limit for ".
+#
+# Markers are SPECIFIC on purpose. A bare "quota" or "usage limit" would match a reviewer
+# discussing rate limiting in the code under review — which is exactly the string that turned
+# up in the field runs' stdout and briefly looked like evidence. A false positive here tells an
+# operator to wait out a limit they have not hit, so the cost of looseness is a wrong diagnosis.
+_USAGE_LIMIT_MARKERS = (
+    "usagelimitreached",
+    "quotaexceeded",
+    # snake_case, and the MOST common form in the binary (35 occurrences, more than any other).
+    # Also the safest: prose says "usage limit" with a space, so the underscore cannot collide
+    # with a reviewer discussing rate limiting. The first version of this tuple measured that
+    # number, wrote it into the brief, and then left the marker out.
+    "usage_limit",
+    "usage limit reached",
+    "hit your usage limit",
+    "exceeded your quota",
+    "quota exceeded",
+)
+
+
+def is_usage_limit_error(exc: BaseException) -> bool:
+    """Return ``True`` iff ``exc`` is the provider refusing on exhausted quota.
+
+    Neither transient nor permanent: the correct response is to stop cleanly and let the
+    operator resume once the window resets, which is exit 25's existing contract.
+    """
+    if not isinstance(exc, ReviewerInvocationError):
+        return False
+    text = f"{exc} {exc.stderr}".lower()
+    return any(marker in text for marker in _USAGE_LIMIT_MARKERS)
+
+
+def is_transient_api_error(exc: BaseException) -> bool:
+    """Return ``True`` iff ``exc`` is a transient provider/network failure
+    worth one more subprocess attempt. See the module docstring for the
+    (whitelist) taxonomy."""
+    if not isinstance(exc, ReviewerInvocationError):
+        return False
+    if is_usage_limit_error(exc):
+        # Quota is its own outcome; retrying it just burns the remaining attempts.
+        return False
+    status = exc.api_error_status
+    if status == 429 or (status is not None and 500 <= status <= 599):
+        return True
+    if status is not None:
+        # A concrete non-5xx/429 status is a terminal provider verdict.
+        return False
+    text = f"{exc} {exc.stderr}".lower()
+    return any(marker in text for marker in _TRANSIENT_MARKERS)
+
+
+def backoff_sleep(retry_index: int) -> None:
+    """Sleep a short, fully-jittered interval before retry ``retry_index``
+    (1-based).
+
+    Exponential base (0.5s, 1s, …) with full jitter so concurrent reviewers
+    that all hit a rate limit don't re-fire in lockstep. Small by design: the
+    goal is to ride out a brief blip, not to implement a production backoff
+    schedule. Isolated here so tests can monkeypatch it to a no-op.
+    """
+    base = 0.5 * (2 ** (retry_index - 1))
+    time.sleep(random.uniform(0.0, base))

syncade/run_inputs.py

@@ -0,0 +1,40 @@
+"""Cheap, certain validation of a run's inputs — one predicate, several call sites.
+
+A LEAF (imports only ``pathlib``), and deliberately so. The CLI must run this BEFORE
+anything mutates the operator's directory (PR-h-04 item A), and making the CLI import
+``orchestrator.loop`` just to check whether a file exists would drag the whole loop in for
+a `Path.exists()`. It also keeps ``loop.py`` under the file-length cap.
+
+The value is having ONE implementation: ``run_review`` calls it and so does the CLI, so a
+pre-flight cannot refuse what the library would accept. A private copy in the CLI is
+precisely the drift PR-h-02d.5 spent four rounds on — and reintroducing one here silently
+dropped the "is it a file?" half, which is why a directory passed as the brief slipped
+through in calibration.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def validate_run_inputs(repo_root: Path, pr_doc_path: Path) -> None:
+    """Cheap, certain input checks. Raises ``NotADirectoryError`` / ``FileNotFoundError``.
+
+    Lifted out of :func:`run_review` so the CLI can run it BEFORE anything mutates the
+    operator's directory (PR-h-04 item A). Previously a mistyped brief path reached this
+    point only after ``ensure_repo_initialized`` had created a repo and a baseline commit,
+    and in an existing repo the default-branch guard refused FIRST — so a typo was reported
+    as a branch problem while the real mistake was a filename.
+
+    It lives here, in the module that owns the authoritative check, and the CLI calls this
+    same function: one predicate, two call sites, so the pre-flight cannot drift from what
+    ``run_review`` accepts. That drift is the defect PR-h-02d.5 spent four rounds on.
+    """
+    if not repo_root.exists():
+        raise NotADirectoryError(f"repo_root does not exist: {repo_root}")
+    if not repo_root.is_dir():
+        raise NotADirectoryError(f"repo_root is not a directory: {repo_root}")
+    if not pr_doc_path.exists():
+        raise FileNotFoundError(f"pr_doc_path does not exist: {pr_doc_path}")
+    if not pr_doc_path.is_file():
+        raise FileNotFoundError(f"pr_doc_path is not a file: {pr_doc_path}")

syncade/run_status.py

@@ -0,0 +1,198 @@
+"""Live run-status breadcrumb: never terminate without a discoverable reason.
+
+One ``.syncade/runs/<id>/status.json`` per run, rewritten at each phase transition
+(``state: running``) and finalized on every exit path (normal reason / OS signal /
+exception). A ``running`` file whose pid is dead IS the evidence of a hard kill
+(SIGKILL) at that phase — see :func:`is_stale_running`. syncade runs one review
+per process, so the active status is a module global rather than threaded through
+the orchestrator call chain.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from syncade.persistence._atomic import atomic_write_json
+
+STATUS_FILENAME = "status.json"
+
+
+@dataclass
+class RunStatus:
+    """The live breadcrumb for one run. ``running()`` and ``finalize()`` each
+    rewrite ``status.json`` atomically with the current phase."""
+
+    path: Path
+    started_at: datetime
+    pid: int
+    phase: str = "starting"
+    round_index: int | None = None
+
+    def _write(self, state: str, **extra: object) -> None:
+        record = {
+            "state": state,
+            "phase": self.phase,
+            "round": self.round_index,
+            "pid": self.pid,
+            "started_at_utc": self.started_at.isoformat(),
+            "updated_at_utc": datetime.now(tz=UTC).isoformat(),
+            **extra,
+        }
+        atomic_write_json(self.path, record, sort_keys=False)
+
+    def running(self, phase: str, round_index: int | None = None) -> None:
+        self.phase = phase
+        self.round_index = round_index
+        self._write("running")
+
+    def finalize(self, reason: str, exit_code: int | None) -> None:
+        self._write("terminated", reason=reason, exit_code=exit_code)
+
+
+_active: RunStatus | None = None
+_began: bool = False
+
+
+def begin(run_dir: Path, started_at: datetime) -> RunStatus:
+    """Create + register the active breadcrumb and write the first ``running`` record."""
+    global _active, _began
+    _active = RunStatus(Path(run_dir) / STATUS_FILENAME, started_at, os.getpid())
+    _began = True
+    _active.running("starting")
+    return _active
+
+
+def update_phase(phase: str, round_index: int | None = None) -> None:
+    """Advance the active breadcrumb's phase. No-op when no run is active."""
+    if _active is not None:
+        _active.running(phase, round_index)
+
+
+def finalize_active(reason: str, exit_code: int | None) -> None:
+    """Finalize + clear the active breadcrumb. No-op when no run is active."""
+    global _active
+    if _active is not None:
+        _active.finalize(reason, exit_code)
+        _active = None
+
+
+def clear_active() -> None:
+    global _active, _began
+    _active = None
+    _began = False
+
+
+def active() -> RunStatus | None:
+    return _active
+
+
+def began() -> bool:
+    """Did :func:`begin` run in this process since the last :func:`clear_active`?
+
+    ``active()`` cannot answer this: :func:`finalize_active` clears it, so by the time a
+    caller handles an exception ``run_review`` re-raised, ``active()`` reads ``None`` for a
+    run that had very much begun. A caller that used it to decide "was this a clean refusal?"
+    deleted the operator's repository and its artifacts after a real mid-run failure.
+
+    This flag is set at the one moment the run takes ownership — immediately after the run
+    directory is created — and only ``clear_active`` (in-process reuse) resets it.
+    """
+    return _began
+
+
+def _pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # exists but owned by another user
+    return True
+
+
+def is_stale_running(status: dict) -> bool:
+    """A ``running`` status whose pid is no longer alive = hard-killed at its phase."""
+    if status.get("state") != "running":
+        return False
+    pid = status.get("pid")
+    return isinstance(pid, int) and pid > 0 and not _pid_alive(pid)
+
+
+_received_signal: int | None = None
+
+_SIGNALS = [signal.SIGTERM, signal.SIGINT]
+if hasattr(signal, "SIGHUP"):
+    _SIGNALS.append(signal.SIGHUP)
+
+
+def _handler(signum: int, _frame: object) -> None:
+    global _received_signal
+    _received_signal = signum
+    raise KeyboardInterrupt
+
+
+@contextmanager
+def install_signal_handlers() -> Iterator[None]:
+    """Install parent-process SIGTERM/SIGINT/SIGHUP handlers that raise
+    KeyboardInterrupt — so process.py's existing child-group cleanup fires and the
+    interrupt bubbles to the run's finalizer. Restores prior handlers on exit.
+
+    Must be called from the main thread (Python signal constraint); the CLI review
+    dispatch is the main thread.
+    """
+    global _received_signal
+    _received_signal = None  # clear any stale signum from a prior in-process run
+    previous = {sig: signal.signal(sig, _handler) for sig in _SIGNALS}
+    try:
+        yield
+    finally:
+        for sig, prev in previous.items():
+            signal.signal(sig, prev)
+
+
+def received_signal() -> int | None:
+    return _received_signal
+
+
+def signal_exit_code(signum: int | None) -> int:
+    """Shell convention: a process killed by signal N exits ``128 + N``."""
+    return 128 + int(signum if signum is not None else signal.SIGINT)
+
+
+def signal_name(signum: int | None) -> str:
+    if signum is None:
+        return "UNKNOWN"
+    try:
+        return signal.Signals(signum).name
+    except ValueError:
+        return f"SIG{signum}"
+
+
+def finalize_signal() -> int:
+    """Finalize the active breadcrumb with the received signal, log one stderr
+    line, and return the ``128+signum`` exit code. Used by the CLI's
+    KeyboardInterrupt handler."""
+    signum = _received_signal
+    name = signal_name(signum)
+    rs = active()
+    phase = rs.phase if rs is not None else "startup"
+    if rs is not None:
+        print(
+            f"[syncade] terminated by signal {name} during '{phase}' — recorded in status.json",
+            file=sys.stderr,
+        )
+    else:
+        print(
+            f"[syncade] terminated by signal {name} during '{phase}'"
+            " — no active run, status.json not written",
+            file=sys.stderr,
+        )
+    finalize_active(f"signal:{name}", signal_exit_code(signum))
+    return signal_exit_code(signum)