@drisp/cli 0.4.2 → 0.4.4

package/dist/athena-gateway.js

@@ -23,7 +23,6 @@ import {
 } from "./chunk-4CRZXLIP.js";
 
 // src/gateway/daemon.ts
-import crypto from "crypto";
 import fs3 from "fs";
 
 // src/gateway/adapters/console/adapter.ts
@@ -35,6 +34,8 @@ import { WebSocket } from "ws";
 var DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
 var DEFAULT_INITIAL_RECONNECT_MS = 1e3;
 var DEFAULT_MAX_RECONNECT_MS = 3e4;
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 3e4;
+var DEFAULT_HEARTBEAT_TIMEOUT_MS = 9e4;
 function createConsoleBrokerClient(opts) {
   const hasStatic = typeof opts.pairingToken === "string" && opts.pairingToken.length > 0;
   const hasProvider = typeof opts.pairingTokenProvider === "function";
@@ -46,6 +47,8 @@ function createConsoleBrokerClient(opts) {
   const provider = hasStatic ? async () => opts.pairingToken : opts.pairingTokenProvider;
   const initialDelay = opts.reconnect?.initialDelayMs ?? DEFAULT_INITIAL_RECONNECT_MS;
   const maxDelay = opts.reconnect?.maxDelayMs ?? DEFAULT_MAX_RECONNECT_MS;
+  const heartbeatInterval = opts.heartbeat?.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+  const heartbeatTimeout = opts.heartbeat?.timeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
   let ws = null;
   let ready = null;
   let closeRequested = false;
@@ -53,6 +56,8 @@ function createConsoleBrokerClient(opts) {
   let reconnectTimer = null;
   let lastHello = null;
   let currentToken = null;
+  let heartbeatTimer = null;
+  let lastPongAt = null;
   const frameHandlers = /* @__PURE__ */ new Set();
   const closeHandlers = /* @__PURE__ */ new Set();
   const readyHandlers = /* @__PURE__ */ new Set();
@@ -61,6 +66,44 @@ function createConsoleBrokerClient(opts) {
     if (!currentToken) return message;
     return message.split(currentToken).join(tokenRedacted);
   }
+  function stopHeartbeat() {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    lastPongAt = null;
+  }
+  function startHeartbeat(currentWs) {
+    stopHeartbeat();
+    lastPongAt = Date.now();
+    heartbeatTimer = setInterval(() => {
+      if (currentWs !== ws || currentWs.readyState !== WebSocket.OPEN) {
+        stopHeartbeat();
+        return;
+      }
+      if (lastPongAt !== null && Date.now() - lastPongAt >= heartbeatTimeout) {
+        opts.log(
+          "warn",
+          "console broker: heartbeat watchdog fired, no pong received \u2014 terminating"
+        );
+        stopHeartbeat();
+        try {
+          currentWs.terminate();
+        } catch {
+        }
+        return;
+      }
+      const ping = {
+        kind: "console.ping",
+        frameId: makeFrameId(),
+        sentAt: Date.now()
+      };
+      try {
+        currentWs.send(JSON.stringify(ping));
+      } catch {
+      }
+    }, heartbeatInterval);
+  }
   function emitClose(reason) {
     for (const h of [...closeHandlers]) {
       try {
@@ -216,6 +259,10 @@ function createConsoleBrokerClient(opts) {
             );
             return;
           }
+          if (parsed.kind === "console.pong") {
+            lastPongAt = Date.now();
+            return;
+          }
           for (const h of [...frameHandlers]) {
             try {
               h(parsed);
@@ -240,12 +287,14 @@ function createConsoleBrokerClient(opts) {
       throw err;
     }
     next.on("close", (_code, reasonBuf) => {
+      stopHeartbeat();
       if (next !== ws) return;
       ws = null;
       ready = null;
       emitClose(reasonBuf.toString() || "closed");
       if (!closeRequested) scheduleReconnect();
     });
+    startHeartbeat(next);
   }
   async function connect(hello) {
     if (ws) throw new Error("console broker client already connected");
@@ -255,6 +304,7 @@ function createConsoleBrokerClient(opts) {
   }
   function close(reason) {
     closeRequested = true;
+    stopHeartbeat();
     if (reconnectTimer) {
       clearTimeout(reconnectTimer);
       reconnectTimer = null;
@@ -1873,8 +1923,7 @@ var ChannelManager = class {
 // src/gateway/control/handlers.ts
 import { createRequire } from "module";
 
-// src/gateway/sessionRegistry.ts
-import { randomUUID } from "crypto";
+// src/gateway/runtimeBindingStore.ts
 var AlreadyRegisteredError = class extends Error {
   code = "already_registered";
   constructor(existing) {
@@ -1891,120 +1940,145 @@ var NotRegisteredError = class extends Error {
     this.name = "NotRegisteredError";
   }
 };
-var UnknownDispatchError = class extends Error {
-  code = "unknown_dispatch";
-  constructor(id) {
-    super(`unknown dispatchId: ${id}`);
-    this.name = "UnknownDispatchError";
-  }
-};
 function maybeLastRebindAt(value) {
   return value !== void 0 ? { lastRebindAt: value } : {};
 }
-var SessionRegistry = class {
+var RuntimeBindingStore = class {
   current = null;
-  binding = null;
-  dispatches = /* @__PURE__ */ new Map();
-  idFactory;
+  bindingState = null;
+  staleTimer = null;
+  staleSince = null;
+  gracePeriodMs;
+  observers;
   now;
   constructor(opts = {}) {
-    this.idFactory = opts.idFactory ?? randomUUID;
+    this.gracePeriodMs = opts.gracePeriodMs ?? 0;
+    this.observers = opts.observers ?? {};
     this.now = opts.now ?? Date.now;
   }
-  register(input) {
-    if (this.current) {
-      if (this.current.runtimeId === input.runtimeId) {
-        this.current = {
-          ...this.current,
-          defaultAgentId: input.defaultAgentId,
-          pid: input.pid
-        };
-        return this.current;
-      }
+  // ── lifecycle ─────────────────────────────────────────────
+  /** Register a runtime and bind its connection in one atomic step. */
+  bind(input) {
+    const previous = this.bindingState;
+    const wasStale = previous?.state === "stale";
+    const staleSince = wasStale ? previous.staleSince : null;
+    if (!this.current) {
+      this.current = {
+        runtimeId: input.runtimeId,
+        defaultAgentId: input.defaultAgentId,
+        pid: input.pid,
+        registeredAt: this.now()
+      };
+    } else if (this.current.runtimeId === input.runtimeId) {
+      this.current = {
+        ...this.current,
+        defaultAgentId: input.defaultAgentId,
+        pid: input.pid
+      };
+    } else {
       throw new AlreadyRegisteredError(this.current);
     }
-    this.current = { ...input, registeredAt: this.now() };
-    return this.current;
-  }
-  bindConnection(runtimeId, connectionId) {
-    if (!this.current || this.current.runtimeId !== runtimeId) {
-      throw new NotRegisteredError();
-    }
-    const previous = this.binding;
     const now = this.now();
-    const isRebind = previous !== null && (previous.state === "stale" || previous.connectionId !== connectionId);
+    const isRebind = previous !== null && (previous.state === "stale" || previous.connectionId !== input.connectionId);
     const lastRebindAt = isRebind ? now : previous?.lastRebindAt;
     const epoch = previous ? previous.epoch + (isRebind ? 1 : 0) : 1;
-    this.binding = {
+    this.bindingState = {
       state: "active",
-      connectionId,
+      connectionId: input.connectionId,
       boundAt: now,
       epoch,
       ...maybeLastRebindAt(lastRebindAt)
     };
+    this.clearStaleTimer();
+    if (wasStale && staleSince !== null) {
+      this.observers.onRuntimeRebind?.({
+        runtimeId: input.runtimeId,
+        gapMs: now - staleSince,
+        epoch: this.bindingState.epoch
+      });
+    }
+    return { registeredAt: this.current.registeredAt };
+  }
+  /** Fully unregister a runtime. Throws NotRegisteredError if id does not match. */
+  unbind(runtimeId) {
+    if (!this.current || this.current.runtimeId !== runtimeId) {
+      throw new NotRegisteredError();
+    }
+    this.current = null;
+    this.bindingState = null;
+    this.clearStaleTimer();
   }
-  markConnectionStale(connectionId) {
-    if (!this.current || !this.binding || this.binding.connectionId !== connectionId || this.binding.state !== "active") {
+  /**
+   * Called when the transport connection closes.
+   * Returns the runtimeId if the close was for the current binding (caller should
+   * clear the push handle); returns null if the connectionId was not recognised.
+   */
+  notifyConnectionClosed(connectionId) {
+    if (!this.current || !this.bindingState || this.bindingState.connectionId !== connectionId) {
       return null;
     }
-    this.binding = {
+    const runtimeId = this.current.runtimeId;
+    const now = this.now();
+    this.bindingState = {
       state: "stale",
       connectionId,
-      staleSince: this.now(),
-      epoch: this.binding.epoch,
-      ...maybeLastRebindAt(this.binding.lastRebindAt)
+      staleSince: now,
+      epoch: this.bindingState.epoch,
+      ...maybeLastRebindAt(this.bindingState.lastRebindAt)
     };
-    return this.current.runtimeId;
+    if (this.gracePeriodMs <= 0) {
+      this.current = null;
+      this.bindingState = null;
+      this.observers.onRuntimeConnectionLost?.({ runtimeId, graceful: false });
+      return runtimeId;
+    }
+    this.staleSince = now;
+    this.staleTimer = setTimeout(() => {
+      this.expireStaleBinding(runtimeId);
+    }, this.gracePeriodMs);
+    return runtimeId;
+  }
+  stop() {
+    this.clearStaleTimer();
   }
+  // ── reads ─────────────────────────────────────────────────
   hasActiveBinding(runtimeId) {
-    if (!this.current || !this.binding || this.binding.state !== "active") {
+    if (!this.current || !this.bindingState || this.bindingState.state !== "active") {
       return false;
     }
     return runtimeId === void 0 || this.current.runtimeId === runtimeId;
   }
+  getCurrent() {
+    return this.current;
+  }
   getBinding() {
-    return this.binding;
+    return this.bindingState;
   }
   getRuntimeIdByConnection(connectionId) {
-    if (!this.current || !this.binding) return null;
-    return this.binding.connectionId === connectionId ? this.current.runtimeId : null;
-  }
-  unregister(runtimeId) {
-    if (!this.current || this.current.runtimeId !== runtimeId) {
-      throw new NotRegisteredError();
+    if (!this.current || !this.bindingState) return null;
+    return this.bindingState.connectionId === connectionId ? this.current.runtimeId : null;
+  }
+  // ── private ───────────────────────────────────────────────
+  expireStaleBinding(runtimeId) {
+    this.staleTimer = null;
+    const since = this.staleSince;
+    this.staleSince = null;
+    if (!this.current || this.current.runtimeId !== runtimeId || this.hasActiveBinding(runtimeId)) {
+      return;
     }
     this.current = null;
-    this.binding = null;
-    this.dispatches.clear();
-  }
-  getCurrent() {
-    return this.current;
-  }
-  beginDispatch(input) {
-    if (!this.current) {
-      throw new NotRegisteredError();
+    this.bindingState = null;
+    this.observers.onRuntimeConnectionLost?.({ runtimeId, graceful: false });
+    if (since !== null) {
+      this.observers.onRuntimeExpired?.({ runtimeId, gapMs: this.now() - since });
     }
-    const dispatchId = this.idFactory();
-    const entry = {
-      dispatchId,
-      sessionKey: input.sessionKey,
-      agentId: input.agentId,
-      location: input.location,
-      createdAt: this.now()
-    };
-    this.dispatches.set(dispatchId, entry);
-    return entry;
   }
-  completeDispatch(dispatchId) {
-    const entry = this.dispatches.get(dispatchId);
-    if (!entry) {
-      throw new UnknownDispatchError(dispatchId);
+  clearStaleTimer() {
+    if (this.staleTimer) {
+      clearTimeout(this.staleTimer);
+      this.staleTimer = null;
     }
-    this.dispatches.delete(dispatchId);
-    return entry;
-  }
-  pendingDispatchCount() {
-    return this.dispatches.size;
+    this.staleSince = null;
   }
 };
 
@@ -2014,7 +2088,7 @@ var cachedVersion = null;
 function readVersion() {
   if (cachedVersion !== null) return cachedVersion;
   try {
-    const injected = "0.4.2";
+    const injected = "0.4.4";
     if (typeof injected === "string" && injected.length > 0) {
       cachedVersion = injected;
       return cachedVersion;
@@ -2029,273 +2103,258 @@ function readVersion() {
   }
   return cachedVersion;
 }
+var PING = {
+  kind: "ping",
+  handle: (_envelope, { ts, deps }) => {
+    const payload = {
+      pong: true,
+      daemonPid: process.pid,
+      uptimeMs: ts - deps.startedAt
+    };
+    return payload;
+  }
+};
+var STATUS = {
+  kind: "status",
+  handle: (_envelope, { ts, deps }) => {
+    const channels = (deps.channelManager?.listChannels() ?? []).map((c) => ({
+      id: c.id,
+      state: c.health?.transportOk === false ? "degraded" : "running",
+      ...c.health?.at !== void 0 ? { lastHealthAt: c.health.at } : {},
+      ...c.health?.note !== void 0 ? { note: c.health.note } : {}
+    }));
+    const payload = {
+      daemonPid: process.pid,
+      startedAt: deps.startedAt,
+      uptimeMs: ts - deps.startedAt,
+      version: readVersion(),
+      listener: deps.getListener?.() ?? {
+        kind: "uds",
+        socketPath: "<unknown>"
+      },
+      channels,
+      runtimes: runtimeStatusEntries(deps.pipeline)
+    };
+    return payload;
+  }
+};
+var CHANNELS_RELOAD = {
+  kind: "channels.reload",
+  requires: ["reloadChannels"],
+  unsupportedMessage: "channel reload not configured",
+  handle: async (_envelope, { deps }) => {
+    const payload = await deps.reloadChannels();
+    return payload;
+  }
+};
+var SESSION_REGISTER = {
+  kind: "session.register",
+  requires: ["pipeline"],
+  unsupportedMessage: "session.register not configured",
+  handle: (envelope, { deps, connection }) => {
+    const req = envelope.payload;
+    const reg = deps.pipeline.registerRuntime({
+      runtimeId: req.runtimeId,
+      defaultAgentId: req.defaultAgentId,
+      pid: req.pid,
+      connectionId: connection.connectionId,
+      push: connection.push
+    });
+    const payload = {
+      registeredAt: reg.registeredAt,
+      gatewayStartedAt: deps.startedAt
+    };
+    return payload;
+  }
+};
+var SESSION_UNREGISTER = {
+  kind: "session.unregister",
+  requires: ["pipeline"],
+  unsupportedMessage: "session.unregister not configured",
+  handle: (envelope, { deps, ts }) => {
+    const req = envelope.payload;
+    deps.pipeline.unregisterRuntime(req.runtimeId);
+    const payload = {
+      unregisteredAt: ts
+    };
+    return payload;
+  }
+};
+var SESSION_TURN_COMPLETE = {
+  kind: "session.turn.complete",
+  requires: ["pipeline"],
+  unsupportedMessage: "pipeline not configured",
+  handle: async (envelope, { deps }) => {
+    const req = envelope.payload;
+    return await deps.pipeline.handleTurnComplete(req);
+  }
+};
+var CHANNEL_SEND = {
+  kind: "channel.send",
+  requires: ["channelManager"],
+  unsupportedMessage: "channel manager not configured",
+  handle: async (envelope, { deps }) => {
+    const req = envelope.payload;
+    const result = await deps.channelManager.send(
+      req.message.location.channelId,
+      req.message
+    );
+    const payload = {
+      providerMessageId: result.providerMessageId,
+      deliveredAt: result.deliveredAt
+    };
+    return payload;
+  }
+};
+var RELAY_PERMISSION_REQUEST = {
+  kind: "relay.permission.request",
+  requires: ["relayCoordinator"],
+  unsupportedMessage: "relay coordinator not configured",
+  requireRegisteredRuntime: true,
+  handle: async (envelope, { deps, callerRuntimeId }) => {
+    const req = envelope.payload;
+    const broadcast = deps.relayCoordinator.requestPermission({
+      ...req.channelRequestId !== void 0 ? { channelRequestId: req.channelRequestId } : {},
+      toolName: req.toolName,
+      description: req.description,
+      inputPreview: req.inputPreview,
+      ...req.ttlMs !== void 0 ? { ttlMs: req.ttlMs } : {},
+      ...callerRuntimeId !== void 0 ? { runtimeId: callerRuntimeId } : {}
+    });
+    const result = await broadcast.result;
+    const payload = {
+      channelRequestId: broadcast.channelRequestId,
+      result
+    };
+    return payload;
+  }
+};
+var RELAY_PERMISSION_CANCEL = {
+  kind: "relay.permission.cancel",
+  requires: ["relayCoordinator"],
+  unsupportedMessage: "relay coordinator not configured",
+  requireRegisteredRuntime: true,
+  handle: (envelope, { deps, callerRuntimeId }) => {
+    const req = envelope.payload;
+    const cancelled = deps.relayCoordinator.cancel(
+      req.channelRequestId,
+      req.reason,
+      callerRuntimeId
+    );
+    const payload = { cancelled };
+    return payload;
+  }
+};
+var RELAY_QUESTION_REQUEST = {
+  kind: "relay.question.request",
+  requires: ["relayCoordinator"],
+  unsupportedMessage: "relay coordinator not configured",
+  requireRegisteredRuntime: true,
+  handle: async (envelope, { deps, callerRuntimeId }) => {
+    const req = envelope.payload;
+    const broadcast = deps.relayCoordinator.requestQuestion({
+      ...req.channelRequestId !== void 0 ? { channelRequestId: req.channelRequestId } : {},
+      title: req.title,
+      questions: req.questions,
+      ...req.ttlMs !== void 0 ? { ttlMs: req.ttlMs } : {},
+      ...callerRuntimeId !== void 0 ? { runtimeId: callerRuntimeId } : {}
+    });
+    const result = await broadcast.result;
+    const payload = {
+      channelRequestId: broadcast.channelRequestId,
+      result
+    };
+    return payload;
+  }
+};
+var RELAY_QUESTION_CANCEL = {
+  kind: "relay.question.cancel",
+  requires: ["relayCoordinator"],
+  unsupportedMessage: "relay coordinator not configured",
+  requireRegisteredRuntime: true,
+  handle: (envelope, { deps, callerRuntimeId }) => {
+    const req = envelope.payload;
+    const cancelled = deps.relayCoordinator.cancel(
+      req.channelRequestId,
+      req.reason,
+      callerRuntimeId
+    );
+    const payload = { cancelled };
+    return payload;
+  }
+};
+var HANDLERS = new Map(
+  [
+    PING,
+    STATUS,
+    CHANNELS_RELOAD,
+    SESSION_REGISTER,
+    SESSION_UNREGISTER,
+    SESSION_TURN_COMPLETE,
+    CHANNEL_SEND,
+    RELAY_PERMISSION_REQUEST,
+    RELAY_PERMISSION_CANCEL,
+    RELAY_QUESTION_REQUEST,
+    RELAY_QUESTION_CANCEL
+  ].map((spec) => [spec.kind, spec])
+);
 function createDispatcher(deps) {
   const handle = async (envelope, connection) => {
     const ts = Date.now();
-    switch (envelope.kind) {
-      case "ping": {
-        const payload = {
-          pong: true,
-          daemonPid: process.pid,
-          uptimeMs: ts - deps.startedAt
-        };
-        return ok(envelope, ts, payload);
-      }
-      case "status": {
-        const channels = (deps.channelManager?.listChannels() ?? []).map((c) => ({
-          id: c.id,
-          state: c.health?.transportOk === false ? "degraded" : "running",
-          ...c.health?.at !== void 0 ? { lastHealthAt: c.health.at } : {},
-          ...c.health?.note !== void 0 ? { note: c.health.note } : {}
-        }));
-        const payload = {
-          daemonPid: process.pid,
-          startedAt: deps.startedAt,
-          uptimeMs: ts - deps.startedAt,
-          version: readVersion(),
-          listener: deps.getListener?.() ?? {
-            kind: "uds",
-            socketPath: "<unknown>"
-          },
-          channels,
-          runtimes: runtimeStatusEntries(deps.registry)
-        };
-        return ok(envelope, ts, payload);
-      }
-      case "channels.reload": {
-        if (!deps.reloadChannels) {
-          return error(
-            envelope,
-            ts,
-            "unsupported",
-            "channel reload not configured"
-          );
-        }
-        const payload = await deps.reloadChannels();
-        return ok(envelope, ts, payload);
-      }
-      case "session.register": {
-        if (!deps.registry)
-          return error(
-            envelope,
-            ts,
-            "unsupported",
-            "session.register not configured"
-          );
-        const req = envelope.payload;
-        try {
-          const reg = deps.registry.register({
-            runtimeId: req.runtimeId,
-            defaultAgentId: req.defaultAgentId,
-            pid: req.pid
-          });
-          deps.registerRuntimeConnection?.(req.runtimeId, connection);
-          try {
-            deps.dispatcher?.drainPending();
-          } catch (err) {
-            process.stderr.write(
-              `gateway: drainPending failed: ${err instanceof Error ? err.message : String(err)}
-`
-            );
-          }
-          const payload = {
-            registeredAt: reg.registeredAt,
-            gatewayStartedAt: deps.startedAt
-          };
-          return ok(envelope, ts, payload);
-        } catch (err) {
-          if (err instanceof AlreadyRegisteredError) {
-            return error(envelope, ts, err.code, err.message);
-          }
-          throw err;
-        }
-      }
-      case "session.unregister": {
-        if (!deps.registry)
-          return error(
-            envelope,
-            ts,
-            "unsupported",
-            "session.unregister not configured"
-          );
-        const req = envelope.payload;
-        try {
-          deps.registry.unregister(req.runtimeId);
-          deps.unregisterRuntimeConnection?.(req.runtimeId);
-          const payload = {
-            unregisteredAt: ts
-          };
-          return ok(envelope, ts, payload);
-        } catch (err) {
-          if (err instanceof NotRegisteredError) {
-            return error(envelope, ts, err.code, err.message);
-          }
-          throw err;
-        }
-      }
-      case "session.turn.complete": {
-        if (!deps.dispatcher)
-          return error(
-            envelope,
-            ts,
-            "unsupported",
-            "dispatcher not configured"
-          );
-        const req = envelope.payload;
-        const result = await deps.dispatcher.handleTurnComplete(req);
-        return ok(envelope, ts, result);
-      }
-      case "channel.send": {
-        if (!deps.channelManager)
-          return error(
-            envelope,
-            ts,
-            "unsupported",
-            "channel manager not configured"
-          );
-        const req = envelope.payload;
-        const result = await deps.channelManager.send(
-          req.message.location.channelId,
-          req.message
-        );
-        const payload = {
-          providerMessageId: result.providerMessageId,
-          deliveredAt: result.deliveredAt
-        };
-        return ok(envelope, ts, payload);
-      }
-      case "relay.permission.request": {
-        if (!deps.relayCoordinator)
-          return error(
-            envelope,
-            ts,
-            "unsupported",
-            "relay coordinator not configured"
-          );
-        const req = envelope.payload;
-        const callerRuntimeId = deps.registry?.getRuntimeIdByConnection(connection.connectionId) ?? void 0;
-        if (deps.registry && callerRuntimeId === void 0) {
-          return error(
-            envelope,
-            ts,
-            "not_registered",
-            "relay.permission.request requires a registered runtime connection"
-          );
-        }
-        const broadcast = deps.relayCoordinator.requestPermission({
-          ...req.channelRequestId !== void 0 ? { channelRequestId: req.channelRequestId } : {},
-          toolName: req.toolName,
-          description: req.description,
-          inputPreview: req.inputPreview,
-          ...req.ttlMs !== void 0 ? { ttlMs: req.ttlMs } : {},
-          ...callerRuntimeId !== void 0 ? { runtimeId: callerRuntimeId } : {}
-        });
-        const result = await broadcast.result;
-        const payload = {
-          channelRequestId: broadcast.channelRequestId,
-          result
-        };
-        return ok(envelope, Date.now(), payload);
-      }
-      case "relay.permission.cancel": {
-        if (!deps.relayCoordinator)
-          return error(
-            envelope,
-            ts,
-            "unsupported",
-            "relay coordinator not configured"
-          );
-        const req = envelope.payload;
-        const callerRuntimeId = deps.registry?.getRuntimeIdByConnection(connection.connectionId) ?? void 0;
-        if (deps.registry && callerRuntimeId === void 0) {
-          return error(
-            envelope,
-            ts,
-            "not_registered",
-            "relay.permission.cancel requires a registered runtime connection"
-          );
-        }
-        const cancelled = deps.relayCoordinator.cancel(
-          req.channelRequestId,
-          req.reason,
-          callerRuntimeId
-        );
-        const payload = { cancelled };
-        return ok(envelope, ts, payload);
-      }
-      case "relay.question.request": {
-        if (!deps.relayCoordinator)
-          return error(
-            envelope,
-            ts,
-            "unsupported",
-            "relay coordinator not configured"
-          );
-        const req = envelope.payload;
-        const callerRuntimeId = deps.registry?.getRuntimeIdByConnection(connection.connectionId) ?? void 0;
-        if (deps.registry && callerRuntimeId === void 0) {
-          return error(
-            envelope,
-            ts,
-            "not_registered",
-            "relay.question.request requires a registered runtime connection"
-          );
-        }
-        const broadcast = deps.relayCoordinator.requestQuestion({
-          ...req.channelRequestId !== void 0 ? { channelRequestId: req.channelRequestId } : {},
-          title: req.title,
-          questions: req.questions,
-          ...req.ttlMs !== void 0 ? { ttlMs: req.ttlMs } : {},
-          ...callerRuntimeId !== void 0 ? { runtimeId: callerRuntimeId } : {}
-        });
-        const result = await broadcast.result;
-        const payload = {
-          channelRequestId: broadcast.channelRequestId,
-          result
-        };
-        return ok(envelope, Date.now(), payload);
-      }
-      case "relay.question.cancel": {
-        if (!deps.relayCoordinator)
+    const spec = HANDLERS.get(envelope.kind);
+    if (!spec) {
+      return error(
+        envelope,
+        ts,
+        "unknown_kind",
+        `unknown kind: ${envelope.kind}`
+      );
+    }
+    if (spec.requires) {
+      for (const name of spec.requires) {
+        if (deps[name] === void 0) {
           return error(
             envelope,
             ts,
             "unsupported",
-            "relay coordinator not configured"
-          );
-        const req = envelope.payload;
-        const callerRuntimeId = deps.registry?.getRuntimeIdByConnection(connection.connectionId) ?? void 0;
-        if (deps.registry && callerRuntimeId === void 0) {
-          return error(
-            envelope,
-            ts,
-            "not_registered",
-            "relay.question.cancel requires a registered runtime connection"
+            spec.unsupportedMessage ?? `${spec.kind} not configured`
           );
         }
-        const cancelled = deps.relayCoordinator.cancel(
-          req.channelRequestId,
-          req.reason,
-          callerRuntimeId
-        );
-        const payload = { cancelled };
-        return ok(envelope, ts, payload);
       }
-      default:
+    }
+    let callerRuntimeId;
+    if (spec.requireRegisteredRuntime) {
+      callerRuntimeId = deps.pipeline?.getRuntimeIdByConnection(connection.connectionId) ?? void 0;
+      if (deps.pipeline && callerRuntimeId === void 0) {
         return error(
           envelope,
           ts,
-          "unknown_kind",
-          `unknown kind: ${envelope.kind}`
+          "not_registered",
+          `${spec.kind} requires a registered runtime connection`
         );
+      }
+    }
+    try {
+      const payload = await spec.handle(envelope, {
+        deps,
+        connection,
+        callerRuntimeId,
+        ts
+      });
+      return ok(envelope, Date.now(), payload);
+    } catch (err) {
+      if (err instanceof AlreadyRegisteredError || err instanceof NotRegisteredError) {
+        return error(envelope, ts, err.code, err.message);
+      }
+      throw err;
     }
   };
   return handle;
 }
-function runtimeStatusEntries(registry) {
-  const runtime = registry?.getCurrent();
-  if (!runtime || !registry) return [];
-  const binding = registry.getBinding();
+function runtimeStatusEntries(pipeline) {
+  const runtime = pipeline?.getCurrentRuntime();
+  if (!runtime || !pipeline) return [];
+  const binding = pipeline.getBinding();
   return [
     {
       runtimeId: runtime.runtimeId,
@@ -2313,7 +2372,7 @@ function runtimeStatusEntries(registry) {
         epoch: binding.epoch,
         ...maybeLastRebindAt(binding.lastRebindAt)
       } : { state: "none" },
-      pendingDispatchCount: registry.pendingDispatchCount()
+      pendingDispatchCount: pipeline.pendingDispatchCount()
     }
   ];
 }
@@ -2436,256 +2495,8 @@ function handleConnection(connection, expectedToken, startedAt, handler, logErro
   });
 }
 
-// src/gateway/router/sessionKey.ts
-function deriveSessionKey(loc) {
-  const c = loc.channelId;
-  const a = loc.accountId;
-  if (loc.peer?.id) {
-    const peer = loc.peer.id;
-    if (loc.thread?.id) {
-      return `peer:${c}:${a}:${peer}:${loc.thread.id}`;
-    }
-    return `peer:${c}:${a}:${peer}`;
-  }
-  if (loc.room?.id) {
-    const room = loc.room.id;
-    if (loc.thread?.id) {
-      return `room:${c}:${a}:${room}:${loc.thread.id}`;
-    }
-    return `room:${c}:${a}:${room}`;
-  }
-  return `default:${c}:${a}`;
-}
-
-// src/gateway/dispatcher.ts
-var Dispatcher = class {
-  registry;
-  pushDispatch;
-  sendOutbound;
-  resolveAgent;
-  inboundQueue;
-  canDispatch;
-  log;
-  constructor(opts) {
-    this.registry = opts.registry;
-    this.pushDispatch = opts.pushDispatch;
-    this.sendOutbound = opts.sendOutbound;
-    this.resolveAgent = opts.resolveAgent ?? ((input) => input.defaultAgentId);
-    this.inboundQueue = opts.inboundQueue;
-    this.canDispatch = opts.canDispatch ?? (() => true);
-    this.log = opts.log;
-  }
-  handleInbound(inbound) {
-    const current = this.registry.getCurrent();
-    if (!current || !this.canDispatch()) {
-      if (!this.inboundQueue) {
-        this.log?.(
-          "debug",
-          `no runtime registered; dropping inbound ${inbound.idempotencyKey}`
-        );
-        return { kind: "dropped", reason: "no_runtime" };
-      }
-      const result = this.inboundQueue.enqueue(inbound);
-      if (result.kind === "queued") {
-        this.log?.(
-          "info",
-          `no runtime registered; parked inbound ${inbound.idempotencyKey} as queue#${result.id}`
-        );
-        return { kind: "queued", queueId: result.id };
-      }
-      if (result.kind === "duplicate") {
-        this.log?.(
-          "debug",
-          `inbound ${inbound.idempotencyKey} already parked; ignoring duplicate`
-        );
-        return { kind: "dropped", reason: "no_runtime" };
-      }
-      this.log?.(
-        "warn",
-        `inbound queue full (>=${this.inboundQueue.size()}); dropping ${inbound.idempotencyKey}`
-      );
-      return { kind: "dropped", reason: "queue_full" };
-    }
-    const sessionKey = deriveSessionKey(inbound.location);
-    const agentId = this.resolveAgent({
-      sessionKey,
-      channelId: inbound.location.channelId,
-      defaultAgentId: current.defaultAgentId
-    });
-    if (!agentId) {
-      this.log?.(
-        "warn",
-        `agent resolution returned empty for sessionKey=${sessionKey}`
-      );
-      return { kind: "dropped", reason: "no_default_agent" };
-    }
-    const entry = this.registry.beginDispatch({
-      sessionKey,
-      agentId,
-      location: inbound.location
-    });
-    this.pushDispatch({
-      dispatchId: entry.dispatchId,
-      sessionKey,
-      agentId,
-      inbound
-    });
-    return {
-      kind: "dispatched",
-      dispatchId: entry.dispatchId,
-      sessionKey
-    };
-  }
-  /**
-   * Drain parked inbound messages and dispatch them in FIFO order. Called by
-   * the session.register handler after a runtime attaches. Safe to call when
-   * no queue is configured (no-op).
-   */
-  drainPending() {
-    if (!this.inboundQueue) return { dispatched: 0, dropped: 0 };
-    const current = this.registry.getCurrent();
-    if (!current || !this.canDispatch()) return { dispatched: 0, dropped: 0 };
-    const parked = this.inboundQueue.drain();
-    let dispatched = 0;
-    let dropped = 0;
-    for (const { inbound } of parked) {
-      const sessionKey = deriveSessionKey(inbound.location);
-      const agentId = this.resolveAgent({
-        sessionKey,
-        channelId: inbound.location.channelId,
-        defaultAgentId: current.defaultAgentId
-      });
-      if (!agentId) {
-        dropped += 1;
-        this.log?.(
-          "warn",
-          `drainPending: no agent for ${sessionKey}; dropping ${inbound.idempotencyKey}`
-        );
-        continue;
-      }
-      const entry = this.registry.beginDispatch({
-        sessionKey,
-        agentId,
-        location: inbound.location
-      });
-      this.pushDispatch({
-        dispatchId: entry.dispatchId,
-        sessionKey,
-        agentId,
-        inbound
-      });
-      dispatched += 1;
-    }
-    if (dispatched > 0 || dropped > 0) {
-      this.log?.(
-        "info",
-        `drainPending: dispatched=${dispatched} dropped=${dropped}`
-      );
-    }
-    return { dispatched, dropped };
-  }
-  async handleTurnComplete(payload) {
-    const current = this.registry.getCurrent();
-    writeGatewayTrace(
-      `dispatcher turn.complete received runtimeId=${payload.runtimeId} dispatchId=${payload.dispatchId} channel=${payload.location.channelId} account=${payload.location.accountId} thread=${payload.location.thread?.id ?? ""} textLength=${payload.text.length}`
-    );
-    if (!current || current.runtimeId !== payload.runtimeId) {
-      throw new Error("runtime mismatch on session.turn.complete");
-    }
-    let entry;
-    try {
-      entry = this.registry.completeDispatch(payload.dispatchId);
-    } catch (err) {
-      if (err instanceof UnknownDispatchError) {
-        writeGatewayTrace(
-          `dispatcher turn.complete unknown dispatchId=${payload.dispatchId}`
-        );
-        return { delivered: false };
-      }
-      throw err;
-    }
-    writeGatewayTrace(
-      `dispatcher sendOutbound channel=${entry.location.channelId} dispatchId=${payload.dispatchId} parkedAccount=${entry.location.accountId} parkedThread=${entry.location.thread?.id ?? ""}`
-    );
-    const result = await this.sendOutbound(entry.location.channelId, {
-      location: payload.location,
-      text: payload.text,
-      idempotencyKey: payload.idempotencyKey
-    });
-    writeGatewayTrace(
-      `dispatcher sendOutbound delivered dispatchId=${payload.dispatchId} providerMessageId=${result.providerMessageId}`
-    );
-    return {
-      delivered: true,
-      providerMessageId: result.providerMessageId
-    };
-  }
-};
-
-// src/gateway/lock.ts
-import fs from "fs";
-import path from "path";
-var GatewayAlreadyRunningError = class extends Error {
-  otherPid;
-  constructor(otherPid) {
-    super(`gateway already running (pid=${otherPid})`);
-    this.name = "GatewayAlreadyRunningError";
-    this.otherPid = otherPid;
-  }
-};
-function isProcessAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    const code = err.code;
-    return code === "EPERM";
-  }
-}
-function readPidFile(p) {
-  try {
-    const text = fs.readFileSync(p, "utf-8").trim();
-    const pid = Number.parseInt(text, 10);
-    return Number.isInteger(pid) && pid > 0 ? pid : null;
-  } catch {
-    return null;
-  }
-}
-function acquireLock(lockPath) {
-  fs.mkdirSync(path.dirname(lockPath), { recursive: true, mode: 448 });
-  for (let attempt = 0; attempt < 2; attempt++) {
-    try {
-      const fd = fs.openSync(lockPath, "wx", 384);
-      fs.writeSync(fd, String(process.pid) + "\n");
-      fs.closeSync(fd);
-      return {
-        path: lockPath,
-        pid: process.pid,
-        release: () => {
-          try {
-            const pidNow = readPidFile(lockPath);
-            if (pidNow === process.pid) {
-              fs.unlinkSync(lockPath);
-            }
-          } catch {
-          }
-        }
-      };
-    } catch (err) {
-      const code = err.code;
-      if (code !== "EEXIST") throw err;
-      const otherPid = readPidFile(lockPath);
-      if (otherPid !== null && isProcessAlive(otherPid)) {
-        throw new GatewayAlreadyRunningError(otherPid);
-      }
-      try {
-        fs.unlinkSync(lockPath);
-      } catch {
-      }
-    }
-  }
-  throw new Error(`failed to acquire gateway lock at ${lockPath}`);
-}
+// src/gateway/dispatchPipeline.ts
+import crypto from "crypto";
 
 // src/gateway/outboundDispatcher.ts
 var DEFAULT_BACKOFF = [
@@ -2784,43 +2595,504 @@ var OutboundDispatcher = class {
     } finally {
       this.draining = false;
     }
-    return { retried, succeeded, dropped };
-  }
-  async attempt(row) {
-    try {
-      await this.send(row.channelId, row.message);
-      this.outbox.delete(row.id);
+    return { retried, succeeded, dropped };
+  }
+  async attempt(row) {
+    try {
+      await this.send(row.channelId, row.message);
+      this.outbox.delete(row.id);
+      this.log?.(
+        "info",
+        `outbox#${row.id} delivered to ${row.channelId} on attempt ${row.attempt + 1}`
+      );
+      return "succeeded";
+    } catch (err) {
+      const error2 = err instanceof Error ? err.message : String(err);
+      const nextAttempt = row.attempt + 1;
+      if (nextAttempt >= this.maxAttempts) {
+        this.outbox.delete(row.id);
+        this.log?.(
+          "error",
+          `outbox#${row.id} dropped after ${nextAttempt} attempts: ${error2}`
+        );
+        return "dropped";
+      }
+      const nextAttemptAt = this.now() + this.backoffFor(nextAttempt);
+      this.outbox.recordFailure({
+        id: row.id,
+        nextAttemptAt,
+        lastError: error2
+      });
+      return "requeued";
+    }
+  }
+  backoffFor(attempt) {
+    if (this.backoff.length === 0) return 1e3;
+    const idx = Math.min(attempt, this.backoff.length - 1);
+    return this.backoff[idx];
+  }
+};
+
+// src/gateway/router/sessionKey.ts
+function deriveSessionKey(loc) {
+  const c = loc.channelId;
+  const a = loc.accountId;
+  if (loc.peer?.id) {
+    const peer = loc.peer.id;
+    if (loc.thread?.id) {
+      return `peer:${c}:${a}:${peer}:${loc.thread.id}`;
+    }
+    return `peer:${c}:${a}:${peer}`;
+  }
+  if (loc.room?.id) {
+    const room = loc.room.id;
+    if (loc.thread?.id) {
+      return `room:${c}:${a}:${room}:${loc.thread.id}`;
+    }
+    return `room:${c}:${a}:${room}`;
+  }
+  return `default:${c}:${a}`;
+}
+
+// src/gateway/sessionRegistry.ts
+import { randomUUID } from "crypto";
+var UnknownDispatchError = class extends Error {
+  code = "unknown_dispatch";
+  constructor(id) {
+    super(`unknown dispatchId: ${id}`);
+    this.name = "UnknownDispatchError";
+  }
+};
+var SessionRegistry = class {
+  dispatches = /* @__PURE__ */ new Map();
+  idFactory;
+  now;
+  constructor(opts = {}) {
+    this.idFactory = opts.idFactory ?? randomUUID;
+    this.now = opts.now ?? Date.now;
+  }
+  beginDispatch(input) {
+    const dispatchId = this.idFactory();
+    const entry = {
+      dispatchId,
+      sessionKey: input.sessionKey,
+      agentId: input.agentId,
+      location: input.location,
+      createdAt: this.now()
+    };
+    this.dispatches.set(dispatchId, entry);
+    return entry;
+  }
+  completeDispatch(dispatchId) {
+    const entry = this.dispatches.get(dispatchId);
+    if (!entry) {
+      throw new UnknownDispatchError(dispatchId);
+    }
+    this.dispatches.delete(dispatchId);
+    return entry;
+  }
+  pendingDispatchCount() {
+    return this.dispatches.size;
+  }
+  clearDispatches() {
+    this.dispatches.clear();
+  }
+};
+
+// src/gateway/state/inboundQueue.ts
+var DEFAULT_MAX_ENTRIES = 1e3;
+var InboundQueue = class {
+  db;
+  maxEntries;
+  constructor(db, opts = {}) {
+    this.db = db;
+    this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  }
+  size() {
+    const row = this.db.prepare("SELECT COUNT(*) as n FROM inbound_queue").get();
+    return row.n;
+  }
+  enqueue(inbound) {
+    if (this.size() >= this.maxEntries) {
+      return { kind: "rejected", reason: "queue_full" };
+    }
+    const stmt = this.db.prepare(
+      `INSERT INTO inbound_queue
+				(channel_id, account_id, idempotency_key, payload_json, created_at)
+			 VALUES (?, ?, ?, ?, ?)
+			 ON CONFLICT(channel_id, account_id, idempotency_key) DO NOTHING`
+    );
+    const result = stmt.run(
+      inbound.location.channelId,
+      inbound.location.accountId,
+      inbound.idempotencyKey,
+      JSON.stringify(inbound),
+      Date.now()
+    );
+    if (result.changes === 0) {
+      return { kind: "duplicate" };
+    }
+    return { kind: "queued", id: Number(result.lastInsertRowid) };
+  }
+  /** Atomically read and remove all parked entries in FIFO order. */
+  drain() {
+    return this.db.transaction(() => {
+      const rows = this.db.prepare("SELECT id, payload_json FROM inbound_queue ORDER BY id ASC").all();
+      if (rows.length > 0) {
+        this.db.prepare("DELETE FROM inbound_queue").run();
+      }
+      return rows.map((r) => ({
+        id: r.id,
+        inbound: JSON.parse(r.payload_json)
+      }));
+    })();
+  }
+};
+
+// src/gateway/state/outbox.ts
+var Outbox = class {
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  size() {
+    const row = this.db.prepare("SELECT COUNT(*) as n FROM channel_outbox").get();
+    return row.n;
+  }
+  enqueue(input) {
+    const result = this.db.prepare(
+      `INSERT INTO channel_outbox
+					(channel_id, payload_json, attempt, next_attempt_at, last_error, created_at)
+				 VALUES (?, ?, 0, ?, ?, ?)`
+    ).run(
+      input.channelId,
+      JSON.stringify(input.message),
+      input.nextAttemptAt,
+      input.lastError ?? null,
+      Date.now()
+    );
+    return Number(result.lastInsertRowid);
+  }
+  /** Rows whose `next_attempt_at` is at or before `now`, oldest first. */
+  peekDue(now, limit) {
+    const rows = this.db.prepare(
+      `SELECT id, channel_id, payload_json, attempt, next_attempt_at, last_error
+				 FROM channel_outbox
+				 WHERE next_attempt_at <= ?
+				 ORDER BY next_attempt_at ASC, id ASC
+				 LIMIT ?`
+    ).all(now, limit);
+    return rows.map((r) => ({
+      id: r.id,
+      channelId: r.channel_id,
+      message: JSON.parse(r.payload_json),
+      attempt: r.attempt,
+      nextAttemptAt: r.next_attempt_at,
+      lastError: r.last_error
+    }));
+  }
+  delete(id) {
+    this.db.prepare("DELETE FROM channel_outbox WHERE id = ?").run(id);
+  }
+  recordFailure(input) {
+    this.db.prepare(
+      `UPDATE channel_outbox
+				 SET attempt = attempt + 1,
+				     next_attempt_at = ?,
+				     last_error = ?
+				 WHERE id = ?`
+    ).run(input.nextAttemptAt, input.lastError, input.id);
+  }
+};
+
+// src/gateway/dispatchPipeline.ts
+var DispatchPipeline = class {
+  bindingStore;
+  registry;
+  inboundQueue;
+  outbox;
+  outboundDispatcher;
+  resolveAgent;
+  log;
+  now;
+  idFactory;
+  push = null;
+  constructor(opts) {
+    this.bindingStore = new RuntimeBindingStore({
+      gracePeriodMs: opts.gracePeriodMs,
+      observers: opts.observers,
+      now: opts.now
+    });
+    this.registry = new SessionRegistry({
+      now: opts.now ?? Date.now,
+      ...opts.idFactory ? { idFactory: opts.idFactory } : {}
+    });
+    this.inboundQueue = new InboundQueue(opts.stateDb, opts.inboundQueue ?? {});
+    this.outbox = new Outbox(opts.stateDb);
+    this.outboundDispatcher = new OutboundDispatcher({
+      outbox: this.outbox,
+      send: opts.send,
+      ...opts.outbox?.backoffSchedule ? { backoffSchedule: opts.outbox.backoffSchedule } : {},
+      ...opts.outbox?.maxAttempts !== void 0 ? { maxAttempts: opts.outbox.maxAttempts } : {},
+      ...opts.outbox?.tickIntervalMs !== void 0 ? { tickIntervalMs: opts.outbox.tickIntervalMs } : {},
+      ...opts.outbox?.drainBatchSize !== void 0 ? { drainBatchSize: opts.outbox.drainBatchSize } : {},
+      ...opts.now ? { now: opts.now } : {},
+      ...opts.log ? { log: opts.log } : {}
+    });
+    this.resolveAgent = opts.resolveAgent ?? ((input) => input.defaultAgentId);
+    this.log = opts.log;
+    this.now = opts.now ?? Date.now;
+    this.idFactory = opts.idFactory ?? crypto.randomUUID;
+  }
+  // ── lifecycle ────────────────────────────────────────────
+  start() {
+    this.outboundDispatcher.start();
+  }
+  async stop() {
+    this.outboundDispatcher.stop();
+    this.bindingStore.stop();
+  }
+  // ── inbound (channel side) ───────────────────────────────
+  handleInbound(inbound) {
+    const current = this.bindingStore.getCurrent();
+    if (!current || !this.bindingStore.hasActiveBinding(current.runtimeId)) {
+      const result = this.inboundQueue.enqueue(inbound);
+      if (result.kind === "queued") {
+        this.log?.(
+          "info",
+          `no runtime registered; parked inbound ${inbound.idempotencyKey} as queue#${result.id}`
+        );
+        return { kind: "queued", queueId: result.id };
+      }
+      if (result.kind === "duplicate") {
+        this.log?.(
+          "debug",
+          `inbound ${inbound.idempotencyKey} already parked; ignoring duplicate`
+        );
+        return { kind: "dropped", reason: "no_runtime" };
+      }
+      this.log?.(
+        "warn",
+        `inbound queue full (>=${this.inboundQueue.size()}); dropping ${inbound.idempotencyKey}`
+      );
+      return { kind: "dropped", reason: "queue_full" };
+    }
+    return this.dispatchInboundToRuntime(inbound, current);
+  }
+  dispatchInboundToRuntime(inbound, current) {
+    const sessionKey = deriveSessionKey(inbound.location);
+    const agentId = this.resolveAgent({
+      sessionKey,
+      channelId: inbound.location.channelId,
+      defaultAgentId: current.defaultAgentId
+    });
+    if (!agentId) {
+      this.log?.(
+        "warn",
+        `agent resolution returned empty for sessionKey=${sessionKey}`
+      );
+      return { kind: "dropped", reason: "no_default_agent" };
+    }
+    const entry = this.registry.beginDispatch({
+      sessionKey,
+      agentId,
+      location: inbound.location
+    });
+    this.pushDispatch({
+      dispatchId: entry.dispatchId,
+      sessionKey,
+      agentId,
+      inbound
+    });
+    return { kind: "dispatched", dispatchId: entry.dispatchId, sessionKey };
+  }
+  pushDispatch(payload) {
+    if (!this.push) return;
+    this.push.push({
+      push_id: this.idFactory(),
+      ts: this.now(),
+      kind: "session.dispatch.turn",
+      payload
+    });
+  }
+  // ── runtime side ─────────────────────────────────────────
+  registerRuntime(input) {
+    const result = this.bindingStore.bind({
+      runtimeId: input.runtimeId,
+      defaultAgentId: input.defaultAgentId,
+      pid: input.pid,
+      connectionId: input.connectionId
+    });
+    this.push = { connectionId: input.connectionId, push: input.push };
+    writeGatewayTrace(
+      `pipeline registered runtime runtimeId=${input.runtimeId} connectionId=${input.connectionId}`
+    );
+    this.drainPending();
+    return { registeredAt: result.registeredAt };
+  }
+  unregisterRuntime(runtimeId) {
+    this.bindingStore.unbind(runtimeId);
+    this.registry.clearDispatches();
+    this.push = null;
+    writeGatewayTrace(`pipeline unregistered runtime runtimeId=${runtimeId}`);
+  }
+  notifyConnectionClosed(connectionId) {
+    const runtimeId = this.bindingStore.notifyConnectionClosed(connectionId);
+    if (runtimeId === null) return;
+    writeGatewayTrace(
+      `pipeline runtime connection closed runtimeId=${runtimeId} connectionId=${connectionId}`
+    );
+    this.push = null;
+  }
+  async handleTurnComplete(payload) {
+    const current = this.bindingStore.getCurrent();
+    writeGatewayTrace(
+      `pipeline turn.complete received runtimeId=${payload.runtimeId} dispatchId=${payload.dispatchId} channel=${payload.location.channelId} account=${payload.location.accountId} thread=${payload.location.thread?.id ?? ""} textLength=${payload.text.length}`
+    );
+    if (!current || current.runtimeId !== payload.runtimeId) {
+      throw new Error("runtime mismatch on session.turn.complete");
+    }
+    let entry;
+    try {
+      entry = this.registry.completeDispatch(payload.dispatchId);
+    } catch (err) {
+      if (err instanceof UnknownDispatchError) {
+        writeGatewayTrace(
+          `pipeline turn.complete unknown dispatchId=${payload.dispatchId}`
+        );
+        return { delivered: false };
+      }
+      throw err;
+    }
+    const result = await this.sendOutbound(entry.location, payload);
+    writeGatewayTrace(
+      `pipeline sendOutbound delivered dispatchId=${payload.dispatchId} providerMessageId=${result.providerMessageId}`
+    );
+    return { delivered: true, providerMessageId: result.providerMessageId };
+  }
+  async sendOutbound(_parkedLocation, payload) {
+    const out = {
+      location: payload.location,
+      text: payload.text,
+      idempotencyKey: payload.idempotencyKey
+    };
+    const result = await this.outboundDispatcher.dispatch(
+      payload.location.channelId,
+      out
+    );
+    if (result.kind === "sent") return result.result;
+    return {
+      providerMessageId: `outbox:${result.outboxId}`,
+      deliveredAt: this.now()
+    };
+  }
+  drainPending() {
+    const current = this.bindingStore.getCurrent();
+    if (!current || !this.bindingStore.hasActiveBinding(current.runtimeId))
+      return;
+    const parked = this.inboundQueue.drain();
+    let dispatched = 0;
+    let dropped = 0;
+    for (const { inbound } of parked) {
+      const result = this.dispatchInboundToRuntime(inbound, current);
+      if (result.kind === "dispatched") dispatched += 1;
+      else dropped += 1;
+    }
+    if (dispatched > 0 || dropped > 0) {
       this.log?.(
         "info",
-        `outbox#${row.id} delivered to ${row.channelId} on attempt ${row.attempt + 1}`
+        `drainPending: dispatched=${dispatched} dropped=${dropped}`
       );
-      return "succeeded";
-    } catch (err) {
-      const error2 = err instanceof Error ? err.message : String(err);
-      const nextAttempt = row.attempt + 1;
-      if (nextAttempt >= this.maxAttempts) {
-        this.outbox.delete(row.id);
-        this.log?.(
-          "error",
-          `outbox#${row.id} dropped after ${nextAttempt} attempts: ${error2}`
-        );
-        return "dropped";
-      }
-      const nextAttemptAt = this.now() + this.backoffFor(nextAttempt);
-      this.outbox.recordFailure({
-        id: row.id,
-        nextAttemptAt,
-        lastError: error2
-      });
-      return "requeued";
     }
   }
-  backoffFor(attempt) {
-    if (this.backoff.length === 0) return 1e3;
-    const idx = Math.min(attempt, this.backoff.length - 1);
-    return this.backoff[idx];
+  // ── reads ────────────────────────────────────────────────
+  getCurrentRuntime() {
+    return this.bindingStore.getCurrent();
+  }
+  getBinding() {
+    return this.bindingStore.getBinding();
+  }
+  hasActiveBinding(runtimeId) {
+    return this.bindingStore.hasActiveBinding(runtimeId);
+  }
+  getRuntimeIdByConnection(connectionId) {
+    return this.bindingStore.getRuntimeIdByConnection(connectionId);
+  }
+  pendingDispatchCount() {
+    return this.registry.pendingDispatchCount();
+  }
+  pendingInboundCount() {
+    return this.inboundQueue.size();
+  }
+  pendingOutboxCount() {
+    return this.outbox.size();
+  }
+};
+
+// src/gateway/lock.ts
+import fs from "fs";
+import path from "path";
+var GatewayAlreadyRunningError = class extends Error {
+  otherPid;
+  constructor(otherPid) {
+    super(`gateway already running (pid=${otherPid})`);
+    this.name = "GatewayAlreadyRunningError";
+    this.otherPid = otherPid;
   }
 };
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = err.code;
+    return code === "EPERM";
+  }
+}
+function readPidFile(p) {
+  try {
+    const text = fs.readFileSync(p, "utf-8").trim();
+    const pid = Number.parseInt(text, 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+function acquireLock(lockPath) {
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true, mode: 448 });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs.openSync(lockPath, "wx", 384);
+      fs.writeSync(fd, String(process.pid) + "\n");
+      fs.closeSync(fd);
+      return {
+        path: lockPath,
+        pid: process.pid,
+        release: () => {
+          try {
+            const pidNow = readPidFile(lockPath);
+            if (pidNow === process.pid) {
+              fs.unlinkSync(lockPath);
+            }
+          } catch {
+          }
+        }
+      };
+    } catch (err) {
+      const code = err.code;
+      if (code !== "EEXIST") throw err;
+      const otherPid = readPidFile(lockPath);
+      if (otherPid !== null && isProcessAlive(otherPid)) {
+        throw new GatewayAlreadyRunningError(otherPid);
+      }
+      try {
+        fs.unlinkSync(lockPath);
+      } catch {
+      }
+    }
+  }
+  throw new Error(`failed to acquire gateway lock at ${lockPath}`);
+}
 
 // src/gateway/relay/coordinator.ts
 var DEFAULT_RELAY_TTL_MS = 5 * 6e4;
@@ -2874,10 +3146,7 @@ var RelayCoordinator = class {
       resolveFn = resolve;
     });
     const timer = setTimeout(() => {
-      this.settlePermission(channelRequestId, {
-        kind: "cancelled",
-        reason: "timeout"
-      });
+      this.settle(channelRequestId, { kind: "cancelled", reason: "timeout" });
     }, ttlMs);
     if (typeof timer.unref === "function") timer.unref();
     const entry = {
@@ -2902,10 +3171,7 @@ var RelayCoordinator = class {
       const ctrl = controllers[idx];
       Promise.resolve().then(() => adapter.requestPermissionVerdict(fullReq, ctrl.signal)).then((res) => {
         if (res.kind === "verdict") {
-          this.settlePermission(channelRequestId, {
-            ...res,
-            channelId: adapter.id
-          });
+          this.settle(channelRequestId, { ...res, channelId: adapter.id });
         }
       }).catch((err) => {
         this.log?.(
@@ -2954,10 +3220,7 @@ var RelayCoordinator = class {
       resolveFn = resolve;
     });
     const timer = setTimeout(() => {
-      this.settleQuestion(channelRequestId, {
-        kind: "cancelled",
-        reason: "timeout"
-      });
+      this.settle(channelRequestId, { kind: "cancelled", reason: "timeout" });
     }, ttlMs);
     if (typeof timer.unref === "function") timer.unref();
     const entry = {
@@ -2981,10 +3244,7 @@ var RelayCoordinator = class {
       const ctrl = controllers[idx];
       Promise.resolve().then(() => adapter.requestQuestionAnswer(fullReq, ctrl.signal)).then((res) => {
         if (res.kind === "answer") {
-          this.settleQuestion(channelRequestId, {
-            ...res,
-            channelId: adapter.id
-          });
+          this.settle(channelRequestId, { ...res, channelId: adapter.id });
         }
       }).catch((err) => {
         this.log?.(
@@ -3001,11 +3261,7 @@ var RelayCoordinator = class {
     if (expectedRuntimeId !== void 0 && entry.runtimeId !== void 0 && entry.runtimeId !== expectedRuntimeId) {
       return false;
     }
-    if (entry.kind === "permission") {
-      this.settlePermission(channelRequestId, { kind: "cancelled", reason });
-    } else {
-      this.settleQuestion(channelRequestId, { kind: "cancelled", reason });
-    }
+    this.settle(channelRequestId, { kind: "cancelled", reason });
     return true;
   }
   pendingCount() {
@@ -3016,27 +3272,18 @@ var RelayCoordinator = class {
       this.cancel(id, reason);
     }
   }
-  settlePermission(channelRequestId, result) {
-    const entry = this.pending.get(channelRequestId);
-    if (!entry || entry.kind !== "permission" || entry.settled) return;
-    entry.settled = true;
-    this.pending.delete(channelRequestId);
-    clearTimeout(entry.timer);
-    for (const ctrl of entry.controllers) {
-      if (!ctrl.signal.aborted) ctrl.abort();
-    }
-    entry.resolve(result);
-  }
-  settleQuestion(channelRequestId, result) {
+  settle(channelRequestId, result) {
     const entry = this.pending.get(channelRequestId);
-    if (!entry || entry.kind !== "question" || entry.settled) return;
+    if (!entry || entry.settled) return;
     entry.settled = true;
     this.pending.delete(channelRequestId);
     clearTimeout(entry.timer);
     for (const ctrl of entry.controllers) {
       if (!ctrl.signal.aborted) ctrl.abort();
     }
-    entry.resolve(result);
+    entry.resolve(
+      result
+    );
   }
 };
 function permissionFingerprint(req) {
@@ -3116,112 +3363,6 @@ function initGatewayStateSchema(db) {
   }
 }
 
-// src/gateway/state/inboundQueue.ts
-var DEFAULT_MAX_ENTRIES = 1e3;
-var InboundQueue = class {
-  db;
-  maxEntries;
-  constructor(db, opts = {}) {
-    this.db = db;
-    this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
-  }
-  size() {
-    const row = this.db.prepare("SELECT COUNT(*) as n FROM inbound_queue").get();
-    return row.n;
-  }
-  enqueue(inbound) {
-    if (this.size() >= this.maxEntries) {
-      return { kind: "rejected", reason: "queue_full" };
-    }
-    const stmt = this.db.prepare(
-      `INSERT INTO inbound_queue
-				(channel_id, account_id, idempotency_key, payload_json, created_at)
-			 VALUES (?, ?, ?, ?, ?)
-			 ON CONFLICT(channel_id, account_id, idempotency_key) DO NOTHING`
-    );
-    const result = stmt.run(
-      inbound.location.channelId,
-      inbound.location.accountId,
-      inbound.idempotencyKey,
-      JSON.stringify(inbound),
-      Date.now()
-    );
-    if (result.changes === 0) {
-      return { kind: "duplicate" };
-    }
-    return { kind: "queued", id: Number(result.lastInsertRowid) };
-  }
-  /** Atomically read and remove all parked entries in FIFO order. */
-  drain() {
-    return this.db.transaction(() => {
-      const rows = this.db.prepare("SELECT id, payload_json FROM inbound_queue ORDER BY id ASC").all();
-      if (rows.length > 0) {
-        this.db.prepare("DELETE FROM inbound_queue").run();
-      }
-      return rows.map((r) => ({
-        id: r.id,
-        inbound: JSON.parse(r.payload_json)
-      }));
-    })();
-  }
-};
-
-// src/gateway/state/outbox.ts
-var Outbox = class {
-  db;
-  constructor(db) {
-    this.db = db;
-  }
-  size() {
-    const row = this.db.prepare("SELECT COUNT(*) as n FROM channel_outbox").get();
-    return row.n;
-  }
-  enqueue(input) {
-    const result = this.db.prepare(
-      `INSERT INTO channel_outbox
-					(channel_id, payload_json, attempt, next_attempt_at, last_error, created_at)
-				 VALUES (?, ?, 0, ?, ?, ?)`
-    ).run(
-      input.channelId,
-      JSON.stringify(input.message),
-      input.nextAttemptAt,
-      input.lastError ?? null,
-      Date.now()
-    );
-    return Number(result.lastInsertRowid);
-  }
-  /** Rows whose `next_attempt_at` is at or before `now`, oldest first. */
-  peekDue(now, limit) {
-    const rows = this.db.prepare(
-      `SELECT id, channel_id, payload_json, attempt, next_attempt_at, last_error
-				 FROM channel_outbox
-				 WHERE next_attempt_at <= ?
-				 ORDER BY next_attempt_at ASC, id ASC
-				 LIMIT ?`
-    ).all(now, limit);
-    return rows.map((r) => ({
-      id: r.id,
-      channelId: r.channel_id,
-      message: JSON.parse(r.payload_json),
-      attempt: r.attempt,
-      nextAttemptAt: r.next_attempt_at,
-      lastError: r.last_error
-    }));
-  }
-  delete(id) {
-    this.db.prepare("DELETE FROM channel_outbox WHERE id = ?").run(id);
-  }
-  recordFailure(input) {
-    this.db.prepare(
-      `UPDATE channel_outbox
-				 SET attempt = attempt + 1,
-				     next_attempt_at = ?,
-				     last_error = ?
-				 WHERE id = ?`
-    ).run(input.nextAttemptAt, input.lastError, input.id);
-  }
-};
-
 // src/gateway/transport/tlsWs.ts
 import { WebSocketServer } from "ws";
 import { createServer as createHttpsServer } from "https";
@@ -3466,62 +3607,35 @@ async function startDaemon(opts) {
     loopback: listenSpec.kind === "uds" || isLoopbackHost(listenSpec.host)
   };
   const stateDb = openGatewayState(paths.statePath);
-  const inboundQueue = new InboundQueue(stateDb);
-  const outbox = new Outbox(stateDb);
-  const registry = new SessionRegistry();
   const channelManager = new ChannelManager();
   const relayCoordinator = new RelayCoordinator({
     adapters: () => channelManager.listAdapters()
   });
-  const runtimeConnections = /* @__PURE__ */ new Map();
-  const staleRuntimeTimers = /* @__PURE__ */ new Map();
   const connectionOpenedAt = /* @__PURE__ */ new Map();
   const disconnectGracePeriodMs = opts.disconnectGracePeriodMs ?? 0;
   let listenerStatus = null;
-  const pushDispatch = (payload) => {
-    const current = registry.getCurrent();
-    if (!current) return;
-    const ctx = runtimeConnections.get(current.runtimeId);
-    if (!ctx) return;
-    ctx.push({
-      push_id: crypto.randomUUID(),
-      ts: Date.now(),
-      kind: "session.dispatch.turn",
-      payload
-    });
-  };
   const log = (level, message) => {
     if (opts.silent) return;
     const stream = level === "error" || level === "warn" ? "stderr" : "stdout";
     process[stream].write(`athena-gateway: [${level}] ${message}
 `);
   };
-  const outboundDispatcher = new OutboundDispatcher({
-    outbox,
+  const pipeline = new DispatchPipeline({
+    stateDb,
     send: (channelId, msg) => channelManager.send(channelId, msg),
-    log
-  });
-  outboundDispatcher.start();
-  const dispatcher = new Dispatcher({
-    registry,
-    pushDispatch,
-    canDispatch: () => {
-      const current = registry.getCurrent();
-      return current ? registry.hasActiveBinding(current.runtimeId) : false;
-    },
-    sendOutbound: async (channelId, msg) => {
-      const result = await outboundDispatcher.dispatch(channelId, msg);
-      if (result.kind === "sent") return result.result;
-      return {
-        providerMessageId: `outbox:${result.outboxId}`,
-        deliveredAt: Date.now()
-      };
-    },
-    inboundQueue,
-    log
+    gracePeriodMs: disconnectGracePeriodMs,
+    log,
+    observers: {
+      onRuntimeRebind: ({ gapMs, epoch }) => trackGatewayRuntimeRebind({ gapMs, epoch }),
+      onRuntimeExpired: ({ gapMs }) => trackGatewayRuntimeExpired({ gapMs }),
+      // Single-runtime v1: blanket dispose is safe. Multi-runtime must
+      // scope to the disconnecting runtime via disposeAllForRuntime.
+      onRuntimeConnectionLost: () => relayCoordinator.disposeAll("connection_lost")
+    }
   });
+  pipeline.start();
   channelManager.setInboundSink((inbound) => {
-    dispatcher.handleInbound(inbound);
+    pipeline.handleInbound(inbound);
   });
   const channelConfigHome = opts.env?.HOME;
   const reloadChannels = async () => {
@@ -3635,45 +3749,11 @@ async function startDaemon(opts) {
   }
   const handler = createDispatcher({
     startedAt,
-    registry,
-    dispatcher,
+    pipeline,
     channelManager,
     relayCoordinator,
     getListener: () => listenerStatus ?? buildListenerStatus(listenSpec, null),
-    reloadChannels,
-    registerRuntimeConnection: (runtimeId, ctx) => {
-      const timer = staleRuntimeTimers.get(runtimeId);
-      if (timer) {
-        clearTimeout(timer);
-        staleRuntimeTimers.delete(runtimeId);
-      }
-      const previousBinding = registry.getBinding();
-      const wasStale = previousBinding?.state === "stale";
-      const staleSince = wasStale ? previousBinding.staleSince : null;
-      registry.bindConnection(runtimeId, ctx.connectionId);
-      runtimeConnections.set(runtimeId, ctx);
-      writeGatewayTrace(
-        `daemon registered runtime runtimeId=${runtimeId} connectionId=${ctx.connectionId}`
-      );
-      if (wasStale && staleSince !== null) {
-        const newBinding = registry.getBinding();
-        if (newBinding?.state === "active") {
-          trackGatewayRuntimeRebind({
-            gapMs: Date.now() - staleSince,
-            epoch: newBinding.epoch
-          });
-        }
-      }
-    },
-    unregisterRuntimeConnection: (runtimeId) => {
-      const timer = staleRuntimeTimers.get(runtimeId);
-      if (timer) {
-        clearTimeout(timer);
-        staleRuntimeTimers.delete(runtimeId);
-      }
-      runtimeConnections.delete(runtimeId);
-      writeGatewayTrace(`daemon unregistered runtime runtimeId=${runtimeId}`);
-    }
+    reloadChannels
   });
   let server;
   let listener;
@@ -3707,39 +3787,7 @@ async function startDaemon(opts) {
           reason: "closed",
           durationMs
         });
-        const current = registry.getCurrent();
-        if (current && runtimeConnections.get(current.runtimeId)?.connectionId === ctx.connectionId) {
-          writeGatewayTrace(
-            `daemon runtime connection disconnected runtimeId=${current.runtimeId} connectionId=${ctx.connectionId}`
-          );
-          runtimeConnections.delete(current.runtimeId);
-          const staleAt = Date.now();
-          registry.markConnectionStale(ctx.connectionId);
-          if (disconnectGracePeriodMs <= 0) {
-            try {
-              registry.unregister(current.runtimeId);
-            } catch {
-            }
-            relayCoordinator.disposeAll("connection_lost");
-            return;
-          }
-          const runtimeId = current.runtimeId;
-          const timer = setTimeout(() => {
-            staleRuntimeTimers.delete(runtimeId);
-            const latest = registry.getCurrent();
-            if (latest?.runtimeId === runtimeId && !registry.hasActiveBinding(runtimeId)) {
-              try {
-                registry.unregister(runtimeId);
-              } catch {
-              }
-              relayCoordinator.disposeAll("connection_lost");
-              trackGatewayRuntimeExpired({
-                gapMs: Date.now() - staleAt
-              });
-            }
-          }, disconnectGracePeriodMs);
-          staleRuntimeTimers.set(runtimeId, timer);
-        }
+        pipeline.notifyConnectionClosed(ctx.connectionId);
       }
     });
     if (listenSpec.kind === "tcp") {
@@ -3775,11 +3823,7 @@ async function startDaemon(opts) {
     if (stopping) return;
     stopping = true;
     try {
-      outboundDispatcher.stop();
-      for (const timer of staleRuntimeTimers.values()) {
-        clearTimeout(timer);
-      }
-      staleRuntimeTimers.clear();
+      await pipeline.stop();
       relayCoordinator.disposeAll("auto_resolved");
       await channelManager.stop();
       await server.close();
@@ -3804,13 +3848,9 @@ async function startDaemon(opts) {
     startedAt,
     pid,
     paths,
-    registry,
-    dispatcher,
+    pipeline,
     channelManager,
     relayCoordinator,
-    inboundQueue,
-    outbox,
-    outboundDispatcher,
     listener,
     stop
   };