diff --git a/docs/wiki/agent-harness.md b/docs/wiki/agent-harness.md index 0d882f4..14ff614 100644 --- a/docs/wiki/agent-harness.md +++ b/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`). diff --git a/docs/wiki/glasspane.md b/docs/wiki/glasspane.md index 093879a..f66282d 100644 --- a/docs/wiki/glasspane.md +++ b/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` diff --git a/docs/wiki/index.md b/docs/wiki/index.md index 73a3183..416a61f 100644 --- a/docs/wiki/index.md +++ b/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. diff --git a/docs/wiki/mother-hive.md b/docs/wiki/mother-hive.md index 5838f8c..dd2e7ce 100644 --- a/docs/wiki/mother-hive.md +++ b/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 diff --git a/docs/wiki/naming-decisions.md b/docs/wiki/naming-decisions.md index e96807e..b1263d8 100644 --- a/docs/wiki/naming-decisions.md +++ b/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` | diff --git a/docs/wiki/operator-attention.md b/docs/wiki/operator-attention.md index 8db0410..1860755 100644 --- a/docs/wiki/operator-attention.md +++ b/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`) diff --git a/docs/wiki/terminal.md b/docs/wiki/terminal.md index fefe652..8855dab 100644 --- a/docs/wiki/terminal.md +++ b/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 diff --git a/scripts/wiki-lint b/scripts/wiki-lint index 7844d15..69685af 100755 --- a/scripts/wiki-lint +++ b/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 ───────────────────────────────────────────────────