watch: cancel pending restart on shutdown

Cancel any pending FilesWatcher debounce timer when watch mode clears
its watchers. This prevents a queued change event from restarting the
watched process after shutdown has started.

Keep the watched child exit handling attached for the lifetime of the
child so overlapping restart and shutdown paths do not remove each
other's exit listeners.

Signed-off-by: Kamat, Trivikram <16024985+trivikr@users.noreply.github.com>
Assisted-by: openai:gpt-5.5
PR-URL: #63383
Reviewed-By: Tim Perry <pimterry@gmail.com>

Author: trivikr

lib/internal/main/watch_mode.js

@@ -87,10 +87,13 @@ ArrayPrototypeForEach(kWatchedPaths, (p) => watcher.watchPath(p));
 
 let graceTimer;
 let child;
+let childExitPromise;
 let exited;
+let stopping;
 
 function start() {
   exited = false;
+  stopping = false;
   const stdio = kShouldFilterModules ? ['inherit', 'inherit', 'inherit', 'ipc'] : 'inherit';
   child = spawn(process.execPath, argsWithoutWatchOptions, {
     stdio,
@@ -107,29 +110,36 @@ function start() {
     ArrayPrototypeForEach(kOptionalEnvFiles,
                           (file) => watcher.filterFile(resolve(file), undefined, { allowMissing: true }));
   }
-  child.once('exit', (code) => {
+  childExitPromise = once(child, 'exit').then(({ 0: code }) => {
     exited = true;
+    if (stopping) {
+      return code;
+    }
     const waitingForChanges = 'Waiting for file changes before restarting...';
     if (code === 0) {
       process.stdout.write(`${blue}Completed running ${kCommandStr}. ${waitingForChanges}${white}\n`);
     } else {
       process.stdout.write(`${red}Failed running ${kCommandStr}. ${waitingForChanges}${white}\n`);
     }
+    return code;
   });
   return child;
 }
 
 async function killAndWait(signal = kKillSignal, force = false) {
-  child?.removeAllListeners();
-  if (!child) {
+  const processToKill = child;
+  const onExit = childExitPromise;
+  if (!processToKill) {
     return;
   }
-  if ((child.killed || exited) && !force) {
+  if ((processToKill.killed || exited) && !force) {
     return;
   }
-  const onExit = once(child, 'exit');
-  child.kill(signal);
-  const { 0: exitCode } = await onExit;
+  stopping = true;
+  if (!exited && processToKill.exitCode === null && processToKill.signalCode === null) {
+    processToKill.kill(signal);
+  }
+  const exitCode = await onExit;
   return exitCode;
 }
 

lib/internal/watch_mode/files_watcher.js

@@ -204,6 +204,9 @@ class FilesWatcher extends EventEmitter {
     this.#filteredFiles.clear();
   }
   clear() {
+    clearTimeout(this.#debounceTimer);
+    this.#debounceTimer = null;
+    this.#debounceOwners.clear();
     this.#watchers.forEach(this.#unwatch);
     this.#watchers.clear();
     this.#filteredFiles.clear();

test/parallel/test-watch-mode-files_watcher-clear.mjs

@@ -0,0 +1,69 @@
+// Flags: --expose-internals
+import * as common from '../common/index.mjs';
+import tmpdir from '../common/tmpdir.js';
+import assert from 'node:assert';
+import { writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+if (common.isIBMi)
+  common.skip('IBMi does not support `fs.watch()`');
+
+const require = createRequire(import.meta.url);
+const timers = require('node:timers');
+const originalSetTimeout = timers.setTimeout;
+const originalClearTimeout = timers.clearTimeout;
+const { promise, resolve } = Promise.withResolvers();
+const debounce = 1000;
+let debounceTimer;
+let debounceTimerCallback;
+let debounceTimerCleared = false;
+
+timers.setTimeout = function(fn, delay, ...args) {
+  // Only intercept the FilesWatcher debounce timer configured below.
+  if (delay === debounce) {
+    const timer = {
+      __proto__: null,
+      ref() { return this; },
+      unref() { return this; },
+    };
+    debounceTimer = timer;
+    debounceTimerCallback = () => {
+      if (!debounceTimerCleared) {
+        fn(...args);
+      }
+    };
+    resolve();
+    return timer;
+  }
+  return originalSetTimeout(fn, delay, ...args);
+};
+
+timers.clearTimeout = function(timer) {
+  if (timer === debounceTimer) {
+    debounceTimerCleared = true;
+  }
+  return originalClearTimeout(timer);
+};
+
+try {
+  const { FilesWatcher } = require('internal/watch_mode/files_watcher');
+
+  tmpdir.refresh();
+  const file = tmpdir.resolve('watcher-clear.js');
+  writeFileSync(file, '0');
+
+  const watcher = new FilesWatcher({ debounce, mode: 'all' });
+  watcher.on('changed', common.mustNotCall());
+  watcher.watchPath(file, false);
+
+  const interval = setInterval(() => writeFileSync(file, `${Date.now()}`), 50);
+  await promise;
+  clearInterval(interval);
+
+  watcher.clear();
+  assert.strictEqual(debounceTimerCleared, true);
+  debounceTimerCallback();
+} finally {
+  timers.setTimeout = originalSetTimeout;
+  timers.clearTimeout = originalClearTimeout;
+}

test/sequential/test-watch-mode.mjs

@@ -171,6 +171,23 @@ async function failWriteSucceed({ file, watchedFile }) {
 tmpdir.refresh();
 
 describe('watch mode', { concurrency: !process.env.TEST_PARALLEL, timeout: 60_000 }, () => {
+  it('should exit when terminated after the watched process has completed', async () => {
+    const file = createTmpFile();
+    const child = spawn(execPath, ['--watch', '--no-warnings', file], {
+      encoding: 'utf8',
+      stdio: 'pipe',
+    });
+
+    for await (const line of createInterface({ input: child.stdout })) {
+      if (line.includes('Completed running')) {
+        break;
+      }
+    }
+
+    child.kill();
+    await once(child, 'exit');
+  });
+
   it('should watch changes to a file', async () => {
     const file = createTmpFile();
     const { stderr, stdout } = await runWriteSucceed({ file, watchedFile: file, watchFlag: '--watch=true', options: {