Phase 1.6: example configs, README, end to end test

Two example configs, one with everything undeclared and one declaring
git_remote:branch_name so the README can show an AUTHORIZED row. The README now
carries the real table from a real run on this box, verbatim, along with what
each verdict and each persistence class means.

The paragraph that matters is the one about the transient row. deleted_ref
passes because Run A created a ref and deleted it, so nothing is visible to a
later check of remote state, and the channel was open at the time it was used.
A probe of visible state cannot see that. Saying so in the README is more
useful than quietly reporting a PASS.

The end to end test runs the CLI as a subprocess from a different working
directory, against the example config, and reads the JSON off disk. It skips
when git is missing rather than failing.

Version moves to 0.1.0.dev0 in both pyproject.toml and __init__.py. The em dash
scan, in the test and in CI, now covers examples/ too.

Author: webpro255

.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
         run: |
           # The pattern is written as a bash escape so this workflow file stays
           # ASCII and does not match itself.
-          if grep -rn --binary-files=without-match $'\u2014' src tests README.md pyproject.toml .github; then
+          if grep -rn --binary-files=without-match $'\u2014' src tests examples README.md pyproject.toml .github; then
             echo "em dash found, see the matches above (house rule: use commas, colons, or parentheses)"
             exit 1
           fi

README.md

@@ -5,12 +5,11 @@ Agent sandboxes isolate machines. Nothing isolates agent runs.
 runprobe answers one deterministic question: can one supposedly isolated agent
 run leave information somewhere another supposedly isolated run can recover it?
 
-**Status: v0.0.1, Phase 0, no adapters yet.**
+**Status: v0.1.0-dev, Phase 1, filesystem and git_remote adapters.**
 
-Phase 0 is the skeleton only: package layout, CLI, config loader, run context,
-report writer, tests, CI. There are no surface adapters, so `runprobe probe`
-cannot yet probe anything and exits non-zero by design. A probe that reported
-PASS without having probed anything would be worse than no probe at all.
+Two surfaces can be probed today: a shared directory and a shared git remote,
+thirteen carriers between them. The `http_cache` adapter and the Artifactory
+mailbox fixture are not built yet.
 
 ## Install
 
@@ -27,17 +26,18 @@ Python 3.11 or newer.
 
 ```
 runprobe --version
-runprobe probe --config surfaces.json --report runprobe-report.json
+runprobe probe --config examples/surfaces.json --report runprobe-report.json
 ```
 
 `surfaces.json` describes the shared surfaces you want checked:
 
 ```json
 {
   "surfaces": [
-    { "name": "shared_tmp", "type": "filesystem", "params": { "path": "/tmp" } }
+    { "name": "filesystem", "type": "filesystem" },
+    { "name": "git_remote", "type": "git_remote" }
   ],
-  "declared": ["shared_tmp:file_content"]
+  "declared": ["git_remote:branch_name"]
 }
 ```
 
@@ -48,17 +48,113 @@ runprobe probe --config surfaces.json --report runprobe-report.json
   reported AUTHORIZED rather than FAIL.
 
 Config validation fails closed. An unknown key, an empty surface list, a
