5 files changed, 321 insertions, 0 deletions

diff --git a/packages/api/src/app.ts b/packages/api/src/app.ts
index 19cc193..0dabb0d 100644
--- a/packages/api/src/app.ts
+++ b/packages/api/src/app.ts
@@ -1,3 +1,4 @@
+import { getTab, NotificationDispatcher } from "@dispatch/core";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { AgentManager } from "./agent-manager.js";
@@ -5,12 +6,39 @@ import { PermissionManager } from "./permission-manager.js";
 import { agentsRoutes } from "./routes/agents.js";
 import { configRoutes } from "./routes/config.js";
 import { modelsRoutes, startWakeScheduler } from "./routes/models.js";
+import { notificationsRoutes } from "./routes/notifications.js";
 import { skillsRoutes } from "./routes/skills.js";
 import { tabsRoutes } from "./routes/tabs.js";
 
 export const permissionManager = new PermissionManager();
 export const agentManager = new AgentManager(permissionManager);
 
+// ntfy.sh push notifications. The dispatcher reads its config from the
+// `settings` table on every send, so config changes apply immediately —
+// no restart, no re-attach needed.
+export const notificationDispatcher = new NotificationDispatcher({
+	getTabTitle: (tabId) => {
+		try {
+			return getTab(tabId)?.title ?? null;
+		} catch {
+			return null;
+		}
+	},
+	getTabParentId: (tabId) => {
+		try {
+			// `undefined` when the lookup fails (tab not found / DB unavailable)
+			// so the dispatcher falls back to "treat as top-level" rather than
+			// silently dropping notifications.
+			const row = getTab(tabId);
+			return row ? row.parentTabId : undefined;
+		} catch {
+			return undefined;
+		}
+	},
+});
+notificationDispatcher.attachToAgentManager(agentManager);
+notificationDispatcher.attachToPermissionManager(permissionManager);
+
 export const app = new Hono();
 
 app.use(
@@ -112,6 +140,7 @@ app.route("/skills", skillsRoutes);
 app.route("/models", modelsRoutes);
 app.route("/tabs", tabsRoutes);
 app.route("/agents", agentsRoutes);
+app.route("/notifications", notificationsRoutes);
 
 // Start the wake scheduler on boot (restores persisted schedule)
 startWakeScheduler();
diff --git a/packages/api/src/permission-manager.ts b/packages/api/src/permission-manager.ts
index d98dc52..3a24d03 100644
--- a/packages/api/src/permission-manager.ts
+++ b/packages/api/src/permission-manager.ts
@@ -5,9 +5,25 @@ import {
 	type Ruleset,
 } from "@dispatch/core";
 
+/**
+ * Listener fired exactly once per newly-created pending prompt. Used by
+ * the notification dispatcher so that a permission request triggers a
+ * push notification on the user's phone (without re-firing every time
+ * the pending list mutates for an unrelated reason).
+ */
+export type PromptAddedListener = (prompt: {
+	id: string;
+	permission: string;
+	description: string;
+	metadata: Record<string, unknown>;
+}) => void;
+
 export class PermissionManager {
 	private service = new PermissionService();
 	private wsClients: Map<string, (data: unknown) => void> = new Map();
+	private promptAddedListeners: Set<PromptAddedListener> = new Set();
+	/** Ids that have already been broadcast as "added" — guards against re-emits. */
+	private announcedPromptIds: Set<string> = new Set();
 
 	registerClient(id: string, send: (data: unknown) => void): void {
 		this.wsClients.set(id, send);
@@ -25,6 +41,33 @@ export class PermissionManager {
 		for (const send of this.wsClients.values()) {
 			send(message);
 		}
+
+		// Detect newly-added prompts (ids present now that weren't before) and
+		// fire `promptAddedListeners` once for each. Resolved/rejected ids are
+		// pruned from `announcedPromptIds` so a future prompt that reuses an
+		// id (theoretical, given the monotonic counter) would still notify.
+		const currentIds = new Set(pending.map((p) => p.id));
+		for (const id of this.announcedPromptIds) {
+			if (!currentIds.has(id)) this.announcedPromptIds.delete(id);
+		}
+		for (const p of pending) {
+			if (this.announcedPromptIds.has(p.id)) continue;
+			this.announcedPromptIds.add(p.id);
+			for (const listener of this.promptAddedListeners) {
+				try {
+					listener({
+						id: p.id,
+						permission: p.request.permission,
+						description: p.request.description,
+						metadata: p.request.metadata,
+					});
+				} catch (err) {
+					console.warn(
+						`[permission] promptAdded listener threw: ${err instanceof Error ? err.message : String(err)}`,
+					);
+				}
+			}
+		}
 	}
 
 	async ask(request: PermissionRequest, rulesets: Ruleset[] = []): Promise<PermissionReply> {
@@ -45,4 +88,16 @@ export class PermissionManager {
 	getService(): PermissionService {
 		return this.service;
 	}
+
+	/**
+	 * Subscribe to "a new prompt is now pending" events. Fires once per
+	 * unique prompt id, even if `broadcastPending` is called repeatedly
+	 * for unrelated mutations. Returns an unsubscribe function.
+	 */
+	onPromptAdded(listener: PromptAddedListener): () => void {
+		this.promptAddedListeners.add(listener);
+		return () => {
+			this.promptAddedListeners.delete(listener);
+		};
+	}
 }
diff --git a/packages/api/src/routes/notifications.ts b/packages/api/src/routes/notifications.ts
new file mode 100644
index 0000000..473e837
--- /dev/null
+++ b/packages/api/src/routes/notifications.ts
@@ -0,0 +1,88 @@
+// `/notifications` — ntfy.sh config + test-send route.
+
+import {
+	defaultNtfyConfig,
+	loadNtfyConfig,
+	type NotificationEventType,
+	NTFY_EVENT_TYPES,
+	type NtfyConfig,
+	normalizeNtfyConfig,
+	redactNtfyConfig,
+	saveNtfyConfig,
+	sendNtfy,
+} from "@dispatch/core";
+import { Hono } from "hono";
+
+export const notificationsRoutes = new Hono();
+
+notificationsRoutes.get("/", (c) => {
+	const config = loadNtfyConfig();
+	return c.json({
+		config: redactNtfyConfig(config),
+		eventTypes: NTFY_EVENT_TYPES,
+		defaults: defaultNtfyConfig(),
+	});
+});
+
+notificationsRoutes.put("/", async (c) => {
+	const body = await c.req.json<Partial<NtfyConfig> & { authToken?: string }>();
+	const existing = loadNtfyConfig();
+
+	// `authToken === ""` ⇒ explicit clear; `authToken === undefined` ⇒ keep
+	// the existing token (the GET response redacts it, so the frontend doesn't
+	// have it to send back). Any other string ⇒ replace.
+	let nextAuthToken = existing.authToken;
+	if (typeof body.authToken === "string") nextAuthToken = body.authToken;
+
+	const merged = normalizeNtfyConfig({
+		enabled: typeof body.enabled === "boolean" ? body.enabled : existing.enabled,
+		topic: typeof body.topic === "string" ? body.topic : existing.topic,
+		authToken: nextAuthToken,
+		events: { ...existing.events, ...(body.events ?? {}) },
+		notifySubagents:
+			typeof body.notifySubagents === "boolean" ? body.notifySubagents : existing.notifySubagents,
+	});
+
+	// Only validation: if notifications are turned on, the topic must be
+	// non-empty. Any other "is this a valid ntfy topic name?" check is
+	// punted to the ntfy server itself — its rules vary and have changed
+	// over time, and a syntactically-valid name still might be rejected
+	// (e.g. reserved words), so a clear server error is more useful than
+	// a client-side guess.
+	if (merged.enabled && !merged.topic.trim()) {
+		return c.json({ error: "Topic is required" }, 400);
+	}
+
+	saveNtfyConfig(merged);
+	return c.json({ config: redactNtfyConfig(merged) });
+});
+
+notificationsRoutes.post("/test", async (c) => {
+	const config = loadNtfyConfig();
+	if (!config.enabled) {
+		return c.json({ ok: false, error: "Notifications are disabled" }, 400);
+	}
+	if (!config.topic.trim()) {
+		return c.json({ ok: false, error: "Topic is required" }, 400);
+	}
+
+	// Use a real event type so the per-event toggle is honored when wiring
+	// is tested end-to-end; pick `turn-completed` since it's the most
+	// common enabled-by-default event.
+	const eventType: NotificationEventType = "turn-completed";
+	if (!config.events[eventType]) {
+		return c.json(
+			{ ok: false, error: `Event type "${eventType}" is disabled — enable it to test.` },
+			400,
+		);
+	}
+
+	const result = await sendNtfy(config, {
+		type: eventType,
+		title: "Dispatch test notification",
+		message: "If you can see this, ntfy.sh notifications are wired up correctly.",
+		tags: ["bell"],
+	});
+	if (!result.ok) return c.json(result, 502);
+	return c.json(result);
+});
diff --git a/packages/api/tests/permission-manager.test.ts b/packages/api/tests/permission-manager.test.ts
new file mode 100644
index 0000000..172adb3
--- /dev/null
+++ b/packages/api/tests/permission-manager.test.ts
@@ -0,0 +1,99 @@
+import { describe, expect, it, vi } from "vitest";
+
+// Mock @dispatch/core to provide only the PermissionService impl this test
+// touches — the core barrel transitively pulls in bun:sqlite, which vitest
+// running under Node cannot resolve.
+vi.mock("@dispatch/core", async () => {
+	const mod = await import("../../core/src/permission/service.js");
+	return {
+		PermissionService: mod.PermissionService,
+	};
+});
+
+const { PermissionManager } = await import("../src/permission-manager.js");
+
+interface PermissionRequest {
+	permission: string;
+	patterns: string[];
+	always: string[];
+	description: string;
+	metadata: Record<string, unknown>;
+}
+
+function makeRequest(overrides: Partial<PermissionRequest> = {}): PermissionRequest {
+	return {
+		permission: "bash",
+		patterns: ["git *"],
+		always: ["git status"],
+		description: "Run git status",
+		metadata: {},
+		...overrides,
+	};
+}
+
+describe("PermissionManager.onPromptAdded", () => {
+	it("fires once per newly-added pending prompt", () => {
+		const mgr = new PermissionManager();
+		const seen: Array<{ id: string; permission: string }> = [];
+		mgr.onPromptAdded((p) => {
+			seen.push({ id: p.id, permission: p.permission });
+		});
+
+		void mgr.ask(makeRequest(), []);
+		void mgr.ask(makeRequest({ permission: "read", description: "Read X" }), []);
+
+		expect(seen).toHaveLength(2);
+		expect(seen[0].permission).toBe("bash");
+		expect(seen[1].permission).toBe("read");
+		// Distinct ids
+		expect(seen[0].id).not.toBe(seen[1].id);
+	});
+
+	it("does not re-fire when the pending list is rebroadcast for an unrelated change", async () => {
+		const mgr = new PermissionManager();
+		const seen: string[] = [];
+		mgr.onPromptAdded((p) => seen.push(p.id));
+
+		// Two prompts in; should see two notifications.
+		const p1 = mgr.ask(makeRequest(), []);
+		void mgr.ask(makeRequest({ permission: "read" }), []);
+		expect(seen).toHaveLength(2);
+
+		// Resolve the first one — broadcastPending fires again, but the
+		// remaining (already-announced) prompt must NOT re-notify.
+		const pending = mgr.getPending();
+		const firstId = pending[0].id;
+		mgr.reply(firstId, "once");
+		await p1;
+
+		expect(seen).toHaveLength(2);
+	});
+
+	it("unsubscribe stops further notifications", () => {
+		const mgr = new PermissionManager();
+		const seen: string[] = [];
+		const unsub = mgr.onPromptAdded((p) => seen.push(p.id));
+		void mgr.ask(makeRequest(), []);
+		unsub();
+		void mgr.ask(makeRequest({ permission: "read" }), []);
+		expect(seen).toHaveLength(1);
+	});
+
+	it("listener throws are caught and don't break other listeners", () => {
+		const mgr = new PermissionManager();
+		const seen: string[] = [];
+		mgr.onPromptAdded(() => {
+			throw new Error("boom");
+		});
+		mgr.onPromptAdded((p) => seen.push(p.id));
+		// Swallow the warn during this test.
+		const origWarn = console.warn;
+		console.warn = () => {};
+		try {
+			void mgr.ask(makeRequest(), []);
+		} finally {
+			console.warn = origWarn;
+		}
+		expect(seen).toHaveLength(1);
+	});
+});
diff --git a/packages/api/tests/routes.test.ts b/packages/api/tests/routes.test.ts
index f92b94c..c768cee 100644
--- a/packages/api/tests/routes.test.ts
+++ b/packages/api/tests/routes.test.ts
@@ -268,6 +268,56 @@ vi.mock("@dispatch/core", () => ({
 			execute: async () => "mock",
 		};
 	},
+	// ── ntfy notifications stubs ──────────────────────────────────
+	NotificationDispatcher: class MockNotificationDispatcher {
+		attachToAgentManager() {
+			return () => {};
+		}
+		attachToPermissionManager() {
+			return () => {};
+		}
+		notify() {}
+		dispose() {}
+	},
+	loadNtfyConfig() {
+		return {
+			enabled: false,
+			topic: "",
+			authToken: "",
+			events: {
+				"turn-completed": true,
+				"turn-error": true,
+				"permission-required": true,
+				"agent-spawned": false,
+			},
+			notifySubagents: false,
+		};
+	},
+	saveNtfyConfig() {},
+	normalizeNtfyConfig(c: unknown) {
+		return c;
+	},
+	defaultNtfyConfig() {
+		return {
+			enabled: false,
+			topic: "",
+			authToken: "",
+			events: {
+				"turn-completed": true,
+				"turn-error": true,
+				"permission-required": true,
+				"agent-spawned": false,
+			},
+			notifySubagents: false,
+		};
+	},
+	redactNtfyConfig(c: { authToken?: string }) {
+		return { ...c, authToken: "", hasAuthToken: false };
+	},
+	NTFY_EVENT_TYPES: ["turn-completed", "turn-error", "permission-required", "agent-spawned"],
+	async sendNtfy() {
+		return { ok: true };
+	},
 }));
 
 const { app } = await import("../src/app.js");