# 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

```text
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

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