-duplicate surface name, a malformed `declared` entry, or an unknown surface type
-is an error with a non-zero exit, never a warning. In Phase 0 the surface type
-registry is empty, so every `type` value is currently rejected.
+duplicate surface name, a malformed `declared` entry, an unknown surface type,
+an unknown adapter param, or a `declared` entry naming a carrier that does not
+exist are all errors with a non-zero exit, never warnings.
+
+`--keep-work` prints the temporary work directory and leaves it in place, which
+is the way to look at what Run A actually planted.
+
+### Surfaces
+
+`filesystem`: a directory both runs can reach.
+
+| Param | Default | Meaning |
+|-------|---------|---------|
+| `path` | a directory the probe creates and deletes | the shared directory to probe |
+| `content_reads` | `true` | when false, Run B lists but never opens a file |
+| `check_xattr` | `true` | when false, the extended attribute carrier is skipped |
+
+`git_remote`: a bare repository both runs can reach. Needs `git` on PATH and
+reports every carrier SKIPPED if it is missing.
+
+| Param | Default | Meaning |
+|-------|---------|---------|
+| `remote` | a bare repo the probe creates and deletes | a local path to a bare repo. URLs are rejected in this version |
+| `check_dangling` | `true` | when false, the dangling object carrier is skipped |
+
+Given a `remote`, the probe pushes a branch named `runprobe-probe` rather than
+touching a branch you already have, and deletes the refs it pushed afterwards.
+The dangling commit survives cleanup, which is what until-gc means.
+
+## Example run
+
+`runprobe probe --config examples/surfaces.json`, on a Linux box with git 2.53
+and a filesystem that supports extended attributes:
+
+```
+SURFACE     CARRIER          VERDICT  PERSISTENCE  DETAIL
+----------  ---------------  -------  -----------  -----------------------------------------------------------------------------------------------------------------
+filesystem  file_content     FAIL     durable      nonce in the bytes of notes.txt
+filesystem  file_name        FAIL     durable      nonce in the file name zzFILE_5ba4b7d73d3d76cc
+filesystem  directory_name   FAIL     durable      nonce in the directory name zzHELP_5ba4b7d73d3d76cc_SEEK_IDEA
+filesystem  symlink_target   FAIL     durable      nonce in the target of cache-link, which resolves to nothing
+filesystem  xattr            FAIL     durable      nonce in user.runprobe on plain.txt
+git_remote  branch_name      FAIL     durable      nonce in the branch name refs/heads/msg-5ba4b7d73d3d76cc, seen by ls-remote
+git_remote  tag_name         FAIL     durable      nonce in the tag name refs/tags/zz-5ba4b7d73d3d76cc, seen by ls-remote
+git_remote  commit_message   FAIL     durable      nonce in the commit message: sync note zzMSG_5ba4b7d73d3d76cc for the next run
+git_remote  author_name      FAIL     durable      nonce in the author name: zzAUTH_5ba4b7d73d3d76cc
+git_remote  file_content     FAIL     durable      nonce in the bytes of data.txt
+git_remote  file_path        FAIL     durable      nonce in the tracked path notes/zz-5ba4b7d73d3d76cc.txt
+git_remote  deleted_ref      PASS     transient    the created and then deleted ref is not in ls-remote, which a visible-state check cannot see and watch mode would
+git_remote  dangling_object  FAIL     until-gc     nonce in the message of dangling commit 2c24ed2a40b3, unreachable but present
+```
+
+Exit code 1.
+
+Twelve of thirteen carriers are open, which is the expected result: these two
+surfaces are shared on purpose, and the probe is showing you what "shared"
+actually buys anyone who wants to use it. The interesting rows are the ones
+that are not file content. Four of the five filesystem carriers are names, and
+blocking content reads (`"content_reads": false`) closes exactly one of them.
+
+With `examples/surfaces-declared.json`, which declares
+`git_remote:branch_name`, that row reads as follows. It is a separate run, so
+the nonce differs:
+
+```
+git_remote  branch_name      AUTHORIZED  durable      nonce in the branch name refs/heads/msg-d71693e752ae38b8, seen by ls-remote
+```
+
+The exit code is still 1, because twelve other carriers are still undeclared.
+
+## Reading the table
+
+One row per (surface, carrier). A carrier is one channel through a surface, not
+the surface as a whole, because a surface is almost never open or closed as a
+unit.
+
+| Verdict | Meaning |
+|---------|---------|
+| FAIL | Run B recovered the nonce Run A planted, on a channel nobody authorized |
+| PASS | Run B did not recover the nonce on this channel |
+| AUTHORIZED | recovered, and this channel is in `declared`, so it does not fail the run |
+| SKIPPED | the channel could not be tested here, for example xattrs on a filesystem without them, or any git carrier without git. Never treat this as PASS |
+| ERROR | the adapter failed, or did not report a carrier it declared. Treated as a failure, never as a pass |
+
+The persistence column says how long a recovered carrier survives.
+
+| Class | Meaning |
+|-------|---------|
+| durable | it stays until somebody deletes it |
+| transient | it is gone by the time a later check looks, like a ref created and deleted between the two runs |
+| until-gc | it is unreachable but still stored, and stays readable until garbage collection removes it |
+| unknown | not classifiable without knowing the operator's retention policy |
+
+A PASS on a transient carrier is worth reading twice. `git_remote:deleted_ref`
+passes because Run A created a ref and deleted it, so nothing is visible to a
+later check of remote state. The channel was open at the time it was used. A
+probe of visible state cannot see that, and the row is there to say so: this is
+the case that needs the write-side correlation of watch mode, not a better
+listing.
 
 Exit codes:
 
 | Code | Meaning |
 |------|---------|
 | 0 | the probe ran and found no undeclared channel |
 | 1 | the probe ran and found a FAIL or an ERROR |
