fix: destroy piped streams on child exit to prevent grandchild deadlock (tinylibs#137)

* test: verify exec completes when grandchild holds piped stdout

When a child process spawns a grandchild that inherits the piped stdout
fd (fd 1), the grandchild keeps the pipe open after the child exits.
Without the fix, both `await exec()` and the async iterator hang
indefinitely because the piped streams never end.

Each test runs in a subprocess (spawnSync with a 10s timeout) so the
orphaned grandchild doesn't block vitest. A 5s inner race detects
whether exec completes or hangs.

* fix: destroy piped streams on child exit to prevent grandchild deadlock

When a child process spawns a grandchild that inherits the piped
stdout/stderr file descriptors, the grandchild holds them open after the
child exits. Node's close event waits for all fds to be released, so
it never fires. readStream and combineStreams hang indefinitely because
the streams never end.

Listen for the exit event (fires when the process exits, regardless of
pipe state) and destroy the piped streams. This forces the PassThrough
and readline consumers to complete.

Refs: lint-staged/lint-staged#1800

* test: add grandchild fixture scripts for pipe inheritance tests

Static test fixtures that spawn a long-lived grandchild process
inheriting the piped stdout fd, simulating tsserver inheriting
eslint's piped streams through lint-staged/tinyexec.

* test: restructure grandchild tests to use static fixtures

Use committed fixture scripts instead of generated inline scripts.
Run tests in a subprocess with isolated stdio so orphaned
grandchildren don't block vitest's teardown. Clean up grandchildren
via pkill with a marker comment in the fixture scripts.

* fix: use setImmediate instead of setTimeout for stream cleanup

setImmediate is sufficient to let buffered data drain before destroying
the streams. Removes the timer tracking in _resetState and _onClose
that was needed for the setTimeout approach.

* chore: clarify comment

* test: move tests into main

* fix: account for piped streams

---------

Co-authored-by: James Garbutt <43081j@users.noreply.github.com>

Author: Mearman

src/main.ts

@@ -17,6 +17,8 @@ export {NonZeroExitError, normalizeSpawnCommand};
 
 const LINE_SEPARATOR_REGEX = /\r?\n/;
 
+const pipedStreams = new WeakSet<Readable>();
+
 export interface Output {
   stderr: string;
   stdout: string;
@@ -334,6 +336,7 @@ export class ExecProcess implements Result {
 
     this._process = handle;
     handle.once('error', this._onError);
+    handle.once('exit', this._onExit);
     handle.once('close', this._onClose);
 
     if (handle.stdin) {
@@ -342,7 +345,11 @@ export class ExecProcess implements Result {
       if (typeof stdin === 'string') {
         handle.stdin.end(stdin);
       } else {
-        stdin?.process?.stdout?.pipe(handle.stdin);
+        const src = stdin?.process?.stdout;
+        if (src) {
+          src.pipe(handle.stdin);
+          pipedStreams.add(src);
+        }
       }
     }
   }
@@ -366,6 +373,28 @@ export class ExecProcess implements Result {
     this._thrownError = err;
   };
 
+  protected _onExit = (): void => {
+    // Node emits 'exit' before stdio streams have drained. Use setImmediate
+    // to let buffered data flow through before destroying the streams.
+    // If grandchild processes hold the pipe fds open, they would never fire
+    // 'close', so we destroy here to unblock readStream and combineStreams.
+    const out =
+      this._streamOut && !pipedStreams.has(this._streamOut)
+        ? this._streamOut
+        : undefined;
+    const err =
+      this._streamErr && !pipedStreams.has(this._streamErr)
+        ? this._streamErr
+        : undefined;
+    if (!out && !err) {
+      return;
+    }
+    setImmediate(() => {
+      out?.destroy();
+      err?.destroy();
+    });
+  };
+
   protected _onClose = (): void => {
     if (this._resolveClose) {
       this._resolveClose();

src/test/main_test.ts

@@ -3,8 +3,11 @@ import {describe, test, expect} from 'vitest';
 import os from 'node:os';
 import fs from 'node:fs';
 import path from 'node:path';
+import {spawnSync} from 'node:child_process';
 
 const isWindows = os.platform() === 'win32';
+const fixturesDir = path.join(import.meta.dirname, '../../test/fixtures');
+const distDir = path.join(import.meta.dirname, '../../dist');
 
 const variants = [
   {name: 'async', x, isAsync: true},
@@ -363,6 +366,82 @@ if (!isWindows) {
         fs.rmSync(dir, {recursive: true, force: true});
       }
     });
+
+    test('resolves when grandchild holds piped stdout open', async () => {
+      const dir = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'tinyexec-grandchild-')
+      );
+      const runnerScript = path.join(dir, 'runner.mjs');
+      const distPath = JSON.stringify(path.join(distDir, 'main.mjs'));
+      const fixturePath = JSON.stringify(
+        path.join(fixturesDir, 'grandchild.mjs')
+      );
+
+      fs.writeFileSync(
+        runnerScript,
+        `import { x } from ${distPath}
+  const result = await x('node', [${fixturePath}])
+  process.stdout.write(JSON.stringify({ stdout: result.stdout, exitCode: result.exitCode }))
+  `
+      );
+
+      try {
+        const proc = spawnSync('node', [runnerScript], {
+          timeout: 10000,
+          encoding: 'utf8',
+          killSignal: 'SIGKILL',
+          stdio: ['pipe', 'pipe', 'pipe']
+        });
+
+        expect(proc.signal).not.toBe('SIGKILL');
+        expect(proc.status).toBe(0);
+        const parsed = JSON.parse(proc.stdout.trim());
+        expect(parsed.exitCode).toBe(0);
+        expect(parsed.stdout).toBe('output\n');
+      } finally {
+        spawnSync('pkill', ['-f', 'tinyexec-test-grandchild']);
+        fs.rmSync(dir, {recursive: true, force: true});
+      }
+    });
+
+    test('iterator completes when grandchild holds piped stdout open', async () => {
+      const dir = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'tinyexec-grandchild-')
+      );
+      const runnerScript = path.join(dir, 'runner.mjs');
+      const distPath = JSON.stringify(path.join(distDir, 'main.mjs'));
+      const fixturePath = JSON.stringify(
+        path.join(fixturesDir, 'grandchild_multiline.mjs')
+      );
+
+      fs.writeFileSync(
+        runnerScript,
+        `import { x } from ${distPath}
+  const lines = []
+  for await (const line of x('node', [${fixturePath}])) {
+    lines.push(line)
+  }
+  process.stdout.write(JSON.stringify(lines))
+  `
+      );
+
+      try {
+        const proc = spawnSync('node', [runnerScript], {
+          timeout: 10000,
+          encoding: 'utf8',
+          killSignal: 'SIGKILL',
+          stdio: ['pipe', 'pipe', 'pipe']
+        });
+
+        expect(proc.signal).not.toBe('SIGKILL');
+        expect(proc.status).toBe(0);
+        const parsed = JSON.parse(proc.stdout.trim());
+        expect(parsed).toEqual(['line1', 'line2']);
+      } finally {
+        spawnSync('pkill', ['-f', 'tinyexec-test-grandchild']);
+        fs.rmSync(dir, {recursive: true, force: true});
+      }
+    });
   });
 
   describe('exec (unix-like) (sync)', () => {

test/fixtures/grandchild.mjs

@@ -0,0 +1,13 @@
+import {spawn} from 'node:child_process';
+
+// Spawn a grandchild that inherits the piped stdout fd, simulating
+// tsserver inheriting eslint's piped streams. Short timeout to avoid
+// blocking test teardown.
+spawn(
+  process.argv[0],
+  ['-e', 'setTimeout(() => void 0, 3000)'],
+  {stdio: ['ignore', 1, 'ignore']}
+);
+
+console.log('output');
+process.exit(0);

test/fixtures/grandchild_multiline.mjs

@@ -0,0 +1,11 @@
+import {spawn} from 'node:child_process';
+
+spawn(
+  process.argv[0],
+  ['-e', 'setTimeout(() => void 0, 3000)'],
+  {stdio: ['ignore', 1, 'ignore']}
+);
+
+console.log('line1');
+console.log('line2');
+process.exit(0);