What Problem This Solves

Fixes: on Linux under Node 24, a skills folder that does not exist when the Gateway starts (for example a new <workspace>/skills) never gets a working watch, so creating it and editing skills inside it is only picked up by the 30-minute safety refresh.

The same defect made src/infra/owned-directory-observation.test.ts fail every Linux Node run (reported as a flake from a Crabbox AWS gate at 762750c0). It is deterministic; daily CI runs Linux tests on Bun, so only full validation's Node arm sees it.

User Impact

User impact: on Linux with Node 24, skill folders created after the Gateway starts are watched natively again, so new and edited skills refresh within the normal debounce instead of up to 30 minutes later. No config or behavior change on macOS, Windows, Bun, or Node 26.

Why This Change Was Made

observeOwnedDirectory depends on a native watch of a missing directory throwing synchronously, so it can watch the nearest existing ancestor and re-attach when the directory appears. Node 24's Linux recursive fs.watch fallback (Linux has no native recursive inotify) inverts its throwIfNoEntry check and returns a watch that never reports for a missing root; upstream fixed it in nodejs/node#65635, which also notes that other setup errors such as EACCES were swallowed, and Node 26.12 throws as expected. The observer then keeps that inert handle forever: while the directory is missing the recovery pass re-opens another inert handle, and once it exists the handle is "healthy" by every check.

watchDirectory already owns synchronous admission for the macOS helper path. Its in-process branch now admits recursive roots the same way (fs.accessSync(root, R_OK), which also rejects an unreadable root) before calling fs.watch.

The test file had a second, test-only defect: two sharing cases counted fs.watch calls to prove one native registration, but Node builds a Linux recursive watch from nested fs.watch calls of its own (1 + one per directory, plus one per file on Node 24), so the spy saw 2+ calls for one OpenClaw registration. The recursive cases now stub the recursive native handle the way Node 24 behaves (a watch that never reports, even for a missing root). The spy counts only the observer's registrations on every runtime, and the missing-ancestor case fails on the original defect everywhere instead of only on Linux Node 24.

Accepted edge cases: a root deleted between admission and fs.watch on Node 24 Linux still gets an inert handle until a later rename or recovery pass re-admits it; Node 24's fallback also swallows ENOSPC (inotify limit). Both are rare and covered by the existing safety refresh; the access check goes away with Node 24.

Evidence

Reproduced first, on Linux. The original gate evidence (Crabbox AWS, source 762750c0) holds exactly one Node 24.19.0 run of this file, and that run failed. The gate then stopped, so there were no further Node iterations; Bun passed. On current main (a860374e) the failure is deterministic.

Linux Blacksmith Testbox through scripts/crabbox-wrapper.mjs, focused profile (ci-check-focused-testbox.yml, 2 vCPU, lease tbx_01m5bvnbrgb1t6btq8fvm2kdhm, run). Each iteration ran OPENCLAW_VITEST_RUNTIME=node OPENCLAW_VITEST_FS_MODULE_CACHE=0 node scripts/test-projects.mts src/infra/owned-directory-observation.test.ts src/infra/directory-watch-host.test.ts --maxWorkers=1 --no-cache, as a fresh process per iteration:

Standalone probe on the same Linux box (spy-equivalent wrapper around fs.watch):

v24.19.0 recursive existing dir: fs.watch entries = 4 ["<dir>","<dir>","<dir>/child","<dir>/child/file.txt"]
v24.19.0 recursive missing dir: RETURNED a watcher
v24.19.0 recursive unreadable dir: RETURNED a watcher
v26.12.0 recursive existing dir: fs.watch entries = 3 ["<dir>","<dir>","<dir>/child"]
v26.12.0 recursive missing dir: threw ENOENT
v26.12.0 recursive unreadable dir: threw EACCES

Local macOS: the adjusted missing-ancestor test fails against the main adapter under both Node and Bun (Received: .../owned-directory-ancestor-*/agents/work, the same shape as the CI failure) and passes with the fix. oxlint and oxfmt are clean on both files, and tsgo -p test/tsconfig/tsconfig.core.test.infra.json passes.

Test cost (pnpm test src/infra/owned-directory-observation.test.ts --maxWorkers=1): Vitest duration 6.48s on Bun and 9.78s on Node, about 9–13% of it tests and the rest mostly transform, measured on a heavily loaded Mac (load average about 38). On the idle 2-vCPU Linux box, this file plus directory-watch-host.test.ts took 2.1–3.0s per run, against 1.9–2.5s on main. No new timers, sleeps or subprocesses. CI seconds will follow from PR CI.

Not covered: the macOS helper-forwarding case in directory-watch-host.test.ts times out locally on this Mac while fseventsd is saturated (unchanged path; it passes 10/10 on Linux in the table above). Windows is unchanged by design: the admission check is fs.accessSync(R_OK), which is safe for directories there, and the native recursive watch already throws on Windows.

Review: Codex autoreview of the local diff (P0–P2) came back scoped-clean. Its caveat is accurate: with the stub, the sharing cases count registrations and don't exercise native recursive event delivery. They never did, because they already invoked the registered listener directly.