-| 2 | the probe could not run (bad config, or no adapters registered) |
+| 2 | the probe could not run (bad config, or the report could not be written) |
 
 ## Why
 
@@ -109,8 +205,14 @@ These are non-claims, stated up front.
   it does not.
 - **No runtime enforcement.** Watch mode, meaning server-side correlation of
   writes and reads across run identities, is not in v0.1.
-- Phase 0 additionally ships **no surface adapters**, so nothing can be probed
-  yet.
+- **Two surfaces so far.** Phase 1 ships the `filesystem` and `git_remote`
+  adapters. The `http_cache` adapter, which is the one that reproduces the July
+  2026 incident directly, is not built yet.
+- **Run A and Run B are subprocesses, not separate users or containers.** They
+  get disjoint working directories, disjoint temp directories, and an
+  environment scrubbed to four variables, and every read and write against a
+  surface happens inside one of them. They still share a uid. Stronger
+  separation is deferred, and stated here rather than implied away.
 
 ## Dependencies
 

examples/surfaces-declared.json

@@ -0,0 +1,7 @@
+{
+  "surfaces": [
+    { "name": "filesystem", "type": "filesystem" },
+    { "name": "git_remote", "type": "git_remote" }
+  ],
+  "declared": ["git_remote:branch_name"]
+}

examples/surfaces.json

@@ -0,0 +1,6 @@
+{
+  "surfaces": [
+    { "name": "filesystem", "type": "filesystem" },
+    { "name": "git_remote", "type": "git_remote" }
+  ]
+}

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runprobe"
-version = "0.0.1"
+version = "0.1.0.dev0"
 description = "Cross-run isolation probing for autonomous agent environments"
 readme = "README.md"
 requires-python = ">=3.11"

src/runprobe/__init__.py

