@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/pid-lock.js

@@ -0,0 +1,170 @@
+import { open, readFile, unlink, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { hostname } from "node:os";
+import { z } from "zod";
+export const pidLockInfoSchema = z.object({
+    pid: z.number(),
+    startedAt: z.string(),
+    hostname: z.string(),
+    uid: z.number(),
+    listen: z.string().nullable(),
+    desktopManaged: z.boolean().optional(),
+});
+function parsePidLockInfo(raw) {
+    const result = pidLockInfoSchema.safeParse(raw);
+    return result.success ? result.data : null;
+}
+function isErrnoException(err) {
+    return err instanceof Error && "code" in err;
+}
+export class PidLockError extends Error {
+    constructor(message, existingLock) {
+        super(message);
+        this.existingLock = existingLock;
+        this.name = "PidLockError";
+    }
+}
+function isPidRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getPidFilePath(paseoHome) {
+    return join(paseoHome, "paseo.pid");
+}
+function resolveOwnerPid(ownerPid) {
+    if (typeof ownerPid === "number" && Number.isInteger(ownerPid) && ownerPid > 0) {
+        return ownerPid;
+    }
+    return process.pid;
+}
+export async function acquirePidLock(paseoHome, listen, options) {
+    const pidPath = getPidFilePath(paseoHome);
+    // Ensure paseoHome directory exists
+    if (!existsSync(paseoHome)) {
+        await mkdir(paseoHome, { recursive: true });
+    }
+    // Try to read existing lock
+    let existingLock = null;
+    try {
+        const content = await readFile(pidPath, "utf-8");
+        existingLock = parsePidLockInfo(JSON.parse(content));
+    }
+    catch {
+        // No existing lock or invalid JSON - that's fine
+    }
+    // Check if existing lock is stale
+    const lockOwnerPid = resolveOwnerPid(options?.ownerPid);
+    if (existingLock) {
+        if (isPidRunning(existingLock.pid)) {
+            if (existingLock.pid === lockOwnerPid) {
+                return;
+            }
+            throw new PidLockError(`Another Paseo daemon is already running (PID ${existingLock.pid}, started ${existingLock.startedAt})`, existingLock);
+        }
+        // Stale lock - remove it
+        await unlink(pidPath).catch(() => { });
+    }
+    // Create new lock with exclusive flag
+    const lockInfo = {
+        pid: lockOwnerPid,
+        startedAt: new Date().toISOString(),
+        hostname: hostname(),
+        uid: process.getuid?.() ?? 0,
+        listen,
+        ...(process.env.PASEO_DESKTOP_MANAGED === "1" ? { desktopManaged: true } : {}),
+    };
+    let fd;
+    try {
+        fd = await open(pidPath, "wx");
+        await fd.write(JSON.stringify(lockInfo));
+    }
+    catch (err) {
+        if (isErrnoException(err) && err.code === "EEXIST") {
+            // Race condition - another process created the file
+            // Re-read and check
+            try {
+                const content = await readFile(pidPath, "utf-8");
+                const raceLock = parsePidLockInfo(JSON.parse(content));
+                if (raceLock) {
+                    throw new PidLockError(`Another Paseo daemon is already running (PID ${raceLock.pid})`, raceLock);
+                }
+                throw new PidLockError("Failed to acquire PID lock due to race condition");
+            }
+            catch (innerErr) {
+                if (innerErr instanceof PidLockError)
+                    throw innerErr;
+                throw new PidLockError("Failed to acquire PID lock due to race condition");
+            }
+        }
+        throw err;
+    }
+    finally {
+        await fd?.close();
+    }
+}
+export async function updatePidLock(paseoHome, patch, options) {
+    const pidPath = getPidFilePath(paseoHome);
+    const lockOwnerPid = resolveOwnerPid(options?.ownerPid);
+    const content = await readFile(pidPath, "utf-8");
+    const existingLock = parsePidLockInfo(JSON.parse(content));
+    if (!existingLock) {
+        throw new PidLockError("Cannot update PID lock: invalid lock file");
+    }
+    if (existingLock.pid !== lockOwnerPid) {
+        throw new PidLockError(`Cannot update PID lock owned by PID ${existingLock.pid}`, existingLock);
+    }
+    const updatedLock = {
+        ...existingLock,
+        ...patch,
+    };
+    const fd = await open(pidPath, "r+");
+    try {
+        await fd.truncate(0);
+        await fd.writeFile(JSON.stringify(updatedLock));
+    }
+    finally {
+        await fd.close();
+    }
+}
+export async function releasePidLock(paseoHome, options) {
+    const pidPath = getPidFilePath(paseoHome);
+    const lockOwnerPid = resolveOwnerPid(options?.ownerPid);
+    try {
+        // Only remove if it's our lock
+        const content = await readFile(pidPath, "utf-8");
+        const lock = parsePidLockInfo(JSON.parse(content));
+        if (lock?.pid === lockOwnerPid) {
+            await unlink(pidPath);
+        }
+    }
+    catch {
+        // Ignore errors - lock may already be gone
+    }
+}
+export async function getPidLockInfo(paseoHome) {
+    const pidPath = getPidFilePath(paseoHome);
+    try {
+        const content = await readFile(pidPath, "utf-8");
+        return parsePidLockInfo(JSON.parse(content));
+    }
+    catch {
+        return null;
+    }
+}
+export async function isLocked(paseoHome) {
+    const info = await getPidLockInfo(paseoHome);
+    if (!info) {
+        return { locked: false };
+    }
+    if (!isPidRunning(info.pid)) {
+        return { locked: false, info };
+    }
+    return { locked: true, info };
+}
+//# sourceMappingURL=pid-lock.js.map

package/dist/server/server/private-files.d.ts

@@ -0,0 +1,6 @@
+export declare const PRIVATE_DIRECTORY_MODE = 448;
+export declare const PRIVATE_FILE_MODE = 384;
+export declare function ensurePrivateDirectory(directoryPath: string): void;
+export declare function ensurePrivateFile(filePath: string): void;
+export declare function writePrivateFileAtomicSync(filePath: string, data: string | NodeJS.ArrayBufferView): void;
+//# sourceMappingURL=private-files.d.ts.map

package/dist/server/server/private-files.js

@@ -0,0 +1,37 @@
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+export const PRIVATE_DIRECTORY_MODE = 0o700;
+export const PRIVATE_FILE_MODE = 0o600;
+function chmodBestEffort(targetPath, mode) {
+    if (process.platform === "win32") {
+        return;
+    }
+    try {
+        chmodSync(targetPath, mode);
+    }
+    catch {
+        // Keep startup resilient if the filesystem does not support POSIX modes.
+    }
+}
+export function ensurePrivateDirectory(directoryPath) {
+    mkdirSync(directoryPath, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });
+    chmodBestEffort(directoryPath, PRIVATE_DIRECTORY_MODE);
+}
+export function ensurePrivateFile(filePath) {
+    chmodBestEffort(filePath, PRIVATE_FILE_MODE);
+}
+export function writePrivateFileAtomicSync(filePath, data) {
+    ensurePrivateDirectory(path.dirname(filePath));
+    const tmpPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        writeFileSync(tmpPath, data, { mode: PRIVATE_FILE_MODE });
+        renameSync(tmpPath, filePath);
+        ensurePrivateFile(filePath);
+    }
+    catch (error) {
+        rmSync(tmpPath, { force: true });
+        throw error;
+    }
+}
+//# sourceMappingURL=private-files.js.map

