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.

IMPLEMENTATION_PLAN.md

@@ -0,0 +1,100 @@
+# Pi Status Bridge — Implementation Plan
+
+## Reason for existence
+
+Turn the approved design into small, verifiable slices while preserving Pi as the source of truth for tool policy and model configuration.
+
+## Milestone 1 — Bridge foundation
+
+1. Create the bridge package and an explicit local protocol schema.
+   - Define agent ID, worktree path, state, event, extension-request, and command envelopes.
+   - Define socket path, file modes, lock/PID format, and stale-owner algorithm.
+   - Verify: schema tests reject malformed messages and cross-worktree requests.
+
+2. Implement single-instance startup and Unix-socket serving.
+   - Acquire lock atomically; detect a live owner; recover only a proven-stale lock.
+   - Create the socket in `$XDG_RUNTIME_DIR` with owner-only permissions.
+   - Verify: a second bridge refuses startup; a different user cannot connect.
+
+3. Implement the Pi RPC child adapter.
+   - Spawn `pi --mode rpc` with an explicit worktree cwd and session location.
+   - Correlate command IDs, parse JSONL, normalize state/event payloads, and preserve transcript cursors.
+   - Verify: a fake Pi RPC fixture exercises prompt, streaming, tool events, queue updates, and extension UI requests.
+
+## Milestone 2 — Agent registry and recovery
+
+1. Implement worktree-keyed agent management.
+   - Canonicalize paths before registry lookup.
+   - Create/resume the home agent on bridge startup.
+   - Create/resume worktree agents only when selected or inferred.
+   - Verify: separate worktrees never share agent IDs, transcript entries, or outgoing prompts.
+
+2. Implement session persistence and recovery.
+   - Store the Pi session reference per agent.
+   - Restart unexpected exits with bounded exponential backoff.
+   - Resume the prior Pi session; publish failed-recovery state after limits are exhausted.
+   - Verify: injected crashes resume the expected session and stop retrying at the configured bound.
+
+3. Proxy Pi-owned controls without bridge defaults.
+   - Read current model/thinking state from Pi.
+   - Forward supported user changes directly to Pi and refresh displayed state from Pi’s response/events.
+   - Verify: bridge restarts do not reapply an independent model or thinking value.
+
+## Milestone 3 — Adapter-facing API and local helper
+
+1. Implement adapter operations.
+   - Agent/session listing and explicit selection.
+   - State/transcript subscription and replay after reconnect.
+   - Prompt, steer, follow-up, abort, and extension UI response forwarding.
+   - Verify: a scripted local client can reconnect and catch up without duplicate events.
+
+2. Build the local client helper.
+   - Make it the fallback transport for hosts that cannot open Unix sockets.
+   - Support only the approved bridge protocol; never start a network listener.
+   - Verify: helper cannot reach a socket owned by another user.
+
+## Milestone 4 — Noctalia adapter
+
+1. Implement the bar widget.
+   - Render state glyph/color, selected project, and attention badge.
+   - Keep streaming/tool detail out of the bar.
+   - Verify: fixture states map to the agreed compact bar states.
+
+2. Implement shortcut and popover behavior.
+    - Infer focused worktree when unambiguous.
+    - Otherwise open a selector defaulted to home.
+    - Support explicit switching, transcript streaming, composer, queue/tool state, extension forms, session manager, and Pi-proxied controls.
+    - Escape dismisses the popover only.
+    - Verify: manual checklist passes on Noctalia.
+
+## Milestone 5 — Hardening and release readiness
+
+ 1. Add observability and safe failure presentation.
+    - Structured local logs for agent lifecycle, recovery, socket ownership, and protocol errors.
+    - Redact prompt and tool payload content by default.
+    - Verify: failure reports identify the agent/worktree without leaking transcript content.
+
+ 2. Run the approved readiness gate.
+    - Execute automated bridge tests, manual Noctalia QA, cross-user socket rejection check, crash/recovery scenarios, and overnight soak.
+    - Verify: all exit criteria in `TEST_PLAN.md` pass before daily use.
+
+## Dependencies
+
+```text
+Foundation → Pi RPC adapter → registry/recovery → adapter API/helper → Noctalia UI → hardening/soak
+```
+
+## Never rules
+
+- Never let the bridge decide tool approval policy.
+- Never route a prompt to a worktree different from the selected agent.
+- Never expose a TCP listener in v1.
+- Never persist model or thinking defaults outside Pi.
+
+## Verification
+
+```sh
+# Plan completeness: all five planned milestones are present.
+grep -c '^## Milestone' IMPLEMENTATION_PLAN.md
+# Expected: 5
+```