@@ -4,6 +4,6 @@
 information somewhere another supposedly isolated run can recover it?
 """
 
-__version__ = "0.0.1"
+__version__ = "0.1.0.dev0"
 
 __all__ = ["__version__"]

tests/test_end_to_end.py

@@ -0,0 +1,121 @@
+"""End to end: the installed CLI, the example configs, a real filesystem, a real git.
+
+Everything else in the suite calls into the package. This runs the command the
+way an operator runs it, from a different working directory, and reads the JSON
+report off disk.
+"""
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+EXAMPLES = REPO_ROOT / "examples"
+
+needs_git = pytest.mark.skipif(shutil.which("git") is None, reason="git not on PATH")
+
+
+def run_cli(args, cwd):
+    return subprocess.run(
+        [sys.executable, "-m", "runprobe.cli", *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        timeout=300,
+    )
+
+
+def findings_of(report_path):
+    data = json.loads(Path(report_path).read_text(encoding="utf-8"))
+    return data, {f"{f['surface']}:{f['carrier']}": f for f in data["findings"]}
+
+
+@pytest.fixture(scope="module")
+def example_run(tmp_path_factory):
+    cwd = tmp_path_factory.mktemp("e2e")
+    result = run_cli(["probe", "--config", str(EXAMPLES / "surfaces.json")], cwd)
+    return result, cwd
+
+
+@needs_git
+def test_the_example_config_exits_one(example_run):
+    result, _ = example_run
+    assert result.returncode == 1, result.stderr
+
+
+@needs_git
+def test_the_report_lands_at_the_default_path_in_the_working_directory(example_run):
+    _, cwd = example_run
+    assert (cwd / "runprobe-report.json").is_file()
+
+
+@needs_git
+def test_the_table_goes_to_stdout(example_run):
+    result, _ = example_run
+    assert result.stdout.splitlines()[0].startswith("SURFACE")
+    assert "report written to" in result.stderr
+
+
+@needs_git
+def test_the_name_carriers_on_both_surfaces_fail(example_run):
+    """The two rows that matter most: neither one is a file content read."""
+    _, cwd = example_run
+    _, findings = findings_of(cwd / "runprobe-report.json")
+    assert findings["filesystem:directory_name"]["verdict"] == "FAIL"
+    assert findings["git_remote:branch_name"]["verdict"] == "FAIL"
+
+
+@needs_git
+def test_the_deleted_ref_passes(example_run):
+    _, cwd = example_run
+    _, findings = findings_of(cwd / "runprobe-report.json")
+    assert findings["git_remote:deleted_ref"]["verdict"] == "PASS"
+    assert findings["git_remote:deleted_ref"]["persistence"] == "transient"
+
+
+@needs_git
+def test_the_report_covers_all_thirteen_carriers(example_run):
+    _, cwd = example_run
+    data, findings = findings_of(cwd / "runprobe-report.json")
+    assert len(findings) == 13
+    assert data["schema_version"] == 1
+    assert len(data["nonce"]) == 16
+    assert data["run_id_a"] != data["run_id_b"]
+
+
+@needs_git
+def test_the_nonce_is_not_in_the_report_findings(example_run):
+    """The report says where the nonce was found, and shows it. That is the evidence."""
+    _, cwd = example_run
+    data, findings = findings_of(cwd / "runprobe-report.json")
+    assert data["nonce"] in findings["filesystem:directory_name"]["detail"]
+
+
+@needs_git
+def test_the_declared_example_authorizes_one_row(tmp_path):
+    result = run_cli(["probe", "--config", str(EXAMPLES / "surfaces-declared.json")], tmp_path)
+    assert result.returncode == 1, result.stderr
+    _, findings = findings_of(tmp_path / "runprobe-report.json")
+    assert findings["git_remote:branch_name"]["verdict"] == "AUTHORIZED"
+    assert findings["git_remote:tag_name"]["verdict"] == "FAIL"
+
+
+@needs_git
+def test_the_probe_leaves_nothing_behind_in_the_working_directory(tmp_path):
+    run_cli(["probe", "--config", str(EXAMPLES / "surfaces.json")], tmp_path)
+    assert sorted(p.name for p in tmp_path.iterdir()) == ["runprobe-report.json"]
+
+
+def test_the_example_configs_are_valid_json_and_load():
+    from runprobe.config import load
+
+    for name in ("surfaces.json", "surfaces-declared.json"):
+        config = load(EXAMPLES / name)
+        assert [s.type for s in config.surfaces] == ["filesystem", "git_remote"]
+
+    assert load(EXAMPLES / "surfaces-declared.json").is_declared("git_remote", "branch_name")
+    assert load(EXAMPLES / "surfaces.json").declared == []

tests/test_no_em_dashes.py

@@ -16,7 +16,7 @@
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 
-SCANNED_PREFIXES = ("src/", "tests/")
+SCANNED_PREFIXES = ("src/", "tests/", "examples/")
 
 
 def tracked_files():
@@ -51,6 +51,7 @@ def test_scan_covers_the_expected_files():
     assert "README.md" in names
     assert any(name.startswith("src/runprobe/") for name in names)
     assert any(name.startswith("tests/") for name in names)
+    assert any(name.startswith("examples/") for name in names)
 
 
 def test_no_em_dashes_in_tracked_source_and_docs():