agentic-workflow-manager 3.5.0 → 3.6.0

package/dist/src/commands/sensors/exec.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCommand = runCommand;
+const child_process_1 = require("child_process");
+const DEFAULT_MAX_BUFFER = 64 * 1024 * 1024;
+const DEFAULT_KILL_GRACE_MS = 2_000;
+/** After SIGKILL, resolve regardless. A sensor must never hang the gate. */
+const POST_KILL_GRACE_MS = 1_000;
+/**
+ * Kill an entire process tree, not just its root.
+ *
+ * This is the reason `execSync` had to go. `execSync(cmd, { timeout })` spawns
+ * `/bin/sh -c cmd` and, on the deadline, SIGTERMs *that shell only*. A sensor
+ * command is almost always a wrapper (`npx tsc --noEmit`, `npm test`), so the
+ * tool doing the actual work is a grandchild: it survives, gets reparented to
+ * init, and keeps burning CPU. Every timeout then leaves a full tsc/eslint
+ * running, which makes the next run slower, which makes it time out too. The
+ * leak compounds — a repo that was fine at 200 files becomes ungateable at 2000
+ * for reasons that have nothing to do with its size.
+ *
+ * `detached: true` puts the child in its own process group (pgid === pid) so a
+ * negative-pid kill reaches every descendant at once.
+ */
+function killTree(pid, signal) {
+    if (process.platform === 'win32') {
+        // Windows has no process groups in the POSIX sense; taskkill /T walks the tree.
+        try {
+            (0, child_process_1.execFile)('taskkill', ['/pid', String(pid), '/T', '/F'], () => { });
+        }
+        catch { /* ignore */ }
+        return;
+    }
+    try {
+        process.kill(-pid, signal); // negative pid → the whole group
+    }
+    catch {
+        // Group already gone (normal race with a process exiting on its own),
+        // or we never became a group leader. Fall back to the direct child.
+        try {
+            process.kill(pid, signal);
+        }
+        catch { /* already dead */ }
+    }
+}
+/**
+ * Run a shell command to completion, a deadline, or an output cap — whichever
+ * comes first — and always return what was collected.
+ *
+ * Two guarantees `execSync` could not give:
+ *  1. Cutting a run short kills the whole process tree (see `killTree`).
+ *  2. Output produced before the cut is returned, not discarded. A timeout that
+ *     throws away 60s of eslint output costs double: the wall clock, and then
+ *     the re-run the caller has to do to learn anything at all.
+ */
+function runCommand(cmd, opts) {
+    const maxBuffer = opts.maxBuffer ?? DEFAULT_MAX_BUFFER;
+    const killGraceMs = opts.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let overflowed = false;
+        let settled = false;
+        const timers = [];
+        const child = (0, child_process_1.spawn)(cmd, {
+            shell: true,
+            cwd: opts.cwd,
+            detached: process.platform !== 'win32',
+            // stdin closed: a sensor must never block waiting for input, and the
+            // EOF also tells watch-mode-capable tools (vitest, jest) to run once.
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const later = (fn, ms) => {
+            const t = setTimeout(fn, ms);
+            t.unref?.();
+            timers.push(t);
+            return t;
+        };
+        const finish = (extra) => {
+            if (settled)
+                return;
+            settled = true;
+            timers.forEach(clearTimeout);
+            resolve({ stdout, stderr, code: null, signal: null, timedOut, overflowed, ...extra });
+        };
+        /** Cut the run short: kill the tree, escalate, and never hang waiting for it. */
+        const cutShort = () => {
+            if (settled || child.pid === undefined)
+                return;
+            const pid = child.pid;
+            killTree(pid, 'SIGTERM');
+            later(() => killTree(pid, 'SIGKILL'), killGraceMs);
+            // If `close` still has not fired after the escalation, stop waiting.
+            // Whatever is holding the pipe open is no longer our problem to block on.
+            later(() => { child.unref(); finish({ signal: 'SIGKILL' }); }, killGraceMs + POST_KILL_GRACE_MS);
+        };
+        const collect = (into) => (chunk) => {
+            if (settled || overflowed)
+                return;
+            const text = String(chunk);
+            const current = into === 'out' ? stdout : stderr;
+            const room = maxBuffer - current.length;
+            const next = current + (text.length > room ? text.slice(0, room) : text);
+            if (into === 'out')
+                stdout = next;
+            else
+                stderr = next;
+            if (next.length >= maxBuffer) {
+                overflowed = true;
+                cutShort();
+            }
+        };
+        child.stdout?.on('data', collect('out'));
+        child.stderr?.on('data', collect('err'));
+        child.stdout?.on('error', () => { });
+        child.stderr?.on('error', () => { });
+        child.on('error', (err) => finish({ spawnError: err }));
+        child.on('close', (code, signal) => finish({ code, signal }));
+        later(() => { timedOut = true; cutShort(); }, opts.timeout);
+    });
+}

