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

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

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

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

{phase_loop_runtime-0.7.5 → phase_loop_runtime-0.7.7}/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/

{phase_loop_runtime-0.7.5 → phase_loop_runtime-0.7.7}/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.7/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.7/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.7}/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.7}/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.7}/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)")