package/dist/server/server/process-diagnostics.d.ts

@@ -0,0 +1,17 @@
+export interface ProcessMemoryDiagnostics {
+    rss: number;
+    heapTotal: number;
+    heapUsed: number;
+    external: number;
+    arrayBuffers: number;
+}
+export interface ProcessDiagnostics {
+    pid: number;
+    ppid: number;
+    uptimeSeconds: number;
+    memory: ProcessMemoryDiagnostics;
+}
+export declare function getProcessMemoryDiagnostics(): ProcessMemoryDiagnostics;
+export declare function getProcessUptimeSeconds(): number;
+export declare function getProcessDiagnostics(): ProcessDiagnostics;
+//# sourceMappingURL=process-diagnostics.d.ts.map

package/dist/server/server/process-diagnostics.js

@@ -0,0 +1,22 @@
+export function getProcessMemoryDiagnostics() {
+    const memory = process.memoryUsage();
+    return {
+        rss: memory.rss,
+        heapTotal: memory.heapTotal,
+        heapUsed: memory.heapUsed,
+        external: memory.external,
+        arrayBuffers: memory.arrayBuffers,
+    };
+}
+export function getProcessUptimeSeconds() {
+    return Math.round(process.uptime() * 1000) / 1000;
+}
+export function getProcessDiagnostics() {
+    return {
+        pid: process.pid,
+        ppid: process.ppid,
+        uptimeSeconds: getProcessUptimeSeconds(),
+        memory: getProcessMemoryDiagnostics(),
+    };
+}
+//# sourceMappingURL=process-diagnostics.js.map

