@nemus-cli/nemus 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-09-09
+
+### Added
+
+- **`nemus dev` — multi-repo dev orchestrator.** Start every repo's dev server in
+  a workspace at once and stream their output into one terminal with a
+  color-coded, aligned per-repo prefix; a single Ctrl-C tears them all down
+  cleanly. Each service runs in its own process group and shutdown SIGTERMs the
+  group then SIGKILLs stragglers after `--kill-timeout` (default 5s), so child
+  process trees (a dev server's own subprocesses) are never orphaned. For each
+  repo it runs `--command "<cmd>"` if given, else the first `package.json` script
+  that exists (`--script` → `dev` → `develop` → `start` → `serve`) using the
+  repo's own package manager (pnpm/yarn/npm from its lockfile); repos with no
+  runnable script are skipped with a notice. Flags: `--only <repos>`,
+  `--script`, `--command`, `--exit-on-failure`, `--kill-timeout`.
+
 ## [0.16.0] - 2026-09-09
 
 ### Added

package/README.md

@@ -240,9 +240,42 @@ nemus status my-workspace     # (st) git status for every repo
 nemus sync my-workspace       # (s) git pull every repo (auto-retries on flaky network)
 nemus diff my-workspace       # (d) combined diff summary  (--full for raw diffs)
 nemus run my-workspace "npm install"   # (r) run a command in every repo
+nemus dev my-workspace        # start every repo's dev server together (one Ctrl-C stops all)
 nemus doctor my-workspace     # (doc) health checks + score
 ```
 
+### `nemus dev` — run all your services together
+
+A workspace is usually a set of services you run *together*. `nemus dev` starts
+each repo's dev server at once and streams their output into one terminal with a
+color-coded, aligned per-repo prefix; a single Ctrl-C tears them all down cleanly
+(process-group kill, so child trees die too).
+
+```bash
+nemus dev                     # start every runnable repo in the current workspace
+nemus dev payments --only web,api      # just a subset
+nemus dev payments --script start       # prefer a specific npm script
+nemus dev payments --command "make run"  # run an exact command in every repo
+nemus dev payments --exit-on-failure     # stop everything if any service crashes
+```
+
+```
+web      | VITE ready in 412 ms
+api      | listening on :4000
+worker   | [queue] connected
+```
+
+For each repo it runs `--command` if given, else the first `package.json` script
+that exists (`--script` → `dev` → `develop` → `start` → `serve`), using the
+repo's own package manager (pnpm/yarn/npm from its lockfile). Repos with no
+runnable script are skipped with a notice, so a library in the workspace won't
+block the services.
+
+> On **macOS/Linux** each service runs in its own process group, so shutdown
+> reliably takes down the whole child tree. On **Windows** there are no POSIX
+> process groups; teardown falls back to `taskkill /T /F` (force-kill the tree,
+> no graceful SIGTERM phase).
+
 ```
 Repo             Branch       Status        Ahead/Behind   Modified
 ─────────────────────────────────────────────────────────────────────

package/dist/commands/dev.js

@@ -0,0 +1,118 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDevCommand = registerDevCommand;
+const path = __importStar(require("path"));
+const config_1 = require("../utils/config");
+const workspace_meta_1 = require("../utils/workspace-meta");
+const command_helpers_1 = require("../utils/command-helpers");
+const dev_orchestrator_1 = require("../utils/dev-orchestrator");
+const logger_1 = require("../utils/logger");
+const colors_1 = require("../utils/colors");
+function registerDevCommand(parent) {
+    parent
+        .command('dev [workspace]')
+        .description('Start every repo\'s dev server together, with unified color-coded logs (Ctrl-C stops all)')
+        .option('--only <repos>', 'Comma-separated subset of repos to start')
+        .option('--script <name>', 'npm script to prefer (default: dev → develop → start → serve)')
+        .option('--command <cmd>', 'Run this exact command in every selected repo instead of a script')
+        .option('--exit-on-failure', 'Tear everything down if any service exits non-zero')
+        .option('--kill-timeout <seconds>', 'Grace period before SIGKILL on shutdown', '5')
+        .action(async (workspace, opts, cmd) => {
+        const globalOpts = (0, command_helpers_1.getGlobalOpts)(cmd);
+        await handleDev({ workspace, ...opts, ...globalOpts });
+    });
+}
+async function handleDev(opts) {
+    try {
+        const workspaceName = await (0, command_helpers_1.resolveWorkspace)(opts.workspace);
+        const workspacePath = path.join(config_1.WORKSPACES_DIR, workspaceName);
+        const metadata = await (0, workspace_meta_1.loadMetadata)(workspacePath);
+        if (!metadata) {
+            (0, logger_1.logError)(`Workspace not found: ${workspaceName}`);
+            process.exit(1);
+        }
+        let repos = metadata.repositories.filter(r => r.status === 'success');
+        if (opts.only) {
+            const wanted = new Set((0, command_helpers_1.parseList)(opts.only));
+            repos = repos.filter(r => wanted.has(r.directoryName) || wanted.has(r.name));
+            if (repos.length === 0) {
+                (0, logger_1.logError)(`No repos in "${workspaceName}" matched --only ${opts.only}`);
+                process.exit(1);
+            }
+        }
+        const services = [];
+        const skipped = [];
+        for (const repo of repos) {
+            const cwd = path.join(workspacePath, repo.directoryName);
+            const command = (0, dev_orchestrator_1.resolveDevCommand)(cwd, { commandOverride: opts.command, script: opts.script });
+            if (!command) {
+                skipped.push(repo.directoryName);
+                continue;
+            }
+            services.push({ label: repo.directoryName, cwd, command });
+        }
+        if (services.length === 0) {
+            (0, logger_1.logError)(`Nothing to run in "${workspaceName}".`);
+            (0, logger_1.logInfo)(opts.script
+                ? `No repo has a "${opts.script}" script.`
+                : 'No repo has a dev/develop/start/serve script. Pass --command "<cmd>" to run something explicitly.');
+            process.exit(1);
+        }
+        if (skipped.length > 0) {
+            (0, logger_1.logWarning)(`Skipped (no runnable script): ${skipped.join(', ')}`);
+        }
+        console.log('\n' + (0, colors_1.colorize)('Starting dev servers', 'bright') + (0, colors_1.colorize)(` · ${workspaceName}`, 'cyan'));
+        for (const s of services) {
+            console.log(`  ${(0, colors_1.colorize)(s.label, 'cyan')}  ${(0, colors_1.colorize)(s.command.command, 'gray')} ${(0, colors_1.colorize)(`(${s.command.source})`, 'gray')}`);
+        }
+        console.log((0, colors_1.colorize)('  Ctrl-C to stop all.\n', 'gray'));
+        // NaN check (not `|| 5`) so an explicit --kill-timeout 0 (immediate SIGKILL)
+        // is honored rather than coerced back to the default.
+        const parsedTimeout = Number(opts.killTimeout);
+        const killTimeoutMs = Math.max(0, Number.isFinite(parsedTimeout) ? parsedTimeout : 5) * 1000;
+        const code = await (0, dev_orchestrator_1.runDev)(services, {
+            exitOnFailure: opts.exitOnFailure,
+            killTimeoutMs,
+        });
+        process.exit(code);
+    }
+    catch (error) {
+        (0, logger_1.logError)('Failed to start dev servers');
+        if (error instanceof Error)
+            (0, logger_1.logError)(error.message);
+        process.exit(1);
+    }
+}

package/dist/program.js

@@ -97,6 +97,7 @@ const completion_1 = require("./commands/completion");
 const reflect_1 = require("./commands/reflect");
 const lock_1 = require("./commands/lock");
 const restore_1 = require("./commands/restore");
+const dev_1 = require("./commands/dev");
 (0, create_1.registerCreateCommand)(exports.program);
 (0, list_1.registerListCommand)(exports.program);
 (0, update_1.registerUpdateCommand)(exports.program);
@@ -126,6 +127,7 @@ const restore_1 = require("./commands/restore");
 (0, reflect_1.registerReflectCommand)(exports.program);
 (0, lock_1.registerLockCommand)(exports.program);
 (0, restore_1.registerRestoreCommand)(exports.program);
+(0, dev_1.registerDevCommand)(exports.program);
 // Register TUI (delegates to existing Ink/React implementation)
 exports.program
     .command('tui')

package/dist/utils/dev-orchestrator.js

@@ -0,0 +1,324 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREFIX_COLORS = exports.DEFAULT_SCRIPT_ORDER = void 0;
+exports.detectPackageManager = detectPackageManager;
+exports.pickDevScript = pickDevScript;
+exports.scriptRunCommand = scriptRunCommand;
+exports.resolveDevCommand = resolveDevCommand;
+exports.assignColors = assignColors;
+exports.formatPrefix = formatPrefix;
+exports.createLineSplitter = createLineSplitter;
+exports.runDev = runDev;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const colors_1 = require("./colors");
+/** Detect a repo's package manager from its lockfile (defaults to npm). */
+function detectPackageManager(repoPath) {
+    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. */
+exports.DEFAULT_SCRIPT_ORDER = ['dev', 'develop', 'start', 'serve'];
+/**
+ * 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.
+ */
+function pickDevScript(scripts, preferred) {
+    if (!scripts)
+        return null;
+    if (preferred)
+        return scripts[preferred] ? preferred : null;
+    for (const name of exports.DEFAULT_SCRIPT_ORDER) {
+        if (scripts[name])
+            return name;
+    }
+    return null;
+}
+/** The command string a package manager uses to run a script. */
+function scriptRunCommand(pm, script) {
+    // npm needs `run`; yarn/pnpm accept the bare script name.
+    return pm === 'npm' ? `npm run ${script}` : `${pm} ${script}`;
+}
+/**
+ * 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).
+ */
+function resolveDevCommand(repoPath, opts = {}) {
+    if (opts.commandOverride) {
+        return { command: opts.commandOverride, source: 'command' };
+    }
+    const pkgPath = path.join(repoPath, 'package.json');
+    if (!fs.existsSync(pkgPath))
+        return null;
+    let scripts;
+    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). */
+exports.PREFIX_COLORS = [
+    'cyan', 'green', 'yellow', 'magenta', 'blue', 'red', 'white',
+];
+function assignColors(names) {
+    const map = new Map();
+    names.forEach((name, i) => map.set(name, exports.PREFIX_COLORS[i % exports.PREFIX_COLORS.length]));
+    return map;
+}
+/** Build the aligned, colored `"label | "` prefix for a service's output. */
+function formatPrefix(label, width, color) {
+    return (0, colors_1.colorize)(`${label.padEnd(width)} ${(0, colors_1.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.
+ */
+function createLineSplitter() {
+    let buffer = '';
+    return {
+        push(chunk) {
+            buffer += chunk;
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            return lines;
+        },
+        flush() {
+            if (buffer.length === 0)
+                return null;
+            const rest = buffer;
+            buffer = '';
+            return rest;
+        },
+    };
+}
+/**
+ * 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.
+ */
+function runDev(services, opts = {}) {
+    const out = opts.stdout ?? process.stdout;
+    const err = opts.stderr ?? process.stderr;
+    const spawnFn = opts.spawnFn ?? child_process_1.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((resolve) => {
+        const running = [];
+        let shuttingDown = false;
+        let finished = false;
+        let firstFailureCode = 0;
+        let killTimer = null;
+        let disposeSignals = () => { };
+        const writePrefixed = (sink, label, text) => {
+            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) => {
+            if (shuttingDown) {
+                // Second Ctrl-C: escalate immediately.
+                sigkillSweep();
+                return;
+            }
+            shuttingDown = true;
+            err.write(`\n${(0, colors_1.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 = { 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) => {
+                for (const line of outSplitter.push(chunk))
+                    writePrefixed(out, service.label, line);
+            });
+            child.stderr?.on('data', (chunk) => {
+                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, (0, colors_1.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(`${(0, colors_1.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, signal) {
+    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 = (0, child_process_1.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) {
+    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);
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "workspaces": [
     "packages/*"
   ],

package/skills/nemus/SKILL.md

@@ -46,6 +46,7 @@ Global flags: `-f/--force-refresh` (skip repo cache), `-y/--yes` (skip prompts),
 | Pull latest (git sync) | [workspace-sync](references/workspace-sync.md) | `nemus sync [name]` | `s` |
 | Show diff summary | [workspace-diff](references/workspace-diff.md) | `nemus diff [name]` | `di` |
 | Run shell command across repos | [run-command](references/run-command.md) | `nemus run [name] <cmd>` | `r` |
+| Start all repos' dev servers together | [dev](references/dev.md) | `nemus dev [name]` | — |
 | Health check | [workspace-doctor](references/workspace-doctor.md) | `nemus doctor [name]` | `doc` |
 | Clean node_modules / artifacts | [workspace-cleanup](references/workspace-cleanup.md) | `nemus cleanup <name>` | `cl` |
 | Remove repo from workspace | [remove-repo](references/remove-repo.md) | `nemus remove-repo` | `rr` |

package/skills/nemus/references/dev.md

@@ -0,0 +1,46 @@
+# dev
+
+Start every repo's dev server in a workspace at once, streaming their output into
+one terminal with a color-coded, aligned per-repo prefix. A single Ctrl-C stops
+them all cleanly (process-group kill, so child trees die too).
+
+## CLI
+
+```bash
+nemus dev [workspace] [options]
+```
+
+- `[workspace]` — workspace name; omitted, resolves the current/default one.
+- `--only <repos>` — comma-separated subset of repos to start.
+- `--script <name>` — npm script to prefer (default: `dev` → `develop` → `start` → `serve`).
+- `--command "<cmd>"` — run this exact command in every selected repo instead of a script.
+- `--exit-on-failure` — tear everything down if any service exits non-zero.
+- `--kill-timeout <seconds>` — grace period before SIGKILL on shutdown (default 5).
+
+## Command selection (per repo)
+
+1. `--command` if given.
+2. Else the first `package.json` script that exists (`--script` → `dev` →
+   `develop` → `start` → `serve`), run with the repo's own package manager
+   (pnpm/yarn/npm, detected from its lockfile).
+3. A repo with no runnable script is **skipped with a notice** — so a library in
+   the workspace doesn't block the services. If nothing is runnable, `dev` errors.
+
+## Examples
+
+```bash
+nemus dev                          # every runnable repo in the current workspace
+nemus dev payments --only web,api   # just a subset
+nemus dev payments --command "make run"
+nemus dev payments --exit-on-failure
+```
+
+## Notes
+
+- Long-running: it stays in the foreground hosting the servers until they exit or
+  you Ctrl-C. Not for scripting — use `nemus run` for one-shot commands.
+- Each service runs in its own process group; shutdown SIGTERMs the group, then
+  SIGKILLs stragglers after `--kill-timeout`, so nothing is orphaned.
+- **Platform:** clean process-group teardown is POSIX (macOS/Linux). On Windows
+  it falls back to `taskkill /T /F` (force-kill the tree, no graceful phase).
+- `--kill-timeout 0` is honored (immediate SIGKILL after the SIGTERM).

package/src/commands/dev.ts

@@ -0,0 +1,98 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import { WORKSPACES_DIR } from '../utils/config';
+import { loadMetadata } from '../utils/workspace-meta';
+import { resolveWorkspace, getGlobalOpts, parseList } from '../utils/command-helpers';
+import { resolveDevCommand, runDev, type DevService } from '../utils/dev-orchestrator';
+import { logError, logInfo, logWarning } from '../utils/logger';
+import { colorize } from '../utils/colors';
+
+export function registerDevCommand(parent: Command) {
+  parent
+    .command('dev [workspace]')
+    .description('Start every repo\'s dev server together, with unified color-coded logs (Ctrl-C stops all)')
+    .option('--only <repos>', 'Comma-separated subset of repos to start')
+    .option('--script <name>', 'npm script to prefer (default: dev → develop → start → serve)')
+    .option('--command <cmd>', 'Run this exact command in every selected repo instead of a script')
+    .option('--exit-on-failure', 'Tear everything down if any service exits non-zero')
+    .option('--kill-timeout <seconds>', 'Grace period before SIGKILL on shutdown', '5')
+    .action(async (workspace, opts, cmd) => {
+      const globalOpts = getGlobalOpts(cmd);
+      await handleDev({ workspace, ...opts, ...globalOpts });
+    });
+}
+
+async function handleDev(opts: {
+  workspace?: string;
+  only?: string;
+  script?: string;
+  command?: string;
+  exitOnFailure?: boolean;
+  killTimeout?: string;
+}) {
+  try {
+    const workspaceName = await resolveWorkspace(opts.workspace);
+    const workspacePath = path.join(WORKSPACES_DIR, workspaceName);
+
+    const metadata = await loadMetadata(workspacePath);
+    if (!metadata) {
+      logError(`Workspace not found: ${workspaceName}`);
+      process.exit(1);
+    }
+
+    let repos = metadata.repositories.filter(r => r.status === 'success');
+
+    if (opts.only) {
+      const wanted = new Set(parseList(opts.only));
+      repos = repos.filter(r => wanted.has(r.directoryName) || wanted.has(r.name));
+      if (repos.length === 0) {
+        logError(`No repos in "${workspaceName}" matched --only ${opts.only}`);
+        process.exit(1);
+      }
+    }
+
+    const services: DevService[] = [];
+    const skipped: string[] = [];
+    for (const repo of repos) {
+      const cwd = path.join(workspacePath, repo.directoryName);
+      const command = resolveDevCommand(cwd, { commandOverride: opts.command, script: opts.script });
+      if (!command) {
+        skipped.push(repo.directoryName);
+        continue;
+      }
+      services.push({ label: repo.directoryName, cwd, command });
+    }
+
+    if (services.length === 0) {
+      logError(`Nothing to run in "${workspaceName}".`);
+      logInfo(opts.script
+        ? `No repo has a "${opts.script}" script.`
+        : 'No repo has a dev/develop/start/serve script. Pass --command "<cmd>" to run something explicitly.');
+      process.exit(1);
+    }
+
+    if (skipped.length > 0) {
+      logWarning(`Skipped (no runnable script): ${skipped.join(', ')}`);
+    }
+
+    console.log('\n' + colorize('Starting dev servers', 'bright') + colorize(` · ${workspaceName}`, 'cyan'));
+    for (const s of services) {
+      console.log(`  ${colorize(s.label, 'cyan')}  ${colorize(s.command.command, 'gray')} ${colorize(`(${s.command.source})`, 'gray')}`);
+    }
+    console.log(colorize('  Ctrl-C to stop all.\n', 'gray'));
+
+    // NaN check (not `|| 5`) so an explicit --kill-timeout 0 (immediate SIGKILL)
+    // is honored rather than coerced back to the default.
+    const parsedTimeout = Number(opts.killTimeout);
+    const killTimeoutMs = Math.max(0, Number.isFinite(parsedTimeout) ? parsedTimeout : 5) * 1000;
+    const code = await runDev(services, {
+      exitOnFailure: opts.exitOnFailure,
+      killTimeoutMs,
+    });
+    process.exit(code);
+  } catch (error) {
+    logError('Failed to start dev servers');
+    if (error instanceof Error) logError(error.message);
+    process.exit(1);
+  }
+}

package/src/program.ts

@@ -66,6 +66,7 @@ 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);
@@ -96,6 +97,7 @@ 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);
+  };
+}