myxelium
e49b3ec112
- `LIVE_RELOAD=false npm run dev` keeps the renderer alive across a machine suspend; the reload client otherwise destroys the session under test. - `dev-peer.sh` plus a separate userdata dir runs a second local peer. - `tools/voice-probe.js` samples peer state and RTP counters from a live window, persisting to localStorage so a renderer reload cannot erase it. - e2e helpers for voice pairs, peer-role election, and a TURN relay. - Electron single-instance and dev-client-load decisions move into rules files with colocated specs.
154 lines
5.7 KiB
Markdown
154 lines
5.7 KiB
Markdown
# 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).
|