pi-smart-voice-notify 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.2.0] - 2026-03-07
+
+### Added
+- Added multi-engine TTS support with auto selection plus Edge, espeak-ng, ElevenLabs, OpenAI-compatible, and SAPI backends.
+- Added forwarded permission request watching, reminder playback control, Linux wake/focus helpers, per-project sound discovery, webhook delivery, and AI-generated notification message support.
+- Added targeted tests for abortable commands, reminder playback, and forwarded-permission notification flows.
+
+### Changed
+- Expanded configuration normalization and example config to cover nested reminder, webhook, AI-message, focus-detection, and sound-theme settings while keeping legacy keys compatible.
+- Improved notification orchestration so reminder scheduling, focused-terminal suppression, and desktop/audio delivery can share richer runtime context.
+- Switched the test runner to Node's built-in TypeScript stripping support and raised the documented runtime baseline to Node.js 24.
+
+### Fixed
+- Restored the package test workflow so the published repo can run its checked-in TypeScript tests without a missing loader file.
+- Updated README documentation to cover the new engines, watchers, webhook/AI integrations, and sound-theme behavior.
+
+## [0.1.2] - 2026-03-04
+
+### Fixed
+- Use absolute GitHub raw URL for README image to fix npm display
+
 ## [0.1.1] - 2026-03-04
 
 ### Changed

package/README.md

@@ -2,31 +2,41 @@
 
 Windows-optimized smart notification extension for the Pi coding agent.
 
-**pi-smart-voice-notify** monitors Pi session and tool events to alert you via **Windows SAPI TTS**, **sound playback**, and **desktop toast notifications** when the agent requires your attention.
+**pi-smart-voice-notify** monitors Pi session and tool events to alert you via **multi-engine TTS**, **sound playback**, **desktop toast notifications**, and optional **webhook/AI-assisted messaging** when the agent requires your attention.
 
