chore(mcp-server): restart the dev server only on real source changes - #224

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/dev-watch.cjs, line 188:

<comment>Replacing or removing a watched root can crash the dev runner because asynchronous watcher errors are unhandled. Keep each watcher and handle its `error` event so failure is logged instead of terminating the process.</comment>

<file context>
@@ -0,0 +1,204 @@
+
+for (const dir of watchDirs) {
+    try {
+        watch(dir, { recursive: true }, (_eventType, name) => onFsEvent(dir, name))
+    } catch (error) {
+        log(`cannot watch ${dir}: ${error.message}`)
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/dev-watch.cjs, line 197:

<comment>A Ctrl+C/SIGTERM issued during an in-progress restart can leave the server holding port 3737. `shutdown()` kills `child` (which is `null` in the window where the old process is being torn down and the new one isn't started yet) and then calls `process.exit(0)` immediately. The pending `killTimer` that would escalate to SIGKILL is `unref()`'d, so it won't keep the parent alive to enforce the kill. If a child swallows SIGTERM during that window it is orphaned and the port stays bound. Consider awaiting the child's exit (or clearing/overriding the pending kill with an immediate SIGKILL) before exiting.</comment>

<file context>
@@ -0,0 +1,204 @@
+const shutdown = () => {
+    if (shuttingDown) return
+    shuttingDown = true
+    if (child) child.kill('SIGTERM')
+    process.exit(0)
+}
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/dev-watch.cjs, line 135:

<comment>Editing several files while a reload is already in progress can spawn duplicate server processes. `restart()` doesn't guard against being called while `restarting` is true, and `dying` is the same ChildProcess throughout the kill window (up to KILL_TIMEOUT_MS = 3s). Events that land during that window get debounced and call `restart()` again, which registers another `dying.once('exit', ...)` listener; since `once` fires every registered listener, every extra call runs `startChild()` again once the process exits. The result is two (or more) node servers started back-to-back, with the stragglers failing to bind port 3737 and confusing the dev loop. Add a coalescing guard at the top of `restart()` so a second trigger during an active restart is dropped (the edit is already on disk and covered by the restart in progress).</comment>

<file context>
@@ -0,0 +1,204 @@
+    })
+}
+
+const restart = () => {
+    const changed = Array.from(pendingChanges)
+    pendingChanges.clear()
</file context>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/mcp-server/README.md` around lines 108 - 109, Update the
documentation sentence near the node --watch description to replace “contents
moved” with “file contents changed,” preserving the surrounding explanation and
Windows rationale.

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/dev-watch.cjs, line 151:

<comment>Stopping the watcher during an in-flight restart can leave the replacement MCP server orphaned. The restart exit listener unconditionally calls `startChild()`, while `shutdown()` can be invoked before that listener runs and registers its own exit handler that immediately exits the runner; the newly spawned child then survives the parent and can keep port 3737 bound. The restart completion path should skip spawning when `shuttingDown` is set.</comment>

<file context>
@@ -0,0 +1,239 @@
+    log(`restarting: ${display(changed[0])}${extra}`)
+
+    if (!child) {
+        startChild()
+        return
+    }
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/dev-watch.cjs, line 198:

<comment>Generated directories are still in the recursive watch scope, so activity under `node_modules`, `dist`, or `coverage` still reaches this watcher despite the stated exclusion and can add unnecessary event pressure. Use non-recursive watchers only for eligible directories, adding eligible new directories as needed, when these trees must not be watched.</comment>

<file context>
@@ -0,0 +1,239 @@
+let watchedDirs = 0
+for (const dir of watchDirs) {
+    try {
+        const watcher = watch(dir, { recursive: true }, (_eventType, name) => onFsEvent(dir, name))
+        // An unhandled 'error' (watched root deleted or replaced while running)
+        // is thrown by the EventEmitter and would take the runner down.
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At packages/mcp-server/package.json, line 37:

<comment>Changes to the runtime spec sources do not restart this dev server because the watcher only scans `src` and `packages`. For example, `src/proto.ts`, `src/mex.ts`, `src/appstate-spec.ts`, `src/abprops-spec.ts`, and `src/version-spec.ts` import runtime modules from `../spec`; editing `spec/version/index.js`, `spec/mex/index.js`, or generated protobuf output can therefore leave the running MCP process using stale protocol data until it is manually restarted. Including the `spec` tree in the watched roots would keep the advertised reload behavior complete.</comment>

<file context>
@@ -34,7 +34,7 @@
         "test": "node --import tsx --test \"src/**/__tests__/**/*.test.ts\"",
         "start": "node --import tsx src/bin.ts",
-        "dev": "cross-env MCP_TRANSPORT=http MCP_EVAL_ENABLED=1 MCP_LOG_LEVEL=trace MCP_AUTH_PATH=../../.auth/state.sqlite node --watch --import tsx src/bin.ts"
+        "dev": "cross-env MCP_TRANSPORT=http MCP_EVAL_ENABLED=1 MCP_LOG_LEVEL=trace MCP_AUTH_PATH=../../.auth/state.sqlite node ../../scripts/dev-watch.cjs --watch ../../src --watch ../../packages -- node --import tsx src/bin.ts"
     },
     "dependencies": {
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/dev-watch.cjs, line 181:

<comment>The watcher does not actually verify content changes: it treats `mtimeMs + size` as the file identity. A same-size edit whose timestamp is preserved can be ignored, while a metadata-only mtime update such as `touch` can trigger a restart even when bytes are unchanged. That means the runner can still miss real edits or restart for non-content changes, contrary to the stated content-only behavior; a content digest check (at least after the metadata fingerprint changes) would make this reliable.</comment>

<file context>
@@ -0,0 +1,239 @@
+    const previous = fingerprints.get(filePath)
+    // Same mtime and size: a last-access-time flush or a metadata-only touch,
+    // not an edit. This is the event `node --watch` restarts on.
+    if (previous === next) return
+    if (next === null) {
+        fingerprints.delete(filePath)
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At packages/mcp-server/README.md, line 109:

<comment>Consider rewording "without checking whether the contents moved" to something like "without checking whether the file contents actually changed" — "contents moved" isn't a defined file-change condition and muddles the explanation of why `node --watch` over-restarts on Windows.</comment>

<file context>
@@ -81,27 +81,38 @@ processes only when you want isolated stores / auth files.
+> `fs.watch` to `FILE_NOTIFY_CHANGE_LAST_ACCESS`, so merely **reading** a file
+> emits a change event once NTFS flushes a new last-access time (module load,
+> test run, editor indexing, grep). `node --watch` restarts on any event for a
+> file in its module graph without checking whether the contents moved, which
+> makes the server restart on the first lazy import - `better-sqlite3`, loaded
+> on the first `connect()` - and whenever another tool walks the tree. The
</file context>