package/dist/server/server/push/categories.d.ts

@@ -0,0 +1,35 @@
+import type { PushTriggerKind } from "./triggers.js";
+/**
+ * Story 6.4 / D.1 (FR4.1) — Lock-Screen permission approval category.
+ *
+ * iOS renders interactive notification action buttons when a push carries a
+ * `categoryId` that matches a category the app registered at runtime via
+ * `Notifications.setNotificationCategoryAsync`. This module is the single
+ * server-side source of truth for that category's identifier + actions so the
+ * push payload (`expo-worker.ts`) and the app's runtime registration agree.
+ *
+ * The two actions are BACKGROUND actions (`opensAppToForeground: false`) so
+ * tapping Approve / Reject on the Lock Screen dispatches the decision over the
+ * daemon WebSocket WITHOUT foregrounding the app (the AC).
+ */
+export declare const PERMISSION_REQUEST_CATEGORY_ID = "agent_permission_request";
+export declare const PERMISSION_ACTION_APPROVE = "approve";
+export declare const PERMISSION_ACTION_REJECT = "reject";
+export interface NotificationActionDefinition {
+    identifier: string;
+    buttonTitle: string;
+    /** false = background action that does NOT bring the app to the foreground. */
+    opensAppToForeground: boolean;
+}
+export interface NotificationCategoryDefinition {
+    identifier: string;
+    actions: NotificationActionDefinition[];
+}
+export declare const PERMISSION_REQUEST_CATEGORY: NotificationCategoryDefinition;
+/**
+ * Map a push trigger kind to the iOS notification `categoryId` to attach.
+ * Only permission requests carry the interactive Approve/Reject category;
+ * every other kind returns `null` (a plain notification with no actions).
+ */
+export declare function resolvePushCategoryId(kind: PushTriggerKind): string | null;
+//# sourceMappingURL=categories.d.ts.map

package/dist/server/server/push/categories.js

@@ -0,0 +1,40 @@
+/**
+ * Story 6.4 / D.1 (FR4.1) — Lock-Screen permission approval category.
+ *
+ * iOS renders interactive notification action buttons when a push carries a
+ * `categoryId` that matches a category the app registered at runtime via
+ * `Notifications.setNotificationCategoryAsync`. This module is the single
+ * server-side source of truth for that category's identifier + actions so the
+ * push payload (`expo-worker.ts`) and the app's runtime registration agree.
+ *
+ * The two actions are BACKGROUND actions (`opensAppToForeground: false`) so
+ * tapping Approve / Reject on the Lock Screen dispatches the decision over the
+ * daemon WebSocket WITHOUT foregrounding the app (the AC).
+ */
+export const PERMISSION_REQUEST_CATEGORY_ID = "agent_permission_request";
+export const PERMISSION_ACTION_APPROVE = "approve";
+export const PERMISSION_ACTION_REJECT = "reject";
+export const PERMISSION_REQUEST_CATEGORY = {
+    identifier: PERMISSION_REQUEST_CATEGORY_ID,
+    actions: [
+        {
+            identifier: PERMISSION_ACTION_APPROVE,
+            buttonTitle: "Approve",
+            opensAppToForeground: false,
+        },
+        {
+            identifier: PERMISSION_ACTION_REJECT,
+            buttonTitle: "Reject",
+            opensAppToForeground: false,
+        },
+    ],
+};
+/**
+ * Map a push trigger kind to the iOS notification `categoryId` to attach.
+ * Only permission requests carry the interactive Approve/Reject category;
+ * every other kind returns `null` (a plain notification with no actions).
+ */
+export function resolvePushCategoryId(kind) {
+    return kind === "permission_needed" ? PERMISSION_REQUEST_CATEGORY_ID : null;
+}
+//# sourceMappingURL=categories.js.map

