alex
b7fea83ed6
Deliver the initial local bridge, Noctalia v4/v5 adapters, desktop client, service unit, tests, and implementation documentation for persistent Pi status and control.
94 lines
4.0 KiB
Markdown
94 lines
4.0 KiB
Markdown
# 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
|
||
|
||
### Startup and routing
|
||
|
||
- [ ] Starting the bridge creates the home agent and shows it in the bar/popover.
|
||
- [ ] Shortcut on a known focused worktree opens that worktree’s agent.
|
||
- [ ] Missing or ambiguous focus opens the selector with home preselected.
|
||
- [ ] Popover project/session manager switches agents explicitly and visibly.
|
||
- [ ] Escape closes the popover without aborting streaming work.
|
||
|
||
### Status and conversation
|
||
|
||
- [ ] Bar shows state glyph/color, active project, and attention badge.
|
||
- [ ] Popover streams assistant text and tool activity without blocking the composer.
|
||
- [ ] Prompt, steer, follow-up, and abort map to the intended Pi action.
|
||
- [ ] Queue changes are visible and do not reorder or lose user messages.
|
||
- [ ] Pi model/thinking values display correctly and forwarded changes round-trip from Pi.
|
||
|
||
### Extension prompts
|
||
|
||
- [ ] Select, confirm, input, and editor requests render as native popover UI.
|
||
- [ ] The response reaches the originating extension unchanged.
|
||
- [ ] A pending request produces an attention badge while the popover is closed.
|
||
- [ ] TUI-only unsupported custom UI is presented as an explicit unsupported/error state, never silently approved.
|
||
|
||
## 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
|
||
```
|