crates/colibri-daemon/src/spawner.rs

@@ -334,7 +334,7 @@ impl RpcSender {
 
 /// Build one newline-terminated RPC prompt request line in zot's wire format:
 /// a bare JSON object `{"id","type":"prompt","message"}` (no JSON-RPC envelope),
-/// matching the transcript in `docs/ZOT-RPC-TRANSCRIPT.md`. `serde_json` escapes
+/// matching the transcript in `docs/AGENT-EVENTS-REFERENCE.md`. `serde_json` escapes
 /// the message, so embedded quotes/newlines are safe.
 fn build_rpc_prompt(id: &str, message: &str) -> String {
     let obj = serde_json::json!({

docs/AGENT-EVENTS-REFERENCE.md

@@ -1,4 +1,12 @@
-# zot rpc transcript — DeepSeek (2026-06-21)
+# Agent events reference
+
+> **Developer reference — operators can skip.** Plain version: `wiki/agent-harness`.
+
+Per-harness reference for the event stream Colibri ingests into Glasspane. Each
+harness emits its own format; this file documents one section per harness.
+Currently documented: **zot** (the pi harness emits `pi --mode json` events,
+parsed by `pi_event_type`). The zot capture below is from a real DeepSeek run
+(21.jun.2026).
 
 ## Request shape
 
@@ -56,7 +64,7 @@ needed to capture a real tool call before the driver can trust those mappings.
 
 Step 1 of colibri#143 is complete after the real-key re-run below. Steps 2 and 3 are unblocked.
 
-## Real-key transcript (complete tool call, 2026-06-21)
+## Real-key transcript (complete tool call, 21.jun.2026)
 
 Prompt: "run uname -a and tell me the kernel version in one sentence"
 61 lines, 2 turns, 1 tool call (bash), DeepSeek v4-pro, cached tokens.

docs/README.md

@@ -18,4 +18,4 @@ A quick-reference guide to every document in this folder.
 | [`PLAN-MOTHER-MCP-VAULT-KEYS.md`](PLAN-MOTHER-MCP-VAULT-KEYS.md)               | Vaultwarden pubkey exchange for mother MCP link (direction B)              | Sam & Hermes    |
 | [`PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](PRIORITY-HANDOFF-ISO-SPAWN-COST.md)     | ISO boot validation, Pi spawn path, cost mode enforcement (P2/P3 done)     | All agents      |
 | [`TRUSS-SPAWN-ANALYSIS.md`](TRUSS-SPAWN-ANALYSIS.md)                           | truss trace of jail-spawn Permission Denied — root cause + fix             | Debugging       |
-| [`VAULT-PROVISION-FIRST-PROOF.md`](VAULT-PROVISION-FIRST-PROOF.md)             | First-proof runbook: vault → jail → `.env` chain (clean CLI)               | Agents, Sam     |
+| [`VAULT-PROVISION-RUNBOOK.md`](VAULT-PROVISION-RUNBOOK.md)                     | First-proof runbook: vault → jail → `.env` chain (clean CLI)               | Agents, Sam     |

docs/VAULT-PROVISION-RUNBOOK.md

@@ -1,4 +1,4 @@
-# Vault Provision — First-Proof Runbook (osa)
+# Vault Provision Runbook (osa)
 
 **Status.** The spawn → vault-provision → `.env` chain is **wired, hardened, and
 drivable from the CLI**. The three gaps that previously forced a manual path are

docs/wiki/agent-harness.md

@@ -38,7 +38,7 @@ Where it lives:
 - autospawn binary-aware argv (`zot → rpc`, pi → `--mode json`):
   `crates/colibri-daemon/src/socket.rs` (`default_agent_args`,
   `autospawn_agent_if_configured`)
-- wire format (verified against real zot): [ZOT-RPC-TRANSCRIPT](../ZOT-RPC-TRANSCRIPT.md)
+- wire format (verified against real zot): [AGENT-EVENTS-REFERENCE](../AGENT-EVENTS-REFERENCE.md)
 - end-to-end proof: `crates/colibri-daemon/tests/zot_rpc_smoke.rs`
   (`#[ignore]`, `ZOT_BIN`-gated)
 

docs/wiki/naming-decisions.md

@@ -6,6 +6,24 @@ A living record of renames driven by superseded assumptions, so future drift is
 checkable against one list. "Shipped" means merged to `main`; verify against the
 linked code before trusting a row.
 
+## Naming principle — harness-agnostic by default
+
+Name a thing by what it **is**, not by the harness that happens to be the
+current default:
+
+- **Neutral concept** (any harness has one — a session id, an event type,
+  autospawn, "the agent") → a **neutral name**. The harness is a _configurable
+  value_ (e.g. `COLIBRI_AUTOSPAWN_BINARY=zot`), never baked into the name and
+  always operator-overridable.
+- **Harness-specific thing** (one harness's actual wire format) → the harness
+  name belongs in it, and the parallels stay symmetric (`zot_event_type` ↔
+  `pi_event_type`, `AgentRuntime::{Zot, Pi}`) so neither is privileged.
+
+The `pi_*` rows in [Shipped](#shipped) are the cautionary tale: neutral concepts
+wrongly named after a harness. Same applies to docs — a per-harness reference is
+neutral (`AGENT-EVENTS-REFERENCE`), not `ZOT-…`, unless it is truly about one
+harness only.
+
 ## Shipped
 
 | Old → New                                        | Why                                                                               | Anchor                                         |