Toju/emergency-fix/11-fix-priority-plan.md

11 — Fix priority plan (systematic waves)

Execute in order unless the user explicitly reprioritizes.
Each wave lists user outcome, work, depends on, proof.
Checkboxes are for agents to update when a wave is done.

---

Guiding principles

1. User-visible done > unit-green alone.
2. Fix identity + auth before chasing random WebRTC knobs — many voice/chat bugs are “never identified / wrong id.”
3. Interview before implement on each wave (repo rule) unless opted out / handoff already approved.
4. Stay in toju-app + targeted electron; ask once before server/ or full e2e/.
5. Correct lying docs in the same change (10).

---

Wave 0 — Shared baseline (half day)

• 0.1 Read 00-README.md, 01, 03, 10.
• 0.2 Build a cross-home repro matrix (manual or scripted):
  • Same home, same room
  • Different homes, room on home A
  • Different homes, room on foreign B (provision required)
  • DM + call between different homes
• 0.3 Enable WebRTC/signaling debug logs; capture home id, actor ids, peer keys, signal URLs on failure.
• 0.4 Confirm whether provision secret exists after fresh login vs after restart (Electron + browser).

Proof: Written repro notes attached to the next handoff (short).

---

Wave 1 — Silent multi-signal auth (P0)

User outcome: Never bounced to authorize login just for touching another signal server.

• 1.1 Interview + implement provision-secret ensure on restore (see 04, user story options A–D; recommend A).
• 1.2 Harden auth_required / auth_error home vs foreign handling (no false SESSION_EXPIRED).
• 1.3 Offline endpoints never navigate authorize (regression test).
• 1.4 Prove J4 + restart path (02).

Depends on: Wave 0.
Pack: 04, story agents-docs/user-stories/silent-cross-signal-server-auth.md.

---

Wave 2 — Presence identify/join integrity (P0)

User outcome: When you open a room, others see you; you receive live chat/voice roster.

• 2.1 Verify getIdentifyCredentialsForSignalUrl store fallback on every reconnect path.
• 2.2 Ensure room connect always identify → join with actor id for sourceUrl.
• 2.3 Alias canonicalization / cold-start health wait still correct.
• 2.4 Prove two-client presence + live chat_message after signal restart.

Depends on: Wave 1 (foreign rooms).
Pack: 05, 08.

---

Wave 3 — Cross-signal outbound identity (P0)

User outcome: Calls ring the real person or show a clear error; DMs stay one thread.

• 3.1 Implement outbound routable recipient selection + unreachable UX (09, lesson L2).
• 3.2 Implement DM conversation canonicalize + merge (09, lesson L3).
• 3.3 Relabel/fix LESSONS so examples match shipped symbols.
• 3.4 Prove cross-home call + DM reply visibility.

Depends on: Wave 1. Can parallelize lightly with Wave 2 if staffing allows.
Pack: 09.

---

Wave 4 — Voice negotiation & routing (P0)

User outcome: Bidirectional voice in shared channels, including cross-home users; reconnect either works or errors visibly.

• 4.1 Per-signal-url local actor id for initiator election + polite peer (06 failure 1).
• 4.2 Voice allow-list includes all peer-map aliases.
• 4.3 After reconnect budget: user-visible failure + retry action.
• 4.4 Decide TURN product stance (document vs defaults).
• 4.5 Prove same-home + cross-home voice; takeover; blip recovery.

Depends on: Waves 1–2; benefits from 3.
Pack: 06.

---

Wave 5 — Data channel recovery honesty (P0/P1)

User outcome: Control plane self-heals; chat history catch-up resumes; voice doesn’t mysteriously die without explanation.

• 5.1 Interview: soft replace (A) vs full rebuild + UX/resync (B) (07).
• 5.2 Implement choice; force inventory/resync on DC reopen.
• 5.3 Align realtime/README.md + voice-webrtc.md with code (10 L1).
• 5.4 Prove DC force-close recovery + no silent abandon.

Depends on: Wave 4 preferred (so voice metrics make sense).
Pack: 07, 08.

---

Wave 6 — Messaging catch-up & attachments (P1)

User outcome: Late joiners get history; images/files don’t stick on “Waiting…”.

• 6.1 Verify/fix inventory trigger on peer + DC repair.
• 6.2 Re-verify attachment announce/bind re-queue invariants.
• 6.3 Fix chat README inventory cap (10 L6).
• 6.4 Prove late-join history + image sync under reorder stress.

Depends on: Waves 2 + 5.
Pack: 08.

---

Wave 7 — Doc & contract cleanup (P2, continuous)

• 7.1 Fix auth domain README paths (10 L5).
• 7.2 Deprecate or fix signaling-contracts.ts warning banner.
• 7.3 Sync domain READMEs that oversimplify multi-credential auth.
• 7.4 Clear or refresh agents-docs/HANDOFF.md after each finished wave.

---

Suggested staffing (multiple agents)

Agent	Wave
Auth agent	1
Realtime/signaling agent	2, 5
Identity/DM/call agent	3
Voice agent	4
Chat/attachments agent	6
Docs agent	7 (or same PR as each fix)

Do not start Wave 4 “TURN tuning” before Waves 1–3 — it wastes time on NAT while identity is wrong.

---

Definition of “emergency over”

All of the following true on a two-signal-server manual matrix:

1. No spurious authorize/login while home session valid.
2. Presence mutual in shared rooms.
3. Bidirectional voice same-home and cross-home.
4. Live text + catch-up history.
5. Cross-home DM + call succeed or fail loudly.
6. DC/WS blip recovers or shows retry UI within ~1 minute.
7. Docs for recovery/identity match code (10 critical lies cleared).