docs: add runtime proof ledger

README.md

@@ -5,16 +5,16 @@ Give every agent in Buzz the same project context.
 [![Reference checks](https://github.com/contextstream/buzz-context/actions/workflows/test.yml/badge.svg)](https://github.com/contextstream/buzz-context/actions/workflows/test.yml)
 
 This reference package connects the `contextstream-mcp` stdio server to an
-agent launched by Buzz's `buzz-acp` harness. Claude Code, Codex, Goose, and any
-other conforming ACP agent can then retrieve the same approved ContextStream
-project knowledge before work, preserve durable decisions after human
-approval, and hand work to another agent without a manual rebrief.
+agent launched by Buzz's `buzz-acp` harness. Buzz can launch Claude Code,
+Codex, Goose, and other conforming ACP agents with the same ContextStream
+project. The [runtime proof ledger](runtime-proof.md) records which paths have
+actually completed sourced retrieval and a signed Buzz reply.
 
 > The room changed. The agent changed. The context didn't.
 
 ## What is verified today
 
-This package was checked on 2026-08-05 against
+This package was checked on 2026-08-06 against
 [`block/buzz@06b60e6`](https://github.com/block/buzz/commit/06b60e682d5dd78e6cdcb8e93fe96c7ec4391e2a).
 
 - `buzz-acp` accepts an optional stdio MCP command through
@@ -27,6 +27,14 @@ This package was checked on 2026-08-05 against
 - `contextstream-mcp` works as that stdio command and connects to the hosted
   ContextStream service after normal ContextStream setup.
 
+Contract support and end-to-end proof are intentionally separate. Claude has
+completed sourced ContextStream retrieval and a signed Buzz reply. Codex is
+running and waiting for the deliberately approval-gated continuation. Goose
+passes launcher and ACP startup checks, but its current ContextStream-backed
+prompt remains an open interoperability finding rather than a claimed pass.
+See [runtime-proof.md](runtime-proof.md) for versions, evidence, and the exact
+pass criterion.
+
 Buzz records collaboration inside a Buzz community. ContextStream carries
 durable project understanding across agents, sessions, tools, and workspaces.
 The integration does not copy every Buzz message or replace Buzz history.
@@ -219,6 +227,8 @@ binary execution. The compatibility record is in
   upstream contribution brief
 - [upstream-doc.md](upstream-doc.md) — PR-ready vendor-neutral Buzz docs copy
 - [compatibility.json](compatibility.json) — exact upstream contract verified
+- [runtime-proof.md](runtime-proof.md) — per-runtime evidence and honest pass
+  criteria
 - [measurement.md](measurement.md) — north-star and activation measurement
   contract, including smoke-traffic exclusion
 

compatibility.json

@@ -1,5 +1,5 @@
 {
-  "verified_at": "2026-08-05",
+  "verified_at": "2026-08-06",
   "buzz": {
     "repository": "https://github.com/block/buzz",
     "commit": "06b60e682d5dd78e6cdcb8e93fe96c7ec4391e2a",
@@ -17,6 +17,7 @@
       "codex-acp",
       "claude-agent-acp"
     ],
+    "supported_harnesses_scope": "Buzz configuration and ACP startup support. End-to-end ContextStream retrieval proof is tracked separately in proof.runtime_matrix and runtime-proof.md.",
     "desktop_per_agent_mcp_override": false,
     "desktop_limitation": "Create/update requests accept mcpCommand only for wire compatibility; runtime catalog metadata determines the effective MCP command at spawn time.",
     "claude_headless_default": "dontAsk denies operations that require an interactive permission prompt; read/write work needs an explicitly reviewed project allowlist plus acceptEdits"
@@ -35,6 +36,39 @@
       "cargo test -p buzz-acp mcp_command",
       "cargo test -p buzz-acp session_new_mcp_server_has_required_fields"
     ],
-    "contextstream_test": "node apps/buzz/smoke-contextstream.mjs --project /absolute/project/path"
+    "contextstream_test": "node apps/buzz/smoke-contextstream.mjs --project /absolute/project/path",
+    "pass_standard": "A runtime is end-to-end verified only after a distinct Buzz identity receives an explicit mention, materially retrieves from the attached ContextStream project, and emits a signed Buzz reply. Process startup, online presence, or MCP child-process creation alone do not pass.",
+    "runtime_matrix": {
+      "claude": {
+        "runtime": "Claude Code 2.1.221 via @agentclientprotocol/claude-agent-acp 0.65.0",
+        "buzz_acp_startup": "passed",
+        "canonical_contextstream_mcp": "passed",
+        "sourced_contextstream_retrieval": "passed",
+        "signed_buzz_reply": "passed",
+        "fixture_tests": "5/5 passed",
+        "reply_event_id": "5a7dc066781234a012ef8efe406e29fbb62a18b6949f003ad3fb9a377053e53e"
+      },
+      "codex": {
+        "runtime": "Codex CLI 0.146.1 via @agentclientprotocol/codex-acp 1.1.9",
+        "buzz_acp_startup": "passed",
+        "canonical_contextstream_mcp": "passed",
+        "cross_agent_continuation": "pending_explicit_human_approval",
+        "status_note": "The second-agent continuation remains intentionally unexecuted until a human approves the proposed durable requirement change."
+      },
+      "goose": {
+        "runtime": "goose 1.45.0",
+        "providers_tested": [
+          "claude-acp via @agentclientprotocol/claude-agent-acp 0.65.0",
+          "codex-acp via @agentclientprotocol/codex-acp 1.1.9"
+        ],
+        "launcher_preflight": "passed",
+        "buzz_acp_startup": "passed",
+        "canonical_contextstream_process_started": "passed",
+        "sourced_contextstream_retrieval": "not_yet_proven",
+        "signed_buzz_reply": "not_yet_proven",
+        "observed_stop": "An explicit Buzz mention reached Goose and Goose started the canonical ContextStream MCP process in the selected project directory, but the session remained in extension initialization and emitted no signed reply during the bounded proof run.",
+        "claim_policy": "Do not describe Goose end-to-end retrieval as verified until a signed reply satisfies proof.pass_standard."
+      }
+    }
   }
 }

reference.test.mjs

@@ -53,6 +53,21 @@ test("compatibility record pins the contract that was actually tested", async ()
   assert.match(compatibility.buzz.commit, /^[0-9a-f]{40}$/);
 });
 
