fix(watch): refuse deadlocking Bun runtimes

[benvinegar]

Summary

• Refuse initial --watch startup on Bun versions older than 1.3.14.
• Apply the same runtime check when a live session reload enables watch mode.
• Raise the documented source-development requirement to Bun 1.3.14.

Why

A live bun src/main.tsx diff main --watch --fast session became completely unresponsive: keyboard and mouse bytes accumulated in the PTY while the process remained alive at 0% CPU.

A forced core dump showed an AB/BA lock inversion in Bun 1.3.10:

• Main thread: PathWatcherManager.unregisterWatcher → Watcher.remove, waiting for the watcher mutex.
• File Watcher thread: processINotifyEventBatch → PathWatcherManager.onFileUpdate, waiting for the manager mutex.

This matches oven-sh/bun#31166. The upstream reproduction hung under Bun 1.3.10 after two heartbeats and completed under Bun 1.3.14 after nineteen. Hunk already pins Bun 1.3.14 for builds, but source invocations could still use an older global runtime.

The guard runs before watcher construction and before acquiring a controlling-terminal stream. Headless and non-watch commands remain available on older runtimes. Prebuilt/npm installs continue using their embedded or bundled fixed Bun runtime.

Verification

• bun test src/core/watch/runtime.test.ts src/app/startup.test.ts src/ui/AppHost.reload.test.tsx
• bun run typecheck
• bun run deps:check
• XDG_CONFIG_HOME=$(mktemp -d) bun run test
• bun run test:integration
• bun run test:tty-smoke
• bun run check:docs
• bun run changeset:status
• Black-box old-runtime launch: Bun 1.3.10 exits with the actionable version error before entering the TUI.
• Real Herdr pane: Hunk remained responsive to keyboard input and watch refreshes under Bun 1.3.14.

Tested on Linux x64. The runtime policy and version parser have platform-neutral unit coverage; macOS and Windows were not tested manually.

This PR description was generated by Pi using gpt-5.6-sol

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ignored		Aug 29, 2026 4:28pm

[greptile-apps]

Greptile Summary

The PR prevents watch mode from starting or being enabled by reload on Bun versions older than 1.3.14, before filesystem watchers can be constructed.

• Adds centralized Bun version parsing and watch-runtime validation.
• Applies the guard during initial startup and live-session reload.
• Adds regression coverage for runtime policy, startup ordering, and reload preservation.
• Raises the documented source-development requirement to Bun 1.3.14 and adds a patch changeset.

Confidence Score: 5/5

The PR appears safe to merge; the runtime guard is applied before watcher construction on both initial startup and live reload paths.

The compatibility policy is centralized, covered at its version boundaries, and invoked before side-effecting watch setup while non-watch behavior remains available.

Important Files Changed

Filename	Overview
src/core/watch/runtime.ts	Introduces a focused version parser and runtime policy that rejects malformed, affected, and boundary prerelease versions.
src/app/startup.ts	Moves watch validation ahead of terminal acquisition and bootstrap loading while preserving the existing reloadability check.
src/ui/AppHost.tsx	Applies the same compatibility guard before reload-side resource preparation or active-bootstrap replacement.
src/core/watch/runtime.test.ts	Covers the minimum version boundary, newer releases, prereleases, build metadata, malformed versions, and user-facing recovery guidance.
src/app/startup.test.ts	Verifies affected runtimes are rejected before bootstrap loading or controlling-terminal acquisition.
src/ui/AppHost.reload.test.tsx	Verifies reload cannot enable watch on an affected runtime and that the mounted review remains intact after rejection.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Configured review input] --> B{Watch enabled?}
  B -- No --> C[Continue startup or reload]
  B -- Yes --> D{Bun version at least 1.3.14?}
  D -- No --> E[Raise actionable user error]
  D -- Yes --> F[Load bootstrap]
  F --> G[Adopt review]
  G --> H[Construct watch runtime]

Loading

_{Reviews (1): Last reviewed commit: "fix(watch): refuse deadlocking Bun runti..." | Re-trigger Greptile}