@haywoodmarx/agent-pager 0.1.0

package/dist/src/launch/service.d.ts

@@ -0,0 +1,173 @@
+import type { Broker, BrokerOptions } from "../broker/broker.js";
+import { ProtocolError } from "../broker/protocol.js";
+import { type PagerConfig } from "../configuration-defaults.js";
+import { type SnapshotBrokerPort } from "../broker/snapshot.js";
+import { ImplementationRegistry } from "../implementations/registry.js";
+import { type McpBrokerPort } from "../messaging/mcp.js";
+import { type PushDeliveryBroker } from "../messaging/push-delivery.js";
+import { type OperatorCommandBrokerPort } from "../operator/commands.js";
+import { type OperatorTransportSchedulerPort } from "../operator/transport.js";
+import { type OperatorUpdateSourcePort } from "../operator/updates.js";
+import { type BrokerLockOwner } from "./broker-lock.js";
+export { systemWorkspaceBranch } from "./workspace-branch.js";
+/** Schedules the service's timers, none of which may keep the process alive. */
+export interface BrokerServiceSchedulerPort extends OperatorTransportSchedulerPort {
+    /**
+     * Schedule one callback.
+     * @param callback - Work invoked once the delay has elapsed.
+     * @param delayMs - Non-negative delay in milliseconds, of any size.
+     * @returns A callback that cancels the invocation if it has not yet run.
+     */
+    once(callback: () => void, delayMs: number): () => void;
+}
+/** Filesystem operations the service performs on its database and the files beside it. */
+export type BrokerServiceFilesystemPort = {
+    /**
+     * Report whether a path exists.
+     * @param path - Absolute path to test.
+     * @returns - True when the path exists.
+     */
+    exists(path: string): boolean;
+    /**
+     * Report a file's size.
+     * @param path - Existing file.
+     * @returns - Size in bytes.
+     */
+    sizeOf(path: string): number;
+    /**
+     * Delete a file.
+     * @param path - Existing file.
+     */
+    remove(path: string): void;
+    /**
+     * Create a directory and any missing parents.
+     * @param path - Directory that must exist afterwards.
+     */
+    createDirectory(path: string): void;
+};
+/** Broker operations the service, and every endpoint it composes, reach. */
+export type BrokerServiceBrokerPort = Pick<Broker, "epoch" | "reapExpiredReservations" | "subscribeCommits" | "nextSweepDelayMs" | "reapTerminalAgents" | "dueRedeliveryWakes" | "recordRedeliveryAttempt" | "close"> & PushDeliveryBroker & McpBrokerPort & SnapshotBrokerPort & OperatorCommandBrokerPort & OperatorUpdateSourcePort;
+/** Reports that a configured loopback endpoint could not take its port. */
+export declare class EndpointPortUnavailableError extends ProtocolError {
+    /** Names the endpoint whose port is unavailable. */
+    readonly endpoint: string;
+    /** Names the interface the endpoint attempted to bind. */
+    readonly host: string;
+    /** Records the requested TCP port. */
+    readonly port: number;
+    /**
+     * Constructs a startup failure naming the endpoint that could not bind.
+     * @param endpoint - Human-facing name of the endpoint being started.
+     * @param host - Interface the endpoint attempted to bind.
+     * @param port - Requested TCP port.
+     * @param cause - Operating-system error code that rejected the bind.
+     */
+    constructor(
+    /** Names the endpoint whose port is unavailable. */
+    endpoint: string, 
+    /** Names the interface the endpoint attempted to bind. */
+    host: string, 
+    /** Records the requested TCP port. */
+    port: number, cause: string);
+}
+/** Supplies validated configuration and path metadata to a broker service. */
+export type BrokerServiceOptions = {
+    /**
+     * Supplies the one clock this service process runs on.
+     *
+     * Every component the service composes stamps work that is read against rows the others write;
+     * two clocks between them produce an ordering none of them agreed to. Required of the caller
+     * rather than defaulted here, so that "one clock" is a property the composition root states and a test can substitute.
+     */
+    now: () => number;
+    /**
+     * Receives the diagnostics this service and the components it composes report, including each
+     * failing step of `stop()`, the first of which it also rejects with.
+     *
+     * One sink, so an operator reading it does not have to know which component spoke. The broker's
+     * schema preparation is the exception: it writes to standard error itself.
+     * @param message - Operator-facing diagnostic, never model-facing and never a process binding.
+     */
+    report: (message: string) => void;
+    /** Owns every timer the service arms. */
+    scheduler: BrokerServiceSchedulerPort;
+    /** Watches for the database's removal and tidies the files beside it. */
+    filesystem: BrokerServiceFilesystemPort;
+    /**
+     * Constructs the broker this service owns for the life of its process.
+     *
+     * A dependency built fresh per session from a value resolved late (the database path and the
+     * config `start()` resolves), so it takes a factory rather than a constructed instance.
+     */
+    openBroker: (databasePath: string, options: BrokerOptions) => BrokerServiceBrokerPort;
+    /**
+     * Holds the exclusive claim on the database.
+     *
+     * Must own the lock at `brokerLockPath` of the database path: that is where every adopting caller
+     * reads the endpoints this service publishes. The service reports the path the lock names.
+     */
+    lock: BrokerLockOwner;
+    /** Supplies validated runtime policies and deterministic server endpoints. */
+    config?: PagerConfig;
+    /** Names the resolved user configuration file for diagnostics. */
+    configPath?: string | null;
+    /** Names the user store directory when configuration is supplied. */
+    storeDirectory?: string;
+};
+/** Describes the active loopback endpoints published by the singleton broker service. */
+export type BrokerServiceStatus = {
+    /** Identifies the process serving the endpoints. */
+    pid: number;
+    /** Identifies the current broker generation. */
+    epoch: string;
+    /** Names the durable broker database. */
+    databasePath: string;
+    /** Names the exclusive service lock. */
+    lockPath: string;
+    /** Locates the shared MCP endpoint. */
+    mcpUrl: string;
+    /** Locates the shared snapshot origin. */
+    snapshotUrl: string;
+    /** Locates the operator update stream, or reports that only this endpoint is unavailable. */
+    operatorUrl: string | null;
+};
+/** Runs one durable broker and its loopback endpoints under an exclusive process lock. */
+export declare class BrokerService {
+    #private;
+    /**
+     * Constructs a service with the durable database and adjacent lock-file locations.
+     * @param databasePath - Durable SQLite file owned by the service.
+     * @param implementations - Registry supplying implementation notification capabilities.
+     * @param options - Validated runtime settings and the ports the service runs on.
+     */
+    constructor(databasePath: string, implementations: ImplementationRegistry, options: BrokerServiceOptions);
+    /**
+     * Starts the exclusive broker service and returns its published loopback endpoints.
+     * @returns - Process ownership and endpoint details for the running service.
+     */
+    start(): Promise<BrokerServiceStatus>;
+    /**
+     * Returns the live service status after successful startup.
+     * @returns - Process ownership and endpoint details for the running service.
+     */
+    status(): BrokerServiceStatus;
+    /**
+     * Register what to do once this service finds its database gone.
+     *
+     * A handler registered before abandonment runs before the stop that follows it; one registered after
+     * runs at once, while that stop may still be in flight. Stopping releases the endpoints but cannot
+     * end a process parked waiting for a signal, so the owner of that wait decides how the process ends.
+     * @param handler - Invoked once the database this service serves has gone.
+     */
+    onAbandoned(handler: () => void): void;
+    /**
+     * Stops endpoints, closes the database, and releases this process's lock.
+     *
+     * A call made while a stop is in flight joins it, so any caller's settled stop means teardown has
+     * finished. Every close is attempted and the lock is released whatever the others do. Each failing
+     * step reaches the report sink, and the first one rejects. Sidecar cleanup runs only once every
+     * connection to the database has closed, is best effort, and reports nothing.
+     * @returns - Settles once teardown has finished.
+     */
+    stop(): Promise<void>;
+}