package/dist/server/server/push/expo-worker.d.ts

@@ -0,0 +1,51 @@
+import type pino from "pino";
+import { type ExpoPushMessage, type ExpoPushReceipt, type ExpoPushTicket } from "expo-server-sdk";
+import type { PushTriggerEmitter } from "./triggers.js";
+/**
+ * Story PASEO-CHAT-ACTIONS-V1-story-1.003 — Expo Push delivery worker.
+ *
+ * Subscribes to the pushTrigger emitter from Story 1.1, fans out one Expo Push
+ * message per registered Expo token (from Story 1.2 store), and reaps receipts
+ * after a configurable delay to detect DeviceNotRegistered (token cleanup).
+ *
+ * Honors PASEO_PUSH_ENABLED=false as a kill switch (mirrors the epic Rollback
+ * Plan). Errors from the Expo HTTPS API are logged and swallowed — the daemon
+ * never crashes on push failure.
+ */
+export interface ExpoSubscriptionStore {
+    listExpoTokens(): string[];
+    removeExpoToken(token: string): void;
+}
+export interface ExpoWorkerEnv {
+    PASEO_PUSH_ENABLED?: string;
+    EXPO_ACCESS_TOKEN?: string;
+}
+export interface ExpoWorkerClient {
+    chunkPushNotifications(messages: ExpoPushMessage[]): ExpoPushMessage[][];
+    sendPushNotificationsAsync(messages: ExpoPushMessage[]): Promise<ExpoPushTicket[]>;
+    chunkPushNotificationReceiptIds(ids: string[]): string[][];
+    getPushNotificationReceiptsAsync(ids: string[]): Promise<{
+        [id: string]: ExpoPushReceipt;
+    }>;
+}
+export interface StartExpoPushWorkerOptions {
+    pushTrigger: PushTriggerEmitter;
+    subscriptionStore: ExpoSubscriptionStore;
+    logger: pino.Logger;
+    env?: ExpoWorkerEnv;
+    /** Override for tests. Production calls `new Expo({ accessToken })`. */
+    clientFactory?: (env: ExpoWorkerEnv) => ExpoWorkerClient;
+    /** Receipt-fetch delay; Expo requires ≥15 min in production. Tests override. */
+    receiptDelayMs?: number;
+    /** Override for tests. Used to schedule the deferred receipt fetch. */
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    /** Override for tests. Used to cancel scheduled receipt fetches on stop(). */
+    clearTimer?: (handle: unknown) => void;
+    /** Token-validator hook. Defaults to `Expo.isExpoPushToken`. */
+    isExpoPushToken?: (value: unknown) => boolean;
+}
+export interface ExpoPushWorker {
+    stop(): void;
+}
+export declare function startExpoPushWorker(options: StartExpoPushWorkerOptions): ExpoPushWorker;
+//# sourceMappingURL=expo-worker.d.ts.map

package/dist/server/server/push/expo-worker.js

