pi-smart-voice-notify 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-03
+
+### Added
+- Added an `enabled` master toggle to the config so the extension can be disabled without uninstalling. ([76cd96f](https://github.com/MasuRii/pi-smart-voice-notify/commit/76cd96fbbd6bd0658f00e8d7c043c44260f856bd))
+
+### Changed
+- Widened Pi coding-agent and Pi TUI peer dependency ranges to include `^0.80.0` and bumped development dependencies (`@types/node` to `26.1.0`, `@earendil-works/pi-coding-agent` to `^0.80.3`). ([146ff6e](https://github.com/MasuRii/pi-smart-voice-notify/commit/146ff6edf87de680958e61f0e1db34e6d337c729))
+- Extracted shared utilities and consolidated duplicated logic across config, notification, and platform modules. ([76cd96f](https://github.com/MasuRii/pi-smart-voice-notify/commit/76cd96fbbd6bd0658f00e8d7c043c44260f856bd))
+- Extracted shared test helpers and consolidated fixtures across the test suite. ([6cf3ed0](https://github.com/MasuRii/pi-smart-voice-notify/commit/6cf3ed0168c1460ffca3c447f4a7a55565f5cade))
+
+## [0.5.4] - 2026-06-22
+
+### Fixed
+- Added a command allowlist to `runAbortableCommand` so non-allowlisted executables are rejected before spawning, preventing arbitrary command injection ([2074e30](https://github.com/MasuRii/pi-smart-voice-notify/commit/2074e30)).
+- Replaced dynamic string-based command spawning in Linux helpers with a typed `LinuxCommandName` union and dedicated `spawnLinuxCommand` switch ([2074e30](https://github.com/MasuRii/pi-smart-voice-notify/commit/2074e30)).
+
+### Changed
+- Added `postinstall` hook that runs `patch-vulnerable-deps.mjs` when installed under `.pi/agent/extensions/` ([924e585](https://github.com/MasuRii/pi-smart-voice-notify/commit/924e585)).
+- Pinned `protobufjs` 7.6.3, `ws` 8.21.0, and `uuid` 11.1.1 via npm `overrides` to resolve known vulnerabilities ([924e585](https://github.com/MasuRii/pi-smart-voice-notify/commit/924e585)).
+- Added `@earendil-works/pi-coding-agent` as a devDependency for type-checking ([924e585](https://github.com/MasuRii/pi-smart-voice-notify/commit/924e585)).
+- Updated README badge styling to for-the-badge, added platform badge and ko-fi support button ([f66fff6](https://github.com/MasuRii/pi-smart-voice-notify/commit/f66fff6)).
+- Added `config-store-env-override` test to the test script ([924e585](https://github.com/MasuRii/pi-smart-voice-notify/commit/924e585)).
+
 ## [0.5.3] - 2026-06-16
 
 ### Fixed

package/README.md

@@ -1,13 +1,18 @@
-# 🔔 pi-smart-voice-notify
+<div align="center">
 
-[![npm version](https://img.shields.io/npm/v/pi-smart-voice-notify?style=flat-square)](https://www.npmjs.com/package/pi-smart-voice-notify) [![License](https://img.shields.io/github/license/MasuRii/pi-smart-voice-notify?style=flat-square)](LICENSE)
+# pi-smart-voice-notify
 
-Windows-optimized smart notification extension for the Pi coding agent.
+[![npm version](https://img.shields.io/npm/v/pi-smart-voice-notify?style=for-the-badge)](https://www.npmjs.com/package/pi-smart-voice-notify)
+[![License](https://img.shields.io/github/license/MasuRii/pi-smart-voice-notify?style=for-the-badge)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=for-the-badge)]()
 
-**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.
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/Y8Y01PSSVR)
 
+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.
 <img width="1360" height="752" alt="image" src="https://github.com/user-attachments/assets/c215a7fe-31b4-4bc4-a89e-992a4847819d" />
 
+</div>
 
 ## Features
 
@@ -99,6 +104,7 @@ Configuration is stored at:
 ```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
+Local config path: <repo>/.pi/extensions/pi-smart-voice-notify/config.json
 ```
 
 A starter template is provided in `config/config.example.json`. On startup, the extension creates `config.json` with defaults if missing.
@@ -302,4 +308,4 @@ npm run check      # build + test
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-smart-voice-notify",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Windows-optimized smart voice, sound, and desktop notifications for Pi coding agent.",
   "type": "module",
   "main": "./index.ts",
@@ -19,8 +19,9 @@
   "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 test/abortable-command.test.ts test/reminder-playback.test.ts test/permission-forwarding-watcher.test.ts test/sound-theme.test.ts test/webhook.test.ts test/linux.test.ts test/index.test.ts test/tts.test.ts",
-    "check": "npm run build && npm run test"
+    "test": "node --experimental-strip-types --test test/config-store.test.ts test/config-store-no-global.test.ts test/config-store-env-override.test.ts test/abortable-command.test.ts test/reminder-playback.test.ts test/permission-forwarding-watcher.test.ts test/sound-theme.test.ts test/webhook.test.ts test/linux.test.ts test/index.test.ts test/tts.test.ts",
+    "check": "npm run build && npm run test",
+    "postinstall": "node -e \"const fs=require('fs'),cp=require('child_process'),p=require('path');const cwd=process.cwd();const normalized=cwd.split(p.sep).join('/');if(!normalized.includes('/.pi/agent/extensions/'))process.exit(0);const s=p.resolve(cwd,'../../scripts/patch-vulnerable-deps.mjs');if(!fs.existsSync(s))process.exit(0);const r=cp.spawnSync(process.execPath,[s,'--target',cwd,'--quiet'],{stdio:'inherit'});process.exit(r.status||0)\""
   },
   "keywords": [
     "pi-package",
@@ -61,14 +62,20 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0",
-    "@earendil-works/pi-tui": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0"
+    "@earendil-works/pi-coding-agent": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0 || ^0.80.0",
+    "@earendil-works/pi-tui": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0 || ^0.80.0"
   },
   "dependencies": {
     "node-notifier": "^10.0.1",
     "undici": "^8.5.0"
   },
   "devDependencies": {
-    "@types/node": "25.9.3"
+    "@types/node": "26.1.0",
+    "@earendil-works/pi-coding-agent": "^0.80.3"
+  },
+  "overrides": {
+    "protobufjs": "7.6.3",
+    "ws": "8.21.0",
+    "uuid": "11.1.1"
   }
 }

package/src/abortable-command.ts

@@ -1,4 +1,33 @@
 import { spawn } from "node:child_process";
+import { basename } from "node:path";
+
+import { buildCommandString, attachChildHandlers } from "./shared/index.ts";
+
+const ALLOWED_ABORTABLE_COMMANDS = new Set([
+	"aplay",
+	"edge-tts",
+	"espeak-ng",
+	"ffplay",
+	"gdbus",
+	"paplay",
+	"powershell",
+	"powershell.exe",
+	"swaymsg",
+	"where",
+	"which",
+	"xdotool",
+	"xprop",
+]);
+
+function normalizeCommandName(command: string): string {
+	return basename(command).trim().toLowerCase();
+}
+
+function isAllowedAbortableCommand(command: string): boolean {
+	const normalized = normalizeCommandName(command);
+	const nodeExecutable = normalizeCommandName(process.execPath);
+	return normalized === nodeExecutable || ALLOWED_ABORTABLE_COMMANDS.has(normalized);
+}
 
 export interface AbortableCommandOptions {
 	timeoutMs?: number;
@@ -23,10 +52,6 @@ function stringifyError(error: unknown): string {
 	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;
@@ -38,8 +63,10 @@ function stopChildProcess(child: ReturnType<typeof spawn>, force = false): void
 			return;
 		}
 		child.kill(force ? "SIGKILL" : "SIGTERM");
-	} catch {
-		// noop
+	} catch (error) {
+		// Killing a process that has already exited can throw on some platforms;
+		// the error is non-actionable for shutdown/abort flows.
+		void error;
 	}
 }
 
@@ -55,6 +82,9 @@ export async function runAbortableCommand(
 	if (!Array.isArray(args)) {
 		throw new Error("runAbortableCommand: args must be an array of strings");
 	}
+	if (!isAllowedAbortableCommand(normalizedCommand)) {
+		throw new Error(`runAbortableCommand: command is not allowlisted: ${normalizedCommand}`);
+	}
 
 	const commandLabel = buildCommandString(normalizedCommand, args);
 	if (options.signal?.aborted) {
@@ -69,7 +99,7 @@ export async function runAbortableCommand(
 	}
 
 	return await new Promise<AbortableCommandResult>((resolve) => {
-		const child = spawn(normalizedCommand, [...args], {
+		const child = spawn(normalizedCommand, Array.from(args), { // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- normalizedCommand is checked against ALLOWED_ABORTABLE_COMMANDS (plus the current Node executable for tests) before spawn; args are passed as an array with shell disabled.
 			env: options.env ?? process.env,
 			cwd: options.cwd,
 		});
@@ -118,19 +148,9 @@ export async function runAbortableCommand(
 
 		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;
-		});
+		attachChildHandlers(child, (text: string) => { stdout += text; }, (text: string) => { stderr += text; }, (error: Error) => { spawnError = error; });
 
-		child.on("close", (code) => {
+		child.on("close", (code: number | null) => {
 			cleanup();
 			resolve({
 				code: code ?? (spawnError || timedOut || aborted ? 1 : 0),

package/src/ai-messages.ts

@@ -1,5 +1,7 @@
 import { normalizeFloat } from "./config-store.ts";
 import { getErrorMessage } from "./logging.ts";
+import { clampRoundedInt } from "./shared/index.ts";
+import type { FlatAIMessageConfig } from "./types.ts";
 
 export const AI_EVENT_TYPES = [
 	"idle",
@@ -24,20 +26,7 @@ export interface AIMessageContext {
 	variables?: Record<string, string | number | boolean | null | undefined>;
 }
 
-export interface AIMessageConfig {
-	enableAIMessages: boolean;
-	aiEndpoint: string;
-	aiModel: string;
-	aiApiKey: string;
-	aiTimeoutMs: number;
-	aiTemperature: number;
-	aiMaxTokens: number;
-	aiFallbackToTemplates: boolean;
-	personality: string;
-	tone: string;
-	enableMessageCache: boolean;
-	messageCacheTtlMs: number;
-	maxCacheEntries: number;
+export interface AIMessageConfig extends FlatAIMessageConfig {
 	templates: Partial<Record<CoreAIEventType, string[]>>;
 }
 
@@ -128,24 +117,17 @@ export const DEFAULT_AI_MESSAGE_CONFIG: AIMessageConfig = {
 	templates: {},
 };
 
-function normalizePositiveInt(value: number, fallback: number, min: number, max: number): number {
-	if (!Number.isFinite(value)) {
-		return fallback;
-	}
-	return Math.min(max, Math.max(min, Math.round(value)));
-}
-
-function normalizeConfig(overrides: Partial<AIMessageConfig> = {}): AIMessageConfig {
+function normalizeAIMessageConfig(overrides: Partial<AIMessageConfig> = {}): AIMessageConfig {
 	return {
 		...DEFAULT_AI_MESSAGE_CONFIG,
 		...overrides,
-		aiTimeoutMs: normalizePositiveInt(
+		aiTimeoutMs: clampRoundedInt(
 			overrides.aiTimeoutMs ?? DEFAULT_AI_MESSAGE_CONFIG.aiTimeoutMs,
 			DEFAULT_AI_MESSAGE_CONFIG.aiTimeoutMs,
 			1_000,
 			60_000,
 		),
-		aiMaxTokens: normalizePositiveInt(
+		aiMaxTokens: clampRoundedInt(
 			overrides.aiMaxTokens ?? DEFAULT_AI_MESSAGE_CONFIG.aiMaxTokens,
 			DEFAULT_AI_MESSAGE_CONFIG.aiMaxTokens,
 			40,
@@ -157,13 +139,13 @@ function normalizeConfig(overrides: Partial<AIMessageConfig> = {}): AIMessageCon
 			0,
 			2,
 		),
-		messageCacheTtlMs: normalizePositiveInt(
+		messageCacheTtlMs: clampRoundedInt(
 			overrides.messageCacheTtlMs ?? DEFAULT_AI_MESSAGE_CONFIG.messageCacheTtlMs,
 			DEFAULT_AI_MESSAGE_CONFIG.messageCacheTtlMs,
 			5_000,
 			600_000,
 		),
-		maxCacheEntries: normalizePositiveInt(
+		maxCacheEntries: clampRoundedInt(
 			overrides.maxCacheEntries ?? DEFAULT_AI_MESSAGE_CONFIG.maxCacheEntries,
 			DEFAULT_AI_MESSAGE_CONFIG.maxCacheEntries,
 			20,
@@ -304,15 +286,15 @@ export class AIMessageService {
 	private readonly debugLog: (message: string, details?: Record<string, unknown>) => void;
 
 	constructor(options: AIMessageServiceOptions = {}) {
-		this.config = normalizeConfig(options.config);
+		this.config = normalizeAIMessageConfig(options.config);
 		this.debugLog = options.debugLog ?? (() => {});
 	}
 
-	public updateConfig(overrides: Partial<AIMessageConfig>): void {
-		this.config = normalizeConfig({ ...this.config, ...overrides });
+	public updateAIMessageConfig(overrides: Partial<AIMessageConfig>): void {
+		this.config = normalizeAIMessageConfig({ ...this.config, ...overrides });
 	}
 
-	public getConfig(): AIMessageConfig {
+	public getAIMessageConfig(): AIMessageConfig {
 		return { ...this.config, templates: { ...this.config.templates } };
 	}
 
@@ -449,7 +431,8 @@ export class AIMessageService {
 		}
 
 		while (this.cache.size > this.config.maxCacheEntries) {
-			const oldestKey = this.cache.keys().next().value;
+			const next = this.cache.keys().next();
+			const oldestKey = typeof next.value === "string" ? next.value : undefined;
 			if (!oldestKey) {
 				break;
 			}

package/src/config-store.ts

@@ -2,6 +2,19 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 
 import { resolvePiAgentDir } from "./agent-dir.ts";
+import {
+	clampInt,
+	clampNumber,
+	normalizeFloat,
+	normalizeStringEnum,
+	normalizeStringEnumArray,
+	parseEnvBoolean,
+	readEnvFrom,
+	toRecord,
+	ENGINE_TTS_DEFAULTS,
+} from "./shared/index.ts";
+
+export { clampInt, clampNumber, normalizeFloat, toRecord };
 import type {
 	ConcreteTTSEngine,
 	MessageSet,
@@ -16,6 +29,11 @@ export const EXTENSION_ID = "pi-smart-voice-notify";
 export const STATUS_KEY = "smart-voice-notify";
 export const CONFIG_DIR = join(resolvePiAgentDir(), "extensions", EXTENSION_ID);
 export const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+
+/** Project-local override config: <projectRoot>/.pi/extensions/<id>/config.json (read-only). */
+export function resolveProjectConfigPath(projectRoot: string): string {
+	return join(projectRoot, ".pi", "extensions", EXTENSION_ID, "config.json");
+}
 export const DEBUG_DIR = join(CONFIG_DIR, "debug");
 export const DEBUG_LOG_PATH = join(DEBUG_DIR, `${EXTENSION_ID}.log`);
 
@@ -154,25 +172,7 @@ export const DEFAULT_CONFIG: VoiceNotifyConfig = {
 	sapiPitch: "medium",
 	sapiVolume: "loud",
 
-	edgeVoice: "en-US-JennyNeural",
-	edgeRate: "+10%",
-	edgePitch: "+0Hz",
-	edgeVolume: "+0%",
-	espeakVoice: "en",
-	espeakRate: 175,
-	espeakPitch: 50,
-	elevenLabsApiKey: "",
-	elevenLabsVoiceId: "cgSgspJ2msm6clMCkdW9",
-	elevenLabsModel: "eleven_turbo_v2_5",
-	elevenLabsStability: 0.5,
-	elevenLabsSimilarity: 0.75,
-	elevenLabsStyle: 0.5,
-	openaiTtsEndpoint: "",
-	openaiTtsApiKey: "",
-	openaiTtsModel: "tts-1",
-	openaiTtsVoice: "alloy",
-	openaiTtsFormat: "mp3",
-	openaiTtsSpeed: 1,
+	...ENGINE_TTS_DEFAULTS,
 
 	idleSoundFile: "assets/soft-notification.mp3",
 	permissionSoundFile: "assets/attention-alert.mp3",
@@ -256,71 +256,12 @@ export const DEFAULT_CONFIG: VoiceNotifyConfig = {
 	debugLog: false,
 };
 
-export function toRecord(value: unknown): Record<string, unknown> {
-	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		return {};
-	}
-	return value as Record<string, unknown>;
-}
-
 function readEnv(...keys: string[]): string {
-	for (const key of keys) {
-		const value = process.env[key];
-		if (typeof value === "string" && value.trim().length > 0) {
-			return value.trim();
-		}
-	}
-	return "";
+	return readEnvFrom(...keys);
 }
 
 function parseEnvBool(value: string): boolean | undefined {
-	if (!value) {
-		return undefined;
-	}
-	const normalized = value.trim().toLowerCase();
-	if (["1", "true", "yes", "on"].includes(normalized)) {
-		return true;
-	}
-	if (["0", "false", "no", "off"].includes(normalized)) {
-		return false;
-	}
-	return undefined;
-}
-
-function parseNumeric(value: unknown): number | undefined {
-	if (typeof value === "number" && Number.isFinite(value)) {
-		return value;
-	}
-	if (typeof value === "string" && value.trim().length > 0) {
-		const parsed = Number(value.trim());
-		if (Number.isFinite(parsed)) {
-			return parsed;
-		}
-	}
-	return undefined;
-}
-
-export function clampInt(value: unknown, fallback: number, min: number, max: number): number {
-	const numeric = parseNumeric(value);
-	if (numeric === undefined) {
-		return fallback;
-	}
-	return Math.min(max, Math.max(min, Math.trunc(numeric)));
-}
-
-export function clampNumber(value: unknown, fallback: number, min: number, max: number): number {
-	const numeric = parseNumeric(value);
-	if (numeric === undefined) {
-		return fallback;
-	}
-	return Math.min(max, Math.max(min, numeric));
-}
-
-export function normalizeFloat(value: number, fallback: number, min: number, max: number): number {
-	if (!Number.isFinite(value)) {
-		return fallback;
-	}
-	return Math.min(max, Math.max(min, value));
+	return parseEnvBoolean(value);
 }
 
 function boolOrDefault(value: unknown, fallback: boolean): boolean {
@@ -397,17 +338,11 @@ function normalizeStringArray(value: unknown): string[] {
 }
 
 function normalizeNotificationTypes(value: unknown, fallback: NotificationType[]): NotificationType[] {
-	const candidates = normalizeStringArray(value)
-		.map((entry) => entry.toLowerCase())
-		.filter((entry): entry is NotificationType => NOTIFICATION_TYPE_VALUES.includes(entry as NotificationType));
-	return candidates.length > 0 ? [...new Set(candidates)] : [...fallback];
+	return normalizeStringEnumArray(value, NOTIFICATION_TYPE_VALUES, fallback);
 }
 
 function normalizeFallbackChain(value: unknown, fallback: ConcreteTTSEngine[]): ConcreteTTSEngine[] {
-	const candidates = normalizeStringArray(value)
-		.map((entry) => entry.toLowerCase())
-		.filter((entry): entry is ConcreteTTSEngine => CONCRETE_TTS_ENGINE_VALUES.includes(entry as ConcreteTTSEngine));
-	return candidates.length > 0 ? [...new Set(candidates)] : [...fallback];
+	return normalizeStringEnumArray(value, CONCRETE_TTS_ENGINE_VALUES, fallback);
 }
 
 function normalizeTemplates(value: unknown): Partial<Record<string, string[]>> {
@@ -479,17 +414,11 @@ function isHttpUrl(url: string): boolean {
 }
 
 export function normalizeMode(value: unknown): NotificationMode {
-	if (typeof value === "string" && NOTIFICATION_MODES.includes(value as NotificationMode)) {
-		return value as NotificationMode;
-	}
-	return DEFAULT_CONFIG.notificationMode;
+	return normalizeStringEnum(value, NOTIFICATION_MODES, DEFAULT_CONFIG.notificationMode);
 }
 
 export function normalizeTtsEngine(value: unknown): TTSEngine {
-	if (typeof value === "string" && TTS_ENGINE_VALUES.includes(value as TTSEngine)) {
-		return value as TTSEngine;
-	}
-	return DEFAULT_CONFIG.ttsEngine;
+	return normalizeStringEnum(value, TTS_ENGINE_VALUES, DEFAULT_CONFIG.ttsEngine);
 }
 
 export function normalizeConfig(raw: unknown): VoiceNotifyConfig {
@@ -979,28 +908,74 @@ export function ensureDebugDirectory(): void {
 	}
 }
 
-export function readConfigFromDisk(): VoiceNotifyConfig {
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Deep-merge `override` onto `base`. Nested objects merge; arrays and scalars replace. */
+export function deepMergeConfigRecords(
+	base: Record<string, unknown>,
+	override: Record<string, unknown>,
+): Record<string, unknown> {
+	const result: Record<string, unknown> = { ...base };
+	for (const [key, value] of Object.entries(override)) {
+		const existing = result[key];
+		result[key] = isPlainObject(existing) && isPlainObject(value)
+			? deepMergeConfigRecords(existing, value)
+			: value;
+	}
+	return result;
+}
+
+function readConfigRecord(path: string): Record<string, unknown> | null {
+	if (!existsSync(path)) {
+		return null;
+	}
+	try {
+		return toRecord(JSON.parse(readFileSync(path, "utf-8")) as unknown);
+	} catch {
+		return null;
+	}
+}
+
+/** Load and self-heal the global config file, returning its raw record. */
+function loadGlobalConfigRecord(): Record<string, unknown> {
 	ensureConfigDirectory();
+	const defaultsSerialized = `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`;
 	if (!existsSync(CONFIG_PATH)) {
-		writeFileSync(CONFIG_PATH, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, "utf-8");
-		return applyEnvironmentOverrides({ ...DEFAULT_CONFIG, webhook: { ...DEFAULT_CONFIG.webhook, events: [...DEFAULT_CONFIG.webhook.events] } });
+		writeFileSync(CONFIG_PATH, defaultsSerialized, "utf-8");
+		return toRecord(JSON.parse(defaultsSerialized));
 	}
 
 	try {
 		const raw = readFileSync(CONFIG_PATH, "utf-8");
 		const parsed = JSON.parse(raw) as unknown;
-		const normalized = normalizeConfig(parsed);
-		const validation = validateConfig(normalized);
-		const serialized = `${JSON.stringify(validation.config, null, 2)}\n`;
+		const serialized = `${JSON.stringify(validateConfig(normalizeConfig(parsed)).config, null, 2)}\n`;
 		if (raw !== serialized) {
 			writeFileSync(CONFIG_PATH, serialized, "utf-8");
 		}
-		const runtimeConfig = applyEnvironmentOverrides(validation.config);
-		return validateConfig(runtimeConfig).config;
+		return toRecord(parsed);
 	} catch {
-		writeFileSync(CONFIG_PATH, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, "utf-8");
-		return applyEnvironmentOverrides({ ...DEFAULT_CONFIG, webhook: { ...DEFAULT_CONFIG.webhook, events: [...DEFAULT_CONFIG.webhook.events] } });
+		writeFileSync(CONFIG_PATH, defaultsSerialized, "utf-8");
+		return toRecord(JSON.parse(defaultsSerialized));
+	}
+}
+
+/**
+ * Read the effective config. When `projectRoot` is given and a project config
+ * exists, it deep-merges over the global config; environment variables still
+ * override both. The project file is read-only — only the global file is healed.
+ */
+export function readConfigFromDisk(projectRoot?: string): VoiceNotifyConfig {
+	let record = loadGlobalConfigRecord();
+	if (projectRoot) {
+		const projectRecord = readConfigRecord(resolveProjectConfigPath(projectRoot));
+		if (projectRecord) {
+			record = deepMergeConfigRecords(record, projectRecord);
+		}
 	}
+	const runtimeConfig = applyEnvironmentOverrides(validateConfig(normalizeConfig(record)).config);
+	return validateConfig(runtimeConfig).config;
 }
 
 export function writeConfigToDisk(config: VoiceNotifyConfig): void {