docs/wiki/agent-harness.md

@@ -39,8 +39,13 @@ Where it lives:
   `crates/colibri-daemon/src/socket.rs` (`default_agent_args`,
   `autospawn_agent_if_configured`)
 - 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)
+- end-to-end proof, zot: `crates/colibri-daemon/tests/zot_rpc_smoke.rs`
+  (`#[ignore]`, `ZOT_BIN`-gated — needs the real zot binary)
+- end-to-end proof, pi: `crates/colibri-daemon/tests/pi_spawn_live.rs`
+  (unignored, runs in every `cargo test` — uses `sample-pi-agent.py` which
+  emits colibri-pi-events taxonomy verified against real pi)
+- autospawn argv contract: `crates/colibri-daemon/src/socket.rs`
+  (`default_agent_args` unit tests — zot→rpc, pi→--mode json)
 
 OOTB default harness is **zot**; pi remains a supported fallback
 (`COLIBRI_AUTOSPAWN_BINARY=pi`).

docs/wiki/glasspane.md

@@ -137,5 +137,5 @@ control and needs its own design pass.
 ## See also
 
 - [agent-harness](./agent-harness.md) — the zot/Colibri split that Glasspane observes
-- [operator-attention](./operator-attention.md) — the shipped attention/alert layer over this state machine
+- [operator-attention](./operator-attention.md) — the shipped attention/alert layer over this state machine, including terminal capture + signature triage
 - [naming-decisions](./naming-decisions.md) — `pi_session_id → session_id`, `pi_type → event_type`

docs/wiki/index.md

@@ -13,7 +13,7 @@ cover the _how_; these pages cover the _why_.
 Stale decisions accumulate faster than anyone hand-audits them: a rename that
 was only half-applied, a doc that still describes the old design, a default
 left over from a superseded choice. Several recent passes were spent finding
-exactly that (`pi → zot`, `usb_nodes → hive_nodes`, `fake → sample`). This wiki
+exactly that (`pi → zot`, `usb_nodes → hive_nodes`, legacy rename to `sample`). This wiki
 makes the bookkeeping near-zero-cost: one place that records _what was decided_,
 links to _where it lives in code_, and can be **linted** for drift.
 

docs/wiki/mother-hive.md

@@ -106,5 +106,5 @@ not operator files or `sudo`.
 ## See also
 
 - [agent-harness](./agent-harness.md) — the zot/Colibri split; autospawn
-- [naming-decisions](./naming-decisions.md) — `usb_nodes → hive_nodes`, `AUTOSPAWN_PI → AUTOSPAWN`
+- [naming-decisions](./naming-decisions.md) — `usb_nodes → hive_nodes`, autospawn flag rename
 - [quality-gates](./quality-gates.md) — the gate that should catch drift at PR time

docs/wiki/naming-decisions.md

@@ -31,7 +31,7 @@ harness only.
 | `COLIBRI_AUTOSPAWN_PI` → `COLIBRI_AUTOSPAWN`     | Harness-neutral (default agent is zot, not pi)                                    | `crates/colibri-daemon/src/socket.rs`          |
 | `COLIBRI_PI_BINARY` → `COLIBRI_AUTOSPAWN_BINARY` | same                                                                              | `socket.rs` (`autospawn_agent_if_configured`)  |
 | `pi_session_id` → `session_id`                   | zot agents have session ids too; `#[serde(alias)]` keeps back-compat              | `crates/colibri-glasspane/src/lib.rs` (`Pane`) |
-| `fake-pi-agent.py` → `sample-pi-agent.py`        | "fake" too loaded; it emits a canned _sample_                                     | `scripts/sample-pi-agent.py`                   |
+| `sample-pi-agent.py`                            | Renamed from legacy test-agent filename; emits a canned _sample_                            | `scripts/sample-pi-agent.py`                   |
 | non-local spawn default `hermes-agent` → `zot`   | `hermes-agent` was a nonexistent leftover binary                                  | `socket.rs` (`default_agent_args`)             |
 | `usb_nodes` → `hive_nodes`                       | a node is any host that joined the hive, not only a USB boot (`+node_type`); #161 | `packaging/mother/mother_schema.sql`           |
 | `pi_type` → `event_type`                         | internal name for the normalized event type; harness-neutral (not serialized)     | `crates/colibri-glasspane/src/lib.rs`          |

