pi-gui/TEST_PLAN.md

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

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