package/dist/src/launch/service.js

@@ -0,0 +1,492 @@
+import { randomBytes } from "node:crypto";
+import { dirname } from "node:path";
+import { ProtocolError } from "../broker/protocol.js";
+import { LOOPBACK_HOST } from "../configuration-defaults.js";
+import { initializePagerStore } from "../configuration.js";
+import { publicEpoch, startSnapshotServer, } from "../broker/snapshot.js";
+import { implementationId, ImplementationRegistry } from "../implementations/registry.js";
+import { startMcpServer } from "../messaging/mcp.js";
+import { NotificationHub, NotificationScheduler } from "../messaging/notifications.js";
+import { PushDeliveryService } from "../messaging/push-delivery.js";
+import { OperatorCommandService } from "../operator/commands.js";
+import { createSystemRepositoryProjectionDependencies } from "../operator/repository-system.js";
+import { issueOperatorClientId, startOperatorTransport, } from "../operator/transport.js";
+import { SqliteOperatorEventStore } from "../operator/update-store.js";
+import { OperatorUpdateService } from "../operator/updates.js";
+import { currentBrokerServiceIdentity } from "./broker-lock.js";
+import { systemWorkspaceBranch } from "./workspace-branch.js";
+export { systemWorkspaceBranch } from "./workspace-branch.js";
+/** Tables whose rows can move the moment a sweep next has work to do. */
+const SWEEP_DEADLINE_TABLES = ["agents", "sessions", "messages", "wakes"];
+/** Sets how often the watchdog checks that the database this service serves still exists. */
+const ABANDONMENT_WATCHDOG_INTERVAL_MS = 1_000;
+/** Sets how often the operator transport tells a connected client it is still alive. */
+const OPERATOR_HEARTBEAT_INTERVAL_MS = 5_000;
+/** Bounds how long the operator transport waits for a client before treating it as gone. */
+const OPERATOR_LIVENESS_TIMEOUT_MS = 15_000;
+/** Sets the entropy of an operator control id, in bytes. */
+const CONTROL_ID_BYTES = 12;
+/** Delays the retry after a sweep failed, so a persistent failure cannot spin on a due deadline. */
+const SWEEP_FAILURE_RETRY_MS = 1_000;
+/** Reports that a configured loopback endpoint could not take its port. */
+export class EndpointPortUnavailableError extends ProtocolError {
+    endpoint;
+    host;
+    port;
+    /**
+     * Constructs a startup failure naming the endpoint that could not bind.
+     * @param endpoint - Human-facing name of the endpoint being started.
+     * @param host - Interface the endpoint attempted to bind.
+     * @param port - Requested TCP port.
+     * @param cause - Operating-system error code that rejected the bind.
+     */
+    constructor(
+    /** Names the endpoint whose port is unavailable. */
+    endpoint, 
+    /** Names the interface the endpoint attempted to bind. */
+    host, 
+    /** Records the requested TCP port. */
+    port, cause) {
+        super("conflict", `${endpoint} endpoint cannot start: ${host}:${String(port)} is unavailable (${cause}). ` +
+            `Stop the process holding it, or set a different port in the Pager configuration.`);
+        this.endpoint = endpoint;
+        this.host = host;
+        this.port = port;
+    }
+}
+/**
+ * Start one loopback endpoint, reporting a port clash as a named startup failure.
+ * @param endpoint - Human-facing name used in the failure message.
+ * @param port - Requested port, where zero and undefined accept any free port.
+ * @param host - Requested interface.
+ * @param start - Operation that binds the endpoint.
+ * @returns - Started endpoint handle.
+ */
+async function bindEndpoint(endpoint, port, host, start) {
+    try {
+        return await start();
+    }
+    catch (error) {
+        const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
+        if (code !== "EADDRINUSE" && code !== "EACCES")
+            throw error;
+        throw new EndpointPortUnavailableError(endpoint, host, port ?? 0, code);
+    }
+}
+/** Runs one durable broker and its loopback endpoints under an exclusive process lock. */
+export class BrokerService {
+    #now;
+    #report;
+    #scheduler;
+    #filesystem;
+    #databasePath;
+    #lockPath;
+    #lock;
+    #implementations;
+    #options;
+    #broker;
+    #mcp;
+    #snapshot;
+    #operatorScheduler;
+    #pushDelivery;
+    #operatorUpdates;
+    #operatorTransport;
+    #cancelSweep;
+    #unsubscribeCommits;
+    #sweepFloorMs = 0;
+    #abandoned = false;
+    #cancelWatchdog;
+    #onAbandoned;
+    #stopping;
+    /**
+     * Constructs a service with the durable database and adjacent lock-file locations.
+     * @param databasePath - Durable SQLite file owned by the service.
+     * @param implementations - Registry supplying implementation notification capabilities.
+     * @param options - Validated runtime settings and the ports the service runs on.
+     */
+    constructor(databasePath, implementations, options) {
+        this.#databasePath = databasePath;
+        this.#implementations = implementations;
+        this.#options = options;
+        this.#now = options.now;
+        this.#report = options.report;
+        this.#scheduler = options.scheduler;
+        this.#filesystem = options.filesystem;
+        this.#lockPath = options.lock.path;
+        this.#lock = options.lock;
+    }
+    /**
+     * Starts the exclusive broker service and returns its published loopback endpoints.
+     * @returns - Process ownership and endpoint details for the running service.
+     */
+    async start() {
+        this.#lock.acquire();
+        try {
+            if (this.#options.config && this.#options.storeDirectory) {
+                initializePagerStore({
+                    config: this.#options.config,
+                    filePath: this.#options.configPath ?? null,
+                    storeDirectory: this.#options.storeDirectory,
+                });
+            }
+            else {
+                this.#filesystem.createDirectory(dirname(this.#databasePath));
+            }
+            const config = this.#options.config;
+            const now = this.#now;
+            this.#broker = this.#options.openBroker(this.#databasePath, {
+                now,
+                workspaceBranch: systemWorkspaceBranch,
+                report: this.#report,
+                ...(config
+                    ? {
+                        visibilityTimeoutMs: config.visibilityTimeoutMs,
+                        redeliveryBaseDelayMs: config.redeliveryBaseDelayMs,
+                        redeliveryGiveUpMs: config.redeliveryGiveUpMs,
+                        reservationTtlMs: config.reservationTtlMs,
+                        leaseTtlMs: config.leaseTtlMs,
+                        perPairRateLimit: config.perPairRateLimit,
+                        perPairRateWindowMs: config.perPairRateWindowMs,
+                        maxInboxMessages: config.maxInboxMessages,
+                    }
+                    : {}),
+            });
+            const broker = this.#broker;
+            const notifications = new NotificationHub(broker.epoch(), {
+                onSubscriberError: (failure) => {
+                    this.#report(`pager notification: a subscriber for ${failure.agentId} failed on event ${String(failure.sequence)}`);
+                },
+            });
+            const scheduler = new NotificationScheduler(broker, notifications, {
+                now,
+                ...(config ? { wakeBudget: config.wakeBudget, wakeBudgetWindowMs: config.wakeBudgetWindowMs } : {}),
+            });
+            this.#operatorScheduler = scheduler;
+            const implementations = this.#implementations;
+            const pushDelivery = new PushDeliveryService({
+                broker,
+                hub: notifications,
+                scheduler,
+                now,
+                capabilityFor: (id) => {
+                    let capability;
+                    try {
+                        capability = implementations.resolve(implementationId(id)).notification;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                    return capability.supported ? capability : undefined;
+                },
+                report: this.#report,
+            });
+            this.#pushDelivery = pushDelivery;
+            broker.reapExpiredReservations();
+            const bindHost = config?.bindHost ?? LOOPBACK_HOST;
+            this.#mcp = await bindEndpoint("MCP", config?.mcpPort, bindHost, () => startMcpServer({
+                broker,
+                port: config?.mcpPort,
+                notifications: {
+                    notifyMessage: scheduler.notifyMessage.bind(scheduler),
+                    registerDeliveryAddress: (agentId, raw) => {
+                        pushDelivery.registerAddress(agentId, raw);
+                    },
+                    forgetDeliveryAddress: (agentId) => {
+                        pushDelivery.forget(agentId);
+                    },
+                },
+                host: bindHost,
+                healthIdentity: currentBrokerServiceIdentity(),
+            }));
+            this.#snapshot = await bindEndpoint("snapshot", config?.snapshotPort, bindHost, () => startSnapshotServer(broker, config?.snapshotPort, bindHost));
+            await this.#startOperatorEndpoint();
+            const status = this.status();
+            this.#lock.publish({
+                ...currentBrokerServiceIdentity(),
+                pid: status.pid,
+                epoch: status.epoch,
+                mcpUrl: status.mcpUrl,
+                snapshotUrl: status.snapshotUrl,
+                ...(status.operatorUrl ? { operatorUrl: status.operatorUrl } : {}),
+            });
+            this.#unsubscribeCommits = broker.subscribeCommits((commit) => {
+                if (commit.tables === undefined || SWEEP_DEADLINE_TABLES.some((table) => commit.tables?.has(table))) {
+                    this.#scheduleSweep();
+                }
+            });
+            this.#scheduleSweep();
+            this.#armAbandonmentWatchdog();
+            return status;
+        }
+        catch (error) {
+            // Teardown failures reach the report sink; the startup failure is the one the caller must see.
+            await this.stop().catch(() => undefined);
+            throw error;
+        }
+    }
+    /**
+     * Arm one sweep for the moment the broker says work could next exist.
+     *
+     * Rearmed after every sweep and after any commit that could move a deadline, so an idle broker
+     * holds no armed timer at all.
+     */
+    #scheduleSweep() {
+        this.#cancelSweep?.();
+        this.#cancelSweep = undefined;
+        const delay = this.#broker?.nextSweepDelayMs();
+        if (delay === undefined || delay === null) {
+            this.#sweepFloorMs = 0;
+            return;
+        }
+        this.#cancelSweep = this.#scheduler.once(() => {
+            // Both the sweep and the rearm read the database, and a timer callback has no caller to
+            // catch either. An unguarded throw here would take down the process.
+            try {
+                // Ahead of reapTerminalAgents: its own ephemeral-lapsed reap covers the same never-attached
+                // rows and would silently win the race, deleting the reservation before this call could
+                // notify the parent.
+                this.#broker?.reapExpiredReservations();
+                this.#broker?.reapTerminalAgents();
+                this.#redeliverDueInboxes();
+                this.#sweepFloorMs = 0;
+                this.#scheduleSweep();
+            }
+            catch (error) {
+                this.#report(`pager sweep: ${error instanceof Error ? error.message : String(error)}`);
+                this.#sweepFloorMs = SWEEP_FAILURE_RETRY_MS;
+                this.#retrySweepAfterFailure();
+            }
+        }, Math.max(delay, this.#sweepFloorMs));
+    }
+    /**
+     * Wake every recipient the broker's redelivery schedule now owes another notification.
+     *
+     * The broker owns the schedule and the scheduler owns the wake, so this is the only place the two
+     * meet: neither can reach the other.
+     */
+    #redeliverDueInboxes() {
+        const broker = this.#broker;
+        const scheduler = this.#operatorScheduler;
+        if (!broker || !scheduler)
+            return;
+        for (const agentId of broker.dueRedeliveryWakes()) {
+            // The schedule has already been advanced for every recipient in this list, so one that throws
+            // must not take the wakes owed to the others with it.
+            try {
+                if (scheduler.retryUnclaimed(agentId) !== null)
+                    broker.recordRedeliveryAttempt(agentId);
+            }
+            catch (error) {
+                this.#report(`pager redelivery: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    /**
+     * Rearm after a failed sweep without reading the database again.
+     *
+     * The failure may have been the read itself, so the retry is scheduled from the floor rather than
+     * from a deadline this service cannot currently obtain.
+     */
+    #retrySweepAfterFailure() {
+        this.#cancelSweep = this.#scheduler.once(() => {
+            this.#scheduleSweep();
+        }, SWEEP_FAILURE_RETRY_MS);
+    }
+    /**
+     * Returns the live service status after successful startup.
+     * @returns - Process ownership and endpoint details for the running service.
+     */
+    status() {
+        if (!this.#broker || !this.#mcp || !this.#snapshot)
+            throw new Error("Broker service is not running");
+        return {
+            pid: process.pid,
+            epoch: this.#broker.epoch(),
+            databasePath: this.#databasePath,
+            lockPath: this.#lockPath,
+            mcpUrl: this.#mcp.url,
+            snapshotUrl: this.#snapshot.url,
+            operatorUrl: this.#operatorTransport?.url ?? null,
+        };
+    }
+    /**
+     * Watch for the database disappearing from under this service.
+     *
+     * Armed last in `start()`, once every component it builds is assigned, so the stop a tick begins
+     * closes all of them; a start that fails before then stops what it bound itself. The owner is told
+     * before the stop rather than after it, so it can end the process whether or not the stop finishes.
+     */
+    #armAbandonmentWatchdog() {
+        if (this.#cancelWatchdog)
+            return;
+        this.#cancelWatchdog = this.#scheduler.recurring(() => {
+            if (this.#filesystem.exists(this.#databasePath))
+                return;
+            this.#cancelWatchdog?.();
+            this.#cancelWatchdog = undefined;
+            this.#abandoned = true;
+            this.#onAbandoned?.();
+            // Stop reports its own failures.
+            void this.stop().catch(() => undefined);
+        }, ABANDONMENT_WATCHDOG_INTERVAL_MS);
+    }
+    /**
+     * Register what to do once this service finds its database gone.
+     *
+     * A handler registered before abandonment runs before the stop that follows it; one registered after
+     * runs at once, while that stop may still be in flight. Stopping releases the endpoints but cannot
+     * end a process parked waiting for a signal, so the owner of that wait decides how the process ends.
+     * @param handler - Invoked once the database this service serves has gone.
+     */
+    onAbandoned(handler) {
+        this.#onAbandoned = handler;
+        // A handler can be registered after start() resolves, so abandonment can precede this
+        // registration. Without the latch the owner of the wait is never told and the process, having
+        // stopped serving, stays resident until it is killed.
+        if (this.#abandoned)
+            handler();
+    }
+    /**
+     * Stops endpoints, closes the database, and releases this process's lock.
+     *
+     * A call made while a stop is in flight joins it, so any caller's settled stop means teardown has
+     * finished. Every close is attempted and the lock is released whatever the others do. Each failing
+     * step reaches the report sink, and the first one rejects. Sidecar cleanup runs only once every
+     * connection to the database has closed, is best effort, and reports nothing.
+     * @returns - Settles once teardown has finished.
+     */
+    stop() {
+        this.#stopping ??= this.#stopOnce().finally(() => {
+            this.#stopping = undefined;
+        });
+        return this.#stopping;
+    }
+    async #stopOnce() {
+        const snapshot = this.#snapshot;
+        const mcp = this.#mcp;
+        const operatorTransport = this.#operatorTransport;
+        const operatorUpdates = this.#operatorUpdates;
+        const pushDelivery = this.#pushDelivery;
+        const broker = this.#broker;
+        const unsubscribeCommits = this.#unsubscribeCommits;
+        const cancelSweep = this.#cancelSweep;
+        const cancelWatchdog = this.#cancelWatchdog;
+        this.#snapshot = undefined;
+        this.#mcp = undefined;
+        this.#operatorTransport = undefined;
+        this.#operatorUpdates = undefined;
+        this.#pushDelivery = undefined;
+        this.#broker = undefined;
+        this.#unsubscribeCommits = undefined;
+        this.#cancelSweep = undefined;
+        this.#cancelWatchdog = undefined;
+        this.#operatorScheduler = undefined;
+        const failures = [];
+        const attempt = async (step) => {
+            try {
+                await step();
+                return true;
+            }
+            catch (error) {
+                failures.push(error);
+                this.#report(`pager stop: ${error instanceof Error ? error.message : String(error)}`);
+                return false;
+            }
+        };
+        await attempt(() => unsubscribeCommits?.());
+        await attempt(() => cancelSweep?.());
+        await attempt(() => cancelWatchdog?.());
+        await attempt(() => operatorTransport?.close());
+        const eventStoreClosed = await attempt(() => operatorUpdates?.close());
+        await attempt(() => snapshot?.close());
+        await attempt(() => mcp?.close());
+        await attempt(() => pushDelivery?.close());
+        // The sidecars are safe to remove only once every connection to the database has closed.
+        const brokerClosed = await attempt(() => broker?.close());
+        if (eventStoreClosed && brokerClosed)
+            removeCheckpointedSqliteSidecars(this.#databasePath, this.#filesystem);
+        await attempt(() => {
+            this.#lock.release();
+        });
+        if (failures.length > 0)
+            throw failures[0];
+    }
+    async #startOperatorEndpoint() {
+        const broker = this.#broker;
+        const scheduler = this.#operatorScheduler;
+        if (!broker || !scheduler)
+            return;
+        let store;
+        let updates;
+        try {
+            store = new SqliteOperatorEventStore(this.#databasePath, publicEpoch(broker.epoch()));
+            const descriptors = new Map();
+            for (const descriptor of this.#implementations.descriptors())
+                descriptors.set(descriptor.id, descriptor);
+            const operatorUpdates = new OperatorUpdateService({
+                source: broker,
+                store,
+                now: this.#now,
+                projection: {
+                    ...createSystemRepositoryProjectionDependencies(),
+                    implementations: {
+                        find: (implementationId) => {
+                            const descriptor = descriptors.get(implementationId);
+                            return descriptor
+                                ? {
+                                    displayName: descriptor.displayName,
+                                    metadata: { capabilities: [...descriptor.capabilities] },
+                                }
+                                : null;
+                        },
+                    },
+                },
+            });
+            updates = operatorUpdates;
+            const operatorPort = this.#options.config?.operatorPort ?? 0;
+            const operatorBindHost = this.#options.config?.bindHost ?? LOOPBACK_HOST;
+            this.#operatorTransport = await bindEndpoint("operator", operatorPort, operatorBindHost, () => startOperatorTransport(operatorUpdates, {
+                host: operatorBindHost,
+                port: operatorPort,
+                now: this.#now,
+                issueClientId: issueOperatorClientId,
+                scheduler: this.#scheduler,
+                commands: new OperatorCommandService({
+                    broker,
+                    scheduler,
+                    issueControlId: () => randomBytes(CONTROL_ID_BYTES).toString("hex"),
+                }),
+                heartbeatIntervalMs: OPERATOR_HEARTBEAT_INTERVAL_MS,
+                livenessTimeoutMs: OPERATOR_LIVENESS_TIMEOUT_MS,
+            }));
+            this.#operatorUpdates = operatorUpdates;
+        }
+        catch (error) {
+            updates?.close();
+            if (!updates)
+                store?.close();
+            this.#operatorTransport = undefined;
+            this.#operatorUpdates = undefined;
+            // A port clash is an operator mistake with a fix; every other startup failure leaves the
+            // endpoint absent rather than taking durable messaging down with it.
+            if (error instanceof EndpointPortUnavailableError)
+                throw error;
+            this.#report(`pager operator endpoint unavailable: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+function removeCheckpointedSqliteSidecars(databasePath, filesystem) {
+    const walPath = `${databasePath}-wal`;
+    try {
+        if (filesystem.exists(walPath) && filesystem.sizeOf(walPath) !== 0)
+            return;
+        if (filesystem.exists(walPath))
+            filesystem.remove(walPath);
+        const sharedMemoryPath = `${databasePath}-shm`;
+        if (filesystem.exists(sharedMemoryPath))
+            filesystem.remove(sharedMemoryPath);
+    }
+    catch {
+        // Cleanup is opportunistic.
+    }
+}