pi-gui/IMPLEMENTATION_PLAN.md

Pi Status Bridge — Implementation Plan

Reason for existence

Turn the approved design into small, verifiable slices while preserving Pi as the source of truth for tool policy and model configuration.

Milestone 1 — Bridge foundation

1. Create the bridge package and an explicit local protocol schema.

   • Define agent ID, worktree path, state, event, extension-request, and command envelopes.
   • Define socket path, file modes, lock/PID format, and stale-owner algorithm.
   • Verify: schema tests reject malformed messages and cross-worktree requests.

2. Implement single-instance startup and Unix-socket serving.

   • Acquire lock atomically; detect a live owner; recover only a proven-stale lock.
   • Create the socket in $XDG_RUNTIME_DIR with owner-only permissions.
   • Verify: a second bridge refuses startup; a different user cannot connect.

3. Implement the Pi RPC child adapter.

   • Spawn pi --mode rpc with an explicit worktree cwd and session location.
   • Correlate command IDs, parse JSONL, normalize state/event payloads, and preserve transcript cursors.
   • Verify: a fake Pi RPC fixture exercises prompt, streaming, tool events, queue updates, and extension UI requests.

Milestone 2 — Agent registry and recovery

1. Implement worktree-keyed agent management.

   • Canonicalize paths before registry lookup.
   • Create/resume the home agent on bridge startup.
   • Create/resume worktree agents only when selected or inferred.
   • Verify: separate worktrees never share agent IDs, transcript entries, or outgoing prompts.

2. Implement session persistence and recovery.

   • Store the Pi session reference per agent.
   • Restart unexpected exits with bounded exponential backoff.
   • Resume the prior Pi session; publish failed-recovery state after limits are exhausted.
   • Verify: injected crashes resume the expected session and stop retrying at the configured bound.

3. Proxy Pi-owned controls without bridge defaults.

   • Read current model/thinking state from Pi.
   • Forward supported user changes directly to Pi and refresh displayed state from Pi’s response/events.
   • Verify: bridge restarts do not reapply an independent model or thinking value.

Milestone 3 — Adapter-facing API and local helper

1. Implement adapter operations.

   • Agent/session listing and explicit selection.
   • State/transcript subscription and replay after reconnect.
   • Prompt, steer, follow-up, abort, and extension UI response forwarding.
   • Verify: a scripted local client can reconnect and catch up without duplicate events.

2. Build the local client helper.

   • Make it the fallback transport for hosts that cannot open Unix sockets.
   • Support only the approved bridge protocol; never start a network listener.
   • Verify: helper cannot reach a socket owned by another user.

Milestone 4 — Noctalia adapter

1. Implement the bar widget.

   • Render state glyph/color, selected project, and attention badge.
   • Keep streaming/tool detail out of the bar.
   • Verify: fixture states map to the agreed compact bar states.

2. Implement shortcut and popover behavior.

   • Infer focused worktree when unambiguous.
   • Otherwise open a selector defaulted to home.
   • Support explicit switching, transcript streaming, composer, queue/tool state, extension forms, session manager, and Pi-proxied controls.
   • Escape dismisses the popover only.
   • Verify: manual checklist passes on Noctalia.

Milestone 5 — Hardening and release readiness

1. Add observability and safe failure presentation.

   • Structured local logs for agent lifecycle, recovery, socket ownership, and protocol errors.
   • Redact prompt and tool payload content by default.
   • Verify: failure reports identify the agent/worktree without leaking transcript content.

2. Run the approved readiness gate.

   • Execute automated bridge tests, manual Noctalia QA, cross-user socket rejection check, crash/recovery scenarios, and overnight soak.
   • Verify: all exit criteria in TEST_PLAN.md pass before daily use.

Dependencies

Foundation → Pi RPC adapter → registry/recovery → adapter API/helper → Noctalia UI → hardening/soak

Never rules

• Never let the bridge decide tool approval policy.
• Never route a prompt to a worktree different from the selected agent.
• Never expose a TCP listener in v1.
• Never persist model or thinking defaults outside Pi.

Verification

# Plan completeness: all five planned milestones are present.
grep -c '^## Milestone' IMPLEMENTATION_PLAN.md
# Expected: 5