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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.5
+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.5 → 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.5"
+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.5 → phase_loop_runtime-0.7.6}/src/phase_loop_runtime/__init__.py

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

{phase_loop_runtime-0.7.5 → phase_loop_runtime-0.7.6}/src/phase_loop_runtime/convergence/broker/__init__.py

@@ -2,5 +2,6 @@
 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", "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/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/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,
+    )

{phase_loop_runtime-0.7.5 → phase_loop_runtime-0.7.6}/src/phase_loop_runtime/convergence/broker/verbs.py

@@ -32,9 +32,13 @@ class BrokerService:
         # publish_committed_branch de-dups on the canonical (repo, branch, head_sha)
         # triple so a repeat under a fresh admission key is a no-op that returns the
         # SAME prior result.  Other verbs remain keyed by the admission key.
+        # Every key is namespaced by verb so a cross-verb key collision can never
+        # replay one verb's terminal record for a different verb (defense-in-depth).
         if request.verb is BrokerVerb.PUBLISH_COMMITTED_BRANCH:
-            return publish_committed_branch_idempotency_key(request.repo, request.branch, request.head_sha)
-        return request.admission.idempotency_key
+            base = publish_committed_branch_idempotency_key(request.repo, request.branch, request.head_sha)
+        else:
+            base = request.admission.idempotency_key
+        return f"{request.verb.value}\0{base}"
 
     def _replay(self, request: BrokerRequest, key: str, current: EvidenceRecord) -> BrokerExecutionResult:
         observed = current.state is TerminalOutcomeState.EFFECT_TERMINAL_OBSERVED

{phase_loop_runtime-0.7.5 → phase_loop_runtime-0.7.6}/src/phase_loop_runtime/convergence/provider_contracts.py

@@ -74,14 +74,41 @@ class ProviderCompletionContract:
                 raise ValueError("supported operations require terminal evidence")
 
 
-# Repository-derived mutation inventory: current GitHub CLI mutation paths have no
-# contractually sufficient terminal no-effect guarantee, so all remain human-executed.
+# Repository-derived mutation inventory.  The full pair-space stays enumerated so
+# inventory-completeness tests keep every verb×provider explicitly classified.
 AUTOMATED_PROVIDER_VERBS = frozenset(
     (verb, "github")
     for verb in ("publish", "merge", "release", "package", "publish_committed_branch")
 )
 
