fix(manager): stop the design watcher from holding a process open on Linux

[lidge-jun]

What broke

Removing forceExit from the test driver (#661, merged as 2be76dd) exposed a hang it had been hiding. On ubuntu-latest, tests/unit/manager-design-routes.test.ts passes all five of its tests and then its child never exits — the driver's new watchdog reported it precisely:

[tests/run] no progress for 180000ms (JAW_TEST_FILE_STALL_MS); aborting:
  .../tests/unit/manager-design-routes.test.ts — last test:pass 180818ms ago after 25 event(s)

The same file finishes in 98ms on macOS.

Why

startDesignWatcher() called fs.watch(root, { recursive: true }) and then watcher.unref(), with a comment promising it would "never keep a process alive just for the watcher (tests, CLI)". That promise only holds on macOS and Windows.

Linux has no native recursive watch, so node routes it through a JS implementation:

// lib/fs.js
if (options.recursive && !isMacOS && !isWindows) {
  const nonNativeWatcher = require('internal/fs/recursive_watch');

and that implementation's unref() walks the wrong map:

// lib/internal/fs/recursive_watch.js
unref() {
  this.#files.forEach((file) => {
    if (file instanceof StatWatcher) {
      file.unref();
    }
  });
}

#files holds Stats; the live per-directory handles live in #watchers and are never touched. StatWatcher is imported and never constructed there, so the call is a no-op. Worse, a fresh ref'ed handle is added for every directory that appears after the start — and this suite creates one per POST /pages. Node fixed it on main only (nodejs/node#65486, see also #53350); v22 and v24 both ship the no-op, and CI runs Node 22.

The change

{ recursive: true, persistent: false }. persistent is forwarded to every inner watcher (watch(file, { persistent: this.#options.persistent })) and to the native macOS/Windows path, so it expresses "do not hold the loop open" on all three platforms, at construction time rather than after. The watcher still works in the manager server, which stays alive for its listening socket.

tests/unit/manager-design-routes.test.ts also stops the watcher it starts, and gains a case that spawns a child which starts the watcher, creates a directory under it after the start, and asserts the child exits on its own. That case fails against the old code on Linux and passes either way on macOS, so CI is where it earns its keep.

Validation

• npm run typecheck clean, npm run gate:all 23/23.
• Full root,unit scope locally: 13008 tests, 12988 pass, 0 fail.
• The Linux behaviour is only reachable in CI; this PR's own test 2/4 shard is the proof.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: ddc7eaff-0b3d-4b3a-b484-6ca3d868267d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-09T10:24:59.120284Z	3571c68	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.