perf(app): kill the cold-launch beachball + guards against its return

[graydawnc]

Summary

v0.4.17 had a multi-second main-process stall on cold launch on machines with a heavy shell init — long enough that macOS surfaced a beachball within seconds of opening the app. Root cause was the agent-binary resolver doing three serialised `execSync(' -ilc command -v ')` calls on the main-process JS thread. This branch fixes it and adds two independent guards so the same class of regression cannot return silently.

How it manifested

• Cold launch on a machine with a non-trivial `.zshrc` (e.g. mise / asdf / fnm activation, large `PROMPT_COMMAND`)
• Within ~1–2s of opening Spool the cursor became the spinning pinwheel and stayed there for several seconds
• Subsequent launches felt the same because the resolver's cache was per-process; quitting cleared it

`sample` of the main process during launch showed it pinned at `v8::Function::Call` → JIT inside what turned out to be `AcpManager.detectAgents` → `cachedResolve` → `resolveSystemBinary` → `execSync(' -ilc ...')`, with no chance for the AppKit event loop to make forward progress.

What's in this PR

Three commits, each scoped to one defense in depth.

1. `perf(app): async + parallel agent-binary resolution with disk-cached results`

• `@spool-lab/core` gains `resolveSystemBinaryAsync`, `cachedResolveAsync`, `hydrateResolveCache`, and `getResolveCacheSnapshot`. The async path tries process PATH first, then well-known install locations (pure filesystem probes: homebrew, mise shims, nvm, `~/.local/bin`), and only falls back to interactive-shell lookup when nothing else matched. Sync variants kept for API compatibility — they're a single-binary trap door, no longer the default.
• `packages/app/src/main/binaryCache.ts` persists the resolver's snapshot to `~/.spool/resolved-bins.json` after every successful resolve, and hydrates from disk during `app.whenReady` before any IPC handler can fire. Cached entries are validated with `existsSync` before being served, so a brew upgrade or manual removal triggers a re-resolve instead of leaking a stale path.
• `AcpManager.detectAgents` parallelises its three lookups via `Promise.all`; `query()` awaits the async resolver for both the native-binary path and the node fallback; `envSetup` is now async so the claude path also flows through the async cache.

Net effect:

• Cold cache (first ever launch): three lookups in parallel, each tries fast paths before any shell exec — typically resolves via well-known paths in under 50ms
• Warm cache (every subsequent launch): zero shell exec; cached paths served from in-memory map, validated against fs

2. `test(app): catch any main-thread stall on cold launch`

Symptom-level guard — observes main-thread event-loop delay directly via `node:perf_hooks.monitorEventLoopDelay` (nanosecond-precision C++ histogram, built for exactly this). The monitor is started at the very top of `main/index.ts` module evaluation so it covers Electron bootstrap, not just `whenReady`-and-after.

When `SPOOL_E2E_TEST=1` the snapshot is exposed via a `globalThis` getter the e2e harness reads with `electronApp.evaluate(...)` — no production IPC surface.

`e2e/startup-no-beachball.spec.ts` launches the packaged app under the standard launchApp fixture (which already provisions a fresh `SPOOL_HOME` — empty `resolved-bins.json` — i.e. cold cache) and asserts two thresholds:

• `p99 < 200ms` — typical experience hasn't drifted
• `max < 1000ms` — no beachball, ever

Thresholds are intentionally permissive to survive CI runners and GC jitter. The point is to fail loudly if a sub-second stall returns, not to police micro-stutter.

Local run: `maxMs: 152, p99Ms: 35, meanMs: 13, count: 185` (over a 2.4s window).

This catches the symptom regardless of cause — any future sync child_process, sync big I/O, or unbroken `JSON.parse` on a huge blob will fail it.

3. `chore(repo): ESLint setup that bans sync child_process in main/**`

ESLint had not been wired up before. Added for a single targeted purpose: stop sync `execSync` / `spawnSync` / `execFileSync` from reappearing in `packages/app/src/main/**`.

• Root devDependencies: `eslint@10` + `@typescript-eslint/parser`
• `eslint.config.mjs` at repo root using ESLint's flat config
• Root `lint` script: `eslint .` (was `turbo lint` orchestrating an empty per-package script that no package defined, i.e. a no-op)
• Rule: `no-restricted-imports` on `packages/app/src/main/**/*.ts`, banning the three sync `node:child_process` exports by name. Bare `child_process` form also covered.

Two pre-existing call sites are kept and justified inline with `eslint-disable-next-line` plus a comment explaining why the sync form is safe there (both fire on explicit user gestures long after launch, never on the cold path). Anyone adding a new sync-exec usage anywhere else under `main/` will see the error at lint time with the rule message pointing at the async path.

Defense layers

The three commits stack:

1. Fix — async + parallel + persistent cache, so the specific stall is gone
2. Test — perf_hooks histogram + cold-cache e2e asserts `max < 1000ms`, catches any main-thread stall regardless of cause
3. Lint — banned the most likely cause at PR time

Test plan

• `pnpm exec tsc --noEmit` clean across `packages/app` and `packages/core`
• `pnpm lint` clean
• `@spool-lab/core` tests pass (`199 passed (199)`)
• `e2e/startup-no-beachball.spec.ts` passes on local arm64 mac with thresholds noted above
• Packaged mac arm64 build launches with no beachball on cold cache (no `~/.spool/resolved-bins.json`)
• Packaged build launches instantly on warm cache (every subsequent open)
• Negative test: dropping a fresh `import { execSync } from 'node:child_process'` into `main/__test-canary.ts` produces the expected lint error
• CI runs through (Playwright + tests)