@goodandready/dsh-plugin-notify 0.3.8 → 0.4.1

package/lib/index.js

@@ -1,27 +1,30 @@
 import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
 import Schema from '@deepseek-ai/schemastery';
 import { credentialRef } from '@deepseek-ai/dsh-credentials';
 
 export const name = '@goodandready/dsh-plugin-notify';
 /** Settings namespace shared with the Web settings card. */
 export const NS = '@goodandready/dsh-plugin-notify';
+/** Canonical entry id matching cordis.patch.yml */
+export const ENTRY_ID = 'plugin-notify';
 
 // Session firehose + credentials (webhook URL refs) + settings scope for the card + webServer for SSE events + connection for authentication.
 export const inject = ['sessions', 'credentials', 'settings', 'webServer', 'connection'];
 
 const webhookRef = (label) => Schema.string()
     .role('credential-ref')
-    .description(`${label}: DSH credential name whose value is the full webhook URL (not the URL itself). Empty disables the channel.`);
-
-// Unwrap Volatile boxes before any caller reads a value. A volatile field holds a box
-// rather than its value, and the Loader mutates those boxes in place.
-export function plainConfig(value) {
-  if (value === null || typeof value !== 'object') return value
-  if (Array.isArray(value)) return value.map(plainConfig)
-  if (typeof value.get === 'function') return plainConfig(value.get())
-  return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, plainConfig(v)]))
-}
+    .volatile()
+    .description(`${label}: DSH credential name whose value is the full webhook URL (not the URL itself). Empty disables the channel.`)
 
+// Everything the settings card writes is marked volatile so dsh 0.2 accepts
+// live edits through the settings controller (0.1 ignores the flag). Only
+// leaves may be volatile: cordis 0.2 rejects volatile fields under a
+// volatile enclosing object.
 export const Config = Schema.object({
     webhooks: Schema.object({
         feishu: webhookRef('Feishu custom bot'),
@@ -31,23 +34,35 @@ export const Config = Schema.object({
         discord: webhookRef('Discord webhook'),
         custom: webhookRef('Custom generic webhook (POST JSON)'),
     }).description('Per-channel credential refs for webhook URLs; leave empty to disable'),
-    events: Schema.array(Schema.string()).volatile()
+    events: Schema.array(Schema.string())
+        .volatile()
         .description('Events that trigger notifications: task_done / error / approval_requested'),
-    local: Schema.boolean().volatile().default(true).description('Also emit a local system notification (macOS osascript)'),
-    enableSound: Schema.boolean().volatile().default(false).description('Play synthesized audio chime on completion, error, or approval'),
-    enableToasts: Schema.boolean().volatile().default(false).description('Show in-app on-screen toast notifications across sessions'),
-    enableDesktopNotifications: Schema.boolean().volatile().default(false).description('Show native desktop/OS push notifications (Windows, macOS, Linux)'),
-    notifyBackgroundOnly: Schema.boolean().volatile().default(false).description('Notify only if the event occurred in a background/inactive session'),
-    timeoutMs: Schema.number().volatile().default(5000).description('Per-webhook request timeout (ms)'),
+    local: Schema.boolean().default(true).volatile().description('Also emit a local system notification (macOS osascript)'),
+    enableSound: Schema.boolean().default(false).volatile().description('Play synthesized audio chime on completion, error, or approval'),
+    enableToasts: Schema.boolean().default(false).volatile().description('Show in-app on-screen toast notifications across sessions'),
+    enableDesktopNotifications: Schema.boolean().default(false).volatile().description('Show native desktop/OS push notifications (Windows, macOS, Linux)'),
+    notifyBackgroundOnly: Schema.boolean().default(false).volatile().description('Notify only if the event occurred in a background/inactive session'),
+    timeoutMs: Schema.number().default(5000).volatile().description('Per-webhook request timeout (ms)'),
     dnd: Schema.object({
-        start: Schema.string().default('').description('Do-not-disturb start (HH:MM, empty disables)'),
-        end: Schema.string().default('').description('Do-not-disturb end (HH:MM, cross-midnight ok)'),
+        start: Schema.string().default('').volatile().description('Do-not-disturb start (HH:MM, empty disables)'),
+        end: Schema.string().default('').volatile().description('Do-not-disturb end (HH:MM, cross-midnight ok)'),
     }).description('DND window: events are logged but no local/webhook emission'),
-    includeSession: Schema.boolean().volatile().default(true).description('Include the session line in notification text'),
-    includeDuration: Schema.boolean().volatile().default(true).description('Include the duration line in notification text'),
-    excludeSessionPrefixes: Schema.array(Schema.string()).volatile()
+    includeSession: Schema.boolean().default(true).volatile().description('Include the session line in notification text'),
+    includeDuration: Schema.boolean().default(true).volatile().description('Include the duration line in notification text'),
+    excludeSessionPrefixes: Schema.array(Schema.string())
         .default([])
+        .volatile()
         .description('Skip notifications when session id starts with any prefix (e.g. msgw- for messenger-gateway)'),
+    webPush: Schema.object({
+        enabled: Schema.boolean().default(false).volatile()
+            .description('Web Push (PWA) channel: send service-worker push notifications that reach devices with every dsh tab closed'),
+        onlyWhenAway: Schema.boolean().default(true).volatile()
+            .description('Skip web push while a browser client is connected to the SSE stream'),
+        subject: Schema.string().default('mailto:notify@localhost').volatile()
+            .description('VAPID subject (mailto: or https: contact URL) advertised to push services'),
+        stateFile: Schema.string().default('').volatile()
+            .description('State file for VAPID keys and push subscriptions (default: $DSH_HOME/plugin-notify-state.json)'),
+    }).description('Web Push (PWA) channel configuration'),
 });
 
 function isExcludedSession(sessionId, prefixes) {
@@ -59,6 +74,17 @@ function isExcludedSession(sessionId, prefixes) {
     return false;
 }
 
+// Unwrap Volatile boxes before any caller reads a value. A volatile field holds a box
+// rather than its value, and the Loader mutates those boxes in place.
+export function plainConfig(value) {
+  if (value === null || typeof value !== 'object') return value
+  if (Array.isArray(value)) return value.map(plainConfig)
+  if (typeof value.get === 'function') return plainConfig(value.get())
+  return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, plainConfig(v)]))
+}
+
+export const unwrapConfig = plainConfig
+
 const DEFAULT_EVENTS = ['task_done', 'error', 'approval_requested'];
 /** Per-session last `turn/start` epoch ms, for turn-duration reporting. */
 export const turnStarts = new Map();
