bitvid/docs/KNOWN_BUGS.md

Known Bugs (deferred)

Running list of confirmed bugs/limitations found during the data-flow refactor (see architecture-refactor.md) that we chose to fix later rather than block the current phase. Distinct from the planned refactor work in that doc — these are defects.

Format: [severity] short title — where — what — suggested fix / phase.

---

Tracked

Status is per-entry (RESOLVED / FIXED / Open). Items #3 and #4 below remain open; #0, #1, and #2 are resolved and kept here for provenance.

0. Encrypted lists (hashtags, DMs, blocks) fail to DECRYPT on login — RESOLVED (2026-06-16)

• Severity: high — the user's recurring "hashtags/DMs/watch-history don't load in the profile modal."
• Diagnosed from real-env console (2026-06-14): the lists are fetched (e.g. block events Array(2)) but decryption fails, three different ways:
  • DMs: DM decryption helpers are unavailable (client.js listDirectMessages → buildDmDecryptContext returns 0 decryptors → hard throw, no retry). Happens when ensureExtensionPermissions returns ok:false.
  • Blocks: Decryption timed out; signerStatus: 'missing'/'unknown' (userBlocks.js applyEvents) — the signer/decrypt capability isn't resolved.
  • Hashtags: Decryption timed out after 6s (hashtagPreferencesService.js).
