# AMQ Bridge E2E Test Matrix

Purpose: validate user-visible lifecycle and collaboration behavior with structured evidence, not terminal text alone.

## Evidence contract

Every scenario records:

- unique AMQ root, state directory, CWD, and session key
- process PID and watcher PID
- owner identity before/after
- active ID before/after
- processed IDs before/after
- mailbox envelope IDs, headers, box, and body only through explicit read
- tool result `details` including message ID, root, sender, target, kind, priority, thread
- UI output only as secondary diagnostic evidence

## Release-gating tiers

- **Tier 1 — deterministic:** fake AMQ, real lifecycle/state code, no provider dependency. Required.
- **Tier 2 — runtime:** real Pi process/PTY, fake or local AMQ. Required when Pi available.
- **Tier 3 — real peer:** real Pi + real AMQ + provider. Diagnostic; provider failures reported separately.

## Lifecycle scenarios

| ID | Scenario | Required evidence |
|---|---|---|
| DETACH-01 | `/amq-bridge detach` gives immediate feedback | `Detaching...` appears before cleanup; input handler returns; cleanup completion/failure follows asynchronously |
| DETACH-02 | Detach during blocked watcher/send | no input deadlock; owner release ordered after mutation; no lost message; watcher reaped |
| DETACH-03 | Secondary detach | secondary state removed; owner/watcher remain; owner receives next message |
| QUIT-01 | Graceful Pi quit | `session_shutdown`; watcher reaped; owner released; peer receives detached notice |
| QUIT-02 | SIGTERM | cleanup hook behavior, owner state, watcher reaping, peer notice |
| QUIT-03 | SIGKILL | stale owner takeover; no false detached notice; active reset policy explicit |
| RELOAD-01 | Fresh session restore | mailbox repaired before migration; exactly one watcher/owner |
| RELOAD-02 | Reload while another owner lives | read-only secondary; no shared mutation |
| RELOAD-03 | Invalid/partial state | stale state cleared; warning; no watcher until attach |
| PEER-01 | Graceful peer disconnect | detached housekeeping filtered; warning; status shows offline |
| PEER-02 | Presence TTL | active fresh presence online; stale active presence offline |
| PEER-03 | Reconnect | attached notice changes same peer offline → online; no duplicate roster |

## Receive and collaboration scenarios

| ID | Scenario | Required evidence |
|---|---|---|
| QUEUE-01 | Q1/Q2/Q3 backlog | oldest actionable active; one active at a time; deterministic next progression |
| QUEUE-02 | Complete active work | reply completes with response; resolve completes without response; each selects next active |
| QUEUE-03 | Unfinished active after read | active ID survives `new → cur`; explicit reply/resolve required before next active turn |
| QUEUE-04 | Processed inbox | default inbox hides processed old messages; `--all` retains history |
| STACK-01 | Nested peer continuation | parent active; same-thread trusted answer pushes child; child completion resumes parent |
| STACK-02 | Urgent interruption | parent + continuation active; trusted urgent pushes top; urgent completion resumes continuation then parent |
| STACK-03 | Completion/preemption race | urgent push after parent target validation survives parent completion; dequeue never overwrites urgent frame |
| STACK-04 | Depth overflow | ninth promotion is atomically deferred; current top wakes to free capacity; deferred ID auto-promotes on completion; watcher remains owner/alive |
| STACK-05 | Crash recovery | completed top frame persisted before pop; restart removes completed frames and emits parent recovery before blocking watch |
| LOOP-01 | Repeated inbox reads | same ID cannot cause repeated context/turn; no new duplicate sends from bridge |
| LOOP-02 | Repeated application sends | distinct sends remain visible as model behavior; optional guard diagnostics |
| ID-01 | Invalid read/reply/resolve ID | fail closed; no state mutation; queue unchanged |
| ID-02 | Explicit message identity | read/reply/resolve operate only on requested ID |

## Nested-work live acceptance

Real Pi acceptance requires three restarted sessions:

1. `bip` gives `bop` a parent task.
2. `bop` asks `pib` a same-thread question and waits.
3. `pib` answers; `bop` must wake with child answer active while parent is suspended.
4. During continuation, `bip` sends trusted urgent actionable work to `bop` and `pib`.
5. Each handles urgent work at next available turn, then resumes exact interrupted frame.
6. Final evidence records IDs, kinds, priorities, timestamps, stack-top transitions, and zero unfinished test residue.