-![pi-smart-voice-notify configuration modal](assets/pi-smart-voice-notify.png)
+![pi-smart-voice-notify configuration modal](https://raw.githubusercontent.com/MasuRii/pi-smart-voice-notify/main/assets/pi-smart-voice-notify.png)
 
 ## Features
 
 - **Multi-channel notifications**
-  - **Sound** – Windows audio playback via PowerShell (with beep fallback)
-  - **Voice** – Windows SAPI text-to-speech with configurable voice and rate
-  - **Desktop toasts** – Cross-platform notifications via `node-notifier` (Windows/macOS/Linux)
+  - **Sound** – local sound playback with fallback beeps and reusable reminder playback control
+  - **Voice** – auto-selectable TTS engines: Edge, espeak-ng, ElevenLabs, OpenAI-compatible, and Windows SAPI
+  - **Desktop toasts** – cross-platform notifications via `node-notifier` (Windows/macOS/Linux)
+  - **Webhook delivery** – optional Discord or generic HTTP webhook notifications
 
 - **Intelligent event detection**
   - Task completion (idle)
-  - Permission blocks
+  - Direct permission blocks plus forwarded subagent permission requests
   - Questions requiring input (when custom `question` tool is loaded)
   - Errors
 
 - **Reminder system**
-  - Configurable reminder delays with follow-up scheduling
+  - Configurable per-event reminder delays with follow-up scheduling
   - Exponential backoff multiplier for follow-ups
-  - Auto-cancel reminders on user activity
+  - Auto-cancel reminders on user activity or resolution
 
-- **Wake monitor support**
+- **Focus and wake handling**
   - Wakes display from sleep before notifications
-  - Cross-platform: Windows (SendKeys), macOS (caffeinate), Linux (xset/GNOME)
+  - Optional focused-terminal suppression on Linux
+  - Cross-platform wake strategies for Windows, macOS, and Linux sessions
+
+- **Sound customization**
+  - Direct per-event sound files
+  - Theme-based sound selection and optional per-project sound discovery
+  - Theme randomization and default volume controls
+
+- **AI message generation**
+  - Optional AI-generated notification text with caching and template fallback
 
 - **Interactive settings UI**
   - `/voice-notify` command opens a modal for live configuration
@@ -93,14 +103,18 @@ A starter template is provided in `config/config.example.json`. On startup, the
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `enabled` | boolean | `true` | Master on/off switch |
-| `windowsOptimized` | boolean | `true` | Show warning on non-Windows platforms |
+| `windowsOptimized` | boolean | `true` | Show a compatibility notice on platforms other than Windows/Linux |
 | `notificationMode` | string | `"sound-first"` | Mode: `sound-first`, `tts-first`, `both`, `sound-only` |
-| `enableSound` | boolean | `true` | Enable sound playback (Windows) |
-| `enableTts` | boolean | `true` | Enable text-to-speech (Windows) |
+| `enableSound` | boolean | `true` | Enable sound playback |
+| `enableTts` | boolean | `true` | Enable text-to-speech delivery |
+| `ttsEngine` | string | `"auto"` | Engine: `auto`, `edge`, `espeak-ng`, `elevenlabs`, `openai`, `sapi` |
 | `enableDesktopNotification` | boolean | `true` | Enable desktop toast notifications |
 | `desktopNotificationTimeout` | number | `8` | Toast display duration in seconds (1–60) |
 | `wakeMonitor` | boolean | `true` | Wake display from sleep before notifying |
 | `idleThresholdSeconds` | number | `30` | System idle threshold before waking monitor (5–600) |
+| `skipWhenFocused` | boolean | `false` | Suppress notifications while the active Linux terminal/editor is focused |
+
+`windowsOptimized` keeps compatibility messaging for platforms that do not have Linux/Windows-native behavior. Linux users no longer see this notice.
 
 ### Event Toggles
 
@@ -108,12 +122,17 @@ A starter template is provided in `config/config.example.json`. On startup, the
 |--------|------|---------|-------------|
 | `enableIdleNotification` | boolean | `true` | Notify when agent finishes a task |
 | `enablePermissionNotification` | boolean | `true` | Notify on permission blocks |
+| `enableForwardedPermissionWatcher` | boolean | `true` | Watch forwarded permission request files and notify when new requests arrive |
+| `includeForwardedPermissionAgentName` | boolean | `true` | Include sanitized requester agent name in forwarded permission notification text |
+| `watchLegacyForwardedPermissionPath` | boolean | `true` | Also watch legacy `~/.pi/agent/permission-forwarding/requests` when present |
 | `enableQuestionNotification` | boolean | `true` | Notify when agent asks a question* |
 | `enableErrorNotification` | boolean | `true` | Notify on errors |
 | `suppressIdleAfterError` | boolean | `true` | Skip idle notification if turn had errors |
 
 *Question notifications only work when a custom `question` tool is loaded.
 
+Forwarded permission watcher notifications use privacy-safe text and never include raw forwarded `message` content.
+
 ### Reminder Settings
 
 | Option | Type | Default | Description |
@@ -124,12 +143,20 @@ A starter template is provided in `config/config.example.json`. On startup, the
 | `maxFollowUps` | number | `3` | Maximum follow-up count (1–10) |
 | `followUpBackoffMultiplier` | number | `1.5` | Delay multiplier for each follow-up |
 
-### TTS Settings (Windows)
+### TTS Settings
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `ttsVoice` | string | `"Microsoft Zira Desktop"` | SAPI voice name |
-| `ttsRate` | number | `-1` | Speech rate (-10 to 10) |
+| `voice` | string | `"Microsoft Zira Desktop"` | Generic preferred voice label |
+| `rate` | number | `-1` | Generic speaking rate |
+| `volume` | number | `85` | Preferred playback volume percentage |
+| `fallbackChain` | array | `["edge", "espeak-ng", "sapi"]` | TTS engines tried when `ttsEngine` is `auto` |
+| `ttsVoice` | string | `"Microsoft Zira Desktop"` | Legacy SAPI-compatible alias |
+| `ttsRate` | number | `-1` | Legacy SAPI-compatible alias |
+| `edgeVoice` | string | `"en-US-JennyNeural"` | Microsoft Edge voice |
+| `espeakVoice` | string | `"en"` | `espeak-ng` voice for Linux fallback |
+| `elevenLabsVoiceId` | string | `"cgSgspJ2msm6clMCkdW9"` | ElevenLabs voice id |
+| `openaiTtsVoice` | string | `"alloy"` | OpenAI-compatible voice |
 
 ### Sound File Paths
 
@@ -142,10 +169,18 @@ A starter template is provided in `config/config.example.json`. On startup, the
 
 Paths can be absolute or relative to the extension directory.
 
-### Advanced Settings
+### Sound, Webhook, and AI Settings
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
+| `themeName` | string | `"default"` | Preferred sound theme name |
+| `enablePerProjectSounds` | boolean | `false` | Search the current project for matching notification sounds |
+| `randomizeThemeSounds` | boolean | `true` | Randomize among matching themed sounds |
+| `webhook.enabled` | boolean | `false` | Enable Discord/generic webhook delivery |
+| `webhook.events` | array | `["idle", "permission", "question", "error"]` | Notification types sent through webhooks |
+| `aiMessages.enabled` | boolean | `false` | Enable AI-generated notification copy |
+| `aiMessages.model` | string | `"llama3"` | Model id used for AI notification generation |
+| `aiMessages.caching.enabled` | boolean | `true` | Cache generated messages to reduce repeat calls |
 | `minNotificationIntervalMs` | number | `1500` | Throttle interval between same-type notifications |
 | `debugLog` | boolean | `false` | Enable debug logging to file |
 
@@ -196,10 +231,19 @@ Ensure system idle time exceeds `idleThresholdSeconds` for wake to trigger.
 index.ts                    → Extension entrypoint (re-exports src/index.ts)
 src/
 ├── index.ts                → Main extension logic, event handlers, command registration
-├── config-store.ts         → Config paths, normalization, load/save utilities
-├── types.ts                → TypeScript interfaces and types
-├── notify-audio.ts         → Windows sound + SAPI TTS + monitor wake service
+├── config-store.ts         → Config paths, normalization, env overrides, load/save utilities
+├── types.ts                → Shared configuration and runtime types
+├── notify-audio.ts         → Audio dispatch and Windows/SAPI playback integration
+├── tts.ts                  → Multi-engine TTS selection and speech dispatch
 ├── desktop-notify.ts       → Desktop toast notifications via node-notifier
+├── permission-forwarding-watcher.ts → Watches forwarded permission request directories
+├── reminder-playback.ts    → Deduplicates/cancels overlapping reminder playback
+├── sound-theme.ts          → Theme and sound file resolution
+├── per-project-sound.ts    → Project-local sound discovery helpers
+├── webhook.ts              → Discord and generic HTTP webhook delivery
+├── ai-messages.ts          → AI-generated notification message generation and caching
+├── linux.ts                → Linux wake/audio/focus helpers
+├── focus-detect.ts         → Terminal focus detection cache
 ├── logging.ts              → Debug logger with JSONL output
 └── zellij-modal.ts         → Settings modal UI components
 ```
@@ -232,12 +276,12 @@ Events include: config changes, notifications triggered, audio dispatch, reminde
 ```bash
 npm install
 npm run build      # TypeScript compilation
-npm run lint       # Run linter
-npm run test       # Run tests
-npm run check      # lint + test
+npm run lint       # Alias for build
+npm run test       # Node test runner with built-in TypeScript stripping
+npm run check      # build + test
 ```
 
-**Requirements:** Node.js ≥ 20
+**Requirements:** Node.js ≥ 24
 
 ## License
 

package/config/config.example.json

@@ -1,7 +1,12 @@
 {
+  "_comment_0": "pi-smart-voice-notify example config. Copy this file to ~/.pi/agent/extensions/pi-smart-voice-notify/config.json and edit values.",
+  "_comment_1": "Secrets should be provided via environment variables (ELEVENLABS_API_KEY, OPENAI_TTS_API_KEY, OPENAI_API_KEY, DISCORD_WEBHOOK_URL, WEBHOOK_URL).",
+
   "version": 1,
   "enabled": true,
   "windowsOptimized": true,
+
+  "_comment_notifications": "Notification delivery and channel toggles.",
   "notificationMode": "sound-first",
   "enableSound": true,
   "enableTts": true,
@@ -11,20 +16,155 @@
   "idleThresholdSeconds": 30,
   "enableIdleNotification": true,
   "enablePermissionNotification": true,
+  "enableForwardedPermissionWatcher": true,
+  "includeForwardedPermissionAgentName": true,
+  "watchLegacyForwardedPermissionPath": true,
   "enableQuestionNotification": true,
   "enableErrorNotification": true,
+  "minNotificationIntervalMs": 1500,
+  "suppressIdleAfterError": true,
+
+  "_comment_focus": "Focus detection (Linux): when true, suppress notification while terminal/editor is focused.",
+  "skipWhenFocused": false,
+  "focusCacheTtl": 400,
+  "focusCacheTtlMs": 400,
+
+  "_comment_reminders": "Legacy reminder keys remain supported. New nested reminderIntervals/reminderEscalation are preferred.",
   "reminderEnabled": true,
   "reminderDelaySeconds": 30,
   "followUpEnabled": true,
   "maxFollowUps": 3,
   "followUpBackoffMultiplier": 1.5,
-  "minNotificationIntervalMs": 1500,
-  "suppressIdleAfterError": true,
+  "reminderIntervals": {
+    "_comment": "Per-event reminder delays (seconds).",
+    "defaultSeconds": 30,
+    "idleSeconds": 30,
+    "permissionSeconds": 20,
+    "questionSeconds": 25,
+    "errorSeconds": 20
+  },
+  "reminderEscalation": {
+    "_comment": "Escalation behavior for repeat reminders.",
+    "enabled": true,
+    "maxFollowUps": 3,
+    "backoffMultiplier": 1.5
+  },
+
+  "_comment_tts_core": "Generic TTS controls.",
+  "ttsEngine": "auto",
+  "voice": "Microsoft Zira Desktop",
+  "rate": -1,
+  "volume": 85,
+  "fallbackChain": ["edge", "espeak-ng", "sapi"],
+  "commandTimeoutMs": 30000,
+
+  "_comment_tts_legacy": "Legacy SAPI-compatible aliases (kept for backward compatibility).",
   "ttsVoice": "Microsoft Zira Desktop",
   "ttsRate": -1,
+  "sapiVoice": "Microsoft Zira Desktop",
+  "sapiRate": -1,
+  "sapiPitch": "medium",
+  "sapiVolume": "loud",
+
+  "_comment_tts_edge": "Edge TTS settings.",
+  "edgeVoice": "en-US-JennyNeural",
+  "edgeRate": "+10%",
+  "edgePitch": "+0Hz",
+  "edgeVolume": "+0%",
+
+  "_comment_tts_espeak": "espeak-ng settings (Linux fallback).",
+  "espeakVoice": "en",
+  "espeakRate": 175,
+  "espeakPitch": 50,
+
+  "_comment_tts_elevenlabs": "ElevenLabs API settings. Keep api key empty here and use ELEVENLABS_API_KEY env var.",
+  "elevenLabsApiKey": "",
+  "elevenLabsVoiceId": "cgSgspJ2msm6clMCkdW9",
+  "elevenLabsModel": "eleven_turbo_v2_5",
+  "elevenLabsStability": 0.5,
+  "elevenLabsSimilarity": 0.75,
+  "elevenLabsStyle": 0.5,
+
+  "_comment_tts_openai": "OpenAI-compatible TTS endpoint settings. Keep api key empty here and use OPENAI_TTS_API_KEY/OPENAI_API_KEY env vars.",
+  "openaiTtsEndpoint": "",
+  "openaiTtsApiKey": "",
+  "openaiTtsModel": "tts-1",
+  "openaiTtsVoice": "alloy",
+  "openaiTtsFormat": "mp3",
+  "openaiTtsSpeed": 1,
+
+  "_comment_sounds": "Direct sound file fallbacks.",
   "idleSoundFile": "assets/Soft-high-tech-notification-sound-effect.mp3",
   "permissionSoundFile": "assets/Machine-alert-beep-sound-effect.mp3",
   "questionSoundFile": "assets/Machine-alert-beep-sound-effect.mp3",
   "errorSoundFile": "assets/Machine-alert-beep-sound-effect.mp3",
+
+  "_comment_sound_theme": "Sound theme settings.",
+  "themePath": "",
+  "themeName": "default",
+  "themesRootPath": "",
+  "themeConfigPath": "",
+  "customSoundDirectories": [],
+  "perProjectSounds": false,
+  "enablePerProjectSounds": false,
+  "randomizeThemeSounds": true,
+  "themeDefaultVolume": 100,
+
+  "_comment_webhook": "Webhook notifications (Discord and generic HTTP webhooks).",
+  "webhook": {
+    "enabled": false,
+    "discordUrl": "",
+    "genericUrl": "",
+    "events": ["idle", "permission", "question", "error"],
+    "mentionOnPermission": false,
+    "username": "Pi Smart Notify",
+    "minIntervalMs": 1500,
+    "maxRetries": 3,
+    "requestTimeoutMs": 8000
+  },
+  "_comment_webhook_legacy": "Legacy flat webhook keys (kept for backward compatibility).",
+  "enableWebhook": false,
+  "webhookEnabled": false,
+  "discordWebhookUrl": "",
+  "genericWebhookUrl": "",
+  "webhookEvents": ["idle", "permission", "question", "error"],
+
+  "_comment_ai": "AI-generated message settings. Keep api key empty here and use PI_SMART_NOTIFY_AI_API_KEY or OPENAI_API_KEY env var.",
+  "aiMessages": {
+    "enabled": false,
+    "endpoint": "http://localhost:11434/v1",
+    "model": "llama3",
+    "apiKey": "",
+    "timeoutMs": 15000,
+    "temperature": 0.7,
+    "maxTokens": 120,
+    "fallbackToTemplates": true,
+    "personality": "helpful assistant",
+    "tone": "friendly and concise",
+    "caching": {
+      "enabled": true,
+      "ttlMs": 60000,
+      "maxEntries": 200
+    },
+    "templates": {}
+  },
+  "_comment_ai_legacy": "Legacy flat AI keys (kept for backward compatibility).",
+  "enableAIMessages": false,
+  "aiEndpoint": "http://localhost:11434/v1",
+  "aiModel": "llama3",
+  "aiApiKey": "",
+  "aiTimeoutMs": 15000,
+  "aiTemperature": 0.7,
+  "aiMaxTokens": 120,
+  "aiFallbackToTemplates": true,
+  "personality": "helpful assistant",
+  "tone": "friendly and concise",
+  "aiPersonality": "helpful assistant",
+  "aiTone": "friendly and concise",
+  "enableMessageCache": true,
+  "messageCacheTtlMs": 60000,
+  "maxCacheEntries": 200,
+  "aiTemplates": {},
+
   "debugLog": false
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-smart-voice-notify",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Windows-optimized smart voice, sound, and desktop notifications for Pi coding agent.",
   "type": "module",
   "main": "./index.ts",
@@ -17,10 +17,10 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
+    "build": "npx --yes -p typescript@5.7.3 -p @types/node@20.17.57 tsc -p tsconfig.json --noEmit",
     "lint": "npm run build",
-    "test": "node --test",
-    "check": "npm run lint && npm run test"
+    "test": "node --import ./test-ts-register.mjs --test src/abortable-command.test.ts src/reminder-playback.test.ts src/index.test.ts",
+    "check": "npm run build && npm run test"
   },
   "keywords": [
     "pi-package",
@@ -33,7 +33,7 @@
   "author": "MasuRii",
   "license": "MIT",
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "publishConfig": {
     "access": "public"

package/src/abortable-command.test.ts

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { runAbortableCommand } from "./abortable-command.ts";
+
+test("runAbortableCommand returns an aborted result when the signal is already aborted", async () => {
+	const controller = new AbortController();
+	controller.abort();
+
+	const result = await runAbortableCommand(process.execPath, ["-e", "process.exit(0)"], {
+		signal: controller.signal,
+		timeoutMs: 1_000,
+	});
+
+	assert.equal(result.aborted, true);
+	assert.equal(result.code, 1);
+	assert.match(result.errorMessage ?? "", /aborted before start/i);
+});
+
+test("runAbortableCommand stops an in-flight process when aborted", async () => {
+	const controller = new AbortController();
+	const startedAt = Date.now();
+	const command = runAbortableCommand(
+		process.execPath,
+		[
+			"-e",
+			"process.on('SIGTERM', () => process.exit(0)); setTimeout(() => process.exit(0), 10000);",
+		],
+		{
+			signal: controller.signal,
+			timeoutMs: 5_000,
+		},
+	);
+
+	setTimeout(() => {
+		controller.abort();
+	}, 100);
+
+	const result = await command;
+	const elapsedMs = Date.now() - startedAt;
+
+	assert.equal(result.aborted, true);
+	assert.equal(result.timedOut, false);
+	assert.ok(elapsedMs < 4_000, `Expected aborted command to stop quickly, received ${elapsedMs}ms`);
+});

package/src/abortable-command.ts

@@ -0,0 +1,151 @@
+import { spawn } from "node:child_process";
+
+export interface AbortableCommandOptions {
+	timeoutMs?: number;
+	signal?: AbortSignal;
+	env?: NodeJS.ProcessEnv;
+	cwd?: string;
+}
+
+export interface AbortableCommandResult {
+	code: number;
+	stdout: string;
+	stderr: string;
+	timedOut: boolean;
+	aborted: boolean;
+	errorMessage?: string;
+}
+
+function stringifyError(error: unknown): string {
+	if (error instanceof Error && error.message.trim().length > 0) {
+		return error.message;
+	}
+	return String(error);
+}
+
+function buildCommandString(command: string, args: readonly string[]): string {
+	return args.length > 0 ? `${command} ${args.join(" ")}` : command;
+}
+
+function stopChildProcess(child: ReturnType<typeof spawn>, force = false): void {
+	if (child.killed) {
+		return;
+	}
+
+	try {
+		if (process.platform === "win32") {
+			child.kill();
+			return;
+		}
+		child.kill(force ? "SIGKILL" : "SIGTERM");
+	} catch {
+		// noop
+	}
+}
+
+export async function runAbortableCommand(
+	command: string,
+	args: readonly string[] = [],
+	options: AbortableCommandOptions = {},
+): Promise<AbortableCommandResult> {
+	const normalizedCommand = command.trim();
+	if (!normalizedCommand) {
+		throw new Error("runAbortableCommand: command must be a non-empty string");
+	}
+	if (!Array.isArray(args)) {
+		throw new Error("runAbortableCommand: args must be an array of strings");
+	}
+
+	const commandLabel = buildCommandString(normalizedCommand, args);
+	if (options.signal?.aborted) {
+		return {
+			code: 1,
+			stdout: "",
+			stderr: "",
+			timedOut: false,
+			aborted: true,
+			errorMessage: `Command aborted before start: ${commandLabel}`,
+		};
+	}
+
+	return await new Promise<AbortableCommandResult>((resolve) => {
+		const child = spawn(normalizedCommand, [...args], {
+			env: options.env ?? process.env,
+			cwd: options.cwd,
+		});
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+		let aborted = false;
+		let spawnError: Error | null = null;
+		let forceKillTimer: NodeJS.Timeout | null = null;
+
+		const cleanup = (): void => {
+			if (timeoutTimer) {
+				clearTimeout(timeoutTimer);
+			}
+			if (forceKillTimer) {
+				clearTimeout(forceKillTimer);
+				forceKillTimer = null;
+			}
+			options.signal?.removeEventListener("abort", onAbort);
+		};
+
+		const scheduleForceKill = (): void => {
+			if (process.platform === "win32" || forceKillTimer) {
+				return;
+			}
+			forceKillTimer = setTimeout(() => {
+				stopChildProcess(child, true);
+			}, 750);
+		};
+
+		const onAbort = (): void => {
+			aborted = true;
+			stopChildProcess(child);
+			scheduleForceKill();
+		};
+
+		const timeoutMs = typeof options.timeoutMs === "number" ? Math.max(1, Math.floor(options.timeoutMs)) : 0;
+		const timeoutTimer =
+			timeoutMs > 0
+				? setTimeout(() => {
+					timedOut = true;
+					stopChildProcess(child);
+					scheduleForceKill();
+				}, timeoutMs)
+				: null;
+
+		options.signal?.addEventListener("abort", onAbort, { once: true });
+
+		child.stdout?.on("data", (chunk: Buffer | string) => {
+			stdout += chunk.toString();
+		});
+
+		child.stderr?.on("data", (chunk: Buffer | string) => {
+			stderr += chunk.toString();
+		});
+
+		child.on("error", (error) => {
+			spawnError = error;
+		});
+
+		child.on("close", (code) => {
+			cleanup();
+			resolve({
+				code: code ?? (spawnError || timedOut || aborted ? 1 : 0),
+				stdout,
+				stderr,
+				timedOut,
+				aborted,
+				errorMessage: spawnError
+					? stringifyError(spawnError)
+					: timedOut
+						? `Command timed out after ${timeoutMs}ms: ${commandLabel}`
+						: aborted
+							? `Command aborted: ${commandLabel}`
+							: undefined,
+			});
+		});
+	});
+}