• Root cause (strong): a relay-connection STORM. On cold load the app opens WebSockets to the user's full ~20-relay NIP-65 list (most dead) because subsystems build relay lists from relayManager.getReadRelayUrls() + getWriteRelayUrls() (uncapped) — e.g. userBlocks.loadBlocksInternal. The dozens of failing connections churn the main thread and starve the nip-07 extension's postMessage round-trips → permission/decrypt calls fail or time out.
• Partial mitigation shipped: hashtag + subscription decrypt timeout 6s→15s.
• Relay-storm fix SHIPPED (2026-06-14): capReadRelays (in js/nostr/toolkit.js) bounds every read/subscribe path to MAX_SUBSCRIBE_RELAYS = 8, applied centrally at the chokepoints — client.js applyRelayPreferences (this.relays/readRelays) and relayBatchFetcher.js fetchListIncrementally (used by blocks, subs, hashtags). Writes stay uncapped. The helper is user-relays-first (a user's own relays are where their data authoritatively lives, and small fast-path limits would otherwise crowd them out — the bug that broke the first attempt) while RESERVING RESERVED_DEFAULT_RELAY_SLOTS = 2 for the reliable default aggregators so the "~20 personal relays, all dead" case still reaches a live relay. Test-aware: under test the reserved core is the test-relay override, so harnesses stay isolated. Regression coverage: tests/relay-subscribe-cap.test.mjs (bounded + reserved-defaults + writes-uncapped), and the spec-corrected user-blocks, subscriptions-manager, and nostr/client fetch tests.
• Real-env follow-up (2026-06-15 console): the relay cap WORKED (every sub now fans out to exactly 8 relays) but exposed the true blocker: under the post-login burst the nip-07 extension's message port drops ("message channel closed"), after which EVERY decrypt hangs to its ~15s timeout, each list service retries forever, and the app never recovers without a page refresh (CPU pinned — "fans at max"). The signer-readiness gate also took ~67s. Two-part fix in progress ("cut the burst, then add a safety net"):
  • Burst reduction (SHIPPED, increment 1): stop eagerly loading DM history at login (authSessionCoordinator dmStatePromise now defers; DMs load lazily when the Messages tab opens). Removes a 50-message decrypt burst that competed for the channel. Test: tests/app/login-defers-dms.test.mjs.
  • Channel circuit breaker (SHIPPED, increment 2): js/nostr/nip07Permissions.js now opens a circuit after CIRCUIT_TIMEOUT_THRESHOLD consecutive call timeouts — subsequent calls fail FAST (code: "nip07-channel-unresponsive") instead of each hanging ~15s, so the per-list retry loops stop pinning the CPU. A single periodic probe detects recovery; one success closes the circuit (no refresh). Responsive errors don't open it; interactive permission prompts bypass it. Test: tests/nostr/nip07-channel-breaker.test.mjs.
• Resilience shipped (increments 3-6): user-relays-first relay cap with reserved defaults; transient-decrypt → retry (channel-death/timeout no longer swallowed as "empty"); fetch/decrypt decouple + ProfileModalController ensureLoaded (cut the login REQ burst); subscription refresh-loop guard; generous decrypt budget (30s) + 60s backoff cap so a slow-but-responsive signer completes; permission-handshake variant timeout 3s→20s so slow signers aren't killed mid-grant.
• DEFINITIVE root cause for "lists never load" (2026-06-16): confirmed with a raw window.nostr probe in the user's browser — a single clean getPublicKey → nip04.encrypt → nip04.decrypt that bypasses ALL of bitvid hung forever, and the extension's own console showed ObjectMultiplex - orphaned data for stream "background-liveness" + malformed chunk + MaxListenersExceededWarning. i.e. the NIP-07 extension's content-script ↔ background-service-worker channel was dead/orphaned (classic MV3 worker death). This is an EXTENSION/environment failure, not a bitvid bug — no client change can force an unresponsive signer to answer. Fix is user-side: reload/unlock the extension + refresh.
• Client mitigation (SHIPPED): js/utils/signerHealthNotice.js — after a few consecutive list-decrypt timeouts with signerStatus: "present", emit ONE rate-limited, actionable user notice ("signer isn't responding to decryption — unlock/reload your extension and refresh") instead of a silent forever-retry. Wired into blocks/hashtags/subscriptions; reset on any decrypt success. Test: tests/signer-health-notice.test.mjs.
• Harness (scripts/perf/nip07-channel-sim.mjs): with a LATENCY override it proves the client now loads all lists for signers answering up to the decrypt budget; lists only fail once per-call latency exceeds the budget (i.e. the signer is the wall, not the client).
• DM decrypt resilience (SHIPPED): buildDmDecryptContext now gates on method existence (typeof activeSigner.nip44Decrypt === "function") rather than a possibly-stale extensionPermissionResult/capability snapshot, so DMs no longer hard-fail with "DM decryption helpers are unavailable" on a transient permission miss. Also fixed the Controller→Actions wrong-receiver bugs that made opening a conversation throw "… is not a function" (ProfileDirectMessageController/ProfileDirectMessageActions). Tests: tests/dm-decrypt-context.test.mjs, tests/dm-conversation-select.test.mjs.
• Post-login UI freeze (SHIPPED, 2026-06-16): once a responsive signer (nos2x) made decryption instant, profileModalController.handleAuthLogin rendered EVERY profile panel at login (friends list + per-contact avatars, subscriptions, blocks, relays, wallet, hashtags, storage) into a CLOSED modal — one main-thread burst that froze the tab for ~10-15s and stopped the profile panel from opening. Fixed by deferring panel rendering to selectPane() (lazy per-pane on open; added the missing friends case) and gating the block/subscription/contacts "change" re-renders on isProfileModalOpen(). DM-identity setup stays eager.
• CONFIRMED RESOLVED in real env (2026-06-16): after the user switched from KeysBand (dead MV3 worker) to nos2x, real-browser logs show DMs (NIP-04 + NIP-44), watch history (kind 30078), and contact/subscription lists all decrypting in milliseconds with no timeouts, no signerStatus: missing, no channel-death, and no forever-retry. The whole resilience stack (relay cap → DM defer → circuit breaker → transient-retry → decrypt budget → signer-health notice → DM receiver fixes → post-login freeze fix) is validated against the user's real vault. Moving #0 to resolved.
• Still open (follow-ups, lower priority): liveness-ranked relay health (see #4); optional nip-07 queue concurrency bump for slow signers (risks channel drops on some providers — opt-in); optional DM decrypt efficiency — bitvid currently tries BOTH nip44.decrypt and nip04.decrypt per message (half log expected invalid base64/invalid payload length errors), which could be halved by routing on the ?iv= (NIP-04) ciphertext marker. Benign; only worth doing if large-mailbox DM load feels slow.

1. Logged-out: video grid stays empty until a manual refresh — FIXED (2026-06-16)

• Severity: medium (first-load UX, logged-out).
• Symptom: logged out, after dismissing the disclaimer the grid doesn't populate until the page is refreshed.
• Root cause (CONFIRMED via repro): boot order in bootstrapInterface (js/index.js) opens the disclaimer (which makes the background inert via staticModalAccessibility), THEN await handleHashChange() loads the feed view and renders into that inert/hidden background — so the mount/render is dropped — and dismissing the disclaimer never re-triggered a render.
• Fix (SHIPPED): disclaimer.js hide() dispatches a bitvid:disclaimer-dismissed event; index.js listens once and calls application.loadVideos(true) so the feed re-renders into the now-interactive background. Fires only when a shown disclaimer is dismissed (returning visitors are unaffected).
• Repro/regression (scripts/perf/disclaimer-grid.mjs): fresh context, real relays; waits for #acceptDisclaimer, dismisses, then polls the grid for 15s. Before: post-dismiss card timeline 0,0,0,…, only a reload showed 132. After: 132,132,… immediately on dismiss. (The earlier "couldn't reproduce headlessly" was because the harness didn't actually wait for/raise the disclaimer; once it does, the bug is deterministic.)

2. Residual full-feed reload loop on list-loaded signals — FIXED (P5)

• Status: RESOLVED 2026-06-14. handleBlocksLoaded now reloads the feed only when the block-set signature actually changes (emit-on-change guard); handleRelaysLoaded only refreshes the relay UI (never the feed), and handleHashtagPreferencesChange already deduped by signature. Regression test: tests/app/blocks-loaded-reload-guard.test.mjs (cheat-resistant).

3. Direct-pool-access lint still misses MULTI-LINE access

• Severity: low (tooling gap — weakens the L1 chokepoint guarantee).
• Status: partially fixed — the regex now catches bare pool.sub( / pool.list( (re-baselined to 22 files). Still MISSES access split across lines, e.g. js/services/profileMetadataService.js writes nostr.pool newline .list( — so profiles is an unflagged fetch source.
• Fix: normalize whitespace before matching (collapse \.pool\s*\n\s*\.list) or move to an AST/grep -A1 check. Add profileMetadataService (and any other multi-line offenders) to the allowlist once detected.

4. Interim relay cap is static, not liveness-ranked

• Severity: low (acceptable interim).
• Where: js/nostr/toolkit.js capReadRelays — bounds the read/subscribe set to 8 (user relays first, 2 slots reserved for reliable defaults) but does NOT re-rank by live health. If a user's first 6 relays are dead, reads lean on the 2 reserved defaults until other paths recover; the dead ones still get a (bounded) connection attempt each cold load.
• Fix: P1's deferred RelayHealth — rank the bounded set by rolling liveness and re-resolve on health changes, so dead relays drop out of the read set entirely instead of consuming slots.

---

Pre-existing test failures (predate this refactor)

Confirmed failing at the pre-session baseline (4bd9503c) — not caused by the refactor, but should be triaged. Not in KNOWN_ISSUES.md.

5. tests/nostr-delete-flow.test.mjs

• "deleted events should not trigger subscription callbacks" — a deleted event reaches the feed callback (buffer delete-filter or dedupe). Investigate the VideoEventBuffer delete handling.

6. tests/view-counter.test.mjs

• "view event should append the session tag when requested" — view-event publishing tag composition (unrelated to the P3 counting refactor).

7. tests/nostr-count-fallback.test.mjs

• Fails at baseline; NIP-45 COUNT fallback path. Triage.

8. tests/nostr/nip07Permissions.test.js

• writeStoredNip07Permissions / clearStoredNip07Permissions fail under Node (no real localStorage). Likely environmental — provide a localStorage shim (see tests/test-helpers/setup-localstorage.mjs) or guard the test.

9. tests/app/hydrate-sidebar-navigation.test.mjs

• Fails at the pre-session baseline (4bd9503c). Triage.

10. tests/app/is-user-logged-in.test.mjs

• Fails at the pre-session baseline (4bd9503c). Triage.

---

Perf follow-ups (not bugs, but tracked)

• One-time login enrichment burst (~75 REQ frames): batched and O(relays), settles to idle, but could be trimmed by hydrating only on-screen cards.
• Remove js/devReqMonitor.js import + scripts/perf/* diagnostics in P6 cleanup once the refactor lands.