Full Pi process restart is mandatory before this acceptance; `/reload` is not a scheduler upgrade boundary.

## Metadata and urgency scenarios

| ID | Scenario | Required evidence |
|---|---|---|
| META-01 | All actionable kinds | question, decision, review_request, review_response, answer, todo wake when idle |
| META-02 | FYI kinds | status context-only (never wakes, even urgent); brainstorm actionable |
| META-03 | Priority display | normal default; low/urgent preserved in envelope/evidence |
| URG-01 | Trusted urgent actionable | `urgentTrusted=true`, trigger despite existing active |
| URG-02 | Untrusted urgent actionable | envelope delivered; no urgent wake override |
| URG-03 | Urgent stop | delivery measured separately from hard cancellation; active model turn cannot be claimed cancellable without explicit interrupt mechanism |

## Multi-peer scenarios

| ID | Scenario | Required evidence |
|---|---|---|
| PEERS-01 | Explicit routing | target A/B IDs and threads exact; no cross-delivery |
| PEERS-02 | Primary selection | default target follows primary only; explicit target bypasses primary |
| PEERS-03 | Handshake discovery | discovery-only; never implicit primary/trust |
| PEERS-04 | One peer disconnects | only that peer offline; other peer remains online |
| PEERS-05 | Duplicate notices | no duplicate roster/notification |
| PEERS-06 | Add third Pi peer to existing pair | real `bip↔bop`, then `pib→bop`; shared AMQ roster remains `bip,bop,pib`; `bop` renders `bip, pib` with no false `(offline)` marker |

### Exact peer-presence regression harness

`npm run e2e:peer-presence` launches isolated real Pi/tmux sessions using exact live handles and sequence:

1. attach `bip` to `bop` and `bop` to `bip`;
2. attach/detach a read-only secondary `bip` session to exercise shared-identity lifecycle;
3. start new Pi identity `pib` and attach it to `bop`;
4. require final `bop` status `[bop] ↔ bip, pib` and reject `bip (offline)`.

It uses isolated mailbox, owner-state, CWD, and Pi session directories and captures every pane on failure.

## Comprehensive authentic conversation harness

`npm run e2e:authentic` launches two isolated real Pi sessions with only `integrations/pi-extension.ts` loaded. Provider failures are reported separately from bridge assertions.

Coverage:

- Cross-session attach and presence heartbeat.
- Authentic model tool calls: send → inbox → explicit read → either reply by original ID or resolve by original ID.
- Bidirectional multi-turn conversation with exact bodies, senders, subjects, and thread routing.
- Completed-message queue progression and stale-answer loop prevention.
- Urgent actionable message metadata and delivery.
- Quiet-window assertions after each conversation phase; repeated actionable sends fail run.
- Graceful detach and reattach.
- Captures full tmux logs and PNG evidence under unique run directory.

## Naturalistic peer ecology harness

`npm run e2e:natural` uses an isolated per-run mailbox root with `bpat`, `bi-boss`, and `e2e-referee`, using one-shot natural prompts rather than protocol scripts. Use `npm run e2e:natural:existing` or `PI_E2E_ROOT=...` for stale-history diagnostics:

- bpat receives one prompt: invite bi-boss to exactly one RPS game and stop.
- After game traffic appears, referee receives one prompt: send bi-boss one urgent task and stop.
- bi-boss receives no scripted workflow prompt; its behavior comes from injected peer context.
- Assertions observe RPS traffic, urgent priority, responses, quiet windows, and extension-only launch.
- Isolated acceptance root prevents unresolved historical work from changing causal result.
- Existing-root mode intentionally tests stale-work policy and is not equivalent to clean communication acceptance.
- Run artifacts record root mode and run-specific files.

Latest verified isolated runs:
- `e2e-natural-peer-20260803-211328-8569`
- `e2e-natural-peer-20260803-211537-17786`

## Real runtime scenarios

- Pi session start/quit through PTY/tmux.
- `/amq-bridge attach`, `connect`, `peer`, `inbox`, `read`, `send`, `reply`, `resolve`, `detach`.
- Session JSONL/tool results are primary assertions; terminal captures are diagnostics.
- Cross-CWD shared-root behavior.
- Real-peer conversation with provider errors classified separately from bridge errors.

## Completion rule

Scenario is not passing from a source-order assertion alone. Each implemented row needs a runtime test or an explicit documented reason why only a lower-level deterministic test is possible.