@@ -252,13 +278,416 @@ export function closeAllSseClients() {
     sseClients.clear();
 }
 
-function mountWebServer(targetCtx, hostCtx) {
+// ---------------------------------------------------------------------------
+// Web Push (PWA) channel: VAPID keys + subscription state, push routes, sender.
+// Reaches devices with every dsh tab closed — the SSE/local channels cannot.
+// ---------------------------------------------------------------------------
+
+/** Service worker served at GET /dsh-plugin-notify/sw.js (no secrets inside). */
+export const SW_SOURCE = [
+    'self.addEventListener("push", (event) => {',
+    '  let data = {};',
+    '  try { data = event.data ? event.data.json() : {}; } catch (_) { data = {}; }',
+    '  const title = data.title || "DeepSeek Harness";',
+    '  event.waitUntil(self.registration.showNotification(title, {',
+    '    body: data.body || "",',
+    '    tag: data.tag || "dsh-notify",',
+    '    data: { sessionId: data.sessionId || "" },',
+    '  }));',
+    '});',
+    'self.addEventListener("notificationclick", (event) => {',
+    '  event.notification.close();',
+    '  const sessionId = (event.notification.data && event.notification.data.sessionId) || "";',
+    '  const target = sessionId ? "./?dshNotifySession=" + encodeURIComponent(sessionId) : "./";',
+    '  event.waitUntil((async () => {',
+    '    const clientList = await self.clients.matchAll({ type: "window", includeUncontrolled: true });',
+    '    for (const client of clientList) {',
+    '      let pathname = "";',
+    '      try { pathname = new URL(client.url).pathname; } catch (_) { continue; }',
+    '      if (pathname.endsWith("/") || pathname.endsWith("/index.html")) {',
+    '        await client.focus();',
+    '        if (sessionId) client.postMessage({ type: "dsh-notify-jump", sessionId });',
+    '        return;',
+    '      }',
+    '    }',
+    '    await self.clients.openWindow(target);',
+    '  })());',
+    '});',
+].join('\n');
+
+/** Env overrides so users can keep VAPID keys out of the state file entirely. */
+export const VAPID_PUBLIC_ENV = 'DSH_NOTIFY_VAPID_PUBLIC_KEY';
+export const VAPID_PRIVATE_ENV = 'DSH_NOTIFY_VAPID_PRIVATE_KEY';
+
+/** P-256 VAPID keypair as base64url — raw 65-byte point / raw 32-byte scalar,
+ *  the exact shapes web-push.generateVAPIDKeys() produces (applicationServerKey needs the raw point).
+ *  ECDH, not DER slicing: the pkcs8 DER ends with the public key, so slice(-32) would grab point bytes. */
+export function generateVapidKeys() {
+    const ecdh = crypto.createECDH('prime256v1');
+    ecdh.generateKeys();
+    return {
+        publicKey: ecdh.getPublicKey('base64url'),
+        privateKey: ecdh.getPrivateKey('base64url'),
+    };
+}
+
+export function resolveStatePath(webPushConfig = {}) {
+    if (webPushConfig && typeof webPushConfig.stateFile === 'string' && webPushConfig.stateFile.trim())
+        return webPushConfig.stateFile.trim();
+    const home = (process.env.DSH_HOME && process.env.DSH_HOME.trim())
+        || path.join(os.homedir(), '.dsh');
+    return path.join(home, 'plugin-notify-state.json');
+}
+
+export async function loadState(statePath) {
+    try {
+        const raw = await fsp.readFile(statePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return {
+            vapid: (parsed && typeof parsed.vapid === 'object' && parsed.vapid) || null,
+            subscriptions: Array.isArray(parsed?.subscriptions) ? parsed.subscriptions : [],
+        };
+    } catch {
+        return { vapid: null, subscriptions: [] };
+    }
+}
+
+/** Atomic-ish persist: temp file + rename, serialized per path to avoid RMW races. */
+const writeChains = new Map();
+export function saveState(statePath, state) {
+    const prev = writeChains.get(statePath) || Promise.resolve();
+    const next = prev.catch(() => {}).then(async () => {
+        await fsp.mkdir(path.dirname(statePath), { recursive: true });
+        const tmp = `${statePath}.${process.pid}.${Date.now()}.tmp`;
+        await fsp.writeFile(tmp, JSON.stringify(state, null, 2), 'utf8');
+        await fsp.rename(tmp, statePath);
+    });
+    writeChains.set(statePath, next);
+    return next;
+}
+
+/** Env keys win; otherwise state file; otherwise generate once and persist. */
+export async function getVapidKeys(ctx, webPushConfig = {}) {
+    const envPub = process.env[VAPID_PUBLIC_ENV];
+    const envPriv = process.env[VAPID_PRIVATE_ENV];
+    if (envPub && envPriv) {
+        return { publicKey: envPub, privateKey: envPriv };
+    }
+    const statePath = resolveStatePath(webPushConfig);
+    const state = await loadState(statePath);
+    if (state.vapid && state.vapid.publicKey && state.vapid.privateKey)
+        return state.vapid;
+    const keys = generateVapidKeys();
+    state.vapid = keys;
+    await saveState(statePath, state);
+    ctx?.logger?.info?.(`[plugin-notify] generated VAPID keys → ${statePath}`);
+    return keys;
+}
+
+function isValidSubscription(sub) {
+    return Boolean(
+        sub
+        && typeof sub.endpoint === 'string'
+        && /^https:\/\//i.test(sub.endpoint)
+        && sub.keys
+        && typeof sub.keys.p256dh === 'string' && sub.keys.p256dh.length > 0
+        && typeof sub.keys.auth === 'string' && sub.keys.auth.length > 0,
+    );
+}
+
+export async function addSubscription(statePath, sub) {
+    if (!isValidSubscription(sub))
+        throw new Error('invalid push subscription (need https endpoint and keys.p256dh/auth)');
+    const state = await loadState(statePath);
+    const clean = { endpoint: sub.endpoint, keys: { p256dh: sub.keys.p256dh, auth: sub.keys.auth }, addedAt: Date.now() };
+    const existing = state.subscriptions.findIndex((s) => s.endpoint === clean.endpoint);
+    if (existing >= 0) state.subscriptions[existing] = clean;
+    else state.subscriptions.push(clean);
+    await saveState(statePath, state);
+    return state.subscriptions.length;
+}
+
+export async function removeSubscription(statePath, endpoint) {
+    const state = await loadState(statePath);
+    const before = state.subscriptions.length;
+    state.subscriptions = state.subscriptions.filter((s) => s.endpoint !== endpoint);
+    if (state.subscriptions.length !== before)
+        await saveState(statePath, state);
+    return before - state.subscriptions.length;
+}
+
+export async function listSubscriptions(statePath) {
+    const state = await loadState(statePath);
+    return state.subscriptions;
+}
+
+let webPushLibrary = null;
+/** Test seam: inject a stub with async sendNotification(sub, payload, options). */
+export function setWebPushLibrary(lib) {
+    webPushLibrary = lib;
+}
+async function getWebPush() {
+    if (!webPushLibrary) {
+        const mod = await import('web-push');
+        webPushLibrary = mod.default ?? mod;
+    }
+    return webPushLibrary;
+}
+
+/** Compact payload for the 4 KB push budget: pointer + label, never secret material. */
+export function webPushPayload(n, config = {}) {
+    const badge = n.kind === 'task_done' ? '✅' : n.kind === 'error' ? '⚠️' : '⏸️';
+    const kindLabel = n.kind === 'task_done' ? 'Task done' : n.kind === 'error' ? 'Error' : 'Approval needed';
+    const title = `${badge} ${kindLabel}: ${n.title || n.sessionId || ''}`.trim();
+    const bodyLines = [];
+    if (n.summary) bodyLines.push(n.summary);
+    if (n.reason) bodyLines.push(`Reason: ${n.reason}`);
+    if ((config.includeDuration ?? true) && n.durationMs !== undefined)
+        bodyLines.push(`Duration: ${formatDuration(n.durationMs)}`);
+    if ((config.includeSession ?? true) && n.sessionId)
+        bodyLines.push(`Session: ${n.sessionId}`);
+    return {
+        kind: n.kind,
+        title,
+        body: bodyLines.join('\n'),
+        sessionId: n.sessionId || '',
+        tag: `dsh-notify-${n.sessionId || 'any'}`,
+        ts: Date.now(),
+    };
+}
+
+const inFlightDeliveries = new Set();
+/** Test seam: resolves once every in-flight deliverWebPush has finished. */
+export async function settleWebPushDeliveries() {
+  while (inFlightDeliveries.size > 0) {
+    await Promise.allSettled([...inFlightDeliveries]);
+  }
+}
+
+export function deliverWebPush(ctx, n, config = {}) {
+    let tracked;
+    tracked = (async () => {
+        const wp = config.webPush || {};
+        const statePath = resolveStatePath(wp);
+        const subscriptions = await listSubscriptions(statePath);
+        if (subscriptions.length === 0) return 0;
+        const keys = await getVapidKeys(ctx, wp);
+        const webpush = await getWebPush();
+        const payload = JSON.stringify(webPushPayload(n, config));
+        let sent = 0;
+        for (const sub of subscriptions) {
+            try {
+                await webpush.sendNotification(sub, payload, {
+                    vapidDetails: {
+                        subject: wp.subject || 'mailto:notify@localhost',
+                        publicKey: keys.publicKey,
+                        privateKey: keys.privateKey,
+                    },
+                    timeout: Math.max(config.timeoutMs ?? 5000, 1000),
+                });
+                sent++;
+            } catch (error) {
+                if (error?.statusCode === 404 || error?.statusCode === 410) {
+                    await removeSubscription(statePath, sub.endpoint);
+                    ctx?.logger?.info?.(`[plugin-notify] pruned dead push subscription (${error.statusCode})`);
+                } else {
+                    ctx?.logger?.warn?.(`[plugin-notify] web push send failed: ${String(error)}`);
+                }
+            }
+        }
+        return sent;
+    })().finally(() => {
+        inFlightDeliveries.delete(tracked);
+    });
+    inFlightDeliveries.add(tracked);
+    return tracked;
+}
+
+function readJsonBody(req, limit = 64 * 1024) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                reject(new Error('request body too large'));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            try {
+                resolve(chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {});
+            } catch {
+                reject(new Error('invalid JSON body'));
+            }
+        });
+        req.on('error', reject);
+    });
+}
+
+function writeJson(res, status, body, headers = {}) {
+    if (typeof res.writeHead === 'function') {
+        res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', ...headers });
+    } else {
+        res.statusCode = status;
+    }
+    if (typeof res.end === 'function') res.end(JSON.stringify(body));
+}
+
+function writeText(res, status, text, headers = {}) {
+    if (typeof res.writeHead === 'function') {
+        res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8', ...headers });
+    } else {
+        res.statusCode = status;
+    }
+    if (typeof res.end === 'function') res.end(text);
+}
+
+/** Shared auth for push routes: same fence as the SSE stream. Returns true when accepted. */
+export function authorizePushRequest(req, res, targetCtx) {
+    const conn = connectionOf(targetCtx);
+    if (conn && typeof conn.requestRejection === 'function') {
+        const rejection = conn.requestRejection(req);
+        if (rejection !== void 0) {
+            writeText(res, rejection, rejection === 401 ? 'Unauthorized' : 'Forbidden');
+            return false;
+        }
+        return true;
+    }
+    const remoteAddr = req.socket?.remoteAddress || req.connection?.remoteAddress;
+    if (!remoteAddr || !isLoopback(remoteAddr)) {
+        writeText(res, 403, 'Forbidden');
+        return false;
+    }
+    return true;
+}
+
+export function handleServiceWorker(req, res) {
+    if (req.method !== 'GET') {
+        writeText(res, 405, 'Method Not Allowed', { allow: 'GET' });
+        return;
+    }
+    // Unauthenticated on purpose: static, no secrets; the header lets the SW
+    // control the app root even though the script lives under /dsh-plugin-notify/.
+    if (typeof res.writeHead === 'function') {
+        res.writeHead(200, {
+            'Content-Type': 'text/javascript; charset=utf-8',
+            'Service-Worker-Allowed': '/',
+            'Cache-Control': 'no-store',
+        });
+    } else {
+        res.statusCode = 200;
+    }
+    if (typeof res.end === 'function') res.end(SW_SOURCE);
+}
+
+export async function handlePushKey(req, res, targetCtx, getConfig) {
+    const getConfigU = () => unwrapConfig(getConfig());
+    if (req.method !== 'GET') return writeText(res, 405, 'Method Not Allowed', { allow: 'GET' });
+    if (!authorizePushRequest(req, res, targetCtx)) return;
+    const cfg = getConfigU();
+    if (!(cfg.webPush && cfg.webPush.enabled)) return writeText(res, 404, 'web push disabled');
+    const keys = await getVapidKeys(targetCtx, cfg.webPush || {});
+    writeJson(res, 200, { publicKey: keys.publicKey, subject: cfg.webPush.subject || 'mailto:notify@localhost' });
+}
+
+export async function handlePushSubscribe(req, res, targetCtx, getConfig) {
+    const getConfigU = () => unwrapConfig(getConfig());
+    if (req.method !== 'POST') return writeText(res, 405, 'Method Not Allowed', { allow: 'POST' });
+    if (!authorizePushRequest(req, res, targetCtx)) return;
+    const cfg = getConfigU();
+    if (!(cfg.webPush && cfg.webPush.enabled)) return writeText(res, 404, 'web push disabled');
+    let sub;
+    try {
+        sub = await readJsonBody(req);
+    } catch (error) {
+        return writeText(res, 400, String(error.message || error));
+    }
+    const statePath = resolveStatePath(cfg.webPush || {});
+    try {
+        const count = await addSubscription(statePath, sub);
+        targetCtx?.logger?.info?.(`[plugin-notify] push subscribed (${count} total)`);
+        writeJson(res, 200, { ok: true, count });
+    } catch (error) {
+        writeText(res, 400, String(error.message || error));
+    }
+}
+
+export async function handlePushUnsubscribe(req, res, targetCtx, getConfig) {
+    const getConfigU = () => unwrapConfig(getConfig());
+    if (req.method !== 'POST') return writeText(res, 405, 'Method Not Allowed', { allow: 'POST' });
+    if (!authorizePushRequest(req, res, targetCtx)) return;
+    const cfg = getConfigU();
+    if (!(cfg.webPush && cfg.webPush.enabled)) return writeText(res, 404, 'web push disabled');
+    let body;
+    try {
+        body = await readJsonBody(req);
+    } catch (error) {
+        return writeText(res, 400, String(error.message || error));
+    }
+    if (!body || typeof body.endpoint !== 'string') return writeText(res, 400, 'endpoint required');
+    const removed = await removeSubscription(resolveStatePath(cfg.webPush || {}), body.endpoint);
+    writeJson(res, 200, { ok: true, removed });
+}
+
+export async function handlePushTest(req, res, targetCtx, getConfig) {
+    const getConfigU = () => unwrapConfig(getConfig());
+    if (req.method !== 'POST') return writeText(res, 405, 'Method Not Allowed', { allow: 'POST' });
+    if (!authorizePushRequest(req, res, targetCtx)) return;
+    const cfg = getConfigU();
+    if (!(cfg.webPush && cfg.webPush.enabled)) return writeText(res, 404, 'web push disabled');
+    const sent = await deliverWebPush(targetCtx, {
+        kind: 'task_done',
+        title: 'Test notification',
+        sessionId: 'test',
+        summary: 'If you can read this, the dsh-plugin-notify web push channel works.',
+    }, cfg);
+    writeJson(res, 200, { ok: true, sent });
+}
+
+function mountWebServer(targetCtx, hostCtx, getConfig) {
     if (!targetCtx?.webServer?.register) return () => {};
-    const routeDef = {
-        kind: 'exact',
-        path: '/dsh-plugin-notify/events',
-        handler: (req, res) => handleSseConnection(req, res, targetCtx),
+    // Async route wrapper: an unexpected rejection becomes a 500 instead of an
+    // unhandled rejection; authorized handlers have already written their response.
+    const asyncRoute = (handler) => (req, res) => {
+        Promise.resolve(handler(req, res)).catch(() => {
+            try { writeText(res, 500, 'internal error'); } catch { /* ignore */ }
+        });
     };
+    const routeDefs = [
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-notify/events',
+            handler: (req, res) => handleSseConnection(req, res, targetCtx),
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-notify/sw.js',
+            handler: (req, res) => handleServiceWorker(req, res),
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-notify/push/key',
+            handler: asyncRoute((req, res) => handlePushKey(req, res, targetCtx, getConfig)),
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-notify/push/subscribe',
+            handler: asyncRoute((req, res) => handlePushSubscribe(req, res, targetCtx, getConfig)),
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-notify/push/unsubscribe',
+            handler: asyncRoute((req, res) => handlePushUnsubscribe(req, res, targetCtx, getConfig)),
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-notify/push/test',
+            handler: asyncRoute((req, res) => handlePushTest(req, res, targetCtx, getConfig)),
+        },
+    ];
 
     let timer = null;
     const startHeartbeat = () => {
@@ -281,8 +710,10 @@ function mountWebServer(targetCtx, hostCtx) {
             clearInterval(timer);
             timer = null;
         }
-        if (typeof unregister === 'function') {
-            try { unregister(); } catch { /* ignore */ }
+        if (Array.isArray(unregister)) {
+            for (const fn of unregister) {
+                try { fn(); } catch { /* ignore */ }
+            }
             unregister = null;
         }
         closeAllSseClients();
@@ -290,14 +721,14 @@ function mountWebServer(targetCtx, hostCtx) {
 
     if (typeof targetCtx.effect === 'function') {
         targetCtx.effect(() => {
-            unregister = targetCtx.webServer.register(routeDef);
+            unregister = routeDefs.map((routeDef) => targetCtx.webServer.register(routeDef));
             return () => cleanup();
         }, 'dsh-plugin-notify: sse events');
         targetCtx.effect(() => {
             return startHeartbeat();
         }, 'dsh-plugin-notify: sse heartbeat');
     } else {
-        unregister = targetCtx.webServer.register(routeDef);
+        unregister = routeDefs.map((routeDef) => targetCtx.webServer.register(routeDef));
         startHeartbeat();
     }
 
@@ -305,7 +736,7 @@ function mountWebServer(targetCtx, hostCtx) {
 }
 
 export function apply(ctx, config = {}) {
-    let getConfig = () => config ?? {};
+    let getConfig = () => unwrapConfig(config ?? {});
 
     let webServerMounted = false;
     let unmountWebServer = null;
@@ -315,7 +746,7 @@ export function apply(ctx, config = {}) {
         if (target?.webServer?.register) {
             webServerMounted = true;
             const effectiveTarget = target?.connection ? target : (ctx?.connection ? ctx : target);
-            unmountWebServer = mountWebServer(effectiveTarget, ctx);
+            unmountWebServer = mountWebServer(effectiveTarget, ctx, () => getConfig());
         }
     };
 
@@ -338,21 +769,58 @@ export function apply(ctx, config = {}) {
 
     if (typeof ctx.inject === 'function') {
         ctx.inject(['settings'], (sctx) => {
-            const row = (() => { try { return sctx.settings?.describe?.().find((r) => r && r.ns === NS); } catch { return null; } })();
+            if (typeof sctx.settings?.register === 'function') {
+                try {
+                    const scope = sctx.settings.register(ENTRY_ID, Config, { base: config ?? {} });
+                    getConfig = () => (scope ? unwrapConfig(scope.get() ?? config ?? {}) : unwrapConfig(config ?? {}));
+                    return;
+                } catch (err) {
+                    ctx?.logger?.warn?.(`[plugin-notify] settings.register('${ENTRY_ID}') failed, falling back to describe: ${String(err)}`);
+                }
+            }
+            let currentRow = (() => { try { return sctx.settings?.describe?.().find((r) => r && (r.ns === ENTRY_ID || r.ns === NS)); } catch { return null; } })();
+            const refreshSettings = () => {
+                try {
+                    const next = sctx.settings?.describe?.().find((r) => r && (r.ns === ENTRY_ID || r.ns === NS));
+                    if (next) currentRow = next;
+                } catch {
+                    // best effort
+                }
+            };
+            if (typeof ctx.on === 'function') {
+                ctx.on('settings/document-updated', refreshSettings);
+                ctx.on('loader/volatile-update', refreshSettings);
+                ctx.on('settings/updated', refreshSettings);
+            }
+            if (typeof sctx.settings?.on === 'function') {
+                try { sctx.settings.on('update', refreshSettings); } catch { /* ignore */ }
+            }
             const scope = {
-              get: () => row?.value ?? config ?? {},
-              replace: async (next) => { try { return await sctx.settings?.replace?.(NS, next, row?.revision); } catch {} },
+              get: () => {
+                refreshSettings();
+                return currentRow?.value ?? config ?? {};
+              },
+              replace: async (next) => {
+                try {
+                  const targetNs = sctx.settings?.describe?.().some((r) => r && r.ns === ENTRY_ID) ? ENTRY_ID : NS;
+                  const res = await sctx.settings?.replace?.(targetNs, next, currentRow?.revision);
+                  refreshSettings();
+                  return res;
+                } catch (err) {
+                  ctx?.logger?.warn?.(`[plugin-notify] settings replace failed: ${String(err)}`);
+                }
+              },
             };
-            getConfig = () => scope.get() ?? config ?? {};
+            getConfig = () => (scope ? unwrapConfig(scope.get() ?? config ?? {}) : unwrapConfig(config ?? {}));
         });
-        ctx.inject(['webServer'], (wctx) => tryMountWebServer(wctx));
+        ctx.inject(['webServer'], (wctx) => tryMountWebServer(wctx))
     }
     if (ctx.webServer) {
         tryMountWebServer(ctx);
     }
 
     const dispatch = (n) => {
-        const cfg = getConfig();
+        const cfg = unwrapConfig(getConfig());
         const dnd = cfg.dnd;
         if (inDnd(dnd)) {
             (ctx?.logger?.debug ?? ctx?.logger?.info)?.(`[plugin-notify] ${n.kind} · ${n.title} · session ${n.sessionId} · DND (${dnd?.start}-${dnd?.end}), logged only`);
@@ -381,6 +849,19 @@ export function apply(ctx, config = {}) {
             .catch((error) => {
                 ctx?.logger?.warn?.(`[plugin-notify] webhook resolve/send failed: ${String(error)}`);
             });
+
+        // Web Push (PWA) channel: reaches devices with every dsh tab closed.
+        const wp = cfg.webPush;
+        if (wp && wp.enabled) {
+            const away = sseClients.size === 0;
+            if (away || wp.onlyWhenAway === false) {
+                deliverWebPush(ctx, n, cfg).catch((error) => {
+                    ctx?.logger?.warn?.(`[plugin-notify] web push dispatch failed: ${String(error)}`);
+                });
+            } else {
+                (ctx?.logger?.debug ?? ctx?.logger?.info)?.(`[plugin-notify] ${n.kind} · session ${n.sessionId} · web push skipped (clients connected)`);
+            }
+        }
     };
 
     ctx.on('session/event', (session, event) => {