+test("runtime proof never conflates process startup with sourced retrieval", async () => {
+  const compatibility = JSON.parse(await read("compatibility.json"));
+  const ledger = await read("runtime-proof.md");
+  const matrix = compatibility.proof.runtime_matrix;
+
+  assert.equal(matrix.claude.sourced_contextstream_retrieval, "passed");
+  assert.equal(matrix.claude.signed_buzz_reply, "passed");
+  assert.equal(matrix.codex.cross_agent_continuation, "pending_explicit_human_approval");
+  assert.equal(matrix.goose.sourced_contextstream_retrieval, "not_yet_proven");
+  assert.equal(matrix.goose.signed_buzz_reply, "not_yet_proven");
+  assert.match(compatibility.proof.pass_standard, /signed Buzz reply/);
+  assert.match(ledger, /Process startup.*not retrieval proof/is);
+  assert.match(ledger, /open compatibility finding/i);
+});
+
 test("production and smoke clients remain separable for connector metrics", async () => {
   const teaching = await read("agent-instructions.md");
   const smoke = await read("smoke-contextstream.mjs");
@@ -89,6 +104,7 @@ test("examples contain no live-looking ContextStream or Buzz secrets", async ()
     await read("demo-script.md"),
     await read("claude-settings.local.example.json"),
     await read("community-runbook.md"),
+    await read("runtime-proof.md"),
   ].join("\n");
   assert.doesNotMatch(files, /cs_(live|test)_[A-Za-z0-9]{16,}/);
   assert.doesNotMatch(files, /nsec1[023456789acdefghjklmnpqrstuvwxyz]{24,}/);

runtime-proof.md

@@ -0,0 +1,77 @@
+# Buzz runtime proof ledger
+
+Last verified: 2026-08-06
+
+This ledger separates three different claims that are easy to blur together:
+
+1. Buzz knows how to launch a runtime.
+2. Buzz passes a ContextStream MCP server through ACP `session/new`.
+3. The runtime materially retrieves ContextStream knowledge and publishes a
+   signed Buzz reply.
+
+Only the third claim is an end-to-end retrieval pass. Process startup, online
+presence, an initialized ACP session, or a spawned MCP child process are useful
+diagnostics, but they are not retrieval proof.
+
+## Current matrix
+
+| Runtime | Buzz + ACP startup | Canonical ContextStream MCP | Sourced signed Buzz reply | Current result |
+| --- | --- | --- | --- | --- |
+| Claude Code 2.1.221 through `claude-agent-acp` 0.65.0 | Pass | Pass | Pass | End-to-end proven; the disposable fixture passed 5/5 tests |
+| Codex CLI 0.146.1 through `codex-acp` 1.1.9 | Pass | Pass | Approval-gated | The second-agent continuation is deliberately waiting for explicit human approval |
+| Goose 1.45.0 | Pass | MCP process starts | Not yet proven | An explicit mention enters the session, but the bounded run remains in extension initialization without a signed reply |
+
+The Buzz harness contract supports all three runtimes. The matrix above records
+what has actually completed with ContextStream rather than treating contract
+support as end-to-end proof.
+
+## Claude evidence
+
+The Claude agent used its own Buzz identity and the same isolated ContextStream
+project used by the continuing Codex agent. It retrieved the project PRD, ADR,
+constraint, and repository map through `mcp__contextstream__*`, implemented the
+approved 24-hour baseline, passed all five fixture tests, and published signed
+Buzz reply event:
+
+`5a7dc066781234a012ef8efe406e29fbb62a18b6949f003ad3fb9a377053e53e`
+
+The later 30-minute admin-expiry proposal was neither preserved nor
+implemented. It remains behind the documented human-approval gate.
+
+## Goose finding
+
+A clean Goose 1.45.0 binary passed `run-agent.sh --check`, initialized through
+the pinned Buzz `buzz-acp`, authenticated to the relay with a distinct identity,
+joined its private proof channel, and published online presence. Two model
+provider paths were exercised:
+
+- `claude-acp` through `@agentclientprotocol/claude-agent-acp` 0.65.0;
+- `codex-acp` through `@agentclientprotocol/codex-acp` 1.1.9.
+
+For both, an explicit Buzz mention entered a new Goose session and Goose
+started the executable named `contextstream` in the selected project working
+directory. The bounded run then remained in extension initialization and did
+not publish a signed answer. Changing the outer Buzz permission mode from
+`dontAsk` to `acceptEdits` did not change that stop, so permission wiring alone
+does not explain it.
+
+This is an open compatibility finding, not a successful retrieval. Keep Goose
+in the launcher because Buzz supports it, but do not market Goose as
+end-to-end verified until the signed-reply criterion below passes.
+
+## Reproduction and pass criterion
+
+1. Install and authenticate ContextStream, Buzz, and the runtime.
+2. Run the read-only MCP smoke test.
+3. Run `run-agent.sh --check` for the selected runtime.
+4. Give the agent a distinct Buzz identity and add it to a private channel.
+5. Start the agent with the canonical ContextStream alias from `run-agent.sh`.
+6. Send an explicit Buzz mention asking for a known ContextStream requirement,
+   decision, and constraint; prohibit edits and durable writes.
+7. Read the resulting Buzz thread from the relay.
+
+A runtime passes only when the thread contains a signed reply from that
+runtime's distinct identity and the answer cites the attached ContextStream
+sources. Record the runtime versions and reply event ID in
+[`compatibility.json`](compatibility.json). A typing reaction, online presence,
+or MCP subprocess is not sufficient.