ph-runtime-guest 0.1.0__tar.gz

ph_runtime_guest-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Build and environment
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+jjt/
+w2/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+# Written by the guest's subprocess collectors and combined at the end of the
+# run; see `conftest.GUEST_COVERAGE_RC`.
+.coverage-guest*
+htmlcov/
+# Dropped at the repo root by pytest-textual-snapshot when a snapshot test
+# fails. The reference snapshots under `__snapshots__/` are the committed
+# expectation; this is the diff viewer for a run that did not match one.
+snapshot_report.html
+
+# Reference checkouts of the upstream projects this port reads from. Vendored
+# locally so the plans' citations are verifiable; never part of this repo.
+sources/
+
+# Local scratch
+.ph/
+*.local.yaml

ph_runtime_guest-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Charles Tabor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ph_runtime_guest-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: ph-runtime-guest
+Version: 0.1.0
+Summary: The guest half of pH's code runtime: the fd-3 protocol, the run loop, and the binding proxies a cell awaits.
+Project-URL: Homepage, https://github.com/chastabor/pH
+Project-URL: Repository, https://github.com/chastabor/pH
+Project-URL: Documentation, https://github.com/chastabor/pH/blob/main/docs/README.md
+Project-URL: Issues, https://github.com/chastabor/pH/issues
+Author: Charles Tabor
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,code-mode,runtime,sandbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: dill>=0.3.8
+Description-Content-Type: text/markdown
+
+# ph-runtime-guest
+
+*The other side of the process boundary: the interpreter the model's code
+actually runs in.*
+
+pH's Python code runtime is two halves in two venvs. The **host** half is
+[`ph_rlm.kernel`](../ph-rlm/), which spawns and governs; this is the **guest** —
+it runs inside `$PH_CACHE/runtime-venv`, in a subprocess the host starts per
+agent, and reaches the host over one newline-delimited JSON channel on **fd 3**.
+
+It imports neither `ph-core` nor `ph-rlm`, and that is the whole point: the
+process boundary exists so that model-written code cannot reach the harness, and
+importing the harness would put it back inside. Its only dependency is `dill`,
+imported lazily — a venv without it still runs cells and forgoes snapshots.
+
+One module bends that without breaking it. `_json.py` holds the narrowings this package needs out of `ph.json` — one today, `as_str` — copied rather than imported for the reason above: that module ships in the ph-core wheel, and depending on the wheel is what this package exists not to do. `test_protocol_mirror.py` compares each definition against ph-core's character for character — it holds this package's other copy, `truncation_marker`, to `ph.text`'s in the same file — so a copy that drifts fails there rather than in a guest.
+
+```bash
+python -m ph_runtime          # how the host spawns it; not a command you type
+```
+
+**This package registers no rows.** It has no `ph.plugins` and no `ph.bundles`
+entry point, is never mounted, and appears in no profile. Everything about it is
+governed from the other side — see *Configuring it* below.
+
+## What it provides
+
+| module | what it owns |
+|---|---|
+| `channel` | newline-delimited JSON over one duplex descriptor. `json.dumps` never emits a literal newline, so a line is exactly a frame |
+| `protocol` | the fd-3 frame vocabulary, guest side — written twice on purpose, and `FRAME_FIELDS` is the *only* declaration of it here |
+| `runner` | the run loop: one process, many cells, one namespace, runs serialized |
+| `cell` | compiling one cell so that top-level `await`, top-level `return` and cross-cell persistence all hold at once |
+| `proxies` | what the model sees in `globals()`: namespaces whose every call is a governed dispatch |
+| `skill` | Python skills as pre-imported callables |
+| `limits` | `RLIMIT_CPU`, address space and log caps, applied in the child before it reports ready |
+| `lifecycle` | dying with the parent, per platform |
+| `snapshot` | per-variable serialization for `kernel/snapshot` |
+| `errors` | the two failures a cell can see, and the line between them |
+
+### Compiling a cell
+
+Three requirements pull against each other, and reconciling them is the only
+interesting thing in `cell.py`. Top-level `await` needs the program to be a
+coroutine on the child's one loop. Top-level `return` is a syntax error in
+module code even with `PyCF_ALLOW_TOP_LEVEL_AWAIT`, so the body is wrapped in an
+`async def` — which makes the first fall out for free. But a name assigned
+inside a function is *local* to it, so the naive wrapping would lose every
+variable the cell defined and quietly undo the persistent namespace. So the
+wrapper declares every name the cell binds at its top level as `global`,
+computed from the AST including the cases that are easy to forget — `import`,
+`with … as`, `for`, `except … as`, walrus, `del`, and function and class
+definitions. A trailing expression becomes the cell's value, as in a REPL.
+
+### What the model sees
+
+The programming model is prime-agent's, deliberately and exactly:
+
+```python
+files = await tools.glob(pattern="src/**/*.py")
+child = await rlm.run("review this diff", name="reviewer")
+await agent_message.send("done", receiver_role="parent")
+answer = await websearch(query="…")  # a skill: module-as-callable
+```
+
+Namespaces are built from what the **`boot` frame declared**, not from a list in
+this package, so a namespace a plugin adds reaches the cell without this module
+changing (I1, I7). Unknown attributes and unknown keyword arguments fail loudly
+with the available names in the message — the reader is a model, and a silent
+`None` is how a cell spends a turn discovering a capability it invented does not
+exist. A skill that fails to import binds a **stub that explains itself** rather
+than leaving the name undefined, for the same reason.
+
+### Cancellation, three mechanisms for three situations
+
+The channel is read by one task and a cell runs in another — otherwise a cell
+awaiting `tools.read(...)` would be blocked on a reply its own loop was supposed
+to deliver, which is the classic control-channel deadlock and the reason fd 3 is
+not the channel a run occupies (D5). On top of that:
+
+- awaiting a reply or a sleep → the `cancel` frame, or the `SIGINT` callback,
+  cancels the cell's task. `SIGINT` is installed with
+  `loop.add_signal_handler`, **not** the default handler: that one raises
+  `KeyboardInterrupt` into whatever frame is executing, and when a cell is
+  `await`ing that frame is `asyncio`'s own — so the signal killed the entire
+  guest instead of the cell, in the common case rather than a rare one;
+- spinning in Python → the loop is starved, so neither arrives. `SIGXCPU` from
+  the per-run CPU budget lands in the cell's own frame, because it is executing
+  bytecode, which is exactly why it is unreachable by the others;
+- neither works in time → the host escalates to `SIGKILL` and restarts. The
+  namespace is lost and the model is told so, which beats a wedged kernel.
+
+### Dying with the parent
+
+The OS does not do what one would hope: a parent's death does not kill its
+children (POSIX re-parents them to PID 1) and `atexit` never runs under
+`SIGKILL`. Each platform needs its own mechanism and only one is in the guest's
+gift — **Linux** sets `prctl(PR_SET_PDEATHSIG, SIGKILL)` here; **macOS** has no
+equivalent, so a daemon thread watches `os.getppid()` and `os._exit`s when it
+changes; **Windows** is the host's job, a Job Object with `KILL_ON_JOB_CLOSE`.
+The host's orphan journal is the backstop for all three.
+
+## Configuring it
+
+Nothing here is configured directly. Every knob belongs to `ph-rlm`'s
+`code-runtime-python` row, which spawns this package and sends the `boot` frame
+that parameterises it — and the **host owns every default**, because there are
+two definitions of the protocol across the two sides and exactly one owner of
+each value. `boot` carries every limit as a required field, so a guest has
+nothing to guess and a changed default cannot mean two things at once.
+
+```yaml
+- id: code-runtime-python
+  config:
+    python: managed          # which interpreter runs model code
+    cpuSeconds: 30           # per cell, not per kernel — RLIMIT_CPU is re-armed each run
+    addressSpaceBytes: 2147483648
+    maxLogBytes: 65536       # per stream
+    maxValueBytes: 65536     # per snapshotted variable
+    maxSnapshotBytes: 16777216
+    skills: ["acme-websearch"]
+```
+
+`python: managed` is what *creates* the venv this package lives in: `uv venv
+--seed` at `$PH_CACHE/runtime-venv`, then `uv pip install ph-runtime-guest` (the
+checkout's own source directory when pH is running from one) plus each
+configured skill — a local skill directory **editable**, because the staleness
+marker digests the specs rather than their contents. `python: host` runs the
+guest on pH's own interpreter instead: fast, needs no `uv` and no network, and
+what the test suite uses — and also what puts `ph-core`, pydantic and Textual on
+the child's `sys.path`, which is a wider surface and the reason it is not the
+default. `$PH_RUNTIME_PYTHON` (or `interpreter:`) is the third answer.
+
+Staleness is a marker file (`.ph-runtime.json`), not a heuristic: it records the
+protocol version, this package's version and the skill set, and any difference
+rebuilds. A guest one protocol behind would otherwise be discovered as a refused
+`boot` at the first cell of somebody's session (D7).
+
+See [`ph-rlm`'s README](../ph-rlm/README.md#including-it-and-adjusting-it) for
+the full row table.
+
+## Limitations, and things that are deliberate
+
+- **The protocol is written twice and neither side imports the other.**
+  `ph_rlm.kernel.protocol` is the twin. What keeps them honest is
+  `packages/ph-rlm/tests/test_protocol_mirror.py`, which compares
+  `PROTOCOL_VERSION`, every frame's required and optional field set, and the
+  truncation marker byte for byte. **That test is the contract**; there is no
+  shared module to fall back on.
+- **A refusal is not catchable.** `ToolFailed` is the program's to handle — a
+  timeout, a bad argument, a missing file — and catching it to try something
+  else is exactly right. `RunStopped` derives from `BaseException` so
+  `except Exception` cannot swallow it, because a program that can catch a
+  refusal can route around it (C3). A CPU budget raises the same way.
+- **Runs are serialized.** One namespace, one program at a time.
+- **Snapshots are per variable, and some things are never captured.** An
+  unchanged 200 MiB DataFrame emits nothing because its digest did not move. A
+  definitively-immutable value is compared by *identity* — deliberately not
+  extended to tuples or frozensets, since `t = ([1],)` keeps its identity while
+  its contents change, and a fast path that is wrong once is worse than none.
+  The binding proxies, the imported skill modules and anything else the
+  bootstrap put in `globals()` are excluded: they are rebuilt from the `boot`
+  frame, so pickling them would store a stale copy of the harness's own surface.
+- **The C pickler is tried first**, with `dill` as the fallback for what it
+  refuses (a cell-defined function, class or lambda). Each object takes the same
+  path every time, so digests stay stable — and `dill.loads` reads standard
+  pickle bytes unchanged either way.
+- **This package must stay nearly dependency-free.** Every dependency in the
+  runtime venv is another import model code can reach and another thing that can
+  break a session the host cannot repair.
+
+## Tests
+
+Its suite lives with the host half, in `packages/ph-rlm/tests/` — the mirror
+test above, plus `test_kernel.py` (the process boundary), `test_codec.py` (the
+decoder, fuzzed), `test_lifecycle.py`, `test_snapshot.py`, `test_venv.py` and
+`test_runtime_integration.py`. Testing the guest from the host's side is the
+honest arrangement: what matters is that the two halves agree, and only a test
+that holds both can say so.

ph_runtime_guest-0.1.0/README.md

@@ -0,0 +1,179 @@
+# ph-runtime-guest
+
+*The other side of the process boundary: the interpreter the model's code
+actually runs in.*
+
+pH's Python code runtime is two halves in two venvs. The **host** half is
+[`ph_rlm.kernel`](../ph-rlm/), which spawns and governs; this is the **guest** —
+it runs inside `$PH_CACHE/runtime-venv`, in a subprocess the host starts per
+agent, and reaches the host over one newline-delimited JSON channel on **fd 3**.
+
+It imports neither `ph-core` nor `ph-rlm`, and that is the whole point: the
+process boundary exists so that model-written code cannot reach the harness, and
+importing the harness would put it back inside. Its only dependency is `dill`,
+imported lazily — a venv without it still runs cells and forgoes snapshots.
+
+One module bends that without breaking it. `_json.py` holds the narrowings this package needs out of `ph.json` — one today, `as_str` — copied rather than imported for the reason above: that module ships in the ph-core wheel, and depending on the wheel is what this package exists not to do. `test_protocol_mirror.py` compares each definition against ph-core's character for character — it holds this package's other copy, `truncation_marker`, to `ph.text`'s in the same file — so a copy that drifts fails there rather than in a guest.
+
+```bash
+python -m ph_runtime          # how the host spawns it; not a command you type
+```
+
+**This package registers no rows.** It has no `ph.plugins` and no `ph.bundles`
+entry point, is never mounted, and appears in no profile. Everything about it is
+governed from the other side — see *Configuring it* below.
+
+## What it provides
+
+| module | what it owns |
+|---|---|
+| `channel` | newline-delimited JSON over one duplex descriptor. `json.dumps` never emits a literal newline, so a line is exactly a frame |
+| `protocol` | the fd-3 frame vocabulary, guest side — written twice on purpose, and `FRAME_FIELDS` is the *only* declaration of it here |
+| `runner` | the run loop: one process, many cells, one namespace, runs serialized |
+| `cell` | compiling one cell so that top-level `await`, top-level `return` and cross-cell persistence all hold at once |
+| `proxies` | what the model sees in `globals()`: namespaces whose every call is a governed dispatch |
+| `skill` | Python skills as pre-imported callables |
+| `limits` | `RLIMIT_CPU`, address space and log caps, applied in the child before it reports ready |
+| `lifecycle` | dying with the parent, per platform |
+| `snapshot` | per-variable serialization for `kernel/snapshot` |
+| `errors` | the two failures a cell can see, and the line between them |
+
+### Compiling a cell
+
+Three requirements pull against each other, and reconciling them is the only
+interesting thing in `cell.py`. Top-level `await` needs the program to be a
+coroutine on the child's one loop. Top-level `return` is a syntax error in
+module code even with `PyCF_ALLOW_TOP_LEVEL_AWAIT`, so the body is wrapped in an
+`async def` — which makes the first fall out for free. But a name assigned
+inside a function is *local* to it, so the naive wrapping would lose every
+variable the cell defined and quietly undo the persistent namespace. So the
+wrapper declares every name the cell binds at its top level as `global`,
+computed from the AST including the cases that are easy to forget — `import`,
+`with … as`, `for`, `except … as`, walrus, `del`, and function and class
+definitions. A trailing expression becomes the cell's value, as in a REPL.
+
+### What the model sees
+
+The programming model is prime-agent's, deliberately and exactly:
+
+```python
+files = await tools.glob(pattern="src/**/*.py")
+child = await rlm.run("review this diff", name="reviewer")
+await agent_message.send("done", receiver_role="parent")
+answer = await websearch(query="…")  # a skill: module-as-callable
+```
+
+Namespaces are built from what the **`boot` frame declared**, not from a list in
+this package, so a namespace a plugin adds reaches the cell without this module
+changing (I1, I7). Unknown attributes and unknown keyword arguments fail loudly
+with the available names in the message — the reader is a model, and a silent
+`None` is how a cell spends a turn discovering a capability it invented does not
+exist. A skill that fails to import binds a **stub that explains itself** rather
+than leaving the name undefined, for the same reason.
+
+### Cancellation, three mechanisms for three situations
+
+The channel is read by one task and a cell runs in another — otherwise a cell
+awaiting `tools.read(...)` would be blocked on a reply its own loop was supposed
+to deliver, which is the classic control-channel deadlock and the reason fd 3 is
+not the channel a run occupies (D5). On top of that:
+
+- awaiting a reply or a sleep → the `cancel` frame, or the `SIGINT` callback,
+  cancels the cell's task. `SIGINT` is installed with
+  `loop.add_signal_handler`, **not** the default handler: that one raises
+  `KeyboardInterrupt` into whatever frame is executing, and when a cell is
+  `await`ing that frame is `asyncio`'s own — so the signal killed the entire
+  guest instead of the cell, in the common case rather than a rare one;
+- spinning in Python → the loop is starved, so neither arrives. `SIGXCPU` from
+  the per-run CPU budget lands in the cell's own frame, because it is executing
+  bytecode, which is exactly why it is unreachable by the others;
+- neither works in time → the host escalates to `SIGKILL` and restarts. The
+  namespace is lost and the model is told so, which beats a wedged kernel.
+
+### Dying with the parent
+
+The OS does not do what one would hope: a parent's death does not kill its
+children (POSIX re-parents them to PID 1) and `atexit` never runs under
+`SIGKILL`. Each platform needs its own mechanism and only one is in the guest's
+gift — **Linux** sets `prctl(PR_SET_PDEATHSIG, SIGKILL)` here; **macOS** has no
+equivalent, so a daemon thread watches `os.getppid()` and `os._exit`s when it
+changes; **Windows** is the host's job, a Job Object with `KILL_ON_JOB_CLOSE`.
+The host's orphan journal is the backstop for all three.
+
+## Configuring it
+
+Nothing here is configured directly. Every knob belongs to `ph-rlm`'s
+`code-runtime-python` row, which spawns this package and sends the `boot` frame
+that parameterises it — and the **host owns every default**, because there are
+two definitions of the protocol across the two sides and exactly one owner of
+each value. `boot` carries every limit as a required field, so a guest has
+nothing to guess and a changed default cannot mean two things at once.
+
+```yaml
+- id: code-runtime-python
+  config:
+    python: managed          # which interpreter runs model code
+    cpuSeconds: 30           # per cell, not per kernel — RLIMIT_CPU is re-armed each run
+    addressSpaceBytes: 2147483648
+    maxLogBytes: 65536       # per stream
+    maxValueBytes: 65536     # per snapshotted variable
+    maxSnapshotBytes: 16777216
+    skills: ["acme-websearch"]
+```
+
+`python: managed` is what *creates* the venv this package lives in: `uv venv
+--seed` at `$PH_CACHE/runtime-venv`, then `uv pip install ph-runtime-guest` (the
+checkout's own source directory when pH is running from one) plus each
+configured skill — a local skill directory **editable**, because the staleness
+marker digests the specs rather than their contents. `python: host` runs the
+guest on pH's own interpreter instead: fast, needs no `uv` and no network, and
+what the test suite uses — and also what puts `ph-core`, pydantic and Textual on
+the child's `sys.path`, which is a wider surface and the reason it is not the
+default. `$PH_RUNTIME_PYTHON` (or `interpreter:`) is the third answer.
+
+Staleness is a marker file (`.ph-runtime.json`), not a heuristic: it records the
+protocol version, this package's version and the skill set, and any difference
+rebuilds. A guest one protocol behind would otherwise be discovered as a refused
+`boot` at the first cell of somebody's session (D7).
+
+See [`ph-rlm`'s README](../ph-rlm/README.md#including-it-and-adjusting-it) for
+the full row table.
+
+## Limitations, and things that are deliberate
+
+- **The protocol is written twice and neither side imports the other.**
+  `ph_rlm.kernel.protocol` is the twin. What keeps them honest is
+  `packages/ph-rlm/tests/test_protocol_mirror.py`, which compares
+  `PROTOCOL_VERSION`, every frame's required and optional field set, and the
+  truncation marker byte for byte. **That test is the contract**; there is no
+  shared module to fall back on.
+- **A refusal is not catchable.** `ToolFailed` is the program's to handle — a
+  timeout, a bad argument, a missing file — and catching it to try something
+  else is exactly right. `RunStopped` derives from `BaseException` so
+  `except Exception` cannot swallow it, because a program that can catch a
+  refusal can route around it (C3). A CPU budget raises the same way.
+- **Runs are serialized.** One namespace, one program at a time.
+- **Snapshots are per variable, and some things are never captured.** An
+  unchanged 200 MiB DataFrame emits nothing because its digest did not move. A
+  definitively-immutable value is compared by *identity* — deliberately not
+  extended to tuples or frozensets, since `t = ([1],)` keeps its identity while
+  its contents change, and a fast path that is wrong once is worse than none.
+  The binding proxies, the imported skill modules and anything else the
+  bootstrap put in `globals()` are excluded: they are rebuilt from the `boot`
+  frame, so pickling them would store a stale copy of the harness's own surface.
+- **The C pickler is tried first**, with `dill` as the fallback for what it
+  refuses (a cell-defined function, class or lambda). Each object takes the same
+  path every time, so digests stay stable — and `dill.loads` reads standard
+  pickle bytes unchanged either way.
+- **This package must stay nearly dependency-free.** Every dependency in the
+  runtime venv is another import model code can reach and another thing that can
+  break a session the host cannot repair.
+
+## Tests
+
+Its suite lives with the host half, in `packages/ph-rlm/tests/` — the mirror
+test above, plus `test_kernel.py` (the process boundary), `test_codec.py` (the
+decoder, fuzzed), `test_lifecycle.py`, `test_snapshot.py`, `test_venv.py` and
+`test_runtime_integration.py`. Testing the guest from the host's side is the
+honest arrangement: what matters is that the two halves agree, and only a test
+that holds both can say so.

ph_runtime_guest-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ph-runtime-guest"
+version = "0.1.0"
+description = "The guest half of pH's code runtime: the fd-3 protocol, the run loop, and the binding proxies a cell awaits."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Charles Tabor" }]
+keywords = ["agent", "code-mode", "runtime", "sandbox"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Topic :: Software Development",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+# Deliberately almost dependency-free. This package is installed into
+# `$PH_CACHE/runtime-venv`, a venv that executes model-written code; every
+# dependency there is another import that code can reach and another thing that
+# can break a session the host cannot repair. `dill` is the one exception and it
+# is imported lazily, so a venv without it runs cells and forgoes snapshots.
+dependencies = ["dill>=0.3.8"]
+
+[project.urls]
+Homepage = "https://github.com/chastabor/pH"
+Repository = "https://github.com/chastabor/pH"
+Documentation = "https://github.com/chastabor/pH/blob/main/docs/README.md"
+Issues = "https://github.com/chastabor/pH/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ph_runtime"]
+
+# ---------------------------------------------------------------- coverage ----
+# **The guest runs in a subprocess, so the parent's collector records none of
+# it.** Every cell is a fresh `python -m ph_runtime`, which read as `runner.py`
+# at 0 % while twenty-six kernel tests were driving cells through it, and as
+# 26.1 % for this package against a true 84.1 %.
+#
+# `conftest.guest_coverage` points `COVERAGE_PROCESS_START` at this file for the
+# tests that start guests; `coverage`'s own `.pth` hook reads that variable at
+# interpreter startup and starts a collector in the child. It survives
+# `ph.seams.subprocess.scrub_env` because that is a credential denylist rather
+# than an allowlist, so nothing needs a hole poked in the scrub.
+#
+# **Here rather than the workspace gate, and that split is deliberate.** The gate
+# is `--cov=ph` against `fail_under = 93` in the root manifest, measuring
+# `ph-core` alone. Folding `ph_runtime` into that `source` would change the
+# denominator the ratchet was measured against — 683 statements at ~84 % beside
+# 16 821 at ~93 % lands the total just under the floor — so a package getting
+# *measured* for the first time would read as one that had regressed. Two
+# questions, two numbers.
+[tool.coverage.run]
+source = ["ph_runtime"]
+branch = true
+
+# One data file per process, merged afterwards: every cell is a fresh
+# interpreter, and without this they would overwrite each other and the report
+# would describe whichever guest exited last.
+parallel = true
+
+# **Absolute, from the environment, because the guest's cwd is not the repo.** A
+# kernel spawns it in the session's workspace — a `tmp_path` that pytest deletes
+# — so a relative `data_file` writes the measurements into a directory that is
+# gone before anything can combine them. That is one of the two reasons this
+# collection silently produced nothing for so long; the other is that nothing
+# set `COVERAGE_PROCESS_START` at all.
+data_file = "${PH_GUEST_COVERAGE_DATA}"
+
+[tool.coverage.report]
+# No `fail_under` yet, deliberately. The subprocess baseline is 84.1 %, and this
+# number does *not* include this package's own in-process unit tests — those are
+# measured by neither report. A floor belongs here once it means "every way
+# `ph_runtime` is exercised"; the root manifest's own comment makes the argument
+# about a number set from one measurement.
+show_missing = true

ph_runtime_guest-0.1.0/src/ph_runtime/__init__.py

@@ -0,0 +1,23 @@
+"""The guest half of pH's Python code runtime.
+
+Runs inside `$PH_CACHE/runtime-venv`, in a subprocess the host spawns per agent,
+and reaches the host over one framed channel on fd 3. It imports neither
+`ph-core` nor `ph-rlm`: the process boundary exists so that model code cannot
+reach the harness, and importing the harness would put it back inside.
+
+@module ph_runtime
+"""
+
+from __future__ import annotations
+
+from .errors import RunStopped, ToolFailed
+from .protocol import PROTOCOL_FD, PROTOCOL_VERSION
+from .skill import wrap_skill_module
+
+__all__ = [
+    "PROTOCOL_FD",
+    "PROTOCOL_VERSION",
+    "RunStopped",
+    "ToolFailed",
+    "wrap_skill_module",
+]

ph_runtime_guest-0.1.0/src/ph_runtime/__main__.py

@@ -0,0 +1,10 @@
+"""`python -m ph_runtime` — how the host spawns the guest."""
+
+from __future__ import annotations
+
+import sys
+
+from .runner import main
+
+if __name__ == "__main__":
+    sys.exit(main())

ph_runtime_guest-0.1.0/src/ph_runtime/_json.py

@@ -0,0 +1,41 @@
+"""The narrowings `ph_runtime` needs from `ph.json` — a copy, pinned by a test.
+
+This package ships into the guest venv with `dill` as its only dependency, so it
+cannot import `ph.json`: that module lives in the ph-core wheel, and depending on
+the wheel is the thing this package exists not to do.
+
+**Copied by hand, compared character for character by
+`test_protocol_mirror.py`.** What keeps the two in step is the test rather than
+anyone's memory — that file opens by recording that *"a third copy that no test
+compared had already drifted"*. When it fails, copy the definition across again;
+when the guest comes to need a second narrowing, paste that one in and the test
+picks it up by name.
+
+The arrangement `truncation_marker` already has in `ph_runtime.protocol` — the
+other thing this package copies rather than imports — though that one is held to
+ph-core's by its output and this by its source, because a marker is a sentence
+built from two numbers and a narrowing is its text.
+
+Private, and re-exported by `ph_runtime.protocol` for the names the guest uses:
+this is ph-core's code, not the guest's API.
+
+@module ph_runtime._json
+"""
+
+from __future__ import annotations
+
+
+def as_str(value: object, default: str = "") -> str:
+    """A JSON string, or `default` — the fourth of the family, and the copied one.
+
+    One policy, the one `as_int`'s docstring argues for: a mis-shaped field
+    answers with the empty value rather than raising, because a reader of a log
+    some other build wrote must lose a row and not a session.
+
+    **Not `str(value)`**, which is what a reader writes without this and is worse
+    than useless: `str(None)` is `"None"` and `str(3)` is `"3"`, so a field that
+    is absent or of the wrong type comes back as a plausible-looking answer that
+    no assertion catches. Narrowing says "this was not a string" by giving back
+    nothing, which is the same thing `as_obj` and `as_seq` say.
+    """
+    return value if isinstance(value, str) else default