@@ -0,0 +1,188 @@
+import { Expo, } from "expo-server-sdk";
+import { resolvePushCategoryId } from "./categories.js";
+const DEFAULT_RECEIPT_DELAY_MS = 15 * 60 * 1000;
+const BODY_BY_KIND = {
+    completed: "Agent finished",
+    permission_needed: "Permission needed",
+    input_required: "Waiting for your input",
+};
+export function startExpoPushWorker(options) {
+    const { pushTrigger, subscriptionStore, logger } = options;
+    const env = options.env ?? process.env;
+    const workerLogger = logger.child({ component: "expo-push-worker" });
+    if (env.PASEO_PUSH_ENABLED === "false") {
+        workerLogger.info("expo push worker disabled by PASEO_PUSH_ENABLED=false");
+        return { stop() { } };
+    }
+    const isExpoPushToken = options.isExpoPushToken ?? Expo.isExpoPushToken.bind(Expo);
+    const setTimer = options.setTimer ??
+        ((fn, ms) => setTimeout(fn, ms));
+    const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+    const client = options.clientFactory?.(env) ??
+        new Expo({ accessToken: env.EXPO_ACCESS_TOKEN });
+    const receiptDelayMs = options.receiptDelayMs ?? DEFAULT_RECEIPT_DELAY_MS;
+    const pendingReceiptBatches = new Set();
+    workerLogger.info("expo push worker started");
+    const unsubscribe = pushTrigger.on((payload) => {
+        void dispatch(payload).catch((err) => {
+            workerLogger.error({ err, sessionId: payload.sessionId, kind: payload.kind }, "expo push dispatch failed");
+        });
+    });
+    /**
+     * Per-message fallback for a chunk the Expo API refused outright. Returns tickets
+     * positionally aligned with `chunk` so the caller's ticket loop still maps ticket ->
+     * token; a message that fails on its own contributes an error ticket rather than
+     * dropping out and shifting every index after it.
+     */
+    async function sendOneByOne(chunk, payload) {
+        const tickets = [];
+        let delivered = 0;
+        for (const message of chunk) {
+            try {
+                const [ticket] = await client.sendPushNotificationsAsync([message]);
+                if (ticket) {
+                    tickets.push(ticket);
+                    if (ticket.status !== "error")
+                        delivered += 1;
+                    continue;
+                }
+            }
+            catch (err) {
+                workerLogger.warn({ err, sessionId: payload.sessionId, kind: payload.kind }, "expo push rejected for a single token — skipping that device only");
+            }
+            tickets.push({ status: "error", message: "send rejected" });
+        }
+        workerLogger.info({ sessionId: payload.sessionId, kind: payload.kind, delivered, of: chunk.length }, "expo push retried one-by-one after a whole-chunk rejection");
+        return tickets;
+    }
+    async function dispatch(payload) {
+        const tokens = subscriptionStore.listExpoTokens();
+        if (tokens.length === 0)
+            return;
+        const messages = [];
+        for (const token of tokens) {
+            if (!isExpoPushToken(token)) {
+                workerLogger.warn({ token, sessionId: payload.sessionId, kind: payload.kind }, "invalid expo push token — removing from store");
+                subscriptionStore.removeExpoToken(token);
+                continue;
+            }
+            // D.1 — permission pushes carry the iOS interactive category so the Lock
+            // Screen renders Approve/Reject; the requestId rides in `data` so the
+            // background action handler can resolve the decision (NFR1: both fields
+            // are additive and ignored by older app builds).
+            const categoryId = resolvePushCategoryId(payload.kind);
+            messages.push({
+                to: token,
+                sound: "default",
+                title: payload.agentTitle,
+                body: BODY_BY_KIND[payload.kind],
+                ...(categoryId ? { categoryId } : {}),
+                data: {
+                    deepLink: payload.deepLink,
+                    webPath: payload.webPath,
+                    serverId: payload.serverId,
+                    sessionId: payload.sessionId,
+                    agentId: payload.agentId,
+                    kind: payload.kind,
+                    ...(payload.requestId ? { requestId: payload.requestId } : {}),
+                    ...(categoryId ? { categoryId } : {}),
+                },
+            });
+        }
+        if (messages.length === 0)
+            return;
+        const chunks = client.chunkPushNotifications(messages);
+        const ticketsByReceiptId = new Map();
+        for (const chunk of chunks) {
+            let tickets;
+            try {
+                tickets = await client.sendPushNotificationsAsync(chunk);
+            }
+            catch (err) {
+                // A chunk is rejected WHOLE, so one bad token silences every other device in it.
+                // The live case: Expo refuses a request whose tokens span two projects ("All push
+                // notification messages in the same request must be for the same project"), and
+                // chunkPushNotifications only splits by COUNT, so a phone registered against a
+                // second build takes the whole batch down with it. A token carries no project id,
+                // so grouping up front is not possible; retrying one-by-one is. Observed
+                // 2026-08-21: the "agent needs your attention" push for a pending AskUserQuestion
+                // never landed and the question sat unanswered for 1h38m.
+                workerLogger.error({ err, sessionId: payload.sessionId, kind: payload.kind, count: chunk.length }, "sendPushNotificationsAsync rejected");
+                if (chunk.length <= 1)
+                    continue;
+                tickets = await sendOneByOne(chunk, payload);
+                if (tickets.length === 0)
+                    continue;
+            }
+            tickets.forEach((ticket, idx) => {
+                const token = String(chunk[idx]?.to ?? "");
+                if (ticket.status === "error") {
+                    const details = ticket.details;
+                    if (details?.error === "DeviceNotRegistered" && token) {
+                        workerLogger.warn({ sessionId: payload.sessionId, kind: payload.kind }, "DeviceNotRegistered ticket — removing token");
+                        subscriptionStore.removeExpoToken(token);
+                    }
+                    else {
+                        workerLogger.error({ ticket, sessionId: payload.sessionId, kind: payload.kind }, "expo push ticket error");
+                    }
+                    return;
+                }
+                if (ticket.id && token) {
+                    ticketsByReceiptId.set(ticket.id, token);
+                }
+            });
+        }
+        workerLogger.info({ tokens: messages.length, sessionId: payload.sessionId, kind: payload.kind }, "expo push batch sent");
+        if (ticketsByReceiptId.size === 0)
+            return;
+        const batch = { ticketsByReceiptId, handle: null };
+        const handle = setTimer(() => {
+            pendingReceiptBatches.delete(batch);
+            void reapReceipts(batch).catch((err) => {
+                workerLogger.error({ err }, "reapReceipts threw");
+            });
+        }, receiptDelayMs);
+        batch.handle = handle;
+        pendingReceiptBatches.add(batch);
+    }
+    async function reapReceipts(batch) {
+        const ids = Array.from(batch.ticketsByReceiptId.keys());
+        if (ids.length === 0)
+            return;
+        const idChunks = client.chunkPushNotificationReceiptIds(ids);
+        for (const idChunk of idChunks) {
+            let receipts;
+            try {
+                receipts = await client.getPushNotificationReceiptsAsync(idChunk);
+            }
+            catch (err) {
+                workerLogger.error({ err }, "getPushNotificationReceiptsAsync rejected");
+                continue;
+            }
+            for (const [receiptId, receipt] of Object.entries(receipts)) {
+                if (receipt.status !== "error")
+                    continue;
+                const errReceipt = receipt;
+                const token = batch.ticketsByReceiptId.get(receiptId);
+                if (errReceipt.details?.error === "DeviceNotRegistered" && token) {
+                    workerLogger.warn({ receiptId }, "DeviceNotRegistered receipt — removing token");
+                    subscriptionStore.removeExpoToken(token);
+                }
+                else {
+                    workerLogger.error({ receipt }, "expo push receipt error");
+                }
+            }
+        }
+    }
+    return {
+        stop() {
+            unsubscribe();
+            for (const batch of pendingReceiptBatches) {
+                clearTimer(batch.handle);
+            }
+            pendingReceiptBatches.clear();
+            workerLogger.info("expo push worker stopped");
+        },
+    };
+}
+//# sourceMappingURL=expo-worker.js.map

