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));
 
 letgraceTimer;
 letchild;
+letchildExitPromise;
 letexited;
+letstopping;
 
 functionstart(){
 exited=false;
+stopping=false;
 conststdio=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){
+returncode;
+}
 constwaitingForChanges='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`);
 }
+returncode;
 });
 returnchild;
 }
 
 asyncfunctionkillAndWait(signal=kKillSignal,force=false){
-child?.removeAllListeners();
-if(!child){
+constprocessToKill=child;
+constonExit=childExitPromise;
+if(!processToKill){
 return;
 }
-if((child.killed||exited)&&!force){
+if((processToKill.killed||exited)&&!force){
 return;
 }
-constonExit=once(child,'exit');
-child.kill(signal);
-const{0: exitCode}=awaitonExit;
+stopping=true;
+if(!exited&&processToKill.exitCode===null&&processToKill.signalCode===null){
+processToKill.kill(signal);
+}
+constexitCode=awaitonExit;
 returnexitCode;
 }
 

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*ascommonfrom'../common/index.mjs';
+importtmpdirfrom'../common/tmpdir.js';
+importassertfrom'node:assert';
+import{writeFileSync}from'node:fs';
+import{createRequire}from'node:module';
+
+if(common.isIBMi)
+common.skip('IBMi does not support `fs.watch()`');
+
+constrequire=createRequire(import.meta.url);
+consttimers=require('node:timers');
+constoriginalSetTimeout=timers.setTimeout;
+constoriginalClearTimeout=timers.clearTimeout;
+const{ promise, resolve }=Promise.withResolvers();
+constdebounce=1000;
+letdebounceTimer;
+letdebounceTimerCallback;
+letdebounceTimerCleared=false;
+
+timers.setTimeout=function(fn,delay, ...args){
+// Only intercept the FilesWatcher debounce timer configured below.
+if(delay===debounce){
+consttimer={
+__proto__: null,
+ref(){returnthis;},
+unref(){returnthis;},
+};
+debounceTimer=timer;
+debounceTimerCallback=()=>{
+if(!debounceTimerCleared){
+fn(...args);
+}
+};
+resolve();
+returntimer;
+}
+returnoriginalSetTimeout(fn,delay, ...args);
+};
+
+timers.clearTimeout=function(timer){
+if(timer===debounceTimer){
+debounceTimerCleared=true;
+}
+returnoriginalClearTimeout(timer);
+};
+
+try{
+const{ FilesWatcher }=require('internal/watch_mode/files_watcher');
+
+tmpdir.refresh();
+constfile=tmpdir.resolve('watcher-clear.js');
+writeFileSync(file,'0');
+
+constwatcher=newFilesWatcher({ debounce,mode: 'all'});
+watcher.on('changed',common.mustNotCall());
+watcher.watchPath(file,false);
+
+constinterval=setInterval(()=>writeFileSync(file,`${Date.now()}`),50);
+awaitpromise;
+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()=>{
+constfile=createTmpFile();
+constchild=spawn(execPath,['--watch','--no-warnings',file],{
+encoding: 'utf8',
+stdio: 'pipe',
+});
+
+forawait(constlineofcreateInterface({input: child.stdout})){
+if(line.includes('Completed running')){
+break;
+}
+}
+
+child.kill();
+awaitonce(child,'exit');
+});
+
 it('should watch changes to a file',async()=>{
 constfile=createTmpFile();
 const{ stderr, stdout }=awaitrunWriteSucceed({ file,watchedFile: file,watchFlag: '--watch=true',options: {