# Pi Status Bridge — Test Plan / QA Checklist

## Reason for existence

Prove that the always-running Pi bridge is correctly scoped, recoverable, and usable through Noctalia before it becomes part of daily work.

## Automated bridge tests

### Protocol and event normalization

- [ ] Reject malformed, oversized, and unknown local protocol messages.
- [ ] Correlate outgoing RPC commands with replies and errors.
- [ ] Normalize agent, turn, message, tool, queue, retry, and extension UI events.
- [ ] Replay only entries after a reconnect cursor; never duplicate transcript events.
- [ ] Preserve extension request IDs and forward the exact selected/confirmed/input response.

### Agent and worktree isolation

- [ ] Canonical paths map to a single expected agent ID.
- [ ] Different worktrees receive distinct Pi cwd/session references.
- [ ] A prompt, abort, model change, or extension response never targets another selected worktree.
- [ ] Bridge startup creates/resumes only the home agent.
- [ ] Explicit project selection creates/resumes the requested worktree agent.

### Pi configuration proxy

- [ ] Read current model and thinking state from Pi.
- [ ] Forward a user change to Pi using its supported RPC command.
- [ ] Refresh displayed state from Pi, not bridge-held defaults.
- [ ] Restarting the bridge does not overwrite Pi’s model or thinking behavior.

### Socket and ownership

- [ ] Socket is under `$XDG_RUNTIME_DIR` with owner-only permissions.
- [ ] A second live bridge instance refuses to acquire ownership.
- [ ] A stale lock is recovered only after liveness verification.
- [ ] Different-user access is rejected.
- [ ] The local helper cannot create or expose a TCP listener.

### Recovery

- [ ] Unexpected Pi child exit causes bounded exponential-backoff restart.
- [ ] Recovery resumes the last expected Pi session.
- [ ] Retry exhaustion publishes a failed-recovery state and stops looping.
- [ ] Explicit retry/restart returns the agent to a healthy or clearly failed state.

## Manual Noctalia checklist

### Aggregate launcher

- [ ] The widget shows aggregate open, working, attention, recovering, and error counts from `get_workspace_summary`.
- [ ] A background session requiring extension attention increases the aggregate attention count.
- [ ] Clicking the widget starts the bridge when needed and toggles the desktop UI.
- [ ] Noctalia contains no composer, session switcher, or extension-response control.
- [ ] The configured `PI_STATUS_UI_BINARY` and fallback binary both launch with `--toggle`.
- [ ] Restarting Noctalia reconnects to the bridge summary without changing active session runtimes.

## Soak and fault scenarios

- [ ] Run at least one overnight soak with the home agent and a worktree agent active.
- [ ] Inject at least one Pi child crash during streaming and one while idle.
- [ ] Confirm bounded recovery, resumed sessions, no duplicate events, and no orphan children.
- [ ] Restart Noctalia while the bridge remains active; reconnect without losing pending attention state.
- [ ] Verify no socket, lock, or transcript artifacts are world-readable.

## Exit criteria

- All automated cases pass.
- All manual Noctalia checks pass on the target desktop.
- Cross-user socket rejection passes.
- Overnight soak completes without an unbounded restart loop, lost session, incorrect worktree routing, or unhandled extension request.

## Verification

```sh
# Checklist remains complete enough for the agreed readiness gate.
grep -c '^\- \[ \]' TEST_PLAN.md
# Expected: at least 30
```