handmux 0.23.0 → 0.25.0

package/dist/src/projectTask/store.js

@@ -0,0 +1,457 @@
+import crypto from 'node:crypto';
+import fsp from 'node:fs/promises';
+import { ProjectTaskError, requireExpectedVersion, requireTrimmedString, } from './schema.js';
+function projectFromRow(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        rootPath: row.root_path,
+        repositoryRoot: row.repository_root,
+        defaultAgent: row.default_agent,
+        executionMode: row.execution_mode,
+        version: row.version,
+        archivedAt: row.archived_at,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function rowOf(value) {
+    return value && typeof value === 'object' ? value : null;
+}
+function taskFromRow(row) {
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        title: row.title,
+        objective: row.objective,
+        acceptanceCriteria: JSON.parse(row.acceptance_criteria_json),
+        scope: row.scope,
+        constraints: row.constraints,
+        references: JSON.parse(row.references_json),
+        status: row.status,
+        priority: row.priority,
+        briefVersion: row.brief_version,
+        version: row.version,
+        archivedAt: row.archived_at,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function taskEventFromRow(row) {
+    return {
+        id: row.id,
+        taskId: row.task_id,
+        type: row.type,
+        actor: row.actor,
+        taskVersion: row.task_version,
+        briefVersion: row.brief_version,
+        payload: JSON.parse(row.payload_json),
+        createdAt: row.created_at,
+    };
+}
+const TASK_PRIORITIES = new Set(['none', 'high', 'medium', 'low']);
+const BRIEF_FIELDS = ['title', 'objective', 'acceptanceCriteria', 'scope', 'constraints', 'references'];
+function optionalText(value, field) {
+    if (value == null || value === '')
+        return null;
+    if (typeof value !== 'string') {
+        throw new ProjectTaskError('TASK_VALIDATION', 400, `${field} must be text or null`);
+    }
+    return value.trim() || null;
+}
+function objective(value) {
+    if (value == null)
+        return '';
+    if (typeof value !== 'string') {
+        throw new ProjectTaskError('TASK_VALIDATION', 400, 'objective must be text');
+    }
+    return value.trim();
+}
+function acceptanceCriteria(value) {
+    if (value == null)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new ProjectTaskError('TASK_VALIDATION', 400, 'acceptanceCriteria must be a list of text items');
+    }
+    return value.map((item) => item.trim()).filter(Boolean);
+}
+function references(value) {
+    if (value == null)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new ProjectTaskError('TASK_VALIDATION', 400, 'references must be a list');
+    }
+    return value.map((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            throw new ProjectTaskError('TASK_VALIDATION', 400, 'each reference must be an object');
+        }
+        const record = item;
+        if (record.kind !== 'url' && record.kind !== 'path') {
+            throw new ProjectTaskError('TASK_VALIDATION', 400, 'reference kind must be url or path');
+        }
+        if (typeof record.value !== 'string' || !record.value.trim()) {
+            throw new ProjectTaskError('TASK_VALIDATION', 400, 'reference value is required');
+        }
+        if (record.label != null && typeof record.label !== 'string') {
+            throw new ProjectTaskError('TASK_VALIDATION', 400, 'reference label must be text or null');
+        }
+        return {
+            kind: record.kind,
+            value: record.value.trim(),
+            label: typeof record.label === 'string' ? record.label.trim() || null : null,
+        };
+    });
+}
+function priority(value) {
+    const result = value ?? 'none';
+    if (typeof result !== 'string' || !TASK_PRIORITIES.has(result)) {
+        throw new ProjectTaskError('TASK_VALIDATION', 400, 'priority is invalid');
+    }
+    return result;
+}
+function status(value) {
+    if (value !== 'draft' && value !== 'ready') {
+        throw new ProjectTaskError('TASK_VALIDATION', 400, 'status must be draft or ready');
+    }
+    return value;
+}
+function validateReady(task) {
+    if (!task.objective) {
+        throw new ProjectTaskError('TASK_VALIDATION', 400, 'A task needs a goal');
+    }
+}
+function sameJson(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export function createProjectTaskStore(db, { realpath = fsp.realpath, isDirectory = async (target) => (await fsp.stat(target)).isDirectory(), resolveRepositoryRoot = async () => null, randomUUID = crypto.randomUUID, now = () => new Date(), onSuccessfulWrite = () => { }, } = {}) {
+    const selectProject = db.prepare(`
+    SELECT id, name, root_path, repository_root, default_agent, execution_mode,
+           version, archived_at, created_at, updated_at
+    FROM projects WHERE id = ?
+  `);
+    const selectTask = db.prepare(`
+    SELECT id, project_id, title, objective, acceptance_criteria_json, scope, constraints,
+           references_json, status, priority, brief_version, version, archived_at, created_at, updated_at
+    FROM tasks WHERE id = ?
+  `);
+    const selectActiveProjectRoot = db.prepare(`
+    SELECT id FROM projects WHERE root_path = ? AND archived_at IS NULL
+  `);
+    const insertTaskEvent = db.prepare(`
+    INSERT INTO task_events (
+      id, task_id, type, actor, task_version, brief_version, payload_json, created_at
+    ) VALUES (?, ?, ?, 'user', ?, ?, ?, ?)
+  `);
+    const notifyWrite = () => {
+        Promise.resolve(onSuccessfulWrite()).catch(() => { });
+    };
+    const requireProject = (id) => {
+        const row = rowOf(selectProject.get(id));
+        if (!row)
+            throw new ProjectTaskError('PROJECT_NOT_FOUND', 404, 'Project no longer exists');
+        return projectFromRow(row);
+    };
+    const requireTask = (id) => {
+        const row = selectTask.get(id);
+        if (!row)
+            throw new ProjectTaskError('TASK_NOT_FOUND', 404, 'Task no longer exists');
+        return taskFromRow(row);
+    };
+    const assertTaskProjectActive = (task) => {
+        if (requireProject(task.projectId).archivedAt) {
+            throw new ProjectTaskError('PROJECT_NOT_FOUND', 404, 'Project is archived');
+        }
+    };
+    const transaction = (operation) => {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = operation();
+            db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { }
+            throw error;
+        }
+    };
+    const appendTaskEvent = (task, type, payload) => {
+        insertTaskEvent.run(randomUUID(), task.id, type, task.version, task.briefVersion, JSON.stringify(payload), task.updatedAt);
+    };
+    const assertTaskVersion = (task, rawVersion) => {
+        const expectedVersion = requireExpectedVersion(rawVersion, 'TASK_VALIDATION');
+        if (task.version !== expectedVersion) {
+            throw new ProjectTaskError('VERSION_CONFLICT', 409, 'Task changed; refresh before saving again');
+        }
+        return expectedVersion;
+    };
+    return {
+        async listProjects({ archived = false } = {}) {
+            const rows = db.prepare(`
+        SELECT id, name, root_path, repository_root, default_agent, execution_mode,
+               version, archived_at, created_at, updated_at
+        FROM projects
+        WHERE ${archived ? 'archived_at IS NOT NULL' : 'archived_at IS NULL'}
+        ORDER BY updated_at DESC, id
+      `).all();
+            return rows.map(projectFromRow);
+        },
+        async getProject(id) {
+            return requireProject(id);
+        },
+        async createProject(input) {
+            const name = requireTrimmedString(input.name, 'name', 120, 'PROJECT_VALIDATION');
+            if (typeof input.rootPath !== 'string' || !input.rootPath) {
+                throw new ProjectTaskError('PROJECT_VALIDATION', 400, 'rootPath must be an absolute directory');
+            }
+            let rootPath;
+            try {
+                rootPath = await realpath(input.rootPath);
+                if (!await isDirectory(rootPath))
+                    throw new Error('not a directory');
+            }
+            catch {
+                throw new ProjectTaskError('PROJECT_VALIDATION', 400, 'rootPath must be an existing directory');
+            }
+            const existing = selectActiveProjectRoot.get(rootPath);
+            if (existing) {
+                throw new ProjectTaskError('PROJECT_ROOT_EXISTS', 409, 'This directory is already a Project');
+            }
+            const id = randomUUID();
+            const timestamp = now().toISOString();
+            const repositoryRoot = await resolveRepositoryRoot(rootPath);
+            // Repository discovery is async. Recheck at the synchronous write boundary so two concurrent
+            // Add Project requests cannot both pass the first lookup and leak a raw SQLite constraint error.
+            if (selectActiveProjectRoot.get(rootPath)) {
+                throw new ProjectTaskError('PROJECT_ROOT_EXISTS', 409, 'This directory is already a Project');
+            }
+            db.prepare(`
+        INSERT INTO projects (
+          id, name, root_path, repository_root, default_agent, execution_mode,
+          version, archived_at, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, NULL, 'project-root', 1, NULL, ?, ?)
+      `).run(id, name, rootPath, repositoryRoot, timestamp, timestamp);
+            notifyWrite();
+            return requireProject(id);
+        },
+        async updateProject(id, input) {
+            const name = requireTrimmedString(input.name, 'name', 120, 'PROJECT_VALIDATION');
+            const expectedVersion = requireExpectedVersion(input.expectedVersion);
+            const timestamp = now().toISOString();
+            const result = db.prepare(`
+        UPDATE projects
+        SET name = ?, version = version + 1, updated_at = ?
+        WHERE id = ? AND version = ? AND archived_at IS NULL
+      `).run(name, timestamp, id, expectedVersion);
+            if (result.changes === 0) {
+                const current = requireProject(id);
+                if (current.archivedAt) {
+                    throw new ProjectTaskError('PROJECT_NOT_FOUND', 404, 'Project is archived');
+                }
+                throw new ProjectTaskError('VERSION_CONFLICT', 409, 'Project changed; refresh before saving again');
+            }
+            notifyWrite();
+            return requireProject(id);
+        },
+        async archiveProject(id, input) {
+            const expectedVersion = requireExpectedVersion(input.expectedVersion);
+            const timestamp = now().toISOString();
+            const result = db.prepare(`
+        UPDATE projects
+        SET archived_at = ?, version = version + 1, updated_at = ?
+        WHERE id = ? AND version = ? AND archived_at IS NULL
+      `).run(timestamp, timestamp, id, expectedVersion);
+            if (result.changes === 0) {
+                const current = requireProject(id);
+                if (current.archivedAt)
+                    return current;
+                throw new ProjectTaskError('VERSION_CONFLICT', 409, 'Project changed; refresh before archiving');
+            }
+            notifyWrite();
+            return requireProject(id);
+        },
+        async listTasks({ projectId, bucket }) {
+            if (typeof projectId !== 'string' || !projectId) {
+                throw new ProjectTaskError('TASK_VALIDATION', 400, 'projectId is required');
+            }
+            requireProject(projectId);
+            const clauses = {
+                tasks: "archived_at IS NULL AND status = 'ready'",
+                drafts: "archived_at IS NULL AND status = 'draft'",
+                canceled: "archived_at IS NULL AND status = 'canceled'",
+                archived: 'archived_at IS NOT NULL',
+            };
+            if (typeof bucket !== 'string' || !Object.hasOwn(clauses, bucket)) {
+                throw new ProjectTaskError('TASK_VALIDATION', 400, 'bucket must be tasks, drafts, canceled, or archived');
+            }
+            const rows = db.prepare(`
+        SELECT id, project_id, title, objective, acceptance_criteria_json, scope, constraints,
+               references_json, status, priority, brief_version, version, archived_at, created_at, updated_at
+        FROM tasks
+        WHERE project_id = ? AND ${clauses[bucket]}
+        ORDER BY updated_at DESC, id
+      `).all(projectId);
+            return rows.map(taskFromRow);
+        },
+        async getTask(id) {
+            return requireTask(id);
+        },
+        async createTask(input) {
+            if (typeof input.projectId !== 'string' || !input.projectId) {
+                throw new ProjectTaskError('TASK_VALIDATION', 400, 'projectId is required');
+            }
+            const project = requireProject(input.projectId);
+            if (project.archivedAt)
+                throw new ProjectTaskError('PROJECT_NOT_FOUND', 404, 'Project is archived');
+            const taskStatus = status(input.status);
+            const task = {
+                id: randomUUID(),
+                projectId: project.id,
+                title: requireTrimmedString(input.title, 'title', 240, 'TASK_VALIDATION'),
+                objective: objective(input.objective),
+                acceptanceCriteria: acceptanceCriteria(input.acceptanceCriteria),
+                scope: optionalText(input.scope, 'scope'),
+                constraints: optionalText(input.constraints, 'constraints'),
+                references: references(input.references),
+                status: taskStatus,
+                priority: priority(input.priority),
+                briefVersion: 1,
+                version: 1,
+                archivedAt: null,
+                createdAt: now().toISOString(),
+                updatedAt: '',
+            };
+            task.updatedAt = task.createdAt;
+            if (task.status === 'ready')
+                validateReady(task);
+            transaction(() => {
+                db.prepare(`
+          INSERT INTO tasks (
+            id, project_id, title, objective, acceptance_criteria_json, scope, constraints,
+            references_json, status, priority, brief_version, version, archived_at, created_at, updated_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 1, NULL, ?, ?)
+        `).run(task.id, task.projectId, task.title, task.objective, JSON.stringify(task.acceptanceCriteria), task.scope, task.constraints, JSON.stringify(task.references), task.status, task.priority, task.createdAt, task.updatedAt);
+                appendTaskEvent(task, 'task.created', { status: task.status });
+            });
+            notifyWrite();
+            return requireTask(task.id);
+        },
+        async updateTask(id, input) {
+            const current = requireTask(id);
+            assertTaskProjectActive(current);
+            assertTaskVersion(current, input.expectedVersion);
+            if (current.archivedAt)
+                throw new ProjectTaskError('TASK_NOT_FOUND', 404, 'Task is archived');
+            if (current.status === 'canceled') {
+                throw new ProjectTaskError('TASK_TRANSITION_INVALID', 409, 'Canceled tasks are read-only');
+            }
+            const next = {
+                ...current,
+                title: Object.hasOwn(input, 'title')
+                    ? requireTrimmedString(input.title, 'title', 240, 'TASK_VALIDATION') : current.title,
+                objective: Object.hasOwn(input, 'objective') ? objective(input.objective) : current.objective,
+                acceptanceCriteria: Object.hasOwn(input, 'acceptanceCriteria')
+                    ? acceptanceCriteria(input.acceptanceCriteria) : current.acceptanceCriteria,
+                scope: Object.hasOwn(input, 'scope') ? optionalText(input.scope, 'scope') : current.scope,
+                constraints: Object.hasOwn(input, 'constraints')
+                    ? optionalText(input.constraints, 'constraints') : current.constraints,
+                references: Object.hasOwn(input, 'references') ? references(input.references) : current.references,
+                priority: Object.hasOwn(input, 'priority') ? priority(input.priority) : current.priority,
+            };
+            if (next.status === 'ready')
+                validateReady(next);
+            const changedFields = [
+                ...BRIEF_FIELDS.filter((field) => !sameJson(current[field], next[field])),
+                ...(current.priority === next.priority ? [] : ['priority']),
+            ];
+            if (changedFields.length === 0)
+                return current;
+            const briefChanged = changedFields.some((field) => BRIEF_FIELDS.includes(field));
+            next.version += 1;
+            if (briefChanged)
+                next.briefVersion += 1;
+            next.updatedAt = now().toISOString();
+            transaction(() => {
+                db.prepare(`
+          UPDATE tasks SET
+            title = ?, objective = ?, acceptance_criteria_json = ?, scope = ?, constraints = ?,
+            references_json = ?, priority = ?, brief_version = ?, version = ?, updated_at = ?
+          WHERE id = ? AND version = ?
+        `).run(next.title, next.objective, JSON.stringify(next.acceptanceCriteria), next.scope, next.constraints, JSON.stringify(next.references), next.priority, next.briefVersion, next.version, next.updatedAt, next.id, current.version);
+                appendTaskEvent(next, 'task.updated', { changedFields });
+            });
+            notifyWrite();
+            return requireTask(id);
+        },
+        async promoteTask(id, input) {
+            const current = requireTask(id);
+            assertTaskProjectActive(current);
+            assertTaskVersion(current, input.expectedVersion);
+            if (current.archivedAt)
+                throw new ProjectTaskError('TASK_NOT_FOUND', 404, 'Task is archived');
+            if (current.status !== 'draft') {
+                throw new ProjectTaskError('TASK_TRANSITION_INVALID', 409, 'Only a draft can become a task');
+            }
+            validateReady(current);
+            const next = { ...current, status: 'ready', version: current.version + 1, updatedAt: now().toISOString() };
+            transaction(() => {
+                db.prepare(`
+          UPDATE tasks SET status = 'ready', version = ?, updated_at = ? WHERE id = ? AND version = ?
+        `).run(next.version, next.updatedAt, id, current.version);
+                appendTaskEvent(next, 'task.promoted', { from: 'draft', to: 'ready' });
+            });
+            notifyWrite();
+            return requireTask(id);
+        },
+        async cancelTask(id, input) {
+            const current = requireTask(id);
+            assertTaskProjectActive(current);
+            assertTaskVersion(current, input.expectedVersion);
+            if (current.archivedAt)
+                throw new ProjectTaskError('TASK_NOT_FOUND', 404, 'Task is archived');
+            if (current.status === 'canceled') {
+                throw new ProjectTaskError('TASK_TRANSITION_INVALID', 409, 'Task is already canceled');
+            }
+            const next = { ...current, status: 'canceled', version: current.version + 1, updatedAt: now().toISOString() };
+            transaction(() => {
+                db.prepare(`
+          UPDATE tasks SET status = 'canceled', version = ?, updated_at = ? WHERE id = ? AND version = ?
+        `).run(next.version, next.updatedAt, id, current.version);
+                appendTaskEvent(next, 'task.canceled', { from: current.status, to: 'canceled' });
+            });
+            notifyWrite();
+            return requireTask(id);
+        },
+        async archiveTask(id, input) {
+            const current = requireTask(id);
+            assertTaskProjectActive(current);
+            assertTaskVersion(current, input.expectedVersion);
+            if (current.archivedAt)
+                return current;
+            const next = {
+                ...current,
+                version: current.version + 1,
+                archivedAt: now().toISOString(),
+                updatedAt: now().toISOString(),
+            };
+            transaction(() => {
+                db.prepare(`
+          UPDATE tasks SET archived_at = ?, version = ?, updated_at = ? WHERE id = ? AND version = ?
+        `).run(next.archivedAt, next.version, next.updatedAt, id, current.version);
+                appendTaskEvent(next, 'task.archived', { archived: true });
+            });
+            notifyWrite();
+            return requireTask(id);
+        },
+        async listTaskEvents(id) {
+            requireTask(id);
+            const rows = db.prepare(`
+        SELECT id, task_id, type, actor, task_version, brief_version, payload_json, created_at
+        FROM task_events WHERE task_id = ? ORDER BY task_version, created_at, id
+      `).all(id);
+            return rows.map(taskEventFromRow);
+        },
+    };
+}