-PROVIDER_COMPLETION_CLASSIFICATIONS = tuple(
+# The ONE live-enabled verb.  ``publish_committed_branch``/``github`` is SUPPORTED
+# because ``GitHubBrokerAdapter`` supplies contractually-sufficient terminal
+# evidence: after a by-name (non-force) push it READS the remote and only reports
+# the effect terminally observed when the remote branch head equals the pushed
+# head_sha AND the PR's ``headRefOid`` equals it — resolving the real PR url.  Any
+# read-failure / mismatch / ambiguous push fails closed to
+# ``outcome_ambiguous_blocked`` (never inferred as no-effect, never fabricated as
+# success — v5 rule).  ``BrokerService`` de-dups on the canonical
+# ``(repo, branch, head_sha)`` triple with idempotent replay recovery.
+_SUPPORTED_GITHUB_PUBLISH = ProviderCompletionContract(
+    verb="publish_committed_branch",
+    provider="github",
+    classification=ProviderCompletionClassification.SUPPORTED,
+    disposition=ProviderAutomationDisposition.AUTOMATED,
+    status_endpoint="gh pr list --head <branch> --json headRefOid,url (+ git ls-remote origin refs/heads/<branch>)",
+    idempotency_key_supported="canonical (repo, branch, head_sha) triple; repeat under a fresh admission key replays the prior result",
+    terminal_success_evidence="remote branch head == pushed head_sha AND PR headRefOid == pushed head_sha -> effect_terminal_observed with the real PR url",
+    terminal_no_effect_evidence="ONLY a provider-confirmed rejection is no-effect; a failed/ambiguous push is NOT no-effect and fails closed to outcome_ambiguous_blocked (v5)",
+    non_late_commit_guarantee="by-name non-force push linearizes onto origin/<branch> or is rejected; there is no delayed/late apply after the ls-remote read",
+    guaranteed_processing_horizon="N/A — synchronous git push + gh reads; no asynchronous provider processing queue to drain",
+    expected_version_predicate="origin/<branch> head == pushed head_sha (exact-published-head match)",
+    revocation_affects_accepted="no — an accepted (linearized) push observed at head_sha is not revoked by the broker; only ambiguity fails closed",
+    stabilization_drain_interval="N/A — verification is synchronous; no stabilization/drain window",
+)
+
+# Every OTHER verb×provider stays HUMAN_EXECUTED (merge, release, package, publish
+# on github, and — by absence — all non-github providers) so the broker refuses it.
+_HUMAN_EXECUTED_VERBS = tuple(
     ProviderCompletionContract(
         verb=verb,
         provider=provider,
@@ -98,8 +125,11 @@ PROVIDER_COMPLETION_CLASSIFICATIONS = tuple(
         stabilization_drain_interval="N/A",
     )
     for verb, provider in sorted(AUTOMATED_PROVIDER_VERBS)
+    if (verb, provider) != ("publish_committed_branch", "github")
 )
 
+PROVIDER_COMPLETION_CLASSIFICATIONS = (_SUPPORTED_GITHUB_PUBLISH, *_HUMAN_EXECUTED_VERBS)
+
 
 def validate_terminal_transition(
     current: TerminalOutcomeState,

{phase_loop_runtime-0.7.5 → phase_loop_runtime-0.7.6}/src/phase_loop_runtime/train_runner.py

@@ -93,9 +93,12 @@ def _default_build_admission(runtime: "CoordinatorRuntime", node, workspace: Pat
     """Build a per-node AdmissionRequest from the coordinator runtime's authority.
 
     Mirrors the fencing construction used by ``refresh.refresh_downstream_after_merge``.
-    The publish_committed_branch verb remains HUMAN_EXECUTED, so the broker rejects
-    this admission before start — the wiring is live-CAPABLE but live-DISABLED.  This
-    is the default seam; tests inject ``_admission_fn`` to avoid a live git read.
+    The publish_committed_branch/github verb is now SUPPORTED, so a broker-authoritative
+    runtime carrying a live ``broker_client`` (see
+    ``convergence.broker.build_github_broker_client``) will admit this request and
+    perform the real, exact-head-verified publish.  Every OTHER verb stays
+    HUMAN_EXECUTED and is refused before start.  This is the default seam; tests
+    inject ``_admission_fn`` to avoid a live git read.
     """
     import hashlib
 

{phase_loop_runtime-0.7.5 → phase_loop_runtime-0.7.6}/src/phase_loop_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.5
+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.5 → phase_loop_runtime-0.7.6}/src/phase_loop_runtime.egg-info/SOURCES.txt

@@ -221,6 +221,7 @@ src/phase_loop_runtime/convergence/broker/__init__.py
 src/phase_loop_runtime/convergence/broker/admission.py
 src/phase_loop_runtime/convergence/broker/credsep.py
 src/phase_loop_runtime/convergence/broker/evidence.py
+src/phase_loop_runtime/convergence/broker/live.py
 src/phase_loop_runtime/convergence/broker/verbs.py
 src/phase_loop_runtime/deploy/phase-loop-task-message-broker.service
 src/phase_loop_runtime/pipeline_adapter/__init__.py
@@ -473,6 +474,7 @@ tests/test_convergence_event_log.py
 tests/test_convergence_fencing.py
 tests/test_convergence_fixture_contracts.py
 tests/test_convergence_invalidation.py
+tests/test_convergence_live_enable.py
 tests/test_convergence_provider_contracts.py
 tests/test_convergence_reconcile.py
 tests/test_convergence_refresh.py

phase_loop_runtime-0.7.6/tests/test_convergence_broker_credsep.py

@@ -0,0 +1,184 @@
+import json
+from types import SimpleNamespace
+
+from phase_loop_runtime.convergence.broker.credsep import BrokerEnvironmentBoundary, GitHubBrokerAdapter, build_non_force_branch_ref
+from phase_loop_runtime.convergence.contracts import AdmissionRequest, BrokerRequest, BrokerVerb
+
+
+def test_only_broker_role_receives_mutation_credentials():
+    env = {"GH_TOKEN": "value", "NORMAL": "yes"}
+    assert "GH_TOKEN" in BrokerEnvironmentBoundary().environment_for("broker", env)
+    assert "GH_TOKEN" not in BrokerEnvironmentBoundary().environment_for("worker", env)
+    assert build_non_force_branch_ref("feature/broker") == "refs/heads/feature/broker"
+
+
+# --- Blocker 3: exact-published-head verification (injectable git/gh seam) ---
+_HEAD = "abc123def456"
+_BRANCH = "feat/x"
+
+
+class _FakeRun:
+    """Match a git/gh argv against distinctive tokens; no live GitHub."""
+
+    def __init__(self, responses):
+        self.responses = responses
+        self.calls = []
+
+    def __call__(self, args, **kwargs):
+        self.calls.append(list(args))
+        for tokens, stdout, rc in self.responses:
+            if all(tok in args for tok in tokens):
+                return SimpleNamespace(stdout=stdout, stderr="", returncode=rc)
+        raise AssertionError(f"unexpected command: {args!r}")
+
+
+def _request():
+    admission = AdmissionRequest("attempt", 1, "fence", "digest", "predicate", "scope", "key")
+    return BrokerRequest(BrokerVerb.PUBLISH_COMMITTED_BRANCH, admission, "repo", _BRANCH, _HEAD, ("a.py",))
+
+
+def _base_responses():
+    return [
+        (("branch", "--show-current"), _BRANCH, 0),
+        (("rev-parse",), _HEAD, 0),
+        (("get-url",), "https://github.com/owner/repo.git", 0),
+        (("push",), "", 0),
+        (("create",), "", 0),
+    ]
+
+
+def test_remote_head_match_returns_effect_observed_with_real_url(tmp_path):
+    run = _FakeRun(_base_responses() + [
+        (("ls-remote",), f"{_HEAD}\trefs/heads/{_BRANCH}", 0),
+        (("list",), json.dumps([{"url": "https://gh/pr/9", "headRefOid": _HEAD}]), 0),
+    ])
+    result, evidence = GitHubBrokerAdapter(tmp_path, run=run).execute(_request())
+    assert evidence.terminal_state == "effect_terminal_observed"
+    assert result is not None and result.pr_url == "https://gh/pr/9"
+    assert result.head_sha == _HEAD
+
+
+def test_remote_head_mismatch_returns_ambiguous_not_success(tmp_path):
+    run = _FakeRun(_base_responses() + [
+        (("ls-remote",), f"deadbeef\trefs/heads/{_BRANCH}", 0),
+    ])
+    result, evidence = GitHubBrokerAdapter(tmp_path, run=run).execute(_request())
+    assert result is None
+    assert evidence.terminal_state == "outcome_ambiguous_blocked"
+    assert evidence.evidence_reference == "remote-head-mismatch"
+
+
+def test_remote_read_failure_returns_ambiguous_not_no_effect(tmp_path):
+    run = _FakeRun(_base_responses() + [
+        (("ls-remote",), "", 1),
+    ])
+    result, evidence = GitHubBrokerAdapter(tmp_path, run=run).execute(_request())
+    assert result is None
+    # v5 rule: a failed read is ambiguous, never inferred as no_effect nor success.
+    assert evidence.terminal_state == "outcome_ambiguous_blocked"
+    assert evidence.evidence_reference == "remote-read-failed"
+
+
+def test_pr_head_unconfirmed_returns_ambiguous(tmp_path):
+    run = _FakeRun(_base_responses() + [
+        (("ls-remote",), f"{_HEAD}\trefs/heads/{_BRANCH}", 0),
+        (("list",), json.dumps([{"url": "https://gh/pr/9", "headRefOid": "other-sha"}]), 0),
+    ])
+    result, evidence = GitHubBrokerAdapter(tmp_path, run=run).execute(_request())
+    assert result is None
+    assert evidence.terminal_state == "outcome_ambiguous_blocked"
+
+
+# --- CR hardening: bind every gh call to the origin repo (no GH_REPO redirect) ---
+def test_gh_calls_are_bound_to_origin_repo_slug(tmp_path):
+    """gh pr create + pr list must carry --repo <origin slug> so a stray GH_REPO
+    cannot open/read the PR on a different repo while the push+ls-remote match."""
+    run = _FakeRun(_base_responses() + [
+        (("ls-remote",), f"{_HEAD}\trefs/heads/{_BRANCH}", 0),
+        (("list",), json.dumps([{"url": "https://gh/pr/9", "headRefOid": _HEAD}]), 0),
+    ])
+    GitHubBrokerAdapter(tmp_path, run=run).execute(_request())
+    gh = [c for c in run.calls if c and c[0] == "gh"]
+    assert gh, "expected gh calls"
+    for c in gh:
+        # host-qualified: --repo host/owner/repo pins both host AND repo
+        assert "--repo" in c and "github.com/owner/repo" in c, f"gh call not host-bound: {c!r}"
+
+
+def test_unresolvable_origin_fails_closed(tmp_path):
+    run = _FakeRun([
+        (("branch", "--show-current"), _BRANCH, 0),
+        (("rev-parse",), _HEAD, 0),
+        (("get-url",), "not-a-git-url", 0),
+    ])
+    try:
+        GitHubBrokerAdapter(tmp_path, run=run).execute(_request())
+    except ValueError as e:
+        assert "origin" in str(e)
+    else:
+        raise AssertionError("expected fail-closed on unresolvable origin")
+
+
+def test_broker_env_strips_repo_redirect_but_keeps_credential_and_host():
+    env = {"GH_TOKEN": "t", "GH_REPO": "evil/repo", "GH_HOST": "ghe.corp", "NORMAL": "y"}
+    broker = BrokerEnvironmentBoundary().environment_for("broker", env)
+    assert broker.get("GH_TOKEN") == "t"          # broker needs its credential
+    assert "GH_REPO" not in broker               # the repo-redirect var is stripped
+    assert broker.get("GH_HOST") == "ghe.corp"   # GH_HOST kept (host pinned by --repo; preserves GHE config)
+    assert broker.get("NORMAL") == "y"
+
+
+import pytest
+@pytest.mark.parametrize("url,slug", [
+    ("https://github.com/owner/repo.git", "github.com/owner/repo"),
+    ("https://github.com/owner/repo", "github.com/owner/repo"),
+    ("git@github.com:owner/repo.git", "github.com/owner/repo"),
+])
+def test_origin_repo_host_qualified_for_github(tmp_path, url, slug):
+    run = _FakeRun([(("branch", "--show-current"), _BRANCH, 0), (("rev-parse",), _HEAD, 0), (("get-url",), url, 0)])
+    assert GitHubBrokerAdapter(tmp_path, run=run)._origin_repo() == slug
+
+
+# Class-closing origin-host invariant: any non-allow-listed host FAILS CLOSED by
+# default; a self-hosted/GHE fleet resolves only when it passes its own allow-list.
+@pytest.mark.parametrize("url", [
+    "git@ghe.corp:team/svc.git", "ssh://git@ghe.corp:2222/team/svc.git", "https://ghe.corp/team/svc",
+])
+def test_non_allowlisted_origin_host_fails_closed_by_default(tmp_path, url):
+    run = _FakeRun([(("branch", "--show-current"), _BRANCH, 0), (("rev-parse",), _HEAD, 0), (("get-url",), url, 0)])
+    with pytest.raises(ValueError, match="allowed broker hosts"):
+        GitHubBrokerAdapter(tmp_path, run=run)._origin_repo()
+
+def test_ghe_origin_resolves_only_with_explicit_allowlist(tmp_path):
+    run = _FakeRun([(("branch", "--show-current"), _BRANCH, 0), (("rev-parse",), _HEAD, 0),
+                    (("get-url",), "git@ghe.corp:team/svc.git", 0)])
+    adapter = GitHubBrokerAdapter(tmp_path, run=run, allowed_hosts=frozenset({"ghe.corp"}))
+    assert adapter._origin_repo() == "ghe.corp/team/svc"
+
+@pytest.mark.parametrize("bad", [
+    "not-a-git-url", "https://github.com/onlyowner", "git@host:", "",
+    "https://github.com:8443/o/r.git",  # non-default https port -> fail-closed
+    "https://github.com:80/o/r",        # scheme-mismatched port (https+80) -> fail-closed
+    "http://github.com:443/o/r",        # scheme-mismatched port (http+443) -> fail-closed
+    "https://[::1]/team/svc.git",        # IPv6 literal -> fail-closed
+])
+def test_origin_repo_fails_closed_on_garbage_or_unpinnable(tmp_path, bad):
+    run = _FakeRun([(("branch", "--show-current"), _BRANCH, 0), (("rev-parse",), _HEAD, 0), (("get-url",), bad, 0)])
+    with pytest.raises(ValueError):
+        GitHubBrokerAdapter(tmp_path, run=run)._origin_repo()
+
+
+# --- Round-5 fix: push + ls-remote use the EXPLICIT validated origin URL, never the
+# `origin` alias (so remote.origin.pushurl / url.*.pushInsteadOf can't redirect the
+# mutation to an unvalidated same-host repo). ---
+def test_push_and_lsremote_bind_to_explicit_origin_url_not_alias(tmp_path):
+    origin = "https://github.com/owner/repo.git"
+    run = _FakeRun(_base_responses() + [
+        (("ls-remote",), f"{_HEAD}\trefs/heads/{_BRANCH}", 0),
+        (("list",), json.dumps([{"url": "https://gh/pr/9", "headRefOid": _HEAD}]), 0),
+    ])
+    GitHubBrokerAdapter(tmp_path, run=run).execute(_request())
+    push = next(c for c in run.calls if "push" in c)
+    lsrem = next(c for c in run.calls if "ls-remote" in c)
+    assert origin in push and "origin" not in push[push.index("push") + 1:], f"push not bound to explicit url: {push!r}"
+    assert origin in lsrem and "origin" not in lsrem[lsrem.index("ls-remote") + 1:], f"ls-remote not bound to explicit url: {lsrem!r}"