@nemus-cli/nemus 0.15.2 → 0.17.0

package/src/mcp/tools.ts

@@ -21,6 +21,8 @@ import { removeNodeModules, removeBuildArtifacts } from '../utils/cleanup-operat
 import { runPostCloneHooks } from '../utils/hooks';
 import { SuiteEntry, WorkspaceSuite, SuitesStore } from '../types';
 import { resolveWorkspaceNameConflict, sanitizeWorkspaceName, safeWorkspacePath } from '../utils/validation';
+import { buildLock, writeLock, readLockFile, parseLock, LOCK_FILENAME } from '../utils/workspace-lock';
+import { restoreWorkspace } from '../commands/restore';
 
 /**
  * Redirects stdout to stderr for the duration of a function call.
@@ -1017,3 +1019,70 @@ export async function handleSaveContext(workspace: string, content: string, appe
     };
   });
 }
+
+// ── Portable workspaces: lock / restore ─────────────────────────────────────
+
+/**
+ * Snapshot a workspace into a nemus.lock manifest (repos + branch + commit).
+ * Writes it to the workspace root by default and also returns the manifest so
+ * an agent can share/commit it.
+ */
+export async function handleLockWorkspace(workspace: string, output?: string) {
+  return withStdoutProtection(async () => {
+    if (!workspace || workspace.trim().length === 0) {
+      throw new Error('Workspace name is required');
+    }
+    const workspacePath = safeWorkspacePath(sanitizeWorkspaceName(workspace));
+    const metadata = await loadMetadata(workspacePath);
+    if (!metadata) {
+      throw new Error(`Workspace not found: ${workspace}`);
+    }
+    const lock = await buildLock(workspacePath, metadata);
+    const outPath = output ? path.resolve(output) : path.join(workspacePath, LOCK_FILENAME);
+    await writeLock(outPath, lock);
+    return {
+      workspace: metadata.workspaceName,
+      lockfilePath: outPath,
+      repoCount: lock.repositories.length,
+      lock,
+    };
+  });
+}
+
+/**
+ * Recreate a workspace from a nemus.lock. Accepts either inline `lockContent`
+ * (the manifest JSON) or a `lockfile` path (defaults to ./nemus.lock). Clones
+ * every repo and checks out the recorded branch (or exact commit with `pin`).
+ */
+export async function handleRestoreWorkspace(opts: {
+  workspace?: string;
+  lockfile?: string;
+  lockContent?: string;
+  pin?: boolean;
+}) {
+  return withStdoutProtection(async () => {
+    const lock = opts.lockContent
+      ? parseLock(opts.lockContent)
+      : await readLockFile(path.resolve(opts.lockfile || LOCK_FILENAME));
+
+    const { workspaceName, workspacePath, results } = await restoreWorkspace(lock, {
+      workspace: opts.workspace,
+      pin: opts.pin,
+    });
+
+    const cloned = results.filter(r => r.status === 'success');
+    const failed = results.filter(r => r.status === 'failed');
+    return {
+      workspace: workspaceName,
+      path: workspacePath,
+      cloned: cloned.length,
+      failed: failed.length,
+      repositories: results.map(r => ({
+        name: r.repo.name,
+        directoryName: r.directoryName,
+        status: r.status,
+        ...(r.error ? { error: r.error } : {}),
+      })),
+    };
+  });
+}

package/src/program.ts

@@ -64,6 +64,9 @@ import { registerMigrateCommand } from './commands/migrate';
 import { registerReportBugCommand } from './commands/report-bug';
 import { registerCompletionCommand } from './commands/completion';
 import { registerReflectCommand } from './commands/reflect';
+import { registerLockCommand } from './commands/lock';
+import { registerRestoreCommand } from './commands/restore';
+import { registerDevCommand } from './commands/dev';
 
 registerCreateCommand(program);
 registerListCommand(program);
@@ -92,6 +95,9 @@ registerMigrateCommand(program);
 registerReportBugCommand(program);
 registerCompletionCommand(program);
 registerReflectCommand(program);
+registerLockCommand(program);
+registerRestoreCommand(program);
+registerDevCommand(program);
 
 // Register TUI (delegates to existing Ink/React implementation)
 program

package/src/utils/dev-orchestrator.test.ts