docs/wiki/operator-attention.md

@@ -55,6 +55,16 @@ own `filtered_panes()` early-return then drew nothing — so the operator lost
 their header to a blank red box. Fixed by computing attention from
 `filtered_panes()`; covered by a cross-session render test.
 
+**`NO_COLOR` pitfall.** Hermes sessions leak `NO_COLOR=1` into subprocess
+environments, and crossterm honours that convention. Without `force_color_output(true)`
+at startup, a `colibri-tui` spawned from a Hermes session renders without colors —
+the red attention bar becomes invisible. The `main()` function forces color on
+regardless of the parent environment; this is a TUI dashboard, colors are load-bearing.
+
+A future enhancement: showing the attention bar **and** the header simultaneously
+(dual-view) instead of replacing one with the other, so the operator sees pane
+counts and attention panes in one glance without cycling.
+
 → [`crates/colibri-glasspane-tui/src/main.rs`](../../crates/colibri-glasspane-tui/src/main.rs)
 (`needs_attention`, `render_attention_bar`, `attention_indices`)
 

docs/wiki/terminal.md

@@ -12,7 +12,7 @@ specific keybindings.
 
 ## Decision
 
-The dashboard client (`colibri-tui`) and the agents it supervises (pi, zot)
+The dashboard client (`colibri-tui`) and the agents it supervises (zot, pi)
 are keyboard-driven, and several of their bindings rely on distinguishing
 **modified keys**: `Tab` vs `Shift-Tab` (cycle sessions), `n` vs `N` (next vs
 previous attention pane), `Enter` (open detail). Terminals built on VTE
@@ -26,6 +26,8 @@ shipped default on the operator USB, with `xterm` retained as the always-works
 fallback (Kitty is GPU-only; it cannot start on a headless `bhyve` surface with
 no GL, so the rescue path falls back to `xterm`).
 
+**Install:** `pkg install kitty` (FreeBSD port `x11/kitty`, currently 0.47.4).
+
 → [`crates/colibri-glasspane-tui/src/main.rs`](../../crates/colibri-glasspane-tui/src/main.rs)
 (the bindings above)
 
@@ -75,9 +77,9 @@ to the remote on connect — used as the `ssh` alias on operator machines. Lying
 with `TERM=xterm-256color` works but discards the extended-key capability,
 defeating the reason for the terminal choice.
 
-### pi surfaces the same requirement
+### Agent harness surfaces the same requirement
 
-The pi harness — a spawnable Colibri backend — prints a startup warning when
+Agent harnesses (zot, pi) — spawnable Colibri backends — print a startup warning when
 tmux extended-keys is off, because its own bindings (`Enter` to submit,
 `Shift-Enter` for newline) hit the identical collapse. The decision here is the
 same one, stated for Colibri's surfaces: pick a terminal that reports

scripts/wiki-lint

@@ -49,7 +49,6 @@ for wiki_file in "$WIKI_DIR"/*.md; do
         case "$path_ref" in
             ""|index*|agent-harness*|naming-decisions*|quality-gates*) continue ;;
             path/to/*|clawdie-iso/*) continue ;;
-            fake-pi-agent.py) continue ;;            # old name in the Shipped table
             stage-colibri-iso.sh) continue ;;        # cross-repo (clawdie-iso)
             ADR-agent-harness-consolidation.md) continue ;;  # wiki-documented as absent
             *.md|*.rs|*.sh|*.py|*.sql|*.json|*.toml|*.yml|*.cfg|*.env|*.txt) ;;
@@ -157,13 +156,6 @@ while IFS= read -r old_name; do
     fi
 done < "$OLD_NAMES_FILE"
 
-# The renamed sample agent must not reappear under its old filename.
-if [ -f "$REPO_ROOT/scripts/fake-pi-agent.py" ]; then
-    fail "scripts/fake-pi-agent.py still exists (renamed to sample-pi-agent.py)"
-else
-    pass
-fi
-
 echo ""
 
 # ── 3. orphan pages ───────────────────────────────────────────────────