phase-loop-runtime 0.7.4__tar.gz → 0.7.6__tar.gz

{phase_loop_runtime-0.7.4 → phase_loop_runtime-0.7.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.4
+Version: 0.7.6
 Summary: Harness-neutral phase-loop orchestration runtime and CLI
 Author: ViperJuice
 License-Expression: Apache-2.0

{phase_loop_runtime-0.7.4 → phase_loop_runtime-0.7.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phase-loop-runtime"  # PyPI dist name; NOT "agent-harness" (an unrelated third-party PyPI project)
-version = "0.7.4"
+version = "0.7.6"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"

{phase_loop_runtime-0.7.4 → phase_loop_runtime-0.7.6}/src/phase_loop_runtime/__init__.py

@@ -18,4 +18,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.7.4"
+__version__ = "0.7.6"

{phase_loop_runtime-0.7.4 → phase_loop_runtime-0.7.6}/src/phase_loop_runtime/cli.py

@@ -728,6 +728,11 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="FILE",
         help="Path to the cross-repo release-train roadmap (same file as run-train).",
     )
+    train_status_sub.add_argument(
+        "--event-log",
+        metavar="PATH",
+        help="Read a coordinator-owned convergence event log instead of a legacy train ledger.",
+    )
     train_status_sub.add_argument(
         "--ledger-dir",
         default=None,
@@ -3059,6 +3064,21 @@ def _run_train_status_command(*, parser: argparse.ArgumentParser, args: argparse
     """
     import json as _json
 
+    event_log = getattr(args, "event_log", None)
+    if event_log:
+        if getattr(args, "train_file", None) or getattr(args, "ledger_dir", None):
+            parser.error("train-status --event-log is mutually exclusive with --train and --ledger-dir")
+            return 2
+        from .convergence import build_train_status, read_convergence_events, recover_train_state, render_train_status
+        path = Path(event_log)
+        try:
+            snapshot = build_train_status(recover_train_state(read_convergence_events(path)), path)
+        except Exception as exc:
+            print(f"train-status: failed to read event log at {path}: {exc}", file=sys.stderr)
+            return 1
+        print(render_train_status(snapshot, as_json=bool(getattr(args, "json", False))))
+        return 0
+
     from .train_ledger import default_ledger_path, read_ledger
 
     train_file = getattr(args, "train_file", None)

phase_loop_runtime-0.7.6/src/phase_loop_runtime/convergence/__init__.py

@@ -0,0 +1,110 @@
+"""Frozen convergence contracts only; runtime and broker behavior are intentionally absent."""
+
+from phase_loop_runtime.convergence.contracts import (
+    AdmissionRequest,
+    AuthoritySource,
+    BrokerRequest,
+    BrokerTerminalEvidence,
+    BrokerVerb,
+    InvalidationTrigger,
+    PublishCommittedBranchResult,
+    ReconciliationBinding,
+    ResourceIsolationDecision,
+    evaluate_resource_isolation,
+)
+from phase_loop_runtime.convergence.provider_contracts import (
+    PROVIDER_COMPLETION_CLASSIFICATIONS,
+    ProviderAutomationDisposition,
+    ProviderCompletionClassification,
+    ProviderCompletionContract,
+    TerminalOutcomeState,
+    validate_terminal_transition,
+)
+from phase_loop_runtime.train_ledger import (
+    CoordinatorEvent,
+    CoordinatorEventKind,
+    ConvergenceResultEnvelope,
+    ConvergenceResultStatus,
+    normalize_legacy_ledger_record,
+)
+from phase_loop_runtime.convergence.event_log import (
+    RecoveredTrainState,
+    default_convergence_event_log_path,
+    read_convergence_events,
+    record_intent,
+    record_outcome,
+    recover_train_state,
+)
+from phase_loop_runtime.convergence.reconcile import ActionReconciliation, ExactStateProbes, ReconciliationVerdict, SupportedConvergenceVersions, invalidate_action_evidence, reconcile_before_action, reconcile_train_state
+from phase_loop_runtime.convergence.dispatch import DispatchDecision, RepositoryDispatchRequest, RepositoryLockKey, dispatch_ready_nodes
+from phase_loop_runtime.convergence.fencing import ApprovalBinding, AttemptLease, FencedAdmissionFactory, compute_approval_digest, validate_attempt_lease
+from phase_loop_runtime.convergence.refresh import DownstreamRefreshRequest, DownstreamRefreshResult, DownstreamRefreshStatus, refresh_downstream_after_merge
+from phase_loop_runtime.convergence.status import TrainStatusSnapshot, build_train_status, render_train_status
+from phase_loop_runtime.convergence.adapters import AdapterExecutionRequest, run_claude_adapter, run_codex_adapter, run_outside_agent_adapter
+from phase_loop_runtime.convergence.broker import (
+    AdmissionRecord, BrokerAdmissionPolicy, BrokerClient, BrokerEnvironmentBoundary,
+    BrokerEvidenceStore, BrokerExecutionResult, BrokerProviderAdapter, BrokerService,
+    EvidenceRecord, GitHubBrokerAdapter, LinearizableAdmissionStore,
+    publish_committed_branch_idempotency_key,
+)
+
+__all__ = [
+    "AdmissionRequest",
+    "AuthoritySource",
+    "BrokerRequest",
+    "BrokerTerminalEvidence",
+    "BrokerVerb",
+    "CoordinatorEvent",
+    "CoordinatorEventKind",
+    "ConvergenceResultEnvelope",
+    "ConvergenceResultStatus",
+    "InvalidationTrigger",
+    "PROVIDER_COMPLETION_CLASSIFICATIONS",
+    "ProviderAutomationDisposition",
+    "ProviderCompletionClassification",
+    "ProviderCompletionContract",
+    "PublishCommittedBranchResult",
+    "ReconciliationBinding",
+    "ResourceIsolationDecision",
+    "TerminalOutcomeState",
+    "evaluate_resource_isolation",
+    "normalize_legacy_ledger_record",
+    "validate_terminal_transition",
+    "AdapterExecutionRequest",
+    "ExactStateProbes",
+    "ActionReconciliation",
+    "ApprovalBinding",
+    "AttemptLease",
+    "DispatchDecision",
+    "DownstreamRefreshRequest",
+    "DownstreamRefreshResult",
+    "DownstreamRefreshStatus",
+    "FencedAdmissionFactory",
+    "RecoveredTrainState",
+    "ReconciliationVerdict",
+    "RepositoryDispatchRequest",
+    "RepositoryLockKey",
+    "SupportedConvergenceVersions",
+    "TrainStatusSnapshot",
+    "build_train_status",
+    "default_convergence_event_log_path",
+    "compute_approval_digest",
+    "dispatch_ready_nodes",
+    "invalidate_action_evidence",
+    "read_convergence_events",
+    "reconcile_train_state",
+    "reconcile_before_action",
+    "record_intent",
+    "record_outcome",
+    "recover_train_state",
+    "render_train_status",
+    "run_claude_adapter",
+    "run_codex_adapter",
+    "run_outside_agent_adapter",
+    "refresh_downstream_after_merge",
+    "validate_attempt_lease",
+    "AdmissionRecord", "BrokerAdmissionPolicy", "BrokerClient", "BrokerEnvironmentBoundary",
+    "BrokerEvidenceStore", "BrokerExecutionResult", "BrokerProviderAdapter", "BrokerService",
+    "EvidenceRecord", "GitHubBrokerAdapter", "LinearizableAdmissionStore",
+    "publish_committed_branch_idempotency_key",
+]

phase_loop_runtime-0.7.6/src/phase_loop_runtime/convergence/adapters/__init__.py

@@ -0,0 +1,6 @@
+from .base import AdapterExecutionRequest
+from .codex import run_codex_adapter
+from .claude import run_claude_adapter
+from .outside_agent import run_outside_agent_adapter
+
+__all__ = ["AdapterExecutionRequest", "run_codex_adapter", "run_claude_adapter", "run_outside_agent_adapter"]

phase_loop_runtime-0.7.6/src/phase_loop_runtime/convergence/adapters/base.py

@@ -0,0 +1,52 @@
+"""Bounded, credential-stripped adapter execution primitives."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+from phase_loop_runtime.convergence.contracts import AdmissionRequest
+from phase_loop_runtime.train_ledger import ConvergenceResultEnvelope, ConvergenceResultStatus
+
+_DENIED_ENV = ("OPENAI_API_KEY", "ANTHROPIC_API_KEY", "GOOGLE_API_KEY", "GEMINI_API_KEY")
+_ALLOWED_ACTIONS = frozenset({"execute", "repair", "review"})
+
+@dataclass(frozen=True)
+class AdapterExecutionRequest:
+    attempt_id: str
+    admission: AdmissionRequest
+    argv: tuple[str, ...]
+    cwd: Path
+    timeout_seconds: float
+    allowed_action: str
+    evidence_references: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.argv or self.timeout_seconds <= 0 or self.allowed_action not in _ALLOWED_ACTIONS:
+            raise ValueError("adapter request is outside bounded execution contract")
+        if self.admission.attempt_id != self.attempt_id:
+            raise ValueError("adapter request must preserve admission attempt id")
+
+
+def run_bounded(request: AdapterExecutionRequest, *, expected_prefix: str) -> ConvergenceResultEnvelope:
+    if not request.argv[0].startswith(expected_prefix):
+        return ConvergenceResultEnvelope(ConvergenceResultStatus.BLOCKED, request.attempt_id, "adapter command outside provider bounds")
+    env = {key: value for key, value in os.environ.items() if key not in _DENIED_ENV}
+    try:
+        result = subprocess.run(request.argv, cwd=request.cwd, env=env, text=True, capture_output=True, timeout=request.timeout_seconds, start_new_session=True, check=False)
+    except subprocess.TimeoutExpired:
+        return ConvergenceResultEnvelope(ConvergenceResultStatus.DEGRADED, request.attempt_id, "adapter timed out")
+    except OSError as exc:
+        return ConvergenceResultEnvelope(ConvergenceResultStatus.FAILED, request.attempt_id, str(exc)[:256])
+    detail = (result.stdout or result.stderr or "")[:1024]
+    if result.returncode:
+        return ConvergenceResultEnvelope(ConvergenceResultStatus.FAILED, request.attempt_id, detail)
+    try:
+        payload = json.loads(result.stdout)
+        status = ConvergenceResultStatus(payload.get("status", "completed"))
+    except (ValueError, json.JSONDecodeError):
+        status = ConvergenceResultStatus.COMPLETED
+    return ConvergenceResultEnvelope(status, request.attempt_id, detail)

phase_loop_runtime-0.7.6/src/phase_loop_runtime/convergence/adapters/claude.py

@@ -0,0 +1,5 @@
+from .base import AdapterExecutionRequest, run_bounded
+from phase_loop_runtime.train_ledger import ConvergenceResultEnvelope
+
+def run_claude_adapter(request: AdapterExecutionRequest) -> ConvergenceResultEnvelope:
+    return run_bounded(request, expected_prefix="claude")

phase_loop_runtime-0.7.6/src/phase_loop_runtime/convergence/adapters/codex.py

@@ -0,0 +1,5 @@
+from .base import AdapterExecutionRequest, run_bounded
+from phase_loop_runtime.train_ledger import ConvergenceResultEnvelope
+
+def run_codex_adapter(request: AdapterExecutionRequest) -> ConvergenceResultEnvelope:
+    return run_bounded(request, expected_prefix="codex")

phase_loop_runtime-0.7.6/src/phase_loop_runtime/convergence/adapters/outside_agent.py

@@ -0,0 +1,9 @@
+from .base import AdapterExecutionRequest, run_bounded
+from phase_loop_runtime.train_ledger import ConvergenceResultEnvelope, ConvergenceResultStatus
+
+def run_outside_agent_adapter(request: AdapterExecutionRequest, submission: dict | None = None) -> ConvergenceResultEnvelope:
+    if submission is not None:
+        from phase_loop_runtime.conformance import validate_outside_agent_submission
+        if validate_outside_agent_submission(submission).status.value != "pass":
+            return ConvergenceResultEnvelope(ConvergenceResultStatus.BLOCKED, request.attempt_id, "outside-agent submission failed conformance")
+    return run_bounded(request, expected_prefix="outside-agent")

phase_loop_runtime-0.7.6/src/phase_loop_runtime/convergence/broker/__init__.py

@@ -0,0 +1,7 @@
+"""Credential-capable, fail-closed broker epoch."""
+from .admission import AdmissionRecord, BrokerAdmissionPolicy, LinearizableAdmissionStore
+from .credsep import BrokerEnvironmentBoundary, GitHubBrokerAdapter
+from .evidence import BrokerEvidenceStore, EvidenceRecord
+from .live import build_github_broker_client
+from .verbs import BrokerClient, BrokerExecutionResult, BrokerProviderAdapter, BrokerService, publish_committed_branch_idempotency_key
+__all__ = ["AdmissionRecord", "BrokerAdmissionPolicy", "LinearizableAdmissionStore", "BrokerEnvironmentBoundary", "GitHubBrokerAdapter", "BrokerEvidenceStore", "EvidenceRecord", "BrokerClient", "BrokerExecutionResult", "BrokerProviderAdapter", "BrokerService", "build_github_broker_client", "publish_committed_branch_idempotency_key"]

phase_loop_runtime-0.7.6/src/phase_loop_runtime/convergence/broker/admission.py

@@ -0,0 +1,56 @@
+"""Durable, metadata-only broker admission ordering."""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Callable
+
+from phase_loop_runtime.convergence.contracts import AdmissionRequest
+
+
+@dataclass(frozen=True)
+class AdmissionRecord:
+    sequence: int
+    epoch: int
+    request: AdmissionRequest
+
+
+BrokerAdmissionPolicy = Callable[[AdmissionRequest], bool]
+
+
+class LinearizableAdmissionStore:
+    """Append-only admission log guarded by an OS advisory lock."""
+    def __init__(self, root: Path, policy: BrokerAdmissionPolicy | None = None, epoch_blocked: Callable[[], bool] | None = None) -> None:
+        self.root, self.policy, self.epoch_blocked = root, policy, epoch_blocked or (lambda: False)
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.path, self.lock_path = root / "admissions.jsonl", root / "admissions.lock"
+
+    def _records(self) -> list[AdmissionRecord]:
+        if not self.path.exists(): return []
+        records = []
+        for line in self.path.read_text(encoding="utf-8").splitlines():
+            raw = json.loads(line); raw["request"] = AdmissionRequest(**raw["request"]); records.append(AdmissionRecord(**raw))
+        return records
+
+    def admit(self, request: AdmissionRequest) -> AdmissionRecord:
+        import fcntl
+        with self.lock_path.open("a+", encoding="utf-8") as lock:
+            fcntl.flock(lock, fcntl.LOCK_EX)
+            try:
+                if self.epoch_blocked() or self.policy is None or not self.policy(request):
+                    raise PermissionError("broker admission denied")
+                records = self._records()
+                for record in records:
+                    if record.request.idempotency_key == request.idempotency_key:
+                        if record.request != request: raise ValueError("conflicting idempotency key")
+                        return record
+                if records and request.lease_epoch < max(r.epoch for r in records): raise PermissionError("stale epoch")
+                record = AdmissionRecord(len(records) + 1, request.lease_epoch, request)
+                with self.path.open("a", encoding="utf-8") as stream:
+                    stream.write(json.dumps(asdict(record), sort_keys=True) + "\n"); stream.flush(); os.fsync(stream.fileno())
+                return record
+            finally: fcntl.flock(lock, fcntl.LOCK_UN)
+
+    def replay(self) -> tuple[AdmissionRecord, ...]: return tuple(self._records())

phase_loop_runtime-0.7.6/src/phase_loop_runtime/convergence/broker/credsep.py

@@ -0,0 +1,120 @@
+"""Credential boundary and GitHub publish adapter."""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Mapping
+
+from phase_loop_runtime.convergence.contracts import BrokerRequest, BrokerTerminalEvidence, PublishCommittedBranchResult
+
+MUTATION_CREDENTIAL_KEYS = frozenset({"GH_TOKEN", "GITHUB_TOKEN"})
+# Repo-redirect env var: gh resolves its target repo from GH_REPO over cwd's origin,
+# so a stray GH_REPO could send a `gh pr create` to a DIFFERENT repo while the
+# push+ls-remote (bound to origin) still match — an undetected wrong-repo PR. The
+# host is instead pinned by the host-qualified `--repo host/owner/repo` (which beats
+# GH_HOST/gh-config), so GH_HOST is left intact to preserve GHE config routing.
+REPO_REDIRECT_KEYS = frozenset({"GH_REPO"})
+def strip_mutation_credentials(environment: Mapping[str, str]) -> dict[str, str]: return {k: v for k, v in environment.items() if k not in MUTATION_CREDENTIAL_KEYS}
+class BrokerEnvironmentBoundary:
+    def environment_for(self, role: str, environment: Mapping[str, str] | None = None) -> dict[str, str]:
+        env = dict(os.environ if environment is None else environment)
+        # The broker keeps its mutation credential (to push) but NEVER the repo-redirect
+        # vars; every other role is stripped of credentials.
+        return {k: v for k, v in env.items() if k not in REPO_REDIRECT_KEYS} if role == "broker" else strip_mutation_credentials(env)
+def build_non_force_branch_ref(branch: str) -> str:
+    if not branch or branch.startswith("-") or branch in {"main", "master", "develop", "release"}: raise ValueError("unsafe branch")
+    return f"refs/heads/{branch}"
+# Origin-host invariant (fail-closed): the broker only publishes to an allow-listed
+# host, so a `gh --repo host/owner/repo` derived from the origin url can NEVER be
+# mis-bound to a look-alike host by any URL-text edge (custom port, IPv6, ssh alias,
+# twin instance).  Default is github.com-only; a self-hosted/GHE fleet passes its own
+# allow-list explicitly.  This retires the whole host-parse edge class at the boundary.
+ALLOWED_ORIGIN_HOSTS = frozenset({"github.com"})
+class GitHubBrokerAdapter:
+    def __init__(self, repo_path: Path, run=subprocess.run, allowed_hosts: frozenset[str] = ALLOWED_ORIGIN_HOSTS) -> None:
+        self.repo_path, self.run, self.allowed_hosts = repo_path, run, allowed_hosts
+    def _output(self, *args: str) -> str:
+        return self.run(["git", "-C", str(self.repo_path), *args], capture_output=True, text=True, check=True).stdout.strip()
+    def _origin_url(self) -> str:
+        # The single canonical origin URL the broker validates AND operates through
+        # explicitly (push + ls-remote), so the mutation can never be redirected by the
+        # `origin` alias (remote.origin.pushurl / url.*.pushInsteadOf) to an unvalidated
+        # target.  This is git's FETCH url; the broker deliberately publishes to the
+        # canonical repo it validated, not a local triangular pushurl.
+        return self._output("remote", "get-url", "origin")
+    def _origin_repo(self) -> str:
+        return self._slug_for(self._origin_url())
+    def _slug_for(self, url: str) -> str:
+        # Resolve a git URL to a HOST-QUALIFIED `host/owner/repo` slug so `gh` is bound
+        # with `--repo host/owner/repo` (highest precedence — beats a stray
+        # GH_REPO/GH_HOST/cwd/gh-config), pinning the PR to the SAME host AND repo the
+        # push targets.  Fail-closed if the URL cannot be resolved or is not allow-listed.
+        if "://" in url:  # scheme://[user@]host[:port]/owner/repo(.git)
+            scheme = url.split("://", 1)[0].lower()
+            rest = url.split("://", 1)[1].split("@", 1)[-1]
+            authority, _, path = rest.partition("/")
+            # Fail-closed on authorities --repo cannot faithfully pin: an IPv6 literal
+            # (mis-split below) or a non-default http(s) API port (silently dropped →
+            # gh would hit the default-port host, a twin-host risk).  ssh transport
+            # ports are irrelevant to the gh API host, so they are allowed.
+            if authority.startswith("[") or authority.count(":") > 1:
+                raise ValueError(f"unsupported IPv6/authority in origin {url!r}")
+            host, _, port = authority.partition(":")
+            default_port = {"https": "443", "http": "80"}.get(scheme)
+            if scheme in ("http", "https") and port and port != default_port:
+                raise ValueError(f"non-default {scheme} port in origin {url!r} cannot be pinned by --repo")
+        else:  # scp-like: [user@]host:owner/repo(.git)
+            hostpart, sep, path = url.partition(":")
+            host = hostpart.split("@", 1)[-1]
+            if not sep:
+                raise ValueError(f"cannot resolve origin host/owner/repo from {url!r}")
+        if path.endswith(".git"):
+            path = path[:-4]
+        path = path.strip("/")
+        parts = path.split("/")
+        if not host or len(parts) != 2 or not all(parts):
+            raise ValueError(f"cannot resolve origin host/owner/repo from {url!r}")
+        if host not in self.allowed_hosts:
+            # Origin-host invariant: refuse to publish to a host outside the allow-list.
+            # This is the class-closing gate — no URL-text edge (port/IPv6/alias/twin)
+            # can mis-bind a gh call to a look-alike host, because a non-allow-listed
+            # host fails closed here (-> outcome_ambiguous_blocked), never a live PR.
+            raise ValueError(f"origin host {host!r} not in allowed broker hosts {sorted(self.allowed_hosts)}")
+        return f"{host}/{path}"
+    def _ambiguous(self, request: BrokerRequest, reference: str):
+        # v5 rule: a failed/empty remote read is NEVER inferred as no_effect and
+        # NEVER fabricated as success — it is a permanent ambiguous block.
+        return None, BrokerTerminalEvidence(request.admission.idempotency_key, "outcome_ambiguous_blocked", reference)
+
+    def execute(self, request: BrokerRequest):
+        if self._output("branch", "--show-current") != request.branch or self._output("rev-parse", "HEAD") != request.head_sha: raise ValueError("branch/head mismatch")
+        origin_url = self._origin_url()          # ONE canonical url, used explicitly everywhere
+        origin_repo = self._slug_for(origin_url) # validate allow-list + derive the gh slug from the SAME url
+        ref = build_non_force_branch_ref(request.branch)
+        # Push + ls-remote target the EXPLICIT validated url, never the `origin` alias,
+        # so remote.origin.pushurl / url.*.pushInsteadOf cannot redirect the mutation.
+        pushed = self.run(["git", "-C", str(self.repo_path), "push", origin_url, ref], capture_output=True, text=True)
+        if pushed.returncode: return self._ambiguous(request, "push-unconfirmed")
+        args = ["gh", "pr", "create", "--repo", origin_repo, "--draft"] if request.draft else ["gh", "pr", "create", "--repo", origin_repo, "--fill"]
+        created = self.run(args, cwd=self.repo_path, capture_output=True, text=True)
+        if created.returncode: return self._ambiguous(request, "pr-unconfirmed")
+        # Exact-published-head verification: READ the remote and confirm the branch
+        # head on origin equals the pushed sha, then resolve the REAL PR url and
+        # confirm its headRefOid matches.  Only then is the effect terminally observed.
+        remote = self.run(["git", "-C", str(self.repo_path), "ls-remote", origin_url, ref], capture_output=True, text=True)
+        if remote.returncode: return self._ambiguous(request, "remote-read-failed")
+        remote_sha = remote.stdout.split("\t", 1)[0].strip() if remote.stdout.strip() else ""
+        if not remote_sha: return self._ambiguous(request, "remote-branch-absent")
+        if remote_sha != request.head_sha: return self._ambiguous(request, "remote-head-mismatch")
+        listed = self.run(["gh", "pr", "list", "--repo", origin_repo, "--head", request.branch, "--json", "url,headRefOid"], cwd=self.repo_path, capture_output=True, text=True)
+        if listed.returncode: return self._ambiguous(request, "pr-read-failed")
+        try:
+            prs = json.loads(listed.stdout or "[]")
+        except json.JSONDecodeError:
+            return self._ambiguous(request, "pr-read-unparsable")
+        match = next((p for p in prs if p.get("headRefOid") == request.head_sha and p.get("url")), None)
+        if match is None: return self._ambiguous(request, "pr-head-unconfirmed")
+        return PublishCommittedBranchResult(request.branch, request.head_sha, match["url"]), BrokerTerminalEvidence(request.admission.idempotency_key, "effect_terminal_observed", match["url"])

phase_loop_runtime-0.7.6/src/phase_loop_runtime/convergence/broker/evidence.py

@@ -0,0 +1,53 @@
+"""Append-only terminal evidence for broker operations."""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from phase_loop_runtime.convergence.provider_contracts import TerminalOutcomeState, validate_terminal_transition
+
+
+@dataclass(frozen=True)
+class EvidenceRecord:
+    idempotency_key: str
+    state: TerminalOutcomeState
+    evidence_reference: str = ""
+
+
+class BrokerEvidenceStore:
+    def __init__(self, root: Path) -> None:
+        self.root = root; root.mkdir(parents=True, exist_ok=True); self.path = root / "evidence.jsonl"
+    def replay(self) -> dict[str, EvidenceRecord]:
+        result: dict[str, EvidenceRecord] = {}
+        if self.path.exists():
+            for line in self.path.read_text(encoding="utf-8").splitlines():
+                raw = json.loads(line); raw["state"] = TerminalOutcomeState(raw["state"]); result[raw["idempotency_key"]] = EvidenceRecord(**raw)
+        return result
+    @property
+    def epoch_blocked(self) -> bool:
+        return any(r.state is TerminalOutcomeState.OUTCOME_AMBIGUOUS_BLOCKED for r in self.replay().values())
+    def record_intent(self, key: str) -> EvidenceRecord:
+        current = self.replay().get(key)
+        if current: return current
+        return self._append(EvidenceRecord(key, TerminalOutcomeState.PROVIDER_CALL_IN_FLIGHT))
+    def record_terminal(self, record: EvidenceRecord, *, pre_linearization_proven: bool = False) -> EvidenceRecord:
+        current = self.replay().get(record.idempotency_key)
+        if current is None: raise ValueError("intent must precede evidence")
+        if current == record: return current
+        if not validate_terminal_transition(current.state, record.state, pre_linearization_proven=pre_linearization_proven): raise ValueError("invalid terminal transition")
+        return self._append(record)
+    def rejected_before_start(self, key: str, evidence_reference: str) -> EvidenceRecord:
+        return self._append(EvidenceRecord(key, TerminalOutcomeState.REJECTED_BEFORE_START, evidence_reference))
+    def _append(self, record: EvidenceRecord) -> EvidenceRecord:
+        # Storage-layer permanence: no write may transition OUT of a terminal
+        # outcome_ambiguous_blocked record.  This is self-enforcing regardless of
+        # caller path (record_terminal, rejected_before_start, record_intent), so a
+        # buggy caller cannot escape the block by writing a fresh terminal record.
+        current = self.replay().get(record.idempotency_key)
+        if current is not None and current.state is TerminalOutcomeState.OUTCOME_AMBIGUOUS_BLOCKED and record != current:
+            raise ValueError("outcome_ambiguous_blocked is permanent; no transition out")
+        with self.path.open("a", encoding="utf-8") as stream:
+            stream.write(json.dumps(asdict(record), sort_keys=True) + "\n"); stream.flush(); os.fsync(stream.fileno())
+        return record

phase_loop_runtime-0.7.6/src/phase_loop_runtime/convergence/broker/live.py

@@ -0,0 +1,82 @@
+"""Opt-in construction of a live, credential-capable GitHub broker client.
+
+This is the *only* helper that assembles a broker able to perform a real GitHub
+mutation.  It is never auto-instantiated: legacy ``run_train`` callers that pass
+no ``coordinator_runtime`` (or a runtime with ``broker_client=None``) publish
+exactly as before.  A caller wanting broker-mediated publication builds a client
+here and attaches it to :class:`CoordinatorRuntime.broker_client`.
+
+The wired client enforces every already-merged safety property: linearizable
+admission, permanent fail-closed ``outcome_ambiguous_blocked`` evidence, canonical
+``(repo, branch, head_sha)`` idempotency, and the adapter's exact-published-head
+verification.  Only the ``publish_committed_branch``/``github`` verb is SUPPORTED
+(see ``provider_contracts``); the service refuses every other verb.
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Callable
+
+from phase_loop_runtime.convergence.contracts import AdmissionRequest
+from phase_loop_runtime.convergence.provider_contracts import PROVIDER_COMPLETION_CLASSIFICATIONS
+
+from .admission import BrokerAdmissionPolicy, LinearizableAdmissionStore
+from .credsep import GitHubBrokerAdapter
+from .evidence import BrokerEvidenceStore
+from .verbs import BrokerClient, BrokerService
+
+
+def _default_admission_policy(_request: AdmissionRequest) -> bool:
+    """Admit any structurally-valid admission request.
+
+    ``AdmissionRequest.__post_init__`` already rejects a request missing any
+    fencing field, so a request that reaches the policy is well-formed.  Epoch
+    staleness and idempotency-key conflicts are enforced inside
+    ``LinearizableAdmissionStore.admit`` regardless of this policy.
+    """
+    return True
+
+
+def build_github_broker_client(
+    repo_path: Path,
+    *,
+    broker_root: Path,
+    admission_policy: BrokerAdmissionPolicy | None = None,
+    run: Callable[..., subprocess.CompletedProcess] = subprocess.run,
+) -> BrokerClient:
+    """Wire a live GitHub broker client.
+
+    Parameters
+    ----------
+    repo_path:
+        Worktree the :class:`GitHubBrokerAdapter` runs git/gh against.
+    broker_root:
+        Durable directory for the admission log + terminal-evidence log.  MUST
+        live OUTSIDE ``repo_path`` (e.g. ``CoordinatorRuntime.coordinator_root``)
+        so broker state never dirties the worktree being published — a dirty
+        worktree trips the publish staged-diff audit and the train clean-worktree
+        preflight.
+    admission_policy:
+        Optional admission gate; defaults to admitting any well-formed request.
+    run:
+        Injectable subprocess runner (tests pass a fake to mock the git/gh seam).
+
+    Returns
+    -------
+    BrokerClient
+        A :class:`BrokerService` bound to the global (verb-gated) contracts, so
+        only ``publish_committed_branch``/``github`` can execute.
+    """
+    admission_store = LinearizableAdmissionStore(
+        Path(broker_root),
+        admission_policy or _default_admission_policy,
+    )
+    evidence_store = BrokerEvidenceStore(Path(broker_root))
+    adapter = GitHubBrokerAdapter(Path(repo_path), run=run)
+    return BrokerService(
+        admission_store,
+        evidence_store,
+        adapter,
+        contracts=PROVIDER_COMPLETION_CLASSIFICATIONS,
+    )