@@ -0,0 +1,207 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { EventEmitter } from 'events';
+import { PassThrough } from 'stream';
+import type { ChildProcess } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { setColorEnabled } from './colors';
+import {
+  detectPackageManager,
+  pickDevScript,
+  scriptRunCommand,
+  resolveDevCommand,
+  assignColors,
+  formatPrefix,
+  createLineSplitter,
+  runDev,
+  PREFIX_COLORS,
+  type DevService,
+} from './dev-orchestrator';
+
+beforeEach(() => setColorEnabled(false)); // deterministic, uncolored strings
+
+describe('detectPackageManager', () => {
+  let tmp: string;
+  beforeEach(() => { tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dev-pm-')); });
+  afterEach(() => fs.rmSync(tmp, { recursive: true, force: true }));
+
+  it('detects pnpm/yarn from lockfiles, defaults to npm', () => {
+    expect(detectPackageManager(tmp)).toBe('npm');
+    fs.writeFileSync(path.join(tmp, 'yarn.lock'), '');
+    expect(detectPackageManager(tmp)).toBe('yarn');
+    fs.writeFileSync(path.join(tmp, 'pnpm-lock.yaml'), '');
+    expect(detectPackageManager(tmp)).toBe('pnpm'); // pnpm wins over yarn
+  });
+});
+
+describe('pickDevScript', () => {
+  it('honors an explicit preferred script when present', () => {
+    expect(pickDevScript({ dev: 'x', start: 'y' }, 'start')).toBe('start');
+    expect(pickDevScript({ dev: 'x' }, 'start')).toBeNull(); // preferred missing
+  });
+  it('falls back to dev → develop → start → serve order', () => {
+    expect(pickDevScript({ start: 'a', serve: 'b' })).toBe('start');
+    expect(pickDevScript({ serve: 'b' })).toBe('serve');
+    expect(pickDevScript({ develop: 'd', start: 's' })).toBe('develop');
+  });
+  it('returns null for no scripts / no match', () => {
+    expect(pickDevScript(undefined)).toBeNull();
+    expect(pickDevScript({ build: 'x', test: 'y' })).toBeNull();
+  });
+});
+
+describe('scriptRunCommand', () => {
+  it('uses run for npm, bare for yarn/pnpm', () => {
+    expect(scriptRunCommand('npm', 'dev')).toBe('npm run dev');
+    expect(scriptRunCommand('yarn', 'dev')).toBe('yarn dev');
+    expect(scriptRunCommand('pnpm', 'start')).toBe('pnpm start');
+  });
+});
+
+describe('resolveDevCommand', () => {
+  let tmp: string;
+  beforeEach(() => { tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dev-res-')); });
+  afterEach(() => fs.rmSync(tmp, { recursive: true, force: true }));
+
+  it('prefers an explicit command override', () => {
+    expect(resolveDevCommand(tmp, { commandOverride: 'make run' })).toEqual({ command: 'make run', source: 'command' });
+  });
+  it('resolves a package.json script with the detected pm', () => {
+    fs.writeFileSync(path.join(tmp, 'package.json'), JSON.stringify({ scripts: { dev: 'vite' } }));
+    fs.writeFileSync(path.join(tmp, 'pnpm-lock.yaml'), '');
+    expect(resolveDevCommand(tmp)).toEqual({ command: 'pnpm dev', source: 'pnpm · dev' });
+  });
+  it('returns null when there is no package.json or no runnable script', () => {
+    expect(resolveDevCommand(tmp)).toBeNull();
+    fs.writeFileSync(path.join(tmp, 'package.json'), JSON.stringify({ scripts: { build: 'x' } }));
+    expect(resolveDevCommand(tmp)).toBeNull();
+  });
+  it('returns null for malformed package.json', () => {
+    fs.writeFileSync(path.join(tmp, 'package.json'), '{ not json');
+    expect(resolveDevCommand(tmp)).toBeNull();
+  });
+});
+
+describe('assignColors', () => {
+  it('assigns and cycles the palette', () => {
+    const many = Array.from({ length: PREFIX_COLORS.length + 2 }, (_, i) => `r${i}`);
+    const map = assignColors(many);
+    expect(map.get('r0')).toBe(PREFIX_COLORS[0]);
+    expect(map.get(`r${PREFIX_COLORS.length}`)).toBe(PREFIX_COLORS[0]); // wrapped
+  });
+});
+
+describe('formatPrefix', () => {
+  it('pads the label to the column width (colors disabled)', () => {
+    expect(formatPrefix('web', 6, 'cyan')).toBe('web    |');
+  });
+});
+
+describe('createLineSplitter', () => {
+  it('emits complete lines and holds the partial until flushed', () => {
+    const s = createLineSplitter();
+    expect(s.push('hello\nwor')).toEqual(['hello']);
+    expect(s.push('ld\n')).toEqual(['world']);
+    expect(s.push('tail')).toEqual([]);
+    expect(s.flush()).toBe('tail');
+    expect(s.flush()).toBeNull();
+  });
+});
+
+// ── runDev integration (fake spawn / signals / kills) ───────────────────────
+
+class FakeChild extends EventEmitter {
+  stdout = new PassThrough();
+  stderr = new PassThrough();
+  pid = Math.floor(Math.random() * 1e6);
+  kill() { return true; }
+  emitExit(code: number | null, signal: NodeJS.Signals | null = null) {
+    this.emit('exit', code, signal);
+  }
+}
+
+function harness(labels: string[]) {
+  const children = new Map<string, FakeChild>();
+  const out = new PassThrough();
+  const err = new PassThrough();
+  let outBuf = ''; out.on('data', c => (outBuf += c));
+  let errBuf = ''; err.on('data', c => (errBuf += c));
+  let signalHandler: ((s: NodeJS.Signals) => void) | null = null;
+  const kills: Array<{ label: string; signal: string }> = [];
+
+  const services: DevService[] = labels.map(label => ({
+    label, cwd: `/tmp/${label}`, command: { command: `run ${label}`, source: 'command' },
+  }));
+  const labelByChild = new Map<FakeChild, string>();
+
+  const opts = {
+    stdout: out, stderr: err,
+    spawnFn: ((_cmd: string) => {
+      // services spawn in order, so map by creation order
+      const label = labels[children.size];
+      const c = new FakeChild();
+      children.set(label, c);
+      labelByChild.set(c, label);
+      return c as unknown as ChildProcess;
+    }) as any,
+    onSignal: (h: (s: NodeJS.Signals) => void) => { signalHandler = h; return () => { signalHandler = null; }; },
+    killFn: (child: ChildProcess, signal: NodeJS.Signals) => {
+      kills.push({ label: labelByChild.get(child as unknown as FakeChild)!, signal });
+    },
+  };
+  return { services, opts, children, kills, getOut: () => outBuf, getErr: () => errBuf, signal: (s: NodeJS.Signals) => signalHandler?.(s) };
+}
+
+describe('runDev', () => {
+  it('prefixes output and resolves 0 when all services exit cleanly', async () => {
+    const h = harness(['web', 'api']);
+    const p = runDev(h.services, h.opts);
+    h.children.get('web')!.stdout.write('ready on :3000\n');
+    h.children.get('api')!.stdout.write('listening\n');
+    h.children.get('web')!.emitExit(0);
+    h.children.get('api')!.emitExit(0);
+    expect(await p).toBe(0);
+    expect(h.getOut()).toContain('web | ready on :3000');
+    expect(h.getOut()).toContain('api | listening');
+  });
+
+  it('returns the first non-zero exit code', async () => {
+    const h = harness(['web']);
+    const p = runDev(h.services, h.opts);
+    h.children.get('web')!.emitExit(2);
+    expect(await p).toBe(2);
+  });
+
+  it('flushes a newline-less trailing line on exit', async () => {
+    const h = harness(['web']);
+    const p = runDev(h.services, h.opts);
+    h.children.get('web')!.stdout.write('no newline here');
+    h.children.get('web')!.emitExit(0);
+    await p;
+    expect(h.getOut()).toContain('web | no newline here');
+  });
+
+  it('on signal: SIGTERMs every group, then SIGKILL-sweeps before finishing', async () => {
+    const h = harness(['web', 'api']);
+    const p = runDev(h.services, { ...h.opts, killTimeoutMs: 10 });
+    h.signal('SIGINT');
+    // both get SIGTERM immediately
+    expect(h.kills.filter(k => k.signal === 'SIGTERM').map(k => k.label).sort()).toEqual(['api', 'web']);
+    // children exit in response
+    h.children.get('web')!.emitExit(0, 'SIGTERM');
+    h.children.get('api')!.emitExit(0, 'SIGTERM');
+    await p;
+    // a SIGKILL sweep runs before finishing (reaps orphaned group members)
+    expect(h.kills.some(k => k.signal === 'SIGKILL')).toBe(true);
+  });
+
+  it('exitOnFailure tears everything down when a service fails', async () => {
+    const h = harness(['web', 'api']);
+    const p = runDev(h.services, { ...h.opts, exitOnFailure: true, killTimeoutMs: 10 });
+    h.children.get('web')!.emitExit(1); // failure triggers shutdown
+    expect(h.kills.some(k => k.label === 'api' && k.signal === 'SIGTERM')).toBe(true);
+    h.children.get('api')!.emitExit(0, 'SIGTERM');
+    expect(await p).toBe(1);
+  });
+});

package/src/utils/dev-orchestrator.ts

@@ -0,0 +1,325 @@
+import { spawn, type ChildProcess } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { colorize, type ColorName } from './colors';
+
+export type PackageManager = 'npm' | 'yarn' | 'pnpm';
+
+/** Detect a repo's package manager from its lockfile (defaults to npm). */
+export function detectPackageManager(repoPath: string): PackageManager {
+  if (fs.existsSync(path.join(repoPath, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(repoPath, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+/** Default script preference order when the user doesn't pass --script. */
+export const DEFAULT_SCRIPT_ORDER = ['dev', 'develop', 'start', 'serve'] as const;
+
+/**
+ * Pick the dev script to run from a package.json `scripts` map. If `preferred`
+ * is given and present, it wins; otherwise the first of DEFAULT_SCRIPT_ORDER
+ * that exists. Returns null when nothing matches.
+ */
+export function pickDevScript(
+  scripts: Record<string, string> | undefined,
+  preferred?: string
+): string | null {
+  if (!scripts) return null;
+  if (preferred) return scripts[preferred] ? preferred : null;
+  for (const name of DEFAULT_SCRIPT_ORDER) {
+    if (scripts[name]) return name;
+  }
+  return null;
+}
+
+/** The command string a package manager uses to run a script. */
+export function scriptRunCommand(pm: PackageManager, script: string): string {
+  // npm needs `run`; yarn/pnpm accept the bare script name.
+  return pm === 'npm' ? `npm run ${script}` : `${pm} ${script}`;
+}
+
+export interface DevCommand {
+  /** Full shell command string to run in the repo. */
+  command: string;
+  /** How it was chosen, for the startup banner. */
+  source: string;
+}
+
+/**
+ * Resolve the command to run for a repo. An explicit `commandOverride` always
+ * wins; otherwise we read package.json and pick a script. Returns null when the
+ * repo has nothing runnable (e.g. a library with no dev script).
+ */
+export function resolveDevCommand(
+  repoPath: string,
+  opts: { commandOverride?: string; script?: string } = {}
+): DevCommand | null {
+  if (opts.commandOverride) {
+    return { command: opts.commandOverride, source: 'command' };
+  }
+
+  const pkgPath = path.join(repoPath, 'package.json');
+  if (!fs.existsSync(pkgPath)) return null;
+
+  let scripts: Record<string, string> | undefined;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    scripts = pkg?.scripts;
+  } catch {
+    return null;
+  }
+
+  const script = pickDevScript(scripts, opts.script);
+  if (!script) return null;
+
+  const pm = detectPackageManager(repoPath);
+  return { command: scriptRunCommand(pm, script), source: `${pm} · ${script}` };
+}
+
+/** Palette used to color per-repo prefixes (cycled if there are more repos). */
+export const PREFIX_COLORS: ColorName[] = [
+  'cyan', 'green', 'yellow', 'magenta', 'blue', 'red', 'white',
+];
+
+export function assignColors(names: string[]): Map<string, ColorName> {
+  const map = new Map<string, ColorName>();
+  names.forEach((name, i) => map.set(name, PREFIX_COLORS[i % PREFIX_COLORS.length]));
+  return map;
+}
+
+/** Build the aligned, colored `"label | "` prefix for a service's output. */
+export function formatPrefix(label: string, width: number, color: ColorName): string {
+  return colorize(`${label.padEnd(width)} ${colorize('|', 'gray')}`, color);
+}
+
+/**
+ * Stateful line splitter: feed it chunks, it returns complete lines and holds
+ * the trailing partial until the next chunk. `flush()` yields any remainder.
+ */
+export function createLineSplitter() {
+  let buffer = '';
+  return {
+    push(chunk: string): string[] {
+      buffer += chunk;
+      const lines = buffer.split('\n');
+      buffer = lines.pop() ?? '';
+      return lines;
+    },
+    flush(): string | null {
+      if (buffer.length === 0) return null;
+      const rest = buffer;
+      buffer = '';
+      return rest;
+    },
+  };
+}
+
+export interface DevService {
+  label: string;
+  cwd: string;
+  command: DevCommand;
+}
+
+export interface RunDevOptions {
+  exitOnFailure?: boolean;
+  killTimeoutMs?: number;
+  /** Injectable sinks + spawn for testing; default to real stdout/stderr/spawn. */
+  stdout?: NodeJS.WritableStream;
+  stderr?: NodeJS.WritableStream;
+  spawnFn?: typeof spawn;
+  /** Register a signal handler; returns a disposer. Injected for tests. */
+  onSignal?: (handler: (sig: NodeJS.Signals) => void) => () => void;
+  /** How to signal a child's process group. Injected for tests. */
+  killFn?: (child: ChildProcess, signal: NodeJS.Signals) => void;
+}
+
+interface RunningService {
+  service: DevService;
+  child: ChildProcess;
+  exited: boolean;
+  exitCode: number | null;
+}
+
+/**
+ * Start every service, multiplex their output with colored prefixes, and drive a
+ * clean shutdown on Ctrl-C. Resolves with the exit code to use (first non-zero
+ * child code, or 0) once all services have exited.
+ */
+export function runDev(services: DevService[], opts: RunDevOptions = {}): Promise<number> {
+  const out = opts.stdout ?? process.stdout;
+  const err = opts.stderr ?? process.stderr;
+  const spawnFn = opts.spawnFn ?? spawn;
+  const killTimeoutMs = opts.killTimeoutMs ?? 5000;
+  const kill = opts.killFn ?? killGroup;
+  const width = Math.max(...services.map(s => s.label.length), 1);
+  const colors = assignColors(services.map(s => s.label));
+
+  return new Promise<number>((resolve) => {
+    const running: RunningService[] = [];
+    let shuttingDown = false;
+    let finished = false;
+    let firstFailureCode = 0;
+    let killTimer: ReturnType<typeof setTimeout> | null = null;
+    let disposeSignals: () => void = () => {};
+
+    const writePrefixed = (
+      sink: NodeJS.WritableStream,
+      label: string,
+      text: string
+    ) => {
+      const prefix = formatPrefix(label, width, colors.get(label) ?? 'white');
+      sink.write(`${prefix} ${text}\n`);
+    };
+
+    // SIGKILL every started service's process GROUP. Unconditional by design: a
+    // detached leader (the shell) can exit on SIGTERM while its group still has
+    // living members (e.g. a grandchild that ignores SIGTERM) — gating on the
+    // leader having exited is exactly what leaks orphans. kill(-pid) on an empty
+    // group is a harmless ESRCH.
+    //
+    // Deliberate scope: the sweep only runs as part of shutdown (Ctrl-C, or
+    // --exit-on-failure). A single service that exits on its own while others
+    // keep running is NOT swept — its stray detached grandchildren (if any) are
+    // reaped at the eventual overall shutdown, not immediately. Sweeping a live
+    // run per-exit would risk killing an unrelated process that reused the pgid.
+    const sigkillSweep = () => {
+      for (const r of running) kill(r.child, 'SIGKILL');
+    };
+
+    const finalize = () => {
+      if (finished) return;
+      finished = true;
+      if (killTimer) clearTimeout(killTimer);
+      disposeSignals();
+      resolve(firstFailureCode);
+    };
+
+    const maybeFinish = () => {
+      if (!running.every(r => r.exited)) return;
+      // All direct children are gone. If we were shutting down, force-reap any
+      // orphaned group members (detached grandchildren) before finishing —
+      // otherwise we'd exit and leave them running.
+      if (shuttingDown) sigkillSweep();
+      finalize();
+    };
+
+    const shutdown = (reason: string) => {
+      if (shuttingDown) {
+        // Second Ctrl-C: escalate immediately.
+        sigkillSweep();
+        return;
+      }
+      shuttingDown = true;
+      err.write(`\n${colorize(`▸ ${reason} — stopping ${running.filter(r => !r.exited).length} service(s)…`, 'yellow')}\n`);
+      for (const r of running) kill(r.child, 'SIGTERM');
+      // Backstop: SIGKILL anything still alive after the grace period, then finish.
+      killTimer = setTimeout(() => {
+        sigkillSweep();
+        finalize();
+      }, killTimeoutMs);
+      if (typeof killTimer.unref === 'function') killTimer.unref();
+    };
+
+    disposeSignals = (opts.onSignal ?? defaultOnSignal)((sig) => shutdown(`received ${sig}`));
+
+    for (const service of services) {
+      const child = spawnFn(service.command.command, {
+        cwd: service.cwd,
+        shell: true,
+        detached: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: process.env,
+      });
+      const rec: RunningService = { service, child, exited: false, exitCode: null };
+      running.push(rec);
+
+      const outSplitter = createLineSplitter();
+      const errSplitter = createLineSplitter();
+      child.stdout?.setEncoding('utf-8');
+      child.stderr?.setEncoding('utf-8');
+      child.stdout?.on('data', (chunk: string) => {
+        for (const line of outSplitter.push(chunk)) writePrefixed(out, service.label, line);
+      });
+      child.stderr?.on('data', (chunk: string) => {
+        for (const line of errSplitter.push(chunk)) writePrefixed(err, service.label, line);
+      });
+
+      child.on('error', (e) => {
+        if (rec.exited) return; // 'exit' already handled this service
+        writePrefixed(err, service.label, colorize(`failed to start: ${e.message}`, 'red'));
+        rec.exited = true;
+        rec.exitCode = 1;
+        if (firstFailureCode === 0) firstFailureCode = 1;
+        maybeFinish();
+      });
+
+      child.on('exit', (code, signal) => {
+        if (rec.exited) return; // 'error' already handled this service
+        for (const line of [outSplitter.flush(), errSplitter.flush()]) {
+          if (line) writePrefixed(out, service.label, line);
+        }
+        rec.exited = true;
+        rec.exitCode = code ?? (signal ? 0 : 1);
+        const desc = signal ? `signal ${signal}` : `code ${code}`;
+        const color = code && code !== 0 ? 'red' : 'gray';
+        err.write(`${colorize(`▸ ${service.label} exited (${desc})`, color)}\n`);
+        if (code && code !== 0 && firstFailureCode === 0) firstFailureCode = code;
+        if (!shuttingDown && opts.exitOnFailure && code && code !== 0) {
+          shutdown(`${service.label} failed`);
+        }
+        maybeFinish();
+      });
+    }
+
+    if (running.length === 0) finalize();
+  });
+}
+
+/**
+ * Kill a detached child's whole process tree.
+ *
+ * POSIX: the child is its own process-group leader (spawned detached), so
+ * `kill(-pid)` signals the entire group — the reliable way to take down
+ * shell→pm→server→… trees. Windows has no process groups or POSIX signals, so
+ * `kill(-pid)` throws; we fall back to `taskkill /T /F` to force-kill the tree
+ * (graceful SIGTERM isn't meaningful for a Windows console child tree). If even
+ * that isn't available we degrade to a single `child.kill()` (leaf only).
+ */
+function killGroup(child: ChildProcess, signal: NodeJS.Signals): void {
+  if (child.pid == null) return;
+  if (process.platform === 'win32') {
+    // spawn() reports failures (e.g. taskkill missing → ENOENT) via an async
+    // 'error' event, not a synchronous throw, so a try/catch can't catch it — and
+    // an unhandled 'error' event would crash the process. Attach a handler that
+    // degrades to a leaf-only kill.
+    const tk = spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+    tk.on('error', () => {
+      try {
+        child.kill();
+      } catch {
+        // already gone
+      }
+    });
+    return;
+  }
+  try {
+    process.kill(-child.pid, signal);
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {
+      // already gone
+    }
+  }
+}
+
+function defaultOnSignal(handler: (sig: NodeJS.Signals) => void): () => void {
+  const onSigint = () => handler('SIGINT');
+  const onSigterm = () => handler('SIGTERM');
+  process.on('SIGINT', onSigint);
+  process.on('SIGTERM', onSigterm);
+  return () => {
+    process.off('SIGINT', onSigint);
+    process.off('SIGTERM', onSigterm);
+  };
+}