package/dist/server/server/push/index.d.ts

@@ -0,0 +1,39 @@
+import type { Logger } from "pino";
+import type { AgentManager } from "../agent/agent-manager.js";
+import type { PushSubscriptionStore } from "./subscriptions.js";
+import { type PushTriggerEmitter } from "./triggers.js";
+import type { VapidKeys } from "./vapid-keys.js";
+export type { PushTriggerEmitter, PushTriggerKind, PushTriggerPayload } from "./triggers.js";
+export interface PushSubsystem {
+    triggerEmitter: PushTriggerEmitter;
+    /**
+     * Tear down all push-subsystem subscriptions (attention listener, worker, etc.).
+     */
+    dispose(): void;
+}
+export interface CreatePushSubsystemOptions {
+    agentManager: AgentManager;
+    serverId: string;
+    logger: Logger;
+    /**
+     * Story PASEO-CHAT-ACTIONS-V1-story-1.002 subscription store. When provided,
+     * Story 1.3 starts the Expo Push delivery worker against this store, and
+     * Story 1.4 starts the Web Push worker (if `vapidKeys` is also provided).
+     */
+    subscriptionStore?: PushSubscriptionStore;
+    /**
+     * Story PASEO-CHAT-ACTIONS-V1-story-1.004 VAPID key pair. When provided
+     * (alongside `subscriptionStore`), the Web Push delivery worker is started.
+     */
+    vapidKeys?: VapidKeys;
+}
+/**
+ * Composition root for the push subsystem. Stories 1.3 (Expo worker) and 1.4
+ * (Web Push worker) attach to `triggerEmitter.on(...)` here.
+ *
+ * Honors the `PASEO_PUSH_ENABLED=false` kill switch at the emitter layer —
+ * downstream workers also re-check the env var as a defense in depth (the
+ * worker logs a specific disabled-message that the rollback runbook greps for).
+ */
+export declare function createPushSubsystem(options: CreatePushSubsystemOptions): PushSubsystem;
+//# sourceMappingURL=index.d.ts.map

