feat(host-service): generic worker_threads pool — git status + commit-files off the event loop

Merged
KI
4mo ago
+1469-18

Links

  • Linear: SUPER-1544
  • Design + measurements: plans/20260717-host-service-git-worker-pool.md (#5746)

Summary

  • Adds a generic worker_threads pool inside host-service (packages/host-service/src/workers/) and moves git.getStatus + git.getCommitFiles compute onto it. The worker spawns the git subprocesses itself, so stdout draining AND parsing leave the event loop that also relays terminal I/O and serves all tRPC/WS for the org.
  • v1 had exactly this offload (git-task-worker); v2 lost it. Stress tests showed background getStatus queueing 3.7–14.6s under 8-workspace churn — this PR is the infrastructure that makes raising the limiter's concurrency safe (deferred, see Follow-ups).

How It Works

  • Runner: WorkerTaskRunner ported from v1 desktop (v1 keeps its copy; it retires with v1) with two changes: idle reaping (workers terminated after 30s idle — host-service is per-org and long-lived, a 3-org machine must not hold 12 warm workers) and demand-sized spawning (v1 spawned the full pool on any task).
  • Static registry: task modules export defineWorkerTask<In, Out> defs, namespaced git/*; host-worker.ts imports them into a build-time registry. Callers pass the same def to HostWorkerPool.run() for end-to-end typing. Adding a domain = one task module + one import.
  • Inline fallback: missing bundle → run handlers on the main thread (pre-PR behavior) with one warning; worker crash → task retried inline, 3 crashes/60s opens a circuit to inline-only. Pool infrastructure can never fail a caller.
  • Credential env: createGitEnvResolver split out of createGitFactory — the env is resolved in-process (needs the credential provider) and crosses to the worker as plain data; the worker builds its own SimpleGit.
  • Bundling (side-by-side with host-service.js, same pattern as pty-daemon): electron-vite input via apps/desktop/src/main/host-worker/index.ts, second Bun.build in packages/host-service/build.ts, copy in packages/cli/scripts/build-dist.ts. Resolution: SUPERSET_HOST_WORKER_SCRIPT_PATH → side-by-side → workspace dist → inline fallback.

Manual QA Checklist

  • Dev app E2E: git.getStatus on the superset repo through the real app returns a correct snapshot in worker mode (435ms; zero [host-worker-pool] fallback warnings in the host-service log; dist/main/host-worker.js emitted)
  • Standalone bundle: bun run build:host emits dist/host-worker.js; plain-node smoke (new Worker('./dist/host-worker.js')) round-trips the task protocol (ESM entry works under node)

Testing

  • src/workers/host-worker-pool.test.ts (6 tests): worker↔inline parity on a real fixture repo (modified/staged/untracked buckets), unknown-task error propagation, idle reaping, missing-bundle inline fallback, crash → inline retry → circuit open. Mutation-verified: disabling reaping fails the reap test; removing the inline retry fails the crash test.
  • src/workers/no-native-worker-imports.test.ts: worker graph stays free of native addons and process singletons (db/events/daemon); transitive regressions fail the host-worker bundle build.
  • Full host-service suite (904 tests), bun run typecheck (host-service + desktop), bun run lint clean.

Design Decisions

  • Copy the v1 runner instead of extracting a shared package: v1 is sunset; its copy dies with it (repo v1/v2 duplication policy).
  • Handlers ship in both the main bundle and the worker bundle: the inline fallback requires them in-process anyway; the git helpers were already in the main bundle.
  • Pool concurrency mirrors the limiter's min(4, cpus−1): the limiter stays the only queue for status refreshes; pooled tasks never meaningfully queue behind it.

Known Limitations

  • scheduleBaseRefFetch's dedupe state is per-thread now — N workers can, worst case, schedule up to N base-ref fetches for the same worktree within one freshness window. Bounded and rare; noting rather than complicating the payload.

Follow-ups

  • Raise gitStatusRefreshLimiter concurrency now that snapshots don't cost loop time (measure first)
  • GitWatcher rescan/filtering offload — the actual loop-stall driver under many-workspace churn (per the measured findings)
  • getDiff / listCommits / getBranchSyncStatus tenants

Open in Stage

Summary by cubic

Introduces a generic worker_threads pool for packages/host-service and moves git.getStatus and git.getCommitFiles off the event loop to cut stalls and improve responsiveness. Addresses SUPER-1544 by restoring v1’s offload pattern, adding commit-file task deduping ahead of a small cap, and hardening the inline fallback (sync-throw safe, coalesced inline crash-retry).

  • New Features

    • Added WorkerTaskRunner pool with demand-based spawning and 30s idle reaping; concurrency defaults to min(4, cpus−1)+2.
    • Inline fallback and crash handling: worker crashes retry inline; coalesced crashes count once; after 3 crashes/60s open an inline-only circuit and reject the queued backlog; inline path mirrors timeout/abort semantics and is sync-throw safe; re-drains after postMessage failures so bad payloads don’t wedge a slot.
    • Typed task registry and worker entry for git/* tasks; createGitEnvResolver resolves credential env in-process and passes plain data to the worker.
    • Switched tRPC git.getStatusSnapshot and git.getCommitFiles to the pool with 15s timeouts; commit-file tasks capped at 2 and deduped by key outside the cap so identical requests share one slot and one run.
  • Dependencies

    • Built and ship host-worker.js side-by-side with host-service.js:
      • apps/desktop adds src/main/host-worker/index.ts to electron-vite.
      • packages/host-service/build.ts emits host-worker.js (ESM); packages/cli/scripts/build-dist.ts copies it next to host-service.js.
    • Added exports entry ./host-worker in packages/host-service/package.json and resolution order SUPERSET_HOST_WORKER_SCRIPT_PATH → side-by-side → workspace dist → inline fallback.

Summary by CodeRabbit

  • New Features
    • Git status and commit-file operations now run in the background for improved app responsiveness.
    • Added support for efficient handling of repeated Git requests.
  • Bug Fixes
    • Improved resilience when background processing is unavailable or interrupted by automatically retrying operations through a fallback path.
    • Added safeguards for timeouts, cancellation, and worker failures.
  • Chores
    • Updated desktop and distribution packaging to include the required background-processing support.