feat(bridge): establish local pi status bridge

Deliver the initial local bridge, Noctalia v4/v5 adapters, desktop client, service unit, tests, and implementation documentation for persistent Pi status and control.
2026-07-27 14:51:45 +02:00
commit b7fea83ed6
91 changed files with 15029 additions and 0 deletions
@@ -0,0 +1,101 @@
+# Pi Status Bridge — Design
+
+## Reason for existence
+
+Provide a persistent, local Pi coding-agent experience through a compact status-bar UI without duplicating Pi’s terminal TUI or weakening tool-owned safety policy.
+
+## Goals
+
+- Keep one Pi RPC agent per project/worktree, plus a home-directory agent started with the bridge.
+- Open a chat-like popover by shortcut; accept prompts, steering messages, follow-ups, and structured extension questions.
+- Present compact status in Noctalia: state glyph/color, active project, and attention badge.
+- Make the bridge reusable by future desktop/status-bar adapters.
+- Resume sessions after bounded automatic recovery.
+
+## Non-goals
+
+- Terminal emulation or embedding Pi’s terminal TUI.
+- Rendering rich TUI-only extension overlays.
+- Inventing approval policy or interpreting tool permissions.
+- A network service, remote control, or adapters beyond Noctalia in v1.
+
+## Architecture
+
+```text
+Noctalia bar + popover ─┐
+                         ├─ local client helper ─ Unix socket ─ Pi Status Bridge
+future host adapter ────┘                                  │
+                                                            ├─ Agent registry
+                                                            ├─ session/recovery supervisor
+                                                            └─ pi --mode rpc (one child/worktree)
+```
+
+### Bridge
+
+The bridge is the only component that starts, stops, and restarts Pi. It owns:
+
+- Agent registry keyed by canonical project/worktree path.
+- A long-lived `pi --mode rpc` child per active worktree.
+- Translation of Pi JSONL events into a stable local event model.
+- Session resume after child restart, bounded exponential backoff, and terminal error state after exhaustion.
+- A per-user Unix-domain socket under `$XDG_RUNTIME_DIR` with restrictive permissions.
+- A lock/PID file with stale-owner recovery.
+
+It exposes only local request/response and subscription operations: enumerate/select agents, send `prompt`/`steer`/`follow_up`, abort, read state/transcript, proxy model/thinking commands, and answer extension UI requests.
+
+### Noctalia adapter
+
+The adapter is presentation only:
+
+- Bar: glyph/color, selected project name, attention badge.
+- Shortcut: choose the focused worktree when unambiguous; otherwise open a selector defaulted to home.
+- Popover: transcript, composer, tool activity, queue state, extension UI requests, agent/session manager, and Pi-proxied model/thinking controls.
+- Escape hides the popover only; it never aborts Pi.
+
+The popover always permits explicit project/worktree switching.
+
+## Agent lifecycle
+
+1. Bridge starts and acquires the lock.
+2. It creates/resumes the home agent.
+3. A focused worktree or explicit selection creates/resumes that worktree’s agent.
+4. On unexpected child exit, the bridge retries with bounded exponential backoff and resumes the saved Pi session.
+5. After retry exhaustion, it publishes an error state and exposes explicit restart/retry controls.
+
+## Interaction contract
+
+| State | Bar | Popover action |
+| --- | --- | --- |
+| Idle | neutral glyph | send prompt, browse transcript |
+| Streaming/tool active | working glyph | stream response/tool progress, steer or abort |
+| Queued input | attention badge | inspect queue or send follow-up |
+| Extension question/confirmation | attention badge | render request and return response unchanged |
+| Failed recovery | error glyph | inspect failure and retry/restart |
+
+## Policy and configuration boundaries
+
+- Extensions/tools decide whether approval is required.
+- The bridge forwards only RPC-compatible structured extension requests and responses.
+- Pi chooses model and thinking defaults and remains the source of truth.
+- The popover may display current Pi values and forward supported changes; it stores no competing defaults or persistence policy.
+
+## Security invariants
+
+- **Never** listen on TCP for v1.
+- **Never** allow another user to attach to the socket.
+- **Never** map a bridge request to another worktree silently.
+- **Never** treat a bridge/UI action as permission to bypass extension-owned approvals.
+
+## Key risks
+
+- Focused-window worktree inference can fail; explicit selection is mandatory.
+- TUI-only extension overlays cannot cross the RPC boundary.
+- The local client helper must retain same-user-only access.
+- Named-session controls must clearly show the selected worktree before acting.
+
+## Verification
+
+```sh
+# After implementation: required architecture artifacts exist.
+test -f DESIGN.md && test -f IMPLEMENTATION_PLAN.md && test -f TEST_PLAN.md
+```