package/dist/server/server/push/index.js

@@ -0,0 +1,45 @@
+import { startExpoPushWorker } from "./expo-worker.js";
+import { startWebPushWorker } from "./web-worker.js";
+import { createPushTriggerEmitter } from "./triggers.js";
+/**
+ * Composition root for the push subsystem. Stories 1.3 (Expo worker) and 1.4
+ * (Web Push worker) attach to `triggerEmitter.on(...)` here.
+ *
+ * Honors the `PASEO_PUSH_ENABLED=false` kill switch at the emitter layer —
+ * downstream workers also re-check the env var as a defense in depth (the
+ * worker logs a specific disabled-message that the rollback runbook greps for).
+ */
+export function createPushSubsystem(options) {
+    const triggerEmitter = createPushTriggerEmitter({
+        agentManager: options.agentManager,
+        serverId: options.serverId,
+        logger: options.logger,
+    });
+    const unsubscribeAttention = triggerEmitter.subscribeToAttention();
+    let expoWorker = null;
+    let webWorker = null;
+    if (options.subscriptionStore) {
+        expoWorker = startExpoPushWorker({
+            pushTrigger: triggerEmitter,
+            subscriptionStore: options.subscriptionStore,
+            logger: options.logger,
+        });
+        if (options.vapidKeys) {
+            webWorker = startWebPushWorker({
+                pushTrigger: triggerEmitter,
+                subscriptionStore: options.subscriptionStore,
+                vapidKeys: options.vapidKeys,
+                logger: options.logger,
+            });
+        }
+    }
+    return {
+        triggerEmitter,
+        dispose() {
+            unsubscribeAttention();
+            expoWorker?.stop();
+            webWorker?.stop();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/server/server/push/notifications.d.ts

@@ -0,0 +1,9 @@
+import type pino from "pino";
+import { type PushPayload } from "./push-service.js";
+import type { PushTokenStore } from "./token-store.js";
+export type { PushPayload };
+export interface PushNotificationSender {
+    send(payload: PushPayload): Promise<void>;
+}
+export declare function createPushNotificationSender(logger: pino.Logger, tokenStore: PushTokenStore): PushNotificationSender;
+//# sourceMappingURL=notifications.d.ts.map