| name | diagnose-dev-reload |
| description | Diagnose why `task dev` hot-restart isn't picking up Go changes (no sidecar respawn, stale endpoints, renderer hitting old port/token). Use when the user reports "I changed Go code but nothing happened", "the backend didn't reload", or "the watcher seems stuck". |
The reload pipeline (mental model)
task dev runs two processes via concurrently:
- Electron (
pnpm run start) — main process starts the Go sidecar from bin/<os>-<arch>/relay-backend, parses the handshake JSON line, and exposes {port, token, baseUrl} to the renderer via preload.
- Watcher (
node scripts/dev-watcher.mjs) — chokidar watches *.go / go.mod / go.sum, debounces 300ms, then runs openapi → codegen → build:go and writes .dev-reload (content: epoch ms).
The Electron main process fs.watches the parent directory, filters by filename .dev-reload, dedups by mtimeMs, then:
- Kills the old sidecar.
- Spawns a new one (new port, new token).
- Calls
reloadIgnoringCache() on all windows.
- Renderer's
getClient() cache is invalidated by the reload.
Checklist (run in order)
-
Is the watcher actually running?
task dev should show two log streams (electron blue, watcher magenta). If only electron is logging, concurrently killed the watcher — look at terminal for an error. Common cause: chokidar v4+ failure because someone passed a glob instead of a directory.
