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

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

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

{phase_loop_runtime-0.7.6 → phase_loop_runtime-0.7.8}/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.6"
+version = "0.7.8"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"

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

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

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

@@ -653,6 +653,19 @@ def build_parser() -> argparse.ArgumentParser:
             "Default: current directory."
         ),
     )
+    run_train_sub.add_argument(
+        "--workspace",
+        dest="workspace_overrides",
+        action="append",
+        default=None,
+        metavar="repo=PATH",
+        help=(
+            "Per-node workspace override: map a node's repo to an arbitrary "
+            "absolute checkout path (e.g. a different volume). Repeatable: "
+            "--workspace my-service=/mnt/vol/my-service. Takes precedence over "
+            "a node's **Workspace:** attribute and the --workspace-root default."
+        ),
+    )
     run_train_sub.add_argument(
         "--ledger-dir",
         default=None,
@@ -2886,9 +2899,29 @@ def _run_train_command(*, parser: argparse.ArgumentParser, args: argparse.Namesp
     # run_mode mirrors how 'run' handles --governed (cli.py:796)
     run_mode = "governed" if bool(getattr(args, "governed", False)) else "autonomous"
 
-    # Workspace resolution: <workspace-root>/<node.repo>
+    # Workspace resolution precedence (highest first):
+    #   1. --workspace <repo>=<path> CLI override (arbitrary absolute paths)
+    #   2. the node's **Workspace:** attribute (from the train roadmap)
+    #   3. <workspace-root>/<node.repo>  (the default)
     workspace_root = Path(getattr(args, "workspace_root", None) or ".")
+    workspace_overrides: dict = {}
+    for spec in getattr(args, "workspace_overrides", None) or []:
+        if "=" not in spec:
+            parser.error(f"--workspace expects 'repo=PATH', got {spec!r}")
+        repo_key, _, path_val = spec.partition("=")
+        repo_key = repo_key.strip()
+        path_val = path_val.strip()
+        if not repo_key or not path_val:
+            parser.error(f"--workspace expects a non-empty 'repo=PATH', got {spec!r}")
+        workspace_overrides[repo_key] = Path(path_val)
+
     def _resolve_workspace(node) -> Path:
+        override = workspace_overrides.get(node.repo)
+        if override is not None:
+            return override
+        node_ws = getattr(node, "workspace", None)
+        if node_ws:
+            return Path(node_ws)
         return workspace_root / node.repo
 
     # Ledger path — must not be inside any repo's .phase-loop/
@@ -2901,11 +2934,42 @@ def _run_train_command(*, parser: argparse.ArgumentParser, args: argparse.Namesp
 
     as_json = bool(getattr(args, "json", False))
 
+    # Build a broker-authoritative coordinator runtime so publish actually opens PRs.
+    # Without a broker_client, publish_from_worktree fail-closes `broker_required` and
+    # the train opens ZERO PRs.  The routing broker binds per BrokerRequest.repo (the
+    # node's resolved workspace) AND keeps a PER-REPO admission/evidence store, so one
+    # node's ambiguous outcome fail-closes only that repo.  The broker root is namespaced
+    # by the roadmap's RESOLVED PATH hash (not the bare filename stem): two distinct
+    # roadmap files — even same-stemmed, even under one explicit `--ledger-dir` — get
+    # distinct broker roots, so an ambiguous outcome in one train can never fail-close a
+    # different train.  Keying on the stable path (not the content digest) keeps a
+    # resumed train on its own epoch across roadmap edits.  It lives under the ledger dir,
+    # which the roadmap author keeps outside any repo's .phase-loop/ (INV-4); it is NOT
+    # machine-enforced to be outside every node worktree, so keep train roadmaps + their
+    # ledger dir out of the checkouts.
+    import hashlib
+
+    from .convergence.broker import build_routing_broker_client
+
+    train_key = hashlib.sha256(str(train_path.resolve()).encode("utf-8")).hexdigest()[:16]
+    coordinator_root = ledger_dir / "broker" / train_key
+    coordinator_root.mkdir(parents=True, exist_ok=True)
+    roadmap_digest = hashlib.sha256(train_path.read_bytes()).hexdigest()
+    coordinator_runtime = train_runner.CoordinatorRuntime(
+        train_id=train_path.stem,
+        coordinator_root=coordinator_root,
+        roadmap_path=str(train_path),
+        roadmap_digest=roadmap_digest,
+        workspace_id=train_path.stem,
+        broker_client=build_routing_broker_client(broker_root=coordinator_root),
+    )
+
     result = train_runner.run_train(
         roadmap,
         ledger_path,
         run_mode=run_mode,
         resolve_workspace=_resolve_workspace,
+        coordinator_runtime=coordinator_runtime,
         _merge_phase_enabled=True,  # P4 gate: autonomous→drafts_open, governed→merge
     )
 

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

@@ -2,6 +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 .live import build_github_broker_client, build_routing_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"]
+__all__ = ["AdmissionRecord", "BrokerAdmissionPolicy", "LinearizableAdmissionStore", "BrokerEnvironmentBoundary", "GitHubBrokerAdapter", "BrokerEvidenceStore", "EvidenceRecord", "BrokerClient", "BrokerExecutionResult", "BrokerProviderAdapter", "BrokerService", "build_github_broker_client", "build_routing_broker_client", "publish_committed_branch_idempotency_key"]

{phase_loop_runtime-0.7.6 → phase_loop_runtime-0.7.8}/src/phase_loop_runtime/convergence/broker/credsep.py

@@ -98,7 +98,14 @@ class GitHubBrokerAdapter:
         # 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"]
+        # `gh pr create` REQUIRES --title (+ --body) when non-interactive; the bare
+        # `--draft`/`--fill` form aborts headless ("must provide --title and --body").
+        # Derive a deterministic title from the branch HEAD's commit subject and pass
+        # the request's pr_body verbatim (empty body is valid once --title is present).
+        # --head pins the branch explicitly so gh never infers a wrong head.
+        title = self._output("log", "-1", "--format=%s") or request.branch
+        args = ["gh", "pr", "create", "--repo", origin_repo, "--head", request.branch, "--title", title, "--body", request.pr_body or title]
+        if request.draft: args.append("--draft")
         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

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

@@ -0,0 +1,187 @@
+"""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 hashlib
+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 ALLOWED_ORIGIN_HOSTS, 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,
+    )
+
+
+def _repo_store_slug(repo: str) -> str:
+    """Stable, filesystem-safe subdir name for a repo's per-repo broker store.
+
+    ``BrokerRequest.repo`` is an arbitrary absolute workspace path, so hash it rather
+    than embed the path.  A short hex prefix is collision-free in practice and keeps
+    the on-disk layout readable.
+    """
+    return hashlib.sha256(repo.encode("utf-8")).hexdigest()[:16]
+
+
+class _RoutingBrokerService:
+    """A :class:`BrokerClient` that routes each request to a PER-REPO broker service.
+
+    ``build_github_broker_client`` fixes ONE ``repo_path`` at construction, so a single
+    client can only faithfully serve one repo — a multi-repo ``run_train`` threading one
+    ``coordinator_runtime.broker_client`` across every node would run
+    ``git -C <wrong-repo>`` and trip the branch/head guard on node 2+.
+
+    Critically, each repo gets its OWN admission + evidence store under
+    ``broker_root/<repo-slug>`` — the stores are NOT shared.  ``epoch_blocked`` is a
+    GLOBAL scan over a store (``any(state is OUTCOME_AMBIGUOUS_BLOCKED)``) and an
+    ambiguous terminal is durable + permanent, and it fires on BENIGN transients
+    (push-unconfirmed / remote-read-failed / pr-unconfirmed / remote-head-mismatch /
+    pr-head-unconfirmed).  A shared store would therefore let one repo's transient
+    hiccup permanently fail-close every OTHER repo in the train (and, with an
+    un-namespaced ``broker_root``, other trains too).  Per-repo stores scope the
+    fail-closed epoch to exactly the repo whose mutation became ambiguous — the correct
+    blast radius: repo A's unknown state says nothing about repo B's independent remote.
+    The caller namespaces ``broker_root`` per train (see the ``run-train`` CLI), closing
+    the cross-train dimension.
+    """
+
+    def __init__(
+        self,
+        broker_root: Path,
+        *,
+        admission_policy: BrokerAdmissionPolicy,
+        run: Callable[..., subprocess.CompletedProcess],
+        allowed_hosts,
+        contracts=PROVIDER_COMPLETION_CLASSIFICATIONS,
+    ) -> None:
+        self._broker_root = Path(broker_root)
+        self._admission_policy = admission_policy
+        self._run = run
+        self._allowed_hosts = allowed_hosts
+        self._contracts = contracts
+        self._services: dict[str, BrokerService] = {}
+
+    def _service_for(self, repo: str) -> BrokerService:
+        service = self._services.get(repo)
+        if service is None:
+            root = self._broker_root / _repo_store_slug(repo)
+            service = BrokerService(
+                LinearizableAdmissionStore(root, self._admission_policy),
+                BrokerEvidenceStore(root),
+                GitHubBrokerAdapter(Path(repo), run=self._run, allowed_hosts=self._allowed_hosts),
+                contracts=self._contracts,
+            )
+            self._services[repo] = service
+        return service
+
+    def execute(self, request):
+        return self._service_for(request.repo).execute(request)
+
+
+def build_routing_broker_client(
+    *,
+    broker_root: Path,
+    admission_policy: BrokerAdmissionPolicy | None = None,
+    run: Callable[..., subprocess.CompletedProcess] = subprocess.run,
+    allowed_hosts=ALLOWED_ORIGIN_HOSTS,
+) -> BrokerClient:
+    """Wire a live GitHub broker client that serves a MULTI-repo train.
+
+    Like :func:`build_github_broker_client` but routes per ``BrokerRequest.repo``: the
+    git/gh adapter is bound to the request's repo, AND each repo gets its own admission
+    + evidence store under ``broker_root/<repo-slug>``.  Per-repo stores are load-bearing
+    for safety, not just routing — a shared store's GLOBAL ``epoch_blocked`` would let one
+    repo's ambiguous outcome (reachable via a benign transient) permanently fail-close
+    every other repo.  See :class:`_RoutingBrokerService`.
+
+    Parameters
+    ----------
+    broker_root:
+        Durable parent directory for the per-repo admission + evidence stores.  MUST
+        live OUTSIDE every node's worktree, and the caller SHOULD namespace it per train
+        (e.g. ``<ledger-dir>/broker/<train-stem>``) so unrelated trains never share an
+        epoch.
+    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).
+    allowed_hosts:
+        Origin-host allow-list applied to every per-request adapter (github.com-only
+        by default); a self-hosted/GHE fleet passes its own set.
+    """
+    return _RoutingBrokerService(
+        Path(broker_root),
+        admission_policy=admission_policy or _default_admission_policy,
+        run=run,
+        allowed_hosts=allowed_hosts,
+    )

{phase_loop_runtime-0.7.6 → phase_loop_runtime-0.7.8}/src/phase_loop_runtime/train_roadmap.py

@@ -45,12 +45,27 @@ from .cross_repo_channel import ChannelDescriptor, parse_channel_line
 # ---------------------------------------------------------------------------
 # Data model — IF-0-P2-1
 
+#: Supported node modes.  ``execute`` (default) runs the per-repo run_loop to
+#: build the node's phase, then publishes what it produced.  ``prebuilt`` lands
+#: an already-committed, independently-verified branch WITHOUT re-executing the
+#: phase (no executor dispatch) — see ``train_runner`` for the prebuilt path.
+SUPPORTED_NODE_MODES = frozenset({"execute", "prebuilt"})
+
+
 @dataclass(frozen=True)
 class TrainNode:
-    """Identity of one node in the release train: a ``(repo, roadmap)`` pair."""
+    """Identity of one node in the release train: a ``(repo, roadmap)`` pair.
+
+    ``mode`` selects how the coordinator lands the node (``execute`` = run the
+    phase then publish; ``prebuilt`` = publish an already-committed branch with
+    no executor dispatch).  ``workspace`` optionally overrides where the node's
+    checkout lives on disk (an absolute path), for nodes on arbitrary volumes.
+    """
 
     repo: str
     roadmap: str
+    mode: str = "execute"
+    workspace: Optional[str] = None
 
     @property
     def node_id(self) -> str:
@@ -116,7 +131,7 @@ class TrainRoadmap:
 _TITLE_RE = re.compile(r"^#\s+Release Train:\s*(.+?)\s*$", re.MULTILINE)
 _NODE_HEADING_RE = re.compile(r"^###\s+Node:\s*(.+?)\s*$", re.MULTILINE)
 _FIELD_RE = re.compile(
-    r"^\*\*(?P<label>Depends on|Channel):\*\*\s*(?P<value>.+)$",
+    r"^\*\*(?P<label>Depends on|Channel|Mode|Workspace):\*\*\s*(?P<value>.+)$",
     re.MULTILINE | re.IGNORECASE,
 )
 
@@ -180,13 +195,41 @@ def parse_train_roadmap(text: str) -> TrainRoadmap:
     raw_edges: List[Tuple[TrainNode, str, str]] = []  # (downstream, dep_id, channel_raw)
 
     for raw_id, body in node_bodies:
-        node = _parse_node_id(raw_id)
-        nodes.append(node)
+        base = _parse_node_id(raw_id)
 
         fields: Dict[str, str] = {}
         for m in _FIELD_RE.finditer(body):
             fields[m.group("label").lower()] = m.group("value").strip()
 
+        # Mode: default 'execute'; a bare (none) value also means the default.
+        # Reject any unknown mode with a coded, node-named parse error.  (T-A..
+        # T-F are taken by validate_train; (T-G) is the next free code and keeps
+        # the same coded-diagnostic style for the mode-grammar violation.)
+        mode_raw = fields.get("mode", "execute").strip().lower()
+        if mode_raw in _NONE_VALUES:
+            mode_raw = "execute"
+        if mode_raw not in SUPPORTED_NODE_MODES:
+            raise ValueError(
+                f"(T-G) node '{base.node_id}' declares unknown mode {mode_raw!r}; "
+                f"supported modes are 'execute' (default) and 'prebuilt'"
+            )
+
+        # Workspace: optional per-node absolute-path override for the checkout.
+        workspace_raw = fields.get("workspace")
+        workspace = (
+            workspace_raw.strip()
+            if workspace_raw and workspace_raw.strip().lower() not in _NONE_VALUES
+            else None
+        )
+
+        node = TrainNode(
+            repo=base.repo,
+            roadmap=base.roadmap,
+            mode=mode_raw,
+            workspace=workspace,
+        )
+        nodes.append(node)
+
         dep_raw = fields.get("depends on", "(none)")
         channel_raw = fields.get("channel", "(none)")