phase-loop-runtime 0.7.22__tar.gz → 0.7.23__tar.gz

{phase_loop_runtime-0.7.22/src/phase_loop_runtime.egg-info → phase_loop_runtime-0.7.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.22
+Version: 0.7.23
 Summary: Harness-neutral phase-loop orchestration runtime and CLI
 Author-email: ViperJuice <viperjuice@users.noreply.github.com>
 License-Expression: Apache-2.0
@@ -16,7 +16,8 @@ Classifier: Topic :: Software Development :: Build Tools
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: detect-secrets==1.5.0
-Requires-Dist: baml-py<0.223,>=0.222
+Requires-Dist: baml-bridge==0.20.1
+Requires-Dist: protobuf<8,>=6.31.1
 Requires-Dist: pydantic<3,>=2
 Requires-Dist: PyYAML<7,>=6
 Requires-Dist: consiliency-contract<0.7,>=0.6.5
@@ -49,7 +50,7 @@ To install just this runtime package directly:
 
 ```sh
 pip install phase-loop-runtime              # latest compatible release
-pip install phase-loop-runtime==0.7.22      # …or pin an exact version
+pip install phase-loop-runtime==0.7.23      # …or pin an exact version
 ```
 
 To pin a specific tag from source instead, substitute a tag from

{phase_loop_runtime-0.7.22 → phase_loop_runtime-0.7.23}/README.md

@@ -19,7 +19,7 @@ To install just this runtime package directly:
 
 ```sh
 pip install phase-loop-runtime              # latest compatible release
-pip install phase-loop-runtime==0.7.22      # …or pin an exact version
+pip install phase-loop-runtime==0.7.23      # …or pin an exact version
 ```
 
 To pin a specific tag from source instead, substitute a tag from

{phase_loop_runtime-0.7.22 → phase_loop_runtime-0.7.23}/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.22"
+version = "0.7.23"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -20,7 +20,8 @@ classifiers = [
 ]
 dependencies = [
     "detect-secrets==1.5.0",
-    "baml-py>=0.222,<0.223",
+    "baml-bridge==0.20.1",
+    "protobuf>=6.31.1,<8",
     "pydantic>=2,<3",
     "PyYAML>=6,<7",
     # PIN (spec-integration v0.3.0): floor at 0.6.3 -- ships the `gate_posture_registry`

{phase_loop_runtime-0.7.22 → phase_loop_runtime-0.7.23}/src/phase_loop_runtime/__init__.py

@@ -18,4 +18,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.7.22"
+__version__ = "0.7.23"

phase_loop_runtime-0.7.23/src/phase_loop_runtime/_baml_worker.py

@@ -0,0 +1,202 @@
+"""BAML v1 worker process for ``phase_loop_runtime.baml_modular`` (agent-harness#1135).
+
+This file runs as a standalone script (``python -I -S _baml_worker.py ...``).
+It imports only the standard library and, after ``init``, ``baml_bridge``; it
+never imports ``phase_loop_runtime``.  Importing this module has no side
+effects: everything below runs under ``if __name__ == "__main__":``.
+
+argv: ``<owner pid> <comma-separated env allowlist keys> [--no-pdeathsig]``.
+
+Protocol: one JSON object per line, UTF-8 with ``ensure_ascii=True``.  Requests
+arrive on fd 0; responses leave on a dup of fd 1 taken before fd 1 is pointed
+at stderr, so nothing the native runtime prints can corrupt the protocol.
+Every request carries an ``id`` that the response echoes.  A response has
+exactly the keys ``{id, fingerprint, <one of ok|error|request|fault>}``.
+
+Op table (fixed): ``init``, ``parse_closeout``, ``closeout_request``,
+``evidence_request``, plus ``env`` when ``init`` carried ``test_mode``.  An op
+before ``init`` or a second ``init`` is answered with a ``fault``.  Any
+exception raised by an op (``BaseException``, including ``BamlPanic``) is
+returned as a ``fault``; the client then discards and kills the worker.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+
+_OP_FUNCTIONS = {
+    "parse_closeout": ("user.phase_loop_parse_closeout", ("raw",), ("ok", "error")),
+    "closeout_request": (
+        "user.phase_loop_closeout_request",
+        ("phase_alias", "plan_produces", "plan_owned_files", "closeout_commit_sha"),
+        ("request",),
+    ),
+    "evidence_request": (
+        "user.phase_loop_evidence_request",
+        ("tier2_signal_summary", "sample_artifact_content", "expected_artifact_characteristics"),
+        ("request",),
+    ),
+}
+# The client caps a request frame at 4 MiB + 1 KiB; anything larger here is a
+# client bug or a hostile writer, and is refused rather than buffered forever.
+_MAX_REQUEST_LINE = 4 * 1024 * 1024 + 1024 + 4096
+_WATCHDOG_INTERVAL_S = 0.5
+_PR_SET_PDEATHSIG = 1
+
+
+def fingerprint(files: dict[str, str]) -> str:
+    canonical = json.dumps(files, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+    return hashlib.sha256(canonical.encode("ascii")).hexdigest()
+
+
+def _set_pdeathsig(owner_pid: int) -> None:
+    import ctypes
+    import signal
+
+    # ctypes.CDLL(None) resolves prctl on glibc and musl alike; find_library("c")
+    # and "libc.so.6" do not work on musl.
+    libc = ctypes.CDLL(None, use_errno=True)
+    if libc.prctl(_PR_SET_PDEATHSIG, int(signal.SIGKILL), 0, 0, 0) != 0:
+        os._exit(70)
+    # The owner may have died between our fork and the prctl.
+    if os.getppid() != owner_pid:
+        os._exit(0)
+
+
+def _start_watchdog(owner_pid: int) -> None:
+    import threading
+    import time
+
+    def watch() -> None:
+        while True:
+            if os.getppid() != owner_pid:
+                os._exit(0)
+            time.sleep(_WATCHDOG_INTERVAL_S)
+
+    threading.Thread(target=watch, name="baml-worker-watchdog", daemon=True).start()
+
+
+class _Worker:
+    def __init__(self, out_fd: int, no_pdeathsig: bool) -> None:
+        self.out_fd = out_fd
+        self.no_pdeathsig = no_pdeathsig
+        self.fp: str | None = None
+        self.fns: dict[str, object] | None = None
+        self.test_mode = False
+
+    def send(self, obj: dict) -> None:
+        data = (json.dumps(obj, separators=(",", ":"), ensure_ascii=True) + "\n").encode("ascii")
+        view = memoryview(data)
+        while view:
+            written = os.write(self.out_fd, view)
+            view = view[written:]
+
+    def handle(self, line: bytes) -> None:
+        req_id = None
+        try:
+            req = json.loads(line.decode("ascii"))
+            if not isinstance(req, dict):
+                raise ValueError("request is not a JSON object")
+            req_id = req.get("id")
+            op = req.get("op")
+            if op == "init":
+                result = self.init(req)
+                self.send({"id": req_id, "fingerprint": self.fp, "ok": result})
+                return
+            if self.fns is None:
+                raise RuntimeError(f"op before init: {op!r}")
+            if op == "env" and self.test_mode:
+                self.send({"id": req_id, "fingerprint": self.fp, "ok": {"env": sorted(os.environ), "cwd": os.getcwd(), "pid": os.getpid()}})
+                return
+            if op not in _OP_FUNCTIONS:
+                raise RuntimeError(f"unknown op: {op!r}")
+            _name, params, keys = _OP_FUNCTIONS[op]
+            args = req.get("args")
+            if not isinstance(args, dict) or set(args) != set(params):
+                raise RuntimeError(f"bad args for {op}")
+            out = self.fns[op](**args)
+            if not isinstance(out, dict) or len(out) != 1:
+                raise RuntimeError(f"bridge {op} returned an unexpected shape")
+            ((key, value),) = out.items()
+            if key not in keys or not isinstance(value, str):
+                raise RuntimeError(f"bridge {op} returned key {key!r}")
+            self.send({"id": req_id, "fingerprint": self.fp, key: value})
+        except BaseException as exc:  # noqa: BLE001 - every op failure is a typed fault
+            message = f"{type(exc).__module__}.{type(exc).__qualname__}: {str(exc)[:500]}"
+            self.send({"id": req_id, "fingerprint": self.fp, "fault": message})
+
+    def init(self, req: dict) -> dict:
+        if self.fns is not None:
+            raise RuntimeError("second init")
+        self.test_mode = req.get("test_mode") is True
+        if self.no_pdeathsig and not self.test_mode:
+            raise RuntimeError("--no-pdeathsig requires test_mode")
+        for entry in req.get("sys_path") or []:
+            if isinstance(entry, str) and os.path.isabs(entry) and entry not in sys.path:
+                sys.path.append(entry)
+        files = req.get("files")
+        if not isinstance(files, dict) or not all(isinstance(k, str) and isinstance(v, str) for k, v in files.items()):
+            raise RuntimeError("init files must be a map of strings")
+        import baml_bridge
+
+        baml_bridge.BamlRuntime.initialize_runtime("baml_src", files)
+        fns = {op: baml_bridge.define_function(name, "sync", list(params)) for op, (name, params, _keys) in _OP_FUNCTIONS.items()}
+        self.fp = fingerprint(files)
+        self.fns = fns
+        return {"version": baml_bridge.get_version(), "pid": os.getpid()}
+
+    def serve(self) -> None:
+        buf = b""
+        while True:
+            chunk = os.read(0, 1 << 16)
+            if not chunk:
+                return  # stdin EOF: the graceful shutdown path
+            buf += chunk
+            while True:
+                newline = buf.find(b"\n")
+                if newline < 0:
+                    break
+                line, buf = buf[:newline], buf[newline + 1 :]
+                self.handle(line)
+            if len(buf) > _MAX_REQUEST_LINE:
+                self.send({"id": None, "fingerprint": self.fp, "fault": "request line over cap"})
+                return
+
+
+def main(argv: list[str]) -> int:
+    owner_pid = int(argv[1])
+    allowlist = {key for key in argv[2].split(",") if key} if len(argv) > 2 else set()
+    no_pdeathsig = "--no-pdeathsig" in argv[3:]
+
+    out_fd = os.dup(1)
+    os.dup2(2, 1)
+    sys.stdout = sys.stderr
+
+    # Normalize the environment before baml_bridge is ever imported: this drops
+    # interpreter-injected keys (C-locale coercion's LC_CTYPE,
+    # __PYVENV_LAUNCHER__) that the parent's allowlist never passed.
+    for key in list(os.environ):
+        if key not in allowlist:
+            del os.environ[key]
+    # The v1 runtime keeps a profile store of call data under the working
+    # directory (``.baml/profiles-v1``) unless profiling is off.  Forced, not
+    # defaulted: no call data is ever written to disk, whatever was passed in.
+    os.environ["BAML_PROFILE"] = "0"
+    os.environ.pop("BAML_PROFILE_DIR", None)
+
+    if os.name == "posix":
+        if sys.platform.startswith("linux") and not no_pdeathsig:
+            _set_pdeathsig(owner_pid)
+        elif os.getppid() != owner_pid:
+            os._exit(0)
+        _start_watchdog(owner_pid)
+    # Windows: the parent's Job Object (KILL_ON_JOB_CLOSE) enforces owner death.
+
+    _Worker(out_fd, no_pdeathsig).serve()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

{phase_loop_runtime-0.7.22 → phase_loop_runtime-0.7.23}/src/phase_loop_runtime/adoption_bundle.py

@@ -16,6 +16,7 @@ C4_DOCUMENT = Path("docs/c4/phase-loop-runtime-c4-document.md")
 TASK_CATALOG = Path("docs/tasks/dotfiles-task-catalog.md")
 RUNTIME_PROJECTION_SURFACE = "phase-loop status --runtime-projection --json"
 BAML_SCHEMA_ROOT = Path("vendor/phase-loop-runtime/src/phase_loop_runtime/baml_src")
+BAML_BRIDGE_SOURCE = "phase_loop_bridge.baml"
 ADOPTION_BUNDLE_PATH = Path("docs/adoption/dotfiles-adoption-bundle.json")
 
 
@@ -143,6 +144,8 @@ def _source_roots(repo: Path) -> list[dict[str, str]]:
 def _schema_refs(repo: Path) -> list[dict[str, str]]:
     refs: list[dict[str, str]] = []
     for path in sorted((repo / BAML_SCHEMA_ROOT).glob("*.baml")):
+        if path.name == BAML_BRIDGE_SOURCE:
+            continue  # host glue with no classes, not a schema (agent-harness#1135 #26)
         source_path = _repo_relative(repo, path)
         refs.append(
             {

{phase_loop_runtime-0.7.22 → phase_loop_runtime-0.7.23}/src/phase_loop_runtime/advisor_board/CONTRACTS.md

@@ -337,7 +337,153 @@ the caller passes a PATH and the runtime reads it.
   (`max_age_s = 24h`) sweep of `pl-panel-*` dirs, called at the top of
   `_default_spawn`. Reclaims dirs leaked when a run is KILLED before the per-run
   `finally: rmtree` (timeout/crash); a concurrent run's fresh dir is never touched,
-  and a GC failure can NEVER affect the run (fully swallowed).
+  and a GC failure can NEVER affect the run (fully swallowed). It sweeps both the
+  current staging root and the system temp dir, where releases before
+  agent-harness#1147 staged.
+- **Staging root and retention (agent-harness#1147, `sandbox_policy`).**
+  - **Invariant.** Sandbox staging and spawned-CLI scratch are never RAM-backed while a
+    disk-backed candidate is usable. Otherwise they run in a typed DEGRADED mode
+    (`ScratchLocation.degraded`): one warning and hard-clamped retention, and the round is
+    never crashed. `PHASE_LOOP_SANDBOX_REFUSE_RAM=1` refuses instead (leg detail
+    `env_failure: no disk-backed scratch and RAM fallback refused`).
+  - **RAM-backed** means a Linux tmpfs or ramfs, identified by the device serving the path
+    (`st_dev` matched against `/proc/self/mountinfo`), so overmounts and moved mounts are
+    judged correctly. macOS and Windows temp dirs count as disk.
+  - **Named exceptions**, each a typed scratch decision (`child_scratch_env`): the agy
+    qualification and capture jails keep a tmpfs `/tmp` and their frozen env, because they
+    are qualification evidence (follow-up agent-harness#1179); and the Gemini HEARTBEAT
+    seat's jail mounts its own private `/tmp` (agent-harness#1181). Neither covers a
+    bounded Gemini leg or the bounded Gemini president, which run on the host.
+  - **Staging root.** Each round's `pl-panel-*` scratch, and the sandbox clone inside it,
+    is created under `staging_root()`. That is `PHASE_LOOP_SANDBOX_STAGING_DIR` when set;
+    otherwise `phase-loop/sandboxes` in the platform's per-user cache dir (`$XDG_CACHE_HOME`
+    or `~/.cache` on Linux, `~/Library/Caches` on macOS, `%LOCALAPPDATA%` on Windows); else
+    the system temp dir when it is not RAM-backed. `TMPDIR` is not the override. The
+    launcher's agy review copy (without a run log) and the falsifier's stage and
+    dependency snapshot use the same root. Every directory the runtime creates below the
+    cache dir is created 0700 and must be a real directory owned by this account.
+  - **Capacity.** Filesystem size comes from `shutil.disk_usage`, which works on every
+    platform.
+    - Retention ceiling: `min(PHASE_LOOP_SANDBOX_MAX_TOTAL_BYTES (40 GiB), 25% of the
+      filesystem)`, or 10% on a RAM-backed one.
+    - Default floor: 2 GiB capped at 25% of the filesystem, or 25% of a RAM-backed one.
+    - A floor that is configured (by the setting's presence) is used verbatim.
+  - **Reaping.** Before a round is refused for space, retained sandboxes are reaped
+    oldest-first. The TTL, footprint and free-space reaps all skip a sandbox whose owning
+    process is still running. The owner marker is published atomically (temp file, fsync,
+    rename).
+  - **Other knobs:** `PHASE_LOOP_SANDBOX_ROOT` (the selected root, recorded in the
+    evidence; see the placement seam below), `PHASE_LOOP_SANDBOX_REMOTE_REQUIRED`,
+    `PHASE_LOOP_SANDBOX_TTL_S` (24 h), `PHASE_LOOP_SANDBOX_PROBE_TIMEOUT_S`,
+    `PHASE_LOOP_SANDBOX_ARCHIVE_DEST`, `PHASE_LOOP_SANDBOX_DISABLE`.
+- **Sandbox placement seam (agent-harness#896, `sandbox_placement`).** One vendor-neutral
+  seam, several backends. The built-in `LocalBackend` is today's path; a remote host or a
+  cloud sandbox registers a backend under a URL scheme, directly or through the
+  `phase_loop_runtime.placement_backends` entry-point group, which is loaded only when a
+  configured root names that scheme. Core names no vendor.
+  - **Phases, in order, for every backend.** `prepare` is runtime code
+    (`prepare_local_stage`: stage locally, owning the partial stage until it returns), never
+    a backend method. The runtime's revalidations then run against that local stage,
+    unchanged. `commit` transfers the revalidated stage (a no-op locally); it owns any
+    partial remote state until it returns and the backend recomputes the digest. `execute` /
+    `wait` / `cancel` / `renew` are the runtime's own launch branches locally. `release`
+    removes the stage. Code never leaves the operator's custody before revalidation.
+  - **Launch is final.** Once `execute` is called, even if it raised, the attempt is
+    launched: it never falls back to local, and a retry in the same round reuses the same
+    backend or refuses.
+  - **Receipts.** Backends return `BackendReceipt`s only. Only the runtime builds a
+    `PlacementReceipt(attested_by="runtime")`, for a step it performed and observed
+    (`prepared`, `committed`, `launched` -- `execute` called, or a local provider process
+    the runtime started, counted once `Popen` returned; a launch that fails to exec is not
+    one, and infrastructure launches such as the egress namespace holder and its uplink are
+    never counted -- and `completed`). A backend's claim is recorded as `attested_by="backend"`. Every
+    receipt carries `sandbox_ref` (`[A-Za-z0-9._:-]{1,128}`, anything else refuses the
+    placement) and `snapshot_sha256`, which the runtime computes from the local stage.
+  - **`sandbox_root_applied`.** Local: the built-in backend, no host, and the root is the
+    stage's parent. Non-local: runtime-attested `committed` and `completed` share one
+    `sandbox_ref`, both carry the authorization's staged-tree digest, the leg spawned no
+    local provider, and any backend receipts agree. Backend receipts alone never make it
+    true. `sandbox_staged_at` is the path locally and `<scheme>:<sandbox_ref>` otherwise.
+  - **Capabilities and declarations.** `capabilities()` is what a backend can enforce, from
+    a closed set (`private_ranges_unreachable`, `public_egress`, `private_allowlist`,
+    `inbound_closed`, `filesystem_confined`, `uid_isolated`, `bounding_set_empty`,
+    `seccomp_filtered`, `resource_bounded`, `one_shot_secret_channel`, `operator_custody`).
+    `verified` maps a capability verified for this placement to `runtime_end_to_end` (only
+    the runtime writes it) or `backend_attested`, and is a subset of `capabilities()`.
+    `LocalBackend.capabilities()` is empty: local egress and uid facts stay in their own
+    fields. `declaration()` names the backend's egress residuals (closed kinds, each with
+    `closed_in_guest`), the control-plane variables it injects into the guest (values
+    redacted), and `max_lifetime_s`.
+  - **Roots.** `PHASE_LOOP_SANDBOX_ROOT` is the single-root form. Otherwise the user
+    config's `[sandbox]` table in `advisor-boards.toml` names one root per remote backend
+    (`roots.self-hosted = "https://…"`, `roots.e2b = "e2b://…"`) and the order to try them
+    (`order`, default `["self-hosted", "e2b"]`; named roots it omits follow in file order).
+    The single root is an alias for one backend and, when set, the only candidate. A
+    malformed table or unknown key raises `sandbox_config_invalid`; a repository file cannot
+    carry `[sandbox]`. Candidates are tried in order and the first usable one is chosen;
+    each one passed over adds `<name>: <reason>` to `sandbox_root_reason`.
+  - **Root parsing.** A value is stripped; anything containing `://` is a URL and keeps only
+    scheme, host, port and path. A malformed scheme (`sandbox_root_scheme_invalid`), a
+    built-in scheme written as a URL (`sandbox_root_scheme_builtin`), and a non-URL value
+    with `user:…@` or a query (`sandbox_root_unrecognised`) are refused without a probe and
+    rendered as a placeholder. No warning, reason, recorded path or probe argument is built
+    from the configured text; all use the parsed form.
+  - **Execution gate.** A build calls a non-local backend's methods only if its own driver
+    executes on that backend (`panel_invoker._NONLOCAL_EXECUTION_DRIVER`). This release has
+    no such driver: root selection passes over every non-local backend before `prepare` and
+    before any of its methods, and the leg falls back to local with
+    `sandbox_root_fell_back=true` and a reason naming the root and
+    `sandbox_placement_driver_unavailable`.
+  - **Fail-closed knob.** `PHASE_LOOP_SANDBOX_REMOTE_REQUIRED` (`1`/`true`/`yes`/`on`; any
+    unrecognised value is on) refuses a seat leg -- every review-mode leg `_default_spawn`
+    launches for a board seat, tree or no tree -- unless the runtime ran it through a remote
+    backend's `execute`. Exemption is by execution, never by where placement came from, so
+    in this release it refuses every seat leg, before any root is probed or anything is
+    staged, with detail `sandbox_placement_required_unavailable`. Advisory-mode boards are
+    not seat legs and are not governed by it.
+  - **Evidence.** The leg's placement record (`sandbox_placement_backend`,
+    `sandbox_placement_receipts`, `sandbox_placement_verified`,
+    `sandbox_local_provider_spawns`, `sandbox_snapshot_sha256` -- the authorization's
+    digest) is recorded right after `prepare` and travels on
+    `PanelLegResult.sandbox_placement_evidence` on every exit, failures included; the
+    runner persists it in the leg's `implementation-panel-<leg>.json`. The local spawn count
+    is read when the record is serialized. Every exit, including egress teardown raising,
+    releases the stage and resets the leg's facts and spawn counter. A brokered leg's broker evidence
+    carries the same keys, and `scripts/verify_harden_evidence.py` enumerates them and
+    checks the `applied` rule for the recorded backend.
+- **Spawned CLI scratch (agent-harness#1147, `fill_child_tmp_env`).** Agent CLIs write
+  large scratch of their own; Claude Code uses `$CLAUDE_CODE_TMPDIR`, else the temp dir
+  (`/tmp/claude-<uid>`).
+  - **What is filled.** Each of `TMPDIR` and `CLAUDE_CODE_TMPDIR` that the child env does
+    not already set is judged against its own default destination. If that destination is
+    RAM-backed, the variable is set to a private (0700, ours) disk-backed per-user dir that
+    is above its free-space floor: `phase-loop/tmp` in the cache dir, else
+    `phase-loop-<uid>/tmp` under the temp dir.
+  - **Where it applies.** Every review-provider launch: `panel_invoker.launch_provider` /
+    `run_provider` apply `child_scratch_env` to the env they launch with, and only the
+    named exceptions can opt out (`child_scratch=`). The env builders fill too, so the
+    recorded provider evidence matches the launch: board legs and advisory seats
+    (`_subscription_env`, the `_exec_leg` explicit-env route), brokered legs including
+    bounded Gemini, and both presidents (`_broker_leg_env`). Outside the provider
+    interface: executors (`child_executor_env`) and convergence adapters
+    (`_child_environment`). The Agent View executor's `claude --bg` goes through the
+    interface: `ClaudeAgentViewAdapter`'s default runner calls `run_provider` with an
+    explicit env. A bounded brokered agy leg's owned HOME is created in the
+    relocated dir as well. A decision returns a `DecidedEnv` labelled
+    `PHASE_LOOP_SCRATCH_DECIDED=<decision>` and recorded by object identity
+    (`sandbox_policy.decided_scratch`). The test suite's audit hook
+    (`tests/_scratch_audit_hook.py`) -- a regression tripwire, not an adversarial boundary
+    -- fails any test in which the runtime spawns an agent CLI, named from the runtime's own
+    harness registries, with an env object that is not one a decision returned, whatever
+    API spawns it. That is the completeness check. `tests/test_agent_cli_scratch_inventory_1147.py` is a static early
+    warning: it enumerates every process launch in the package and fails on one with no
+    stated decision. It is conservative: an unresolvable use of a launch-capable module (a computed `getattr`,
+    `__dict__`, the module as a value, a dynamic import, `exec`/`eval`) needs a stated
+    decision too. Env builders (`_broker_subscription_env`, `scrub_subscription_env`)
+    take no decision; each route decides after building, so a named exception is never
+    refused by a relocation it is exempt from.
+  - **Overrides.** A value the caller set is never overridden. The brokered allowlist
+    still drops ambient values, so there only the runtime's own dir can appear.
 - **Golden byte-identity preserved.** No ref ⇒ identical staged bytes ⇒ identical
   per-leg argv / env / timeout. `tests/test_advisor_board_golden.py` (Proof A hits
   `_exec_leg`; Proof B injects `spawn=`) is untouched;
@@ -742,8 +888,9 @@ The Linux x64 subscription `agy` entry image must match one member of the closed
 set `gemini_heartbeat.QUALIFIED_IMAGES`: 1.2.11 SHA256
 `ec7cf797ecb0e1d91ddf3b6d9d6c1d616bb89f78a5b0e43536b72a7fce695f56`, 1.2.12 SHA256
 `ce6fdd9e7621ee9ac6eedaa337731ca1f235e412ff57cf9eabcd2aa23b3576ca`, 1.2.14 SHA256
-`0d0d3eba22daf29504dd290151c7ed9a4d33b0c6aa0acfc5da27bc3b01d2f029` or 1.2.15 SHA256
-`5f9c16b286895f8f7fdecd423883ca256a85077b8acf9a6bc1111761d34df164`. Each member
+`0d0d3eba22daf29504dd290151c7ed9a4d33b0c6aa0acfc5da27bc3b01d2f029`, 1.2.15 SHA256
+`5f9c16b286895f8f7fdecd423883ca256a85077b8acf9a6bc1111761d34df164` or 1.2.16 SHA256
+`a759ce7c7a235d9b6c281a25ead97cbbf2e92314a3ffd224e2f9144f3fae7a86`. Each member
 carries its measured help digest and has its own qualification record; the
 evidence catalog and the runtime set must name exactly the same members.
 The running Python/kernel must support sealed memfds, pidfds and pidfd signaling;

{phase_loop_runtime-0.7.22 → phase_loop_runtime-0.7.23}/src/phase_loop_runtime/advisor_board/config.py

@@ -30,6 +30,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 from dataclasses import dataclass
 from pathlib import Path
+import re
 from typing import Any, Callable
 
 try:  # Python 3.11+
@@ -51,7 +52,7 @@ from .schema import (
 )
 
 # Recognised keys — anything else is a hard error (no silent drop).
-_KNOWN_TOP_KEYS: frozenset[str] = frozenset({"default_board", "boards", "president", "agy"})
+_KNOWN_TOP_KEYS: frozenset[str] = frozenset({"default_board", "boards", "president", "agy", "sandbox"})
 # A repository file configures the president ladder only: repo-level boards are not a
 # feature, so a ``[[boards]]`` there is refused rather than silently ignored.
 _KNOWN_REPO_TOP_KEYS: frozenset[str] = frozenset({"president"})
@@ -59,6 +60,11 @@ _KNOWN_PRESIDENT_KEYS: frozenset[str] = frozenset({"ladder"})
 # agent-harness#1076 D3: the USER file's ``[agy] self_qualification = false`` restores the
 # hard refusal of a non-release agy image. A repository file cannot carry it.
 _KNOWN_AGY_KEYS: frozenset[str] = frozenset({"self_qualification"})
+# agent-harness#896: the USER file's ``[sandbox]`` names one root per remote placement
+# backend and the order to try them in. A repository file cannot carry it: roots name hosts.
+_KNOWN_SANDBOX_KEYS: frozenset[str] = frozenset({"roots", "order"})
+DEFAULT_SANDBOX_BACKEND_ORDER: tuple[str, ...] = ("self-hosted", "e2b")
+_SANDBOX_BACKEND_NAME = re.compile(r"[a-z0-9][a-z0-9-]{0,62}")
 # Repository-level config, relative to the repository root.
 REPO_CONFIG_RELATIVE_PATH = ".agent-harness/advisor-boards.toml"
 _KNOWN_BOARD_KEYS: frozenset[str] = frozenset(
@@ -226,6 +232,46 @@ def _parse_agy(data: Mapping[str, Any], where: str) -> bool:
     return _require_bool(raw, "self_qualification", True, f"{where} [agy]")
 
 
+def _parse_sandbox(data: Mapping[str, Any], where: str) -> tuple[tuple[str, str], ...]:
+    """The user file's ``[sandbox]``, validated: ``(name, root)`` in the order to try them."""
+    raw = data.get("sandbox")
+    if raw is None:
+        return ()
+    if not isinstance(raw, Mapping):
+        raise BoardConfigError(f"{where}: 'sandbox' must be a table")
+    _reject_unknown(raw.keys(), _KNOWN_SANDBOX_KEYS, f"{where} [sandbox]")
+    roots = raw.get("roots", {})
+    if not isinstance(roots, Mapping):
+        raise BoardConfigError(f"{where} [sandbox]: 'roots' must be a table")
+    for name, root in roots.items():
+        # The root is never echoed: it may carry a credential.
+        if not isinstance(name, str) or not _SANDBOX_BACKEND_NAME.fullmatch(name):
+            raise BoardConfigError(f"{where} [sandbox] roots: invalid backend name")
+        if not isinstance(root, str) or not root.strip():
+            raise BoardConfigError(f"{where} [sandbox] roots.{name}: must be a non-empty string")
+    order = raw.get("order", list(DEFAULT_SANDBOX_BACKEND_ORDER))
+    if (
+        not isinstance(order, list)
+        or any(not isinstance(n, str) or not _SANDBOX_BACKEND_NAME.fullmatch(n) for n in order)
+        or len(set(order)) != len(order)
+    ):
+        raise BoardConfigError(f"{where} [sandbox] order: must be a list of distinct backend names")
+    ranked = [n for n in order if n in roots] + [n for n in roots if n not in order]
+    return tuple((name, str(roots[name]).strip()) for name in ranked)
+
+
+def load_sandbox_roots(*, path: Path | None = None) -> tuple[tuple[str, str], ...]:
+    """agent-harness#896: the configured remote placement roots, ``(backend name, root)``,
+    first to try first. Named roots the ``order`` omits follow, in file order. Reads the
+    user file only. A malformed table or an unknown key is a ``BoardConfigError``."""
+    user_path = path if path is not None else board_config_path(None)
+    user = _load_toml(user_path)
+    if user is None:
+        return ()
+    _reject_unknown(user.keys(), _KNOWN_TOP_KEYS, str(user_path))
+    return _parse_sandbox(user, str(user_path))
+
+
 def load_agy_self_qualification(*, path: Path | None = None) -> bool:
     """D3 (agent-harness#1076): whether first-use self-qualification is enabled.
 
@@ -372,6 +418,7 @@ def load_boards(
         _reject_unknown(data.keys(), _KNOWN_TOP_KEYS, str(cfg_path))
         _parse_president(data, str(cfg_path))  # a bad [president] fails at load too
         _parse_agy(data, str(cfg_path))  # and a bad [agy] (agent-harness#1076)
+        _parse_sandbox(data, str(cfg_path))  # and a bad [sandbox] (agent-harness#896)
         raw_boards = data.get("boards", [])
         if not isinstance(raw_boards, list):
             raise BoardConfigError(f"{cfg_path}: 'boards' must be an array of tables")