fix(boxel-cli): register realm-watch signal handlers before the initial poll

[habdelra]

Background

boxel realm watch polls a realm's _mtimes on an interval and pulls remote changes into a local directory. Its programmatic entry point, watchRealms(), acquires a lock, initializes each watcher, does an initial poll, and then blocks until it's told to stop — either via a caller-supplied AbortSignal or, when none is supplied (the real CLI path), via SIGINT/SIGTERM handlers it registers itself. On stop it clears the timer, shuts the watchers down, releases the lock file, and unregisters from the process registry.

The problem

The realm-watch integration suite is intermittently red on CI:

FAIL tests/integration/realm-watch.test.ts > realm watch (integration)
     > removes SIGINT/SIGTERM handlers when the watch is stopped via signal
AssertionError: expected [] to have a length of 1 but got +0

watchRealms() registered its stop triggers after the initial poll, which sits behind lock acquisition → watcher.initialize() → an _mtimes network round-trip. The test asserted the handler was registered after a fixed sleep(150). Under CI load that async chain overruns 150ms, so the handler isn't registered yet when the assertion runs → empty array.

Two other tests in the file used the same sleep(150)-then-assert shape against the lock file; they're the same latent race and are hardened here too.

The fix

• start.ts — wire up the stop triggers (abort signal, or SIGINT/SIGTERM) before the initial poll, and skip the poll if a stop already arrived. This also closes a real product gap: with the pre-existing ordering, pressing Ctrl+C during a slow first poll left the lock file and process-registry entry dangling because no handler was installed yet.
• realm-watch.test.ts — replace the fixed sleep(150) waits with a bounded waitFor(predicate, describeFailure) poll-until-condition helper (mirrors the existing waitForRemoteVisibility idiom). Its timeout message reports the observed state — actual SIGINT/SIGTERM listener counts and lock-file contents — so a future failure is diagnosable rather than opaque.

Verifying the root cause

A temporary repro that blocks the initial poll pinned it down deterministically:

• Old ordering: added handler count at 150ms = 0 → expected +0 to be 1 (reproduces the CI failure exactly).
• New ordering: count = 1 — the handler is present even while the initial poll is still blocked.

Verification

• tsc --noEmit and eslint clean.
• Full realm-watch integration suite: 23/23 passing, run twice, no unhandled rejections.
• The previously-flaky SIGINT test: 5/5 green in a loop.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6e5f51cf42

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR hardens boxel realm watch startup/shutdown behavior by ensuring stop triggers (AbortSignal or SIGINT/SIGTERM) are registered before the initial poll, eliminating a race that intermittently flaked CI and also closing a real-world gap where Ctrl+C during a slow first poll could leave locks/registry entries behind.

Changes:

• Register abort/signal stop handlers before the initial tickAll() and skip the initial poll if a stop already arrived.
• Replace fixed sleep(150) waits in the realm-watch integration tests with a bounded waitFor(predicate, describeFailure) polling helper to avoid CI timing races.
• Improve failure diagnostics in the integration tests by reporting observed listener counts / lock-file contents on timeout.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
packages/boxel-cli/src/commands/realm/watch/start.ts	Installs stop triggers before the initial poll and gates the initial poll on !stopped to avoid dangling locks/registry entries during slow startup.
packages/boxel-cli/tests/integration/realm-watch.test.ts	Replaces fixed sleeps with a timeout-bounded poll-until helper and enhances failure messages to make future flakes diagnosable.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.