Boot Wedge Debug

Boot Wedge Debug

Workflow for diagnosing the intermittent webview boot wedge and driving it to a definitive fix. Fixes land iteratively on PR #3436 (fix/injected-boot-recovery).

The bug in one paragraph

Sometimes a workspace webview never finishes booting: the Rocket.Chat throbber spins forever. Its console shows Cannot find module '/app/utils/rocketchat.info' (Meteor module registry incomplete) and often a ServiceWorker InvalidStateError. A plain reload (⌘R = webContents.reload()) never cures it; historically only a full app restart did. src/injected.ts now auto-recovers via force reload with service worker + cache clearing (max 2 attempts, sessionStorage-guarded), but at least one observed wedge survived that — the broken state may live in the guest renderer process itself. The planned escalation is recreating the <webview> (fresh renderer process).

Step 1 — Read the watchdog report first

The dev-only boot watchdog (src/servers/bootWatchdog.ts, enabled when NODE_ENV=development or ROCKETCHAT_BOOT_WATCHDOG=true) appends one JSON line per incident to:

macOS:   ~/Library/Logs/Rocket.Chat/boot-watchdog.jsonl
Windows: %USERPROFILE%\AppData\Roaming\Rocket.Chat\logs\boot-watchdog.jsonl
Linux:   ~/.config/Rocket.Chat/logs/boot-watchdog.jsonl

(The directory is Electron's app.getPath('logs'); in dev the app name may be Electron instead of Rocket.Chat. The watchdog prints the exact path at startup: [bootWatchdog] enabled — … appended to <path>.)

Summarize incidents:

python3 -c "
import json
for l in open('$HOME/Library/Logs/Rocket.Chat/boot-watchdog.jsonl'):
    r = json.loads(l)
    print(r['ts'], r['reason'], r['serverUrl'], '| probe:', json.dumps(r.get('probe'))[:120])
"

Then inspect the interesting incident in full: probe, timeline, serviceWorkers, console (last 150 webview messages), processMetrics.

Reading the report

A healthy boot never produces a report. Navigation failures with a visible ErrorView (e.g. invalid TLS cert) are deliberately excluded.

Step 2 — Live autopsy (wedge currently on screen)

Do NOT restart the app. If it was launched with npx electron . --remote-debugging-port=9222 (preferred during this investigation), probe the wedged webview from outside:

node .claude/skills/boot-wedge-debug/cdp-eval.mjs <server-host> "JSON.stringify({
  readyState: document.readyState,
  title: document.title,
  requireType: typeof window.require,
  infoModule: (()=>{try{return !!window.require('/app/utils/rocketchat.info').Info}catch(e){return 'broken: '+e.message}})(),
  recoveryAttempts: sessionStorage.getItem('rocketChatDesktopBootRecoveryAttempts'),
  swControlled: !!navigator.serviceWorker?.controller
})"

Also useful live:

• List targets: curl -s http://127.0.0.1:9222/json | python3 -m json.tool
• SW registrations: eval navigator.serviceWorker.getRegistrations().then(rs => JSON.stringify(rs.map(r => r.scope)))
• Test the manual cure ladder (record which rung works — it localizes the broken layer):
  1. menu View → Reload (plain reload — historically never cures)
  2. menu View → Reload Clearing Cache (= what auto-recovery does)
  3. remove + re-add the workspace (recreates the <webview> → fresh renderer process)
  4. full app restart (historically always cures)

Step 3 — Map findings to action

Step 4 — Land the fix

1. Reproduce/justify with report evidence; quote the relevant timeline lines in the PR.
2. Fix on branch fix/injected-boot-recovery (worktree ../Rocket.Chat.Electron-worktrees/fix-injected-boot-recovery).
3. Validate: npx tsc --noEmit, yarn lint, yarn test, yarn build, plus a watchdog smoke test: run the app ≥150s with healthy servers → zero new reports (guards against false positives).
4. Push and update PR #3436 with a comment describing what the report revealed and what changed. Log the incident + fix in .wolf/buglog.json.

Known gotchas

• did-start-loading fires for subframes/resources — never use it to reset a boot cycle (caused the watchdog's first false positive; cycles key on did-navigate).
• Injected-script console.logs do NOT reach the main process log; only warn/error are forwarded. The watchdog's console buffer captures all levels.
• WEBVIEW_SERVER_VERSION_UPDATED is the boot-success signal, dispatched by setVersion from setServerInfo (wired in PR #3436 — it was dead code before).
• The re-render loop fix (PR #3435) is a separate branch; a Maximum update depth exceeded storm in a build without it is that bug, not a regression.