pi-gui/DESIGN.md

Pi Status Bridge — Design

Reason for existence

Provide a persistent, local Pi coding-agent experience through a compact status-bar UI without duplicating Pi’s terminal TUI or weakening tool-owned safety policy.

Goals

• Keep one Pi RPC agent per project/worktree, plus a home-directory agent started with the bridge.
• Open a chat-like popover by shortcut; accept prompts, steering messages, follow-ups, and structured extension questions.
• Present compact status in Noctalia: state glyph/color, active project, and attention badge.
• Make the bridge reusable by future desktop/status-bar adapters.
• Resume sessions after bounded automatic recovery.

Non-goals

• Terminal emulation or embedding Pi’s terminal TUI.
• Rendering rich TUI-only extension overlays.
• Inventing approval policy or interpreting tool permissions.
• A network service, remote control, or adapters beyond Noctalia in v1.

Architecture

Noctalia bar + popover ─┐
                         ├─ local client helper ─ Unix socket ─ Pi Status Bridge
future host adapter ────┘                                  │
                                                            ├─ Agent registry
                                                            ├─ session/recovery supervisor
                                                            └─ pi --mode rpc (one child/worktree)

Bridge

The bridge is the only component that starts, stops, and restarts Pi. It owns:

• Agent registry keyed by canonical project/worktree path.
• A long-lived pi --mode rpc child per active worktree.
• Translation of Pi JSONL events into a stable local event model.
• Session resume after child restart, bounded exponential backoff, and terminal error state after exhaustion.
• A per-user Unix-domain socket under $XDG_RUNTIME_DIR with restrictive permissions.
• A lock/PID file with stale-owner recovery.

It exposes only local request/response and subscription operations: enumerate/select agents, send prompt/steer/follow_up, abort, read state/transcript, proxy model/thinking commands, and answer extension UI requests.

Noctalia adapter

The adapter is presentation only:

• Bar: glyph/color, selected project name, attention badge.
• Shortcut: choose the focused worktree when unambiguous; otherwise open a selector defaulted to home.
• Popover: transcript, composer, tool activity, queue state, extension UI requests, agent/session manager, and Pi-proxied model/thinking controls.
• Escape hides the popover only; it never aborts Pi.

The popover always permits explicit project/worktree switching.

Agent lifecycle

1. Bridge starts and acquires the lock.
2. It creates/resumes the home agent.
3. A focused worktree or explicit selection creates/resumes that worktree’s agent.
4. On unexpected child exit, the bridge retries with bounded exponential backoff and resumes the saved Pi session.
5. After retry exhaustion, it publishes an error state and exposes explicit restart/retry controls.

Interaction contract

State	Bar	Popover action
Idle	neutral glyph	send prompt, browse transcript
Streaming/tool active	working glyph	stream response/tool progress, steer or abort
Queued input	attention badge	inspect queue or send follow-up
Extension question/confirmation	attention badge	render request and return response unchanged
Failed recovery	error glyph	inspect failure and retry/restart

Policy and configuration boundaries

• Extensions/tools decide whether approval is required.
• The bridge forwards only RPC-compatible structured extension requests and responses.
• Pi chooses model and thinking defaults and remains the source of truth.
• The popover may display current Pi values and forward supported changes; it stores no competing defaults or persistence policy.

Security invariants

• Never listen on TCP for v1.
• Never allow another user to attach to the socket.
• Never map a bridge request to another worktree silently.
• Never treat a bridge/UI action as permission to bypass extension-owned approvals.

Key risks

• Focused-window worktree inference can fail; explicit selection is mandatory.
• TUI-only extension overlays cannot cross the RPC boundary.
• The local client helper must retain same-user-only access.
• Named-session controls must clearly show the selected worktree before acting.

Verification

# After implementation: required architecture artifacts exist.
test -f DESIGN.md && test -f IMPLEMENTATION_PLAN.md && test -f TEST_PLAN.md