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.

specs/FULL_PI_PANEL_SPEC.md

@@ -0,0 +1,119 @@
+# Full Pi Panel Specification
+
+## Reason for existence
+
+Replace the compact Noctalia status widget with a feature-equivalent local Pi
+client panel. The bar remains a compact launcher and status indicator; the
+panel is the single interaction surface.
+
+## User flow
+
+1. The user session starts one bridge-managed Home agent for `$HOME`.
+2. Clicking the bar opens the **Output** view for the selected agent. Home is
+   selected by default.
+3. Output shows transcript/history, live streaming/tool/queue state, extension
+   requests, and one composer anchored at the bottom.
+4. The composer mirrors the confirmed TUI workflow: submit a normal prompt;
+   when Pi is busy, Pi queues it as a follow-up. The panel never asks the user
+   to choose prompt versus steer versus follow-up for ordinary submission.
+5. **Settings** is the only location for folder management. Adding an absolute
+   folder explicitly creates/resumes its own agent, persists it, and selects it.
+6. The user may switch among remembered agents from Settings. Previously added
+   folders do not start at login unless selected; Home is always running.
+
+## Views
+
+### Output (default)
+
+- Header: selected folder, agent health, streaming/queue/recovery status.
+- Scrollable transcript: user, assistant, tool result, and visible custom
+  messages. Thinking content follows Pi visibility policy; it is not exposed by
+  default merely because the panel exists.
+- Tool activity: current tool name/progress while active and tool results in
+  history after completion.
+- Composer: one input and one submit action. It accepts normal text, Pi command
+  syntax, prompt templates, and skills exactly as Pi RPC `prompt` accepts them.
+- Suggestions: when composer input begins with `/`, show Pi-provided
+  `get_commands` entries. Selecting one inserts it; it does not execute until
+  submitted.
+- Extension requests: select, confirm, input, and editor map to native panel
+  controls and return the exact request ID/response shape. Unsupported custom
+  TUI UI renders an explicit unsupported state and never approves anything.
+
+### Settings
+
+- Agent list: Home plus remembered explicit folders, each with state.
+- Folder input: requires an absolute path. Adding it invokes `select_agent`;
+  bridge canonicalization remains authoritative.
+- Session controls: current session metadata, retry/restart, and agent health.
+- Pi controls: available models, current model, thinking level, and queue modes
+  are read from Pi and changed only through Pi proxy operations. No independent
+  bridge defaults or persistence are allowed.
+
+## Bridge/API contract
+
+The panel speaks only through `pi-status-bridge-client` over the owner-only
+Unix socket. Required operations are:
+
+| Purpose | Operation |
+| --- | --- |
+| agents | `list_agents`, `select_agent` |
+| live state | `get_state`, `subscribe` |
+| history | `get_transcript` |
+| composer | `submit_prompt` |
+| recovery | `retry`, `restart` |
+| Pi controls | `get_available_models`, `set_model`, `set_thinking_level` |
+| suggestions | `get_commands` |
+| extension UI | `extension_response` |
+
+`submit_prompt` is the only default composer operation. The bridge dispatches
+it to Pi `prompt` when idle and Pi `follow_up` while streaming; Pi retains
+queue semantics. Direct `steer` and `follow_up` may exist only as explicit
+advanced/TUI-parity shortcuts after their exact behavior is verified; they are
+not ordinary UI buttons.
+
+## State and persistence
+
+- Bridge persists the Pi session reference per canonical worktree.
+- Noctalia persists the remembered folder list and last selected agent in its
+  plugin data directory, not the plugin installation directory.
+- The bridge starts Home; Noctalia never spawns Pi or owns a socket lock.
+- Agent IDs are bridge-issued. The panel never invents or maps IDs to another
+  worktree.
+
+## Safety invariants
+
+- Never expose TCP.
+- Never silently select a non-Home folder.
+- Never auto-approve extension/tool requests.
+- Never replace Pi model, thinking, or queue policy with panel defaults.
+- Never treat unsupported custom extension UI as approval.
+- Never execute an arbitrary folder path through an unquoted shell command.
+
+## Acceptance scenarios
+
+- **Home startup:** After user login, Home appears as a ready/working agent
+  without opening the panel.
+- **Folder add:** Entering an absolute folder in Settings creates/selects its
+  distinct agent; Home transcript and prompts remain isolated.
+- **Normal prompt:** Submitting the one composer while idle sends one Pi prompt.
+- **Busy prompt:** Submitting while Pi is active follows Pi's follow-up queue
+  behavior without an extra panel decision.
+- **History:** Reopening Output replays existing transcript, then receives live
+  updates without duplicate cursor entries.
+- **Command suggestion:** Typing `/` presents `get_commands` results; selection
+  inserts, not executes, a command.
+- **Extension safety:** Confirm/select/input/editor responses preserve request
+  IDs and values; custom UI shows unsupported.
+- **Recovery:** Failed-recovery state is visible with explicit retry/restart.
+
+## Verification
+
+```sh
+npm run check && npm test
+/usr/bin/noctalia plugins lint ~/.local/share/noctalia/plugins/pi-status-bridge
+/usr/bin/noctalia config validate
+```
+
+Manual verify: open the panel, select Home, add a folder from Settings, submit a
+prompt, close/reopen the panel, and confirm history plus status remain correct.