package/dist/src/push.js

@@ -0,0 +1,224 @@
+// Web Push (VAPID) — minimal delivery layer. Sends notifications to subscribed devices via the
+// browser/OS push services (Android=FCM, iOS=APNs); the server only talks to those services, never
+// to the phone directly, so device reachability/queueing is their problem (see TTL/topic below).
+//
+// Subscriptions are stored as records: { subscription, boundSessions }. The subscription field is
+// the raw PushSubscription the browser hands us ({endpoint, keys:{p256dh, auth}}); boundSessions is
+// the list of session names this device cares about (used by sendToSession for targeted delivery). A
+// dead subscription (404/410 from the push service) is pruned on the next send.
+import webpush from 'web-push';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import crypto from 'node:crypto';
+import { readJsonArray, writeJsonAtomic } from './jsonStore.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const STORE = process.env.PUSH_STORE || path.resolve(here, '../data/push-subs.json');
+// VAPID is optional: without keys every send is a no-op, so the server still boots in an
+// environment that hasn't generated keys (configured=false surfaces as a 503 on /vapid). Push delivers
+// whenever VAPID is configured — there is no separate "dev vs prod server" anymore (one config file, one
+// `handmux start`). If you run a second instance on the same host and don't want it to deliver, leave
+// `vapid` out of that instance's config. Init is LAZY (first use) so the module is import-safe.
+let inited = false;
+let configured = false;
+function ensureInit() {
+    if (inited)
+        return;
+    inited = true;
+    const vapidPublic = process.env.VAPID_PUBLIC;
+    const vapidPrivate = process.env.VAPID_PRIVATE;
+    configured = !!(vapidPublic && vapidPrivate);
+    if (vapidPublic && vapidPrivate) {
+        webpush.setVapidDetails(
+        // Apple (APNs) rejects a VAPID subject on a fake/.local domain with BadJwtToken — it must be a
+        // valid mailto:/https: with a real-looking domain. example.com is reserved and accepted by both.
+        process.env.VAPID_SUBJECT || 'mailto:admin@example.com', vapidPublic, vapidPrivate);
+    }
+}
+const genKey = () => crypto.randomBytes(18).toString('base64url');
+const VALID_PUSH_KEY = /^[A-Za-z0-9_-]{16,128}$/;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const strings = (value) => Array.isArray(value)
+    ? value.filter((item) => typeof item === 'string' && item.length > 0)
+    : [];
+const errorField = (error, field) => isRecord(error) ? error[field] : undefined;
+export function parsePushSubscription(value) {
+    if (!isRecord(value) || typeof value.endpoint !== 'string' || !value.endpoint)
+        return null;
+    if (!isRecord(value.keys) || typeof value.keys.p256dh !== 'string' || typeof value.keys.auth !== 'string')
+        return null;
+    const subscription = {
+        endpoint: value.endpoint,
+        keys: { p256dh: value.keys.p256dh, auth: value.keys.auth },
+    };
+    if (value.expirationTime === null || (typeof value.expirationTime === 'number' && Number.isFinite(value.expirationTime))) {
+        subscription.expirationTime = value.expirationTime;
+    }
+    return subscription;
+}
+function parseStoredSubscription(value) {
+    const wrapped = isRecord(value) && 'subscription' in value;
+    const subscription = parsePushSubscription(wrapped && isRecord(value) ? value.subscription : value);
+    if (!subscription)
+        return null;
+    const record = {
+        subscription,
+        boundSessions: wrapped && isRecord(value) ? strings(value.boundSessions) : [],
+    };
+    if (wrapped && isRecord(value) && typeof value.pushKey === 'string' && VALID_PUSH_KEY.test(value.pushKey)) {
+        record.pushKey = value.pushKey;
+    }
+    return record;
+}
+let subs = load();
+function load() {
+    return readJsonArray(STORE)
+        .map(parseStoredSubscription)
+        .filter((record) => record !== null);
+}
+function persist() { writeJsonAtomic(STORE, subs); }
+export function isConfigured() { ensureInit(); return configured; }
+export function publicKey() { ensureInit(); return process.env.VAPID_PUBLIC || null; }
+export function count() { return subs.length; }
+export function addSubscription(sub, boundSessions = [], preferredPushKey = null) {
+    const parsed = parsePushSubscription(sub);
+    if (!parsed)
+        return false;
+    const sessions = strings(boundSessions);
+    const endpointRecord = subs.find((s) => s.subscription.endpoint === parsed.endpoint);
+    const requestedKey = typeof preferredPushKey === 'string' && VALID_PUSH_KEY.test(preferredPushKey) ? preferredPushKey : null;
+    const keyRecord = requestedKey ? subs.find((s) => s.pushKey === requestedKey) : null;
+    const pushKey = keyRecord?.pushKey || endpointRecord?.pushKey || requestedKey || genKey();
+    // A browser PushSubscription is transport state, not device identity. Re-enabling push can produce a
+    // different endpoint; replace the old endpoint that owns this stable key instead of creating a new
+    // script-push target. Also collapse any legacy duplicate for the new endpoint.
+    subs = subs.filter((s) => s.subscription.endpoint !== parsed.endpoint && s.pushKey !== pushKey);
+    subs.push({ subscription: parsed, boundSessions: sessions, pushKey });
+    persist();
+    return pushKey;
+}
+export function updateBound(endpoint, boundSessions = []) {
+    const rec = subs.find((s) => s.subscription.endpoint === endpoint);
+    if (rec) {
+        rec.boundSessions = strings(boundSessions);
+        persist();
+    }
+}
+export function removeSubscription(endpoint) {
+    const removed = subs.find((s) => s.subscription.endpoint === endpoint);
+    subs = subs.filter((s) => s.subscription.endpoint !== endpoint);
+    if (removed)
+        persist();
+    return removed?.pushKey || null;
+}
+// The device-addressing id (NOT an auth credential — see /api/push/send-local). Lazy-generate for
+// records stored before the feature existed so an already-subscribed device still has one.
+export function getPushKey(endpoint) {
+    const rec = subs.find((s) => s.subscription.endpoint === endpoint);
+    if (!rec)
+        return null;
+    if (!rec.pushKey) {
+        rec.pushKey = genKey();
+        persist();
+    }
+    return rec.pushKey;
+}
+// The push-service Topic header (RFC 8030) must be ≤32 URL/filename-safe base64 chars [A-Za-z0-9_-].
+// An invalid topic makes the service reject the ENTIRE send with a non-404/410 error that deliver()
+// swallows — a silent zero-delivery, no log, no prune. tmux pane ids carry a '%' (e.g. %4), so a
+// pane-derived topic ("pane-%4") breaks every per-pane push (需要你 / 已完成). Sanitize here, the layer
+// that owns the web-push contract, so no caller has to know the rule.
+function safeTopic(value) {
+    if (typeof value !== 'string' || !value)
+        return undefined;
+    const s = value.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 32);
+    return s || undefined;
+}
+// TTL bounds staleness (a phone offline longer than this drops the push instead of getting it
+// hours later); topic collapses older undelivered messages with the same key so a device coming
+// back online sees only the latest per topic. urgency hints the OS how aggressively to wake.
+function options(opts = {}) {
+    const ttl = typeof opts.ttl === 'number' && Number.isFinite(opts.ttl) ? opts.ttl : 90;
+    const urgency = ['very-low', 'low', 'normal', 'high'].includes(String(opts.urgency))
+        ? String(opts.urgency) : 'normal';
+    const result = { TTL: ttl, urgency };
+    const topic = safeTopic(opts.topic);
+    if (topic)
+        result.topic = topic;
+    return result;
+}
+export function classifyDeliveryFailure(error) {
+    const status = Number(errorField(error, 'statusCode')) || 0;
+    if (status === 404 || status === 410)
+        return 'expired';
+    if (status === 429)
+        return 'rate_limited';
+    if (status >= 500)
+        return 'service_unavailable';
+    if (status >= 400)
+        return 'rejected';
+    return 'network_error';
+}
+async function deliver(records, payload, opts = {}) {
+    ensureInit();
+    if (!configured)
+        return {
+            sent: 0, failed: 0, gone: 0, configured: false,
+            deliveries: records.map((rec) => ({ pushKey: rec.pushKey, status: 'failed', reason: 'not_configured' })),
+        };
+    const data = JSON.stringify(payload);
+    const dead = [];
+    const deliveries = [];
+    let sent = 0;
+    let failed = 0;
+    await Promise.all(records.map(async (rec) => {
+        try {
+            await webpush.sendNotification(rec.subscription, data, options(opts));
+            sent += 1;
+            deliveries.push({ pushKey: rec.pushKey, status: 'success' });
+        }
+        catch (e) {
+            failed += 1;
+            const statusCode = Number(errorField(e, 'statusCode')) || 0;
+            if (statusCode === 404 || statusCode === 410)
+                dead.push(rec.subscription.endpoint);
+            deliveries.push({ pushKey: rec.pushKey, status: 'failed', reason: classifyDeliveryFailure(e) });
+            let host = 'unknown push service';
+            try {
+                host = new URL(rec.subscription.endpoint).host;
+            }
+            catch { /* malformed endpoints fail below */ }
+            const detail = String(errorField(e, 'body') || errorField(e, 'message') || 'unknown error').replace(/\s+/g, ' ').slice(0, 200);
+            console.warn(`[handmux] push delivery failed (${host}, HTTP ${statusCode || 'unknown'}): ${detail}`);
+        }
+    }));
+    if (dead.length) {
+        subs = subs.filter((s) => !dead.includes(s.subscription.endpoint));
+        persist();
+    }
+    return { sent, failed, gone: dead.length, configured: true, deliveries };
+}
+export const sendToAll = (payload, opts = {}) => deliver(subs, payload, opts);
+export const sendToSession = (session, payload, opts = {}) => deliver(subs.filter((s) => s.boundSessions.includes(session)), payload, opts);
+export const sendToDevices = (keys, payload, opts = {}) => deliver(subs.filter((s) => typeof s.pushKey === 'string' && keys.includes(s.pushKey)), payload, opts);
+// Union of the given sessions, deduped: a device bound to several of them is still delivered once
+// (deliver() iterates the record list, so each record appears at most once here).
+export const sendToSessions = (sessions, payload, opts = {}) => deliver(subs.filter((s) => s.boundSessions.some((x) => sessions.includes(x))), payload, opts);
+// The pushKeys a given scope resolves to (mirrors sendToDevices/sendToSessions/sendToAll targeting) — used
+// by the inbox to write a record into exactly the devices a manual push is delivered to.
+export const resolveTargetKeys = ({ devices, sessions } = {}) => {
+    const pick = (devices && devices.length)
+        ? subs.filter((s) => typeof s.pushKey === 'string' && devices.includes(s.pushKey))
+        : (sessions && sessions.length)
+            ? subs.filter((s) => s.boundSessions.some((x) => sessions.includes(x)))
+            : subs;
+    return [...new Set(pick.map((s) => s.pushKey).filter((key) => typeof key === 'string'))];
+};
+// Back-compat: the /push/subscribe welcome still pushes to a single just-added subscription.
+export async function sendToOne(sub, payload, opts = {}) {
+    const parsed = parsePushSubscription(sub);
+    if (!parsed)
+        return { sent: 0, failed: 1, gone: 0, configured: isConfigured(), deliveries: [] };
+    const rec = subs.find((s) => s.subscription.endpoint === parsed.endpoint)
+        ?? { subscription: parsed, boundSessions: [] };
+    return deliver([rec], payload, opts);
+}