pi-smart-voice-notify 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.3.3] - 2026-04-22
+
+### Changed
+- Updated README and example config documentation to reflect `PI_CODING_AGENT_DIR`-aware global extension paths and `session_start` lifecycle reasons
+- Resolved extension config/debug paths and forwarded permission watcher paths from `getAgentDir()`
+- Updated `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` peer dependencies to ^0.68.1
+
+### Fixed
+- Prevented reminders, notification playback, and webhook queue flushing/retry waits from continuing after session shutdown
+
+## [0.3.2] - 2026-04-01
+
+### Changed
+- Added Related Pi Extensions cross-linking section to README
+- Aligned npm keywords for improved discoverability
+- Updated README with new image and expanded features documentation
+
 ## [0.3.1] - 2026-04-01
 
 ### Changed
@@ -72,7 +91,7 @@
 - Rewrote README.md with professional documentation standards
 - Added comprehensive feature documentation, configuration reference, and usage examples
 
-## 0.1.0
+## [0.1.0] - 2026-03-02
 
 - Standardized repository structure to `index.ts` shim + `src/` implementation.
 - Added config template and package metadata/scripts aligned with Pi extension conventions.

package/README.md

@@ -4,7 +4,8 @@ Windows-optimized smart notification extension for the Pi coding agent.
 
 **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](https://raw.githubusercontent.com/MasuRii/pi-smart-voice-notify/main/assets/pi-smart-voice-notify.png)
+<img width="1360" height="752" alt="image" src="https://github.com/user-attachments/assets/c215a7fe-31b4-4bc4-a89e-992a4847819d" />
+
 
 ## Features
 
@@ -51,7 +52,7 @@ Windows-optimized smart notification extension for the Pi coding agent.
 
 Place this folder in either location (Pi auto-discovers both):
 
-- **Global:** `~/.pi/agent/extensions/pi-smart-voice-notify`
+- **Global default:** `~/.pi/agent/extensions/pi-smart-voice-notify` (respects `PI_CODING_AGENT_DIR`)
 - **Project:** `.pi/extensions/pi-smart-voice-notify`
 
 ### As an npm Package
@@ -92,8 +93,9 @@ pi install git:github.com/MasuRii/pi-smart-voice-notify
 
 Configuration is stored at:
 
-```
-~/.pi/agent/extensions/pi-smart-voice-notify/config.json
+```text
+Default global path: ~/.pi/agent/extensions/pi-smart-voice-notify/config.json
+Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-smart-voice-notify/config.json when PI_CODING_AGENT_DIR is set
 ```
 
 A starter template is provided in `config/config.example.json`. On startup, the extension creates `config.json` with defaults if missing.
@@ -124,7 +126,7 @@ A starter template is provided in `config/config.example.json`. On startup, the
 | `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 |
+| `watchLegacyForwardedPermissionPath` | boolean | `true` | Also watch the legacy forwarded-permission directory (default: `~/.pi/agent/permission-forwarding/requests`, respects `PI_CODING_AGENT_DIR`) 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 |
@@ -252,8 +254,7 @@ src/
 
 | Event | Behavior |
 |-------|----------|
-| `session_start` | Load config, reset state, update status bar |
-| `session_switch` | Reset state, refresh question tool availability |
+| `session_start` | Load config, reset state, update status bar. Handles all session lifecycle transitions via `reason` (`startup`, `reload`, `new`, `resume`, `fork`). |
 | `session_shutdown` | Cancel reminders, clear status |
 | `input` | Track user activity, cancel pending reminders |
 | `agent_start` | Reset error tracking |
@@ -266,7 +267,7 @@ src/
 When `debugLog: true`, JSONL events are written to:
 
 ```
-~/.pi/agent/extensions/pi-smart-voice-notify/debug/pi-smart-voice-notify.log
+Default global debug log path: ~/.pi/agent/extensions/pi-smart-voice-notify/debug/pi-smart-voice-notify.log (respects PI_CODING_AGENT_DIR)
 ```
 
 Events include: config changes, notifications triggered, audio dispatch, reminders, and errors.
@@ -283,6 +284,13 @@ npm run check      # build + test
 
 **Requirements:** Node.js ≥ 24
 
+## Related Pi Extensions
+
+- [pi-tool-display](https://github.com/MasuRii/pi-tool-display) — Compact tool rendering and diff visualization
+- [pi-permission-system](https://github.com/MasuRii/pi-permission-system) — Permission enforcement for tool and command access
+- [pi-MUST-have-extension](https://github.com/MasuRii/pi-MUST-have-extension) — RFC 2119 keyword normalization for prompts
+- [pi-startup-redraw-fix](https://github.com/MasuRii/pi-startup-redraw-fix) — Fix terminal redraw glitches on startup
+
 ## License
 
 MIT

package/config/config.example.json

@@ -1,5 +1,5 @@
 {
-  "_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_0": "pi-smart-voice-notify example config. Copy this file to the global Pi extension config path (default: ~/.pi/agent/extensions/pi-smart-voice-notify/config.json; respects PI_CODING_AGENT_DIR) 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,

package/package.json

@@ -1,61 +1,70 @@
-{
-  "name": "pi-smart-voice-notify",
-  "version": "0.3.1",
-  "description": "Windows-optimized smart voice, sound, and desktop notifications for Pi coding agent.",
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
-  "files": [
-    "index.ts",
-    "src",
-    "config/config.example.json",
-    "assets",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "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 --experimental-strip-types --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",
-    "pi",
-    "pi-extension",
-    "voice-notify",
-    "windows",
-    "desktop-notification"
-  ],
-  "author": "MasuRii",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MasuRii/pi-smart-voice-notify.git"
-  },
-  "homepage": "https://github.com/MasuRii/pi-smart-voice-notify#readme",
-  "bugs": {
-    "url": "https://github.com/MasuRii/pi-smart-voice-notify/issues"
-  },
-  "engines": {
-    "node": ">=24"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.64.0",
-    "@mariozechner/pi-tui": "^0.64.0"
-  },
-  "dependencies": {
-    "node-notifier": "^10.0.1"
-  }
-}
+{
+  "name": "pi-smart-voice-notify",
+  "version": "0.3.3",
+  "description": "Windows-optimized smart voice, sound, and desktop notifications for Pi coding agent.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config/config.example.json",
+    "assets",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "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 --experimental-strip-types --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",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "coding-agent",
+    "voice-notify",
+    "desktop-notification",
+    "notifications",
+    "voice",
+    "audio",
+    "text-to-speech",
+    "tts",
+    "windows",
+    "linux",
+    "macos"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-smart-voice-notify.git"
+  },
+  "homepage": "https://github.com/MasuRii/pi-smart-voice-notify#readme",
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-smart-voice-notify/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.68.1",
+    "@mariozechner/pi-tui": "^0.68.1"
+  },
+  "dependencies": {
+    "node-notifier": "^10.0.1"
+  }
+}

package/src/config-store.ts

@@ -1,5 +1,5 @@
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 
 import type {
@@ -14,7 +14,7 @@ import type {
 
 export const EXTENSION_ID = "pi-smart-voice-notify";
 export const STATUS_KEY = "smart-voice-notify";
-export const CONFIG_DIR = join(homedir(), ".pi", "agent", "extensions", EXTENSION_ID);
+export const CONFIG_DIR = join(getAgentDir(), "extensions", EXTENSION_ID);
 export const CONFIG_PATH = join(CONFIG_DIR, "config.json");
 export const DEBUG_DIR = join(CONFIG_DIR, "debug");
 export const DEBUG_LOG_PATH = join(DEBUG_DIR, `${EXTENSION_ID}.log`);

package/src/index.ts

@@ -51,11 +51,40 @@ import type { TTSConfig, TTSService } from "./types/tts.ts";
 import { createWebhookService, type WebhookConfig } from "./webhook.ts";
 import { ZellijModal, ZellijSettingsModal } from "./zellij-modal.ts";
 
+type SessionStartReason = "startup" | "reload" | "new" | "resume" | "fork";
+
 function pickRandom<T>(items: readonly T[]): T {
 	const index = Math.floor(Math.random() * items.length);
 	return items[index] ?? items[0];
 }
 
+function getSessionStartReason(event: object): SessionStartReason | undefined {
+	if (!("reason" in event)) {
+		return undefined;
+	}
+
+	const { reason } = event;
+	if (
+		reason === "startup"
+		|| reason === "reload"
+		|| reason === "new"
+		|| reason === "resume"
+		|| reason === "fork"
+	) {
+		return reason;
+	}
+
+	return undefined;
+}
+
+function getPreviousSessionFile(event: object): string | undefined {
+	if (!("previousSessionFile" in event) || typeof event.previousSessionFile !== "string") {
+		return undefined;
+	}
+
+	return event.previousSessionFile;
+}
+
 function extractTextContent(content: unknown): string {
 	if (!Array.isArray(content)) {
 		return "";
@@ -327,6 +356,8 @@ export default function smartVoiceNotifyExtension(
 	let audioQueue: Promise<void> = Promise.resolve();
 	let questionToolAvailable = false;
 	let activeSessionContext: ExtensionContext | null = null;
+	let shutdownRequested = false;
+	let shutdownPromise: Promise<void> | null = null;
 
 	const pendingReminders = new Map<ReminderKey, ReminderState>();
 	const reminderPlayback = new ReminderPlaybackController();
@@ -968,7 +999,13 @@ export default function smartVoiceNotifyExtension(
 		delaySeconds: number,
 		followUpCount: number,
 	): void => {
-		if (!config.enabled || !config.reminderEnabled || !config.enableTts || config.notificationMode === "sound-only") {
+		if (
+			shutdownRequested
+			|| !config.enabled
+			|| !config.reminderEnabled
+			|| !config.enableTts
+			|| config.notificationMode === "sound-only"
+		) {
 			return;
 		}
 
@@ -984,6 +1021,15 @@ export default function smartVoiceNotifyExtension(
 					if (!current || current.scheduledAt !== scheduledAt) {
 						return;
 					}
+					if (shutdownRequested) {
+						pendingReminders.delete(reminderKey);
+						logger.debug("reminder.skipped_shutdown", {
+							reminderKey,
+							type,
+							followUpCount,
+						});
+						return;
+					}
 
 					if (!reminderPlayback.isCurrent(reminderCheckpoint, scheduledAt, lastUserActivityAt)) {
 						pendingReminders.delete(reminderKey);
@@ -1106,9 +1152,17 @@ export default function smartVoiceNotifyExtension(
 			scheduleReminder?: boolean;
 		} = {},
 	): void => {
+		if (shutdownRequested) {
+			logger.debug("notification.skipped_shutdown", {
+				type,
+				reason: options.reason,
+			});
+			return;
+		}
+
 		queueTask(
 			(async () => {
-				if (!config.enabled || !isNotificationEnabled(config, type)) {
+				if (shutdownRequested || !config.enabled || !isNotificationEnabled(config, type)) {
 					return;
 				}
 				if (!options.bypassThrottle && shouldThrottle(type)) {
@@ -1151,6 +1205,14 @@ export default function smartVoiceNotifyExtension(
 				});
 
 				enqueueAudio(async () => {
+					if (shutdownRequested) {
+						logger.debug("notification.playback_skipped", {
+							type,
+							reason: "session_shutdown",
+						});
+						return;
+					}
+
 					const mode = config.notificationMode;
 					const shouldPlaySoundNow =
 						config.enableSound && (mode === "sound-first" || mode === "both" || mode === "sound-only");
@@ -1164,6 +1226,10 @@ export default function smartVoiceNotifyExtension(
 						logger.debug("wake.monitor.error", { error: getErrorMessage(error) });
 					}
 
+					if (shutdownRequested) {
+						return;
+					}
+
 					let soundPlayed = false;
 					if (shouldPlaySoundNow) {
 						soundPlayed = await playNotificationSound(type);
@@ -1172,8 +1238,16 @@ export default function smartVoiceNotifyExtension(
 						}
 					}
 
+					if (shutdownRequested) {
+						return;
+					}
+
 					await dispatchDesktop(type, displayMessage, ctx);
 
+					if (shutdownRequested) {
+						return;
+					}
+
 					if (shouldSpeakNow) {
 						const spoken = await speakNotification(spokenMessage);
 						if (!spoken && !shouldPlaySoundNow && config.enableSound) {
@@ -1181,9 +1255,11 @@ export default function smartVoiceNotifyExtension(
 						}
 					}
 
-					dispatchWebhook(type, spokenMessage);
+					if (!shutdownRequested) {
+						dispatchWebhook(type, spokenMessage);
+					}
 				});
-				if (options.scheduleReminder !== false) {
+				if (!shutdownRequested && options.scheduleReminder !== false) {
 					scheduleReminder(options.reminderKey ?? defaultReminderKey(type), type, getReminderDelaySeconds(type), 0);
 				}
 			})(),
@@ -1580,66 +1656,104 @@ export default function smartVoiceNotifyExtension(
 		},
 	});
 
-	pi.on("session_start", async (_event, ctx) => {
-		activeSessionContext = ctx;
+	pi.on("resources_discover", (event, _ctx) => {
+		if (event.reason === "reload") {
+			// Clear caches on reload
+			clearFocusDetectCache();
+			clearProjectSoundCache();
+			aiMessageService.clearCache();
+		}
+	});
+
+	pi.on("session_start", async (event, ctx) => {
+		const reason = getSessionStartReason(event);
+		const previousSessionFile = getPreviousSessionFile(event);
+
+		shutdownRequested = false;
+		shutdownPromise = null;
 		config = readConfig();
 		refreshIntegratedServiceConfig();
+		activeSessionContext = ctx;
 		syncPermissionForwardingWatcher();
 		refreshQuestionToolAvailability();
 		clearFocusDetectCache();
 		clearProjectSoundCache();
+
+		// Clear AI message cache on reload to pick up config changes
+		if (reason === "reload") {
+			aiMessageService.clearCache();
+		}
 		lastUserActivityAt = Date.now();
 		hadErrorInTurn = false;
-		warnedNonWindows = false;
 		warnedDesktopUnsupported = false;
 		pendingPermissionToolCallIds.clear();
 		blockedPermissionToolCallIds.clear();
 		processedToolResultToolCallIds.clear();
 		lastNotificationAt.clear();
+
+		if (reason === "new" || reason === "resume" || reason === "fork") {
+			resetPermissionBatch(`session_start:${reason}`);
+			cancelReminderActivity(`session_start:${reason}`);
+			updateStatus(ctx);
+			logger.debug("session.start", {
+				reason,
+				previousSessionFile,
+				configPath: CONFIG_PATH,
+				debugLogPath: DEBUG_LOG_PATH,
+				notificationMode: config.notificationMode,
+			});
+			return;
+		}
+
+		warnedNonWindows = false;
 		resetPermissionBatch("session_start");
 		cancelReminderActivity("session_start");
 		updateStatus(ctx);
 		logger.debug("session.start", {
+			reason: reason ?? "startup",
+			previousSessionFile,
 			configPath: CONFIG_PATH,
 			debugLogPath: DEBUG_LOG_PATH,
 			notificationMode: config.notificationMode,
 		});
 	});
 
-	pi.on("session_switch", async (_event, ctx) => {
-		activeSessionContext = ctx;
-		syncPermissionForwardingWatcher();
-		refreshQuestionToolAvailability();
-		clearFocusDetectCache();
-		clearProjectSoundCache();
-		lastUserActivityAt = Date.now();
-		hadErrorInTurn = false;
-		warnedDesktopUnsupported = false;
-		pendingPermissionToolCallIds.clear();
-		blockedPermissionToolCallIds.clear();
-		processedToolResultToolCallIds.clear();
-		lastNotificationAt.clear();
-		resetPermissionBatch("session_switch");
-		cancelReminderActivity("session_switch");
-		updateStatus(ctx);
-		logger.debug("session.switch", {});
-	});
-
 	pi.on("session_shutdown", async (_event, ctx) => {
-		logger.debug("session.shutdown", {});
-		activeSessionContext = null;
-		permissionForwardingWatcher.stop();
-		pendingPermissionToolCallIds.clear();
-		blockedPermissionToolCallIds.clear();
-		processedToolResultToolCallIds.clear();
-		resetPermissionBatch("session_shutdown");
-		cancelReminderActivity("session_shutdown");
-		clearFocusDetectCache();
-		clearProjectSoundCache();
-		await webhookService.flush();
-		if (ctx.hasUI) {
-			ctx.ui.setStatus(STATUS_KEY, undefined);
+		shutdownRequested = true;
+		if (shutdownPromise) {
+			await shutdownPromise;
+			return;
 		}
+
+		shutdownPromise = (async () => {
+			logger.debug("session.shutdown", {});
+			activeSessionContext = null;
+			permissionForwardingWatcher.stop();
+			pendingPermissionToolCallIds.clear();
+			blockedPermissionToolCallIds.clear();
+			processedToolResultToolCallIds.clear();
+			resetPermissionBatch("session_shutdown");
+			cancelReminderActivity("session_shutdown");
+			clearFocusDetectCache();
+			clearProjectSoundCache();
+			try {
+				// Forward abort signal to flush if available (added in pi-coding-agent 0.67.x)
+				const abortSignal = 'signal' in ctx ? (ctx as { signal?: AbortSignal }).signal : undefined;
+				await webhookService.flush(abortSignal);
+			} catch (error) {
+				const message = `Failed to flush webhook queue during shutdown: ${getErrorMessage(error)}`;
+				logger.error(new Error(message));
+				if (ctx.hasUI) {
+					ctx.ui.notify(message, "warning");
+				}
+			} finally {
+				if (ctx.hasUI) {
+					ctx.ui.setStatus(STATUS_KEY, undefined);
+				}
+			}
+		})();
+
+		await shutdownPromise;
 	});
 
 	pi.on("input", async (event) => {

package/src/permission-forwarding-watcher.ts

@@ -1,5 +1,5 @@
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
 import { existsSync, readdirSync, readFileSync, watch, type FSWatcher } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import { getErrorMessage } from "./logging.ts";
@@ -8,8 +8,9 @@ import { toRecord } from "./config-store.ts";
 export type PermissionForwardingSource = "primary" | "legacy";
 export type ForwardedPermissionResolutionReason = "request_removed" | "watch_disabled" | "watcher_stopped";
 
-const PRIMARY_REQUESTS_DIR = join(homedir(), ".pi", "agent", "sessions", "permission-forwarding", "requests");
-const LEGACY_REQUESTS_DIR = join(homedir(), ".pi", "agent", "permission-forwarding", "requests");
+const AGENT_DIR = getAgentDir();
+const PRIMARY_REQUESTS_DIR = join(AGENT_DIR, "sessions", "permission-forwarding", "requests");
+const LEGACY_REQUESTS_DIR = join(AGENT_DIR, "permission-forwarding", "requests");
 const SCAN_INTERVAL_MS = 1_500;
 
 interface WatchDirectoryEntry {

package/src/webhook.ts

@@ -128,6 +128,30 @@ function delay(ms: number): Promise<void> {
 	});
 }
 
+/**
+ * Sleep with abort signal support.
+ */
+function delayWithAbort(ms: number, signal?: AbortSignal): Promise<void> {
+	return new Promise<void>((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new Error("Wait was aborted."));
+			return;
+		}
+
+		const handle = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+
+		const onAbort = () => {
+			clearTimeout(handle);
+			reject(new Error("Wait was aborted."));
+		};
+
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
 function parseBoolean(value: string | undefined): boolean | undefined {
 	if (!value) {
 		return undefined;
@@ -481,8 +505,8 @@ export class WebhookService {
 		return { queued, skipped: queued === 0 };
 	}
 
-	public async flush(): Promise<void> {
-		await this.processQueue();
+	public async flush(signal?: AbortSignal): Promise<void> {
+		await this.processQueue(signal);
 	}
 
 	public getQueueSize(): number {
@@ -520,13 +544,13 @@ export class WebhookService {
 		return `${target.provider}:${target.url}`;
 	}
 
-	private async waitForRateLimit(target: ResolvedWebhookTarget): Promise<void> {
+	private async waitForRateLimit(target: ResolvedWebhookTarget, signal?: AbortSignal): Promise<void> {
 		const key = this.targetKey(target);
 		const state = this.rateLimitState.get(key) ?? { lastSentAt: 0, nextAllowedAt: 0 };
 		const waitUntil = Math.max(state.nextAllowedAt, state.lastSentAt + this.config.minIntervalMs);
 		const now = Date.now();
 		if (waitUntil > now) {
-			await delay(waitUntil - now);
+			await delayWithAbort(waitUntil - now, signal);
 		}
 	}
 
@@ -548,32 +572,45 @@ export class WebhookService {
 		this.config.logger(message, details);
 	}
 
-	private async processQueue(): Promise<void> {
+	private async processQueue(signal?: AbortSignal): Promise<void> {
 		if (this.processingQueue) {
 			return;
 		}
 		this.processingQueue = true;
 		try {
 			while (this.queue.length > 0) {
+				if (signal?.aborted) {
+					// Clear queue on abort to avoid stale items
+					this.queue.length = 0;
+					return;
+				}
 				const item = this.queue.shift();
 				if (!item) {
 					continue;
 				}
-				await this.sendWithRetry(item);
+				await this.sendWithRetry(item, signal);
 			}
 		} finally {
 			this.processingQueue = false;
 		}
 	}
 
-	private async sendWithRetry(item: QueueItem): Promise<void> {
+	private async sendWithRetry(item: QueueItem, signal?: AbortSignal): Promise<void> {
 		for (let attempt = 0; attempt <= this.config.maxRetries; attempt += 1) {
-			await this.waitForRateLimit(item.target);
-			const result = await this.sendOnce(item.target, item.event);
+			if (signal?.aborted) {
+				return;
+			}
+			await this.waitForRateLimit(item.target, signal);
+			const result = await this.sendOnce(item.target, item.event, signal);
 			if (result.success) {
 				return;
 			}
 
+			// Don't retry on abort
+			if (signal?.aborted) {
+				return;
+			}
+
 			const targetLabel = maskWebhookUrl(item.target.url);
 			const shouldRetryCurrentAttempt = attempt < this.config.maxRetries && shouldRetry(result.statusCode);
 			if (!shouldRetryCurrentAttempt) {
@@ -597,22 +634,32 @@ export class WebhookService {
 				delayMs: retryDelay,
 				statusCode: result.statusCode,
 			});
-			await delay(retryDelay);
+			await delayWithAbort(retryDelay, signal);
 		}
 	}
 
-	private async sendOnce(target: ResolvedWebhookTarget, event: WebhookEvent): Promise<SendAttemptResult> {
+	private async sendOnce(target: ResolvedWebhookTarget, event: WebhookEvent, externalSignal?: AbortSignal): Promise<SendAttemptResult> {
 		this.markRequest(target);
 		const payload =
 			target.provider === "discord"
 				? buildDiscordPayload(target, event, this.config)
 				: buildGenericPayload(event);
 
+		// Check if already aborted before starting
+		if (externalSignal?.aborted) {
+			return { success: false, error: "Request aborted" };
+		}
+
+		// Create a combined abort controller that respects both timeout and external signal
 		const controller = new AbortController();
 		const timeout = setTimeout(() => {
 			controller.abort();
 		}, this.config.requestTimeoutMs);
 
+		// Wire external signal to abort
+		const onExternalAbort = () => controller.abort();
+		externalSignal?.addEventListener("abort", onExternalAbort, { once: true });
+
 		const headers: HeadersInit = {
 			"Content-Type": "application/json",
 			...target.headers,
@@ -647,6 +694,10 @@ export class WebhookService {
 				error: `HTTP ${response.status}`,
 			};
 		} catch (error) {
+			// Check if this was an external abort
+			if (externalSignal?.aborted) {
+				return { success: false, error: "Request aborted" };
+			}
 			const message = getErrorMessage(error);
 			return {
 				success: false,
@@ -654,6 +705,7 @@ export class WebhookService {
 			};
 		} finally {
 			clearTimeout(timeout);
+			externalSignal?.removeEventListener("abort", onExternalAbort);
 		}
 	}
 }