package/dist/src/commands/sensors/index.js

@@ -27,8 +27,8 @@ function registerSensorsCommand(program) {
         .option('--fast', 'run fast sensors only (tsc, lint)')
         .option('--slow', 'run slow sensors only (semgrep, mutation)')
         .option('--all', 'run all sensors regardless of speed')
-        .action((opts) => {
-        const output = (0, run_1.runSensors)({ fast: opts.fast, slow: opts.slow, all: opts.all });
+        .action(async (opts) => {
+        const output = await (0, run_1.runSensors)({ fast: opts.fast, slow: opts.slow, all: opts.all });
         // Emit the verdict ALWAYS — an empty `sensors` with overall:'not_certified'
         // must be visible, never a silent exit-0 that reads as "clean".
         process.stdout.write(JSON.stringify(output, null, 2) + '\n');
@@ -51,9 +51,9 @@ function registerSensorsCommand(program) {
     sensors
         .command('baseline')
         .description('snapshot current findings as accepted — sensors then fail only on NEW ones')
-        .action(() => {
+        .action(async () => {
         const manifestDir = (0, run_1.findManifestDir)(process.cwd());
-        const output = (0, run_1.runSensors)({ all: true, ignoreBaseline: true });
+        const output = await (0, run_1.runSensors)({ all: true, ignoreBaseline: true });
         const baseline = (0, baseline_1.buildBaseline)(output.sensors.map(s => ({ name: s.name, errors: s.errors })));
         const writeDir = manifestDir ?? process.cwd();
         (0, baseline_1.writeBaseline)(writeDir, baseline);

package/dist/src/commands/sensors/run.js

@@ -6,10 +6,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyBaseline = applyBaseline;
 exports.reconcilePack = reconcilePack;
 exports.findManifestDir = findManifestDir;
+exports.resolveConcurrency = resolveConcurrency;
 exports.runSensors = runSensors;
-const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const exec_1 = require("./exec");
 const tsc_1 = require("./formatters/tsc");
 const eslint_1 = require("./formatters/eslint");
 const semgrep_1 = require("./formatters/semgrep");
@@ -22,9 +24,11 @@ const MANIFEST_FILE = '.awm/sensors.json';
 const DEFAULT_FAST_TIMEOUT = 10_000;
 const DEFAULT_SLOW_TIMEOUT = 120_000;
 // Sensor JSON output can be several MB on large repos (e.g. `eslint --format json`
-// with thousands of findings). execSync defaults to a 1MB buffer and kills the
-// child with SIGTERM when exceeded — which previously surfaced as a false "timeout".
+// with thousands of findings). A 1MB cap killed the child with SIGTERM when
+// exceeded — which previously surfaced as a false "timeout".
 const MAX_BUFFER = 64 * 1024 * 1024;
+/** Hard ceiling on parallel sensors: past this, they only contend for the same cores. */
+const MAX_CONCURRENCY = 4;
 /**
  * Apply the baseline to a sensor result: keep only findings not already accepted.
  * `status` becomes 'pass' when every finding was baseline-suppressed. Results
@@ -125,75 +129,117 @@ function getFormatter(name) {
 function isExitCodeSensor(name) {
     return name === 'test';
 }
-function runSensor(name, cmd, timeout, cwd) {
-    try {
-        const raw = (0, child_process_1.execSync)(cmd, { encoding: 'utf-8', timeout, cwd, maxBuffer: MAX_BUFFER, stdio: ['pipe', 'pipe', 'pipe'] });
-        const errors = getFormatter(name)(raw);
-        return { name, status: errors.length > 0 ? 'fail' : 'pass', errors };
+async function runSensor(name, cmd, timeout, cwd) {
+    const res = await (0, exec_1.runCommand)(cmd, { timeout, cwd, maxBuffer: MAX_BUFFER });
+    const format = getFormatter(name);
+    // The shell itself never started (bad cwd, no shell). Nothing ran.
+    if (res.spawnError) {
+        return {
+            name,
+            status: 'fail',
+            errors: [{ message: `sensor could not be started: ${res.spawnError.message}` }],
+        };
     }
-    catch (err) {
-        // Output exceeded maxBuffer — child is killed before output can be read.
-        // Check this BEFORE the SIGTERM branch (ENOBUFS kills with SIGTERM too).
-        // Nothing could be read, so nothing was certified.
-        if (err.code === 'ENOBUFS') {
-            return { name, status: 'inconclusive', errors: [], skipReason: `output exceeded ${MAX_BUFFER} bytes` };
-        }
-        // Genuine timeout: execSync kills with SIGTERM after `timeout` ms. The
-        // sensor produced no verdict — inconclusive, not a benign skip.
-        if (err.code === 'ETIMEDOUT' || (err.killed && err.signal === 'SIGTERM')) {
-            return { name, status: 'inconclusive', errors: [], skipReason: `timeout after ${timeout}ms` };
-        }
-        // Non-zero exit — the normal path for linters/typecheckers that found
-        // findings. Parse the output; if it yields findings, that's a fail.
-        const raw = String((err.stdout ?? '') + (err.stderr ?? ''));
-        const errors = getFormatter(name)(raw);
-        if (errors.length > 0)
-            return { name, status: 'fail', errors };
-        // A missing tool (binary not installed) must NOT pass silently — the gate
-        // cannot certify what it could not run. Treat it as a fail with a clear message.
-        //
-        // Exit 127 is the POSIX signal for "command not found" and is the only check
-        // here that holds across shells and locales: bash writes `command not found`
-        // but dash — `/bin/sh` on Debian/Ubuntu, hence most CI runners and containers
-        // — writes `not found`, so matching shell text alone read an absent tool as a
-        // benign skip. `err.code` does not cover it either: that is ENOENT only when
-        // spawning the shell itself fails, not when the shell starts and the command
-        // inside it is missing. The ENOBUFS and timeout branches are evaluated above,
-        // so reaching here with status 127 means the command did not exist.
-        //
-        // A wrapper (`npm test`, `npx …`) that exits 127 because a binary it invokes
-        // is absent is classified the same way, deliberately: the gate still ran
-        // nothing and still cannot certify anything.
-        const lower = raw.toLowerCase();
-        const toolMissing = err.status === 127 || // POSIX: command not found
-            err.code === 'ENOENT' || // execSync spawn failure (no shell)
-            lower.includes('command not found') || // bash, zsh
-            // cmd.exe reports an absent binary with exit 1, so 127 does not cover
-            // Windows; this exact phrase does. Kept narrow on purpose — a loose
-            // `not found` would also match a tool that ran and said "not found"
-            // for reasons of its own.
-            lower.includes('is not recognized as an internal or external command') ||
-            lower.includes('enoent') ||
-            lower.includes('could not determine executable');
-        if (toolMissing) {
+    // Cut short by the deadline or the output cap. The run is NOT a verdict — but
+    // whatever it printed before being cut is still evidence, and throwing it away
+    // is what forced the caller to re-run the same command by hand to learn
+    // anything. Findings in the partial output are real findings; their absence
+    // proves nothing, so a clean partial can never be `pass`.
+    if (res.timedOut || res.overflowed) {
+        const reason = res.timedOut
+            ? `timeout after ${timeout}ms`
+            : `output exceeded ${MAX_BUFFER} bytes`;
+        const errors = format(res.stdout + res.stderr);
+        if (errors.length > 0) {
             return {
                 name,
                 status: 'fail',
-                errors: [{ message: `sensor tool not available: ${raw.slice(0, 200)}` }],
+                errors,
+                incomplete: `${reason} — findings below are from partial output; the run did not finish`,
             };
         }
-        // Exit-code sensors (tests): any genuine non-zero exit is a real failure,
-        // even when no per-line findings can be parsed from the output.
-        if (isExitCodeSensor(name)) {
-            return { name, status: 'fail', errors: [{ message: `SENSOR[${name}] failed (exit ${err.status})` }] };
-        }
-        // Residual case: it exited non-zero, the tool exists, and no finding
-        // could be parsed. We do not know what happened — say so instead of
-        // reporting a benign skip.
-        return { name, status: 'inconclusive', errors: [], skipReason: `exit ${err.status}: ${raw.slice(0, 200)}` };
+        return { name, status: 'inconclusive', errors: [], skipReason: reason };
+    }
+    if (res.code === 0) {
+        const errors = format(res.stdout);
+        return { name, status: errors.length > 0 ? 'fail' : 'pass', errors };
+    }
+    // Non-zero exit — the normal path for linters/typecheckers that found
+    // findings. Parse the output; if it yields findings, that's a fail.
+    const raw = res.stdout + res.stderr;
+    const errors = format(raw);
+    if (errors.length > 0)
+        return { name, status: 'fail', errors };
+    // A missing tool (binary not installed) must NOT pass silently — the gate
+    // cannot certify what it could not run. Treat it as a fail with a clear message.
+    //
+    // Exit 127 is the POSIX signal for "command not found" and is the only check
+    // here that holds across shells and locales: bash writes `command not found`
+    // but dash — `/bin/sh` on Debian/Ubuntu, hence most CI runners and containers
+    // — writes `not found`, so matching shell text alone read an absent tool as a
+    // benign skip. A failure to spawn the shell itself is a different thing and
+    // is handled above via `spawnError`. The cut-short branches are evaluated
+    // above too, so reaching here with status 127 means the command did not exist.
+    //
+    // A wrapper (`npm test`, `npx …`) that exits 127 because a binary it invokes
+    // is absent is classified the same way, deliberately: the gate still ran
+    // nothing and still cannot certify anything.
+    const lower = raw.toLowerCase();
+    const toolMissing = res.code === 127 || // POSIX: command not found
+        lower.includes('command not found') || // bash, zsh
+        // cmd.exe reports an absent binary with exit 1, so 127 does not cover
+        // Windows; this exact phrase does. Kept narrow on purpose — a loose
+        // `not found` would also match a tool that ran and said "not found"
+        // for reasons of its own.
+        lower.includes('is not recognized as an internal or external command') ||
+        lower.includes('enoent') ||
+        lower.includes('could not determine executable');
+    if (toolMissing) {
+        return {
+            name,
+            status: 'fail',
+            errors: [{ message: `sensor tool not available: ${raw.slice(0, 200)}` }],
+        };
     }
+    // Exit-code sensors (tests): any genuine non-zero exit is a real failure,
+    // even when no per-line findings can be parsed from the output.
+    if (isExitCodeSensor(name)) {
+        return { name, status: 'fail', errors: [{ message: `SENSOR[${name}] failed (exit ${res.code})` }] };
+    }
+    // Residual case: it exited non-zero, the tool exists, and no finding
+    // could be parsed. We do not know what happened — say so instead of
+    // reporting a benign skip.
+    return { name, status: 'inconclusive', errors: [], skipReason: `exit ${res.code}: ${raw.slice(0, 200)}` };
+}
+/**
+ * How many sensors may run at once. Sensors are separate processes over the same
+ * tree, so they parallelise cleanly — but each one (tsc, eslint, depcruise) is
+ * largely single-threaded, and oversubscribing the box just makes every sensor
+ * slower and more likely to hit its own deadline. Leave a core for the agent.
+ */
+function resolveConcurrency(manifest, sensorCount) {
+    const configured = Number(process.env.AWM_SENSORS_CONCURRENCY ?? manifest.concurrency);
+    if (Number.isFinite(configured) && configured >= 1)
+        return Math.min(Math.floor(configured), sensorCount);
+    const cores = os_1.default.cpus()?.length ?? 2;
+    return Math.max(1, Math.min(MAX_CONCURRENCY, cores - 1, sensorCount));
+}
+/** Run `tasks` with at most `limit` in flight, preserving input order in the output. */
+async function pooled(tasks, limit) {
+    const results = new Array(tasks.length);
+    let next = 0;
+    const worker = async () => {
+        while (true) {
+            const i = next++;
+            if (i >= tasks.length)
+                return;
+            results[i] = await tasks[i]();
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, tasks.length) }, worker));
+    return results;
 }
-function runSensors(opts = {}) {
+async function runSensors(opts = {}) {
     const startCwd = opts.cwd ?? process.cwd();
     const manifestDir = findManifestDir(startCwd);
     if (!manifestDir)
@@ -204,31 +250,38 @@ function runSensors(opts = {}) {
     const reconciled = reconcilePack(manifestDir, manifest);
     const activeManifest = reconciled.manifest;
     const cwd = manifestDir; // ejecutar sensores y baseline desde donde vive el manifest
-    const results = [];
     // Baseline suppresses already-accepted findings so sensors fail only on NEW
     // ones (essential on repos with a large pre-existing baseline). Absent file or
     // --ignore-baseline → every finding counts (backward-compatible).
     const baseline = opts.ignoreBaseline ? null : (0, baseline_1.readBaseline)(cwd);
+    // Sensors are independent processes over the same tree, so they run
+    // concurrently rather than one-after-another: wall clock becomes the slowest
+    // sensor instead of the sum of all of them. Tasks are built — and dispatched —
+    // in manifest order, so the reported order stays stable.
+    const tasks = [];
+    const settled = (r) => () => Promise.resolve(r);
     for (const [name, config] of Object.entries(activeManifest.sensors)) {
         const isFast = config.fast ?? false;
         if (!shouldRun(isFast, opts))
             continue;
         if (config.enabled === false) {
-            results.push({ name, status: 'skipped', errors: [], skipReason: 'disabled' });
+            tasks.push(settled({ name, status: 'skipped', errors: [], skipReason: 'disabled' }));
             continue;
         }
         if (!config.cmd) {
             // Enabled but with nothing to run: broken config, not a deliberate
             // opt-out. `enabled: false` is how a sensor is turned off.
-            results.push({ name, status: 'inconclusive', errors: [], skipReason: 'no cmd configured' });
+            tasks.push(settled({ name, status: 'inconclusive', errors: [], skipReason: 'no cmd configured' }));
             continue;
         }
+        const cmd = config.cmd;
         const timeout = config.timeout ?? (isFast ? DEFAULT_FAST_TIMEOUT : DEFAULT_SLOW_TIMEOUT);
-        let result = runSensor(name, config.cmd, timeout, cwd);
-        if (baseline)
-            result = applyBaseline(result, baseline[name]);
-        results.push(result);
+        tasks.push(async () => {
+            const result = await runSensor(name, cmd, timeout, cwd);
+            return baseline ? applyBaseline(result, baseline[name]) : result;
+        });
     }
+    const results = await pooled(tasks, resolveConcurrency(activeManifest, tasks.length));
     // `fail` outranks `inconclusive`: when something is broken AND something
     // could not be measured, the broken thing is the actionable verdict.
     let overall = results.some(r => r.status === 'fail') ? 'fail'

package/dist/tests/commands/sensors/exec-fixtures.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnFailed = exports.overflowed = exports.timedOut = exports.exited = exports.ok = void 0;
+/**
+ * Builders for the `ExecResult` shape that `runCommand` returns. Sensor tests
+ * mock the exec boundary rather than `child_process` directly: `runCommand`
+ * never throws, so a mocked run is a value, not an exception.
+ */
+const base = { stdout: '', stderr: '', code: null, signal: null, timedOut: false, overflowed: false };
+/** Clean run: exit 0. */
+const ok = (stdout = '') => ({ ...base, stdout, code: 0 });
+exports.ok = ok;
+/** Ran to completion with a non-zero exit code. */
+const exited = (code, stdout = '', stderr = '') => ({ ...base, stdout, stderr, code });
+exports.exited = exited;
+/** Cut short by the deadline. `stdout` is whatever it managed to print first. */
+const timedOut = (stdout = '', stderr = '') => ({ ...base, stdout, stderr, signal: 'SIGKILL', timedOut: true });
+exports.timedOut = timedOut;
+/** Cut short by the output cap. */
+const overflowed = (stdout = '') => ({ ...base, stdout, signal: 'SIGKILL', overflowed: true });
+exports.overflowed = overflowed;
+/** The shell itself never started. */
+const spawnFailed = (message = 'ENOENT') => ({ ...base, spawnError: Object.assign(new Error(message), { code: 'ENOENT' }) });
+exports.spawnFailed = spawnFailed;

package/dist/tests/commands/sensors/exec.test.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const exec_1 = require("../../../src/commands/sensors/exec");
+const onPosix = process.platform !== 'win32' ? describe : describe.skip;
+/** Poll until `fn()` is true or the budget runs out. Avoids fixed sleeps. */
+async function until(fn, budgetMs = 4000) {
+    const deadline = Date.now() + budgetMs;
+    while (Date.now() < deadline) {
+        if (fn())
+            return true;
+        await new Promise(r => setTimeout(r, 25));
+    }
+    return fn();
+}
+describe('runCommand — exit codes and output', () => {
+    it('returns stdout and code 0 for a clean command', async () => {
+        const r = await (0, exec_1.runCommand)('echo hello', { timeout: 5000, cwd: process.cwd() });
+        expect(r.code).toBe(0);
+        expect(r.stdout.trim()).toBe('hello');
+        expect(r.timedOut).toBe(false);
+        expect(r.overflowed).toBe(false);
+    });
+    it('captures stderr and a non-zero exit code without throwing', async () => {
+        const r = await (0, exec_1.runCommand)('echo oops 1>&2; exit 3', { timeout: 5000, cwd: process.cwd() });
+        expect(r.code).toBe(3);
+        expect(r.stderr).toMatch(/oops/);
+        expect(r.timedOut).toBe(false);
+    });
+    it('reports 127 for a command that does not exist', async () => {
+        const r = await (0, exec_1.runCommand)('awm-definitely-not-a-real-binary-xyz', { timeout: 5000, cwd: process.cwd() });
+        expect(r.code).toBe(127);
+    });
+});
+describe('runCommand — output cap', () => {
+    it('stops at maxBuffer, flags overflow, and keeps what it read', async () => {
+        // 200 lines of ~50 bytes each, capped at 1KB.
+        const r = await (0, exec_1.runCommand)(`for i in $(seq 1 200); do echo "line-$i-padding-padding-padding-padding"; done`, {
+            timeout: 10_000, cwd: process.cwd(), maxBuffer: 1024,
+        });
+        expect(r.overflowed).toBe(true);
+        expect(r.stdout.length).toBeLessThanOrEqual(1024);
+        // The point of the cap change: what was read is still usable, not discarded.
+        expect(r.stdout).toMatch(/line-1-/);
+    });
+});
+onPosix('runCommand — timeout', () => {
+    it('flags the timeout and returns the output produced before the deadline', async () => {
+        const r = await (0, exec_1.runCommand)('echo partial-finding; sleep 30', { timeout: 700, cwd: process.cwd() });
+        expect(r.timedOut).toBe(true);
+        // This is the whole point of dropping execSync: 700ms of work is not thrown away.
+        expect(r.stdout).toMatch(/partial-finding/);
+    });
+    it('kills the grandchild process, not just the shell it spawned', async () => {
+        // Models `npx tsc --noEmit`: the sensor command is a wrapper that spawns the
+        // real tool. execSync SIGTERMs only the shell it started, leaving the tool
+        // running and reparented to init — the leak that compounds across retries.
+        const dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-exec-group-'));
+        const beat = path_1.default.join(dir, 'beat');
+        const worker = path_1.default.join(dir, 'worker.js');
+        fs_1.default.writeFileSync(worker, `
+            const fs = require('fs');
+            setInterval(() => fs.writeFileSync(${JSON.stringify(beat)}, String(Date.now())), 30);
+            setTimeout(() => {}, 60000);
+        `);
+        try {
+            const r = await (0, exec_1.runCommand)(`sh -c "node ${worker} & wait"`, { timeout: 800, cwd: dir });
+            expect(r.timedOut).toBe(true);
+            // The worker must have been alive before the kill, or the test proves nothing.
+            expect(await until(() => fs_1.default.existsSync(beat))).toBe(true);
+            const atKill = fs_1.default.readFileSync(beat, 'utf-8');
+            const stillBeating = await until(() => fs_1.default.readFileSync(beat, 'utf-8') !== atKill, 1000);
+            expect(stillBeating).toBe(false);
+        }
+        finally {
+            fs_1.default.rmSync(dir, { recursive: true, force: true });
+        }
+    }, 15_000);
+});
+describe('runCommand — spawn failure', () => {
+    it('surfaces a spawn error instead of hanging', async () => {
+        const r = await (0, exec_1.runCommand)('echo hi', { timeout: 5000, cwd: path_1.default.join(os_1.default.tmpdir(), 'awm-no-such-dir-xyz') });
+        expect(r.spawnError).toBeDefined();
+        expect(r.code).not.toBe(0);
+    });
+});