@interactive-inc/claude-funnel 0.4.1 → 0.8.0

package/lib/engine/time/memory-clock.ts

@@ -0,0 +1,26 @@
+import { FunnelClock } from "@/engine/time/clock"
+
+type Props = {
+  start?: Date
+}
+
+export class MemoryFunnelClock extends FunnelClock {
+  private current: Date
+
+  constructor(props: Props = {}) {
+    super()
+    this.current = props.start ?? new Date(0)
+  }
+
+  now(): Date {
+    return new Date(this.current.getTime())
+  }
+
+  set(date: Date): void {
+    this.current = date
+  }
+
+  advance(ms: number): void {
+    this.current = new Date(this.current.getTime() + ms)
+  }
+}

package/lib/engine/time/node-clock.ts

@@ -0,0 +1,7 @@
+import { FunnelClock } from "@/engine/time/clock"
+
+export class NodeFunnelClock extends FunnelClock {
+  now(): Date {
+    return new Date()
+  }
+}

package/lib/funnel.ts

@@ -1,95 +1,187 @@
-import { FunnelChannels } from "@/modules/channels/funnel-channels"
-import { FunnelClaude } from "@/modules/claude/funnel-claude"
-import {
-  type ConnectorStoresBundle,
-  createConnectorStores,
-} from "@/modules/connectors/funnel-connector-stores"
-import { FunnelConnectors } from "@/modules/connectors/funnel-connectors"
-import type { FunnelFileSystem } from "@/modules/fs/funnel-file-system"
-import { FunnelGateway } from "@/modules/gateway/funnel-gateway"
-import { FunnelMcp } from "@/modules/mcp/funnel-mcp"
-import { FunnelProfiles } from "@/modules/profiles/funnel-profiles"
-import { FunnelRepositories } from "@/modules/repos/funnel-repositories"
-import { FunnelSchedule } from "@/modules/schedule/funnel-schedule"
-import { FunnelSettingsReader } from "@/modules/settings/funnel-settings-reader"
+import { join } from "node:path"
+import { FunnelConnectorFactory } from "@/connectors/connector-factory"
+import { FunnelChannels } from "@/engine/channels/channels"
+import { FunnelClaude } from "@/engine/claude/claude"
+import type { FunnelFileSystem } from "@/engine/fs/file-system"
+import type { FunnelIdGenerator } from "@/engine/id/id-generator"
+import { FunnelLogger } from "@/engine/logger/logger"
+import { NodeFunnelLogger } from "@/engine/logger/node-logger"
+import { FunnelMcp } from "@/engine/mcp/mcp"
+import { FunnelProcessRunner } from "@/engine/process/process-runner"
+import { NodeFunnelProcessRunner } from "@/engine/process/node-process-runner"
+import { FunnelProfiles } from "@/engine/profiles/profiles"
+import { FunnelSettingsReader } from "@/engine/settings/settings-reader"
+import { FUNNEL_DIR, FunnelSettingsStore } from "@/engine/settings/settings-store"
+import type { FunnelClock } from "@/engine/time/clock"
+import { FunnelGateway } from "@/gateway/gateway"
+import { FunnelGatewayServer } from "@/gateway/gateway-server"
+import { FunnelGatewayToken } from "@/gateway/gateway-token"
+import { FunnelListenersClient } from "@/gateway/listeners-client"
 
 type Props = {
-  store: FunnelSettingsReader
+  /** Settings persistence (channels with nested connectors / profiles). Defaults to a FunnelSettingsStore rooted at `dir`. */
+  store?: FunnelSettingsReader
+  /** Filesystem boundary. Replace with MemoryFunnelFileSystem to sandbox all disk I/O. */
   fs?: FunnelFileSystem
+  /** Process runner used by gateway / claude / gh listener. Replace with MemoryFunnelProcessRunner for tests. */
+  process?: FunnelProcessRunner
+  /** Logger flowed into every facet. Replace with MemoryFunnelLogger or NoopFunnelLogger to silence/inspect. */
+  logger?: FunnelLogger
+  /** Clock used by schedule listener, gh poll watermarks, and gateway timeouts. */
+  clock?: FunnelClock
+  /** ID generator for channel and connector ids. Use MemoryFunnelIdGenerator for deterministic tests. */
+  idGenerator?: FunnelIdGenerator
+  /** Funnel home directory (settings.json + per-channel/per-connector dirs). Defaults to ~/.funnel. */
   dir?: string
-  connectorStores?: ConnectorStoresBundle
+  /** Temp / runtime directory (gateway logs and PID adjacent files). Defaults to /tmp/funnel. */
+  tmpDir?: string
 }
 
+/**
+ * Facade exposing every funnel facet as a getter.
+ *
+ * The same `Funnel` is used by the CLI, the TUI, and as a programmable library.
+ * All side-effecting boundaries (filesystem, process, logger, clock, id, paths) are
+ * injectable via `Props` — passing memory implementations gives a fully sandboxed
+ * Funnel that touches no real disk, processes, or wall-clock time.
+ *
+ * Connectors live nested inside their owning channel (channels[].connectors[]),
+ * so connector CRUD is reached via `funnel.channels.addConnector(...)` etc.
+ *
+ * @example
+ * ```ts
+ * const funnel = new Funnel({})
+ * const channel = funnel.channels.add({ name: "inbox" })
+ * funnel.channels.addConnector("inbox", { type: "slack", name: "ops", botToken, appToken })
+ * await funnel.gatewayServer({ port: 9742 }).start()
+ * ```
+ */
 export class Funnel {
-  constructor(private readonly props: Props) {
+  constructor(private readonly props: Props = {}) {
     Object.freeze(this)
   }
 
-  get stores(): ConnectorStoresBundle {
+  /** Settings reader. If not injected, a FunnelSettingsStore rooted at `dir` is created. */
+  get store(): FunnelSettingsReader {
     return (
-      this.props.connectorStores ??
-      createConnectorStores({ fs: this.props.fs, dir: this.props.dir })
+      this.props.store ??
+      new FunnelSettingsStore({
+        path: join(this.props.dir ?? FUNNEL_DIR, "settings.json"),
+        fs: this.props.fs,
+      })
     )
   }
 
-  get connectors(): FunnelConnectors {
-    const stores = this.stores
-    const profiles = this.profiles
-    const channels: FunnelChannels = new FunnelChannels({
-      store: this.props.store,
-      connectorChecker: { has: (name) => connectors.has(name) },
-      profileChecker: profiles,
-      profileRefUpdater: profiles,
-    })
-    const connectors: FunnelConnectors = new FunnelConnectors({
-      ...stores,
-      refUpdater: channels,
-    })
-    return connectors
+  /** Process runner boundary. Defaults to NodeFunnelProcessRunner. */
+  get process(): FunnelProcessRunner {
+    return this.props.process ?? new NodeFunnelProcessRunner()
   }
 
-  get channels(): FunnelChannels {
-    const stores = this.stores
-    const profiles = this.profiles
-    const channels: FunnelChannels = new FunnelChannels({
-      store: this.props.store,
-      connectorChecker: { has: (name) => connectors.has(name) },
-      profileChecker: profiles,
-      profileRefUpdater: profiles,
-    })
-    const connectors: FunnelConnectors = new FunnelConnectors({
-      ...stores,
-      refUpdater: channels,
+  /** Logger boundary. Defaults to NodeFunnelLogger. */
+  get logger(): FunnelLogger {
+    return this.props.logger ?? new NodeFunnelLogger()
+  }
+
+  /** Pure factory that constructs per-type listeners and adapters from connector configs. */
+  get factory(): FunnelConnectorFactory {
+    return new FunnelConnectorFactory({
+      fs: this.props.fs,
+      process: this.props.process,
+      logger: this.props.logger,
+      dir: this.props.dir,
     })
-    return channels
   }
 
-  get schedule(): FunnelSchedule {
-    return new FunnelSchedule({ store: this.stores.schedule })
+  /** Channel CRUD + nested connector CRUD + schedule entries + listener/adapter dispatch. */
+  get channels(): FunnelChannels {
+    return new FunnelChannels({
+      store: this.store,
+      factory: this.factory,
+      profileChecker: this.profiles,
+      clock: this.props.clock,
+      idGenerator: this.props.idGenerator,
+    })
   }
 
+  /** Launch profiles (named presets for `fnl claude`: path + sub-agent + channel id). */
   get profiles(): FunnelProfiles {
-    return new FunnelProfiles({ store: this.props.store })
+    return new FunnelProfiles({ store: this.store })
   }
 
-  get repositories(): FunnelRepositories {
-    return new FunnelRepositories({ store: this.props.store, mcp: this.mcp })
+  /** funnel MCP installer (writes/removes `.mcp.json` entries in target repos). */
+  get mcp(): FunnelMcp {
+    return new FunnelMcp({ fs: this.props.fs })
   }
 
+  /** Launch Claude Code with a channel injected via env, MCP installed, gateway ensured. */
   get claude(): FunnelClaude {
     return new FunnelClaude({
       channels: this.channels,
-      repositories: this.repositories,
       mcp: this.mcp,
       gateway: this.gateway,
+      fs: this.props.fs,
+      process: this.props.process,
+      logger: this.props.logger,
+      dir: this.props.dir,
     })
   }
 
+  /** Gateway daemon controller (PID-file, start/stop the separate `bun daemon.ts` process). */
   get gateway(): FunnelGateway {
-    return new FunnelGateway()
+    return new FunnelGateway({
+      fs: this.props.fs,
+      process: this.props.process,
+      clock: this.props.clock,
+      dir: this.props.dir,
+      tmpDir: this.props.tmpDir,
+    })
   }
 
-  get mcp(): FunnelMcp {
-    return new FunnelMcp()
+  /** Read / generate the daemon's gateway token (mode 0600 file under `dir`). */
+  get gatewayToken(): FunnelGatewayToken {
+    return new FunnelGatewayToken({ fs: this.props.fs, dir: this.props.dir })
+  }
+
+  /**
+   * HTTP client for listener operations on the running gateway daemon.
+   * Returns `{ state: "offline" }` when the daemon is offline so hot-reload
+   * paths stay write-only without parsing strings.
+   */
+  get listeners(): FunnelListenersClient {
+    const gateway = this.gateway
+    const token = this.gatewayToken
+
+    return new FunnelListenersClient({
+      port: gateway.getPort(),
+      isDaemonRunning: () => gateway.isRunning(),
+      getToken: () => token.read(),
+    })
+  }
+
+  /**
+   * In-process gateway server. Unlike `gateway.start()` (which spawns a daemon),
+   * this returns a class that runs `Bun.serve` + listeners inside the current process —
+   * useful for tests, embedding, or custom hosts.
+   */
+  gatewayServer(
+    options: {
+      port?: number
+      logDir?: string
+      killCompetingSlack?: boolean
+      /** Override the auth token. Defaults to the persisted gateway.token. Pass "" to disable auth (tests). */
+      token?: string
+    } = {},
+  ): FunnelGatewayServer {
+    return new FunnelGatewayServer({
+      channels: this.channels,
+      settings: this.store,
+      port: options.port,
+      logDir: options.logDir,
+      process: this.props.process,
+      clock: this.props.clock,
+      logger: this.props.logger,
+      killCompetingSlack: options.killCompetingSlack,
+      token: options.token ?? this.gatewayToken.ensure(),
+    })
   }
 }

package/lib/gateway/auth-middleware.ts

@@ -0,0 +1,44 @@
+import { timingSafeEqual } from "node:crypto"
+import type { MiddlewareHandler } from "hono"
+import type { Env } from "@/gateway/factory"
+
+type Deps = {
+  expected: string
+}
+
+/**
+ * Verifies `Authorization: Bearer <token>` against the daemon's gateway token.
+ * Mounted on the routes that mutate listener state or expose detailed status.
+ * `/health` is intentionally left unauthenticated so the daemon manager can
+ * probe liveness without needing the token.
+ */
+export const requireBearerToken = (deps: Deps): MiddlewareHandler<Env> => {
+  return async (c, next) => {
+    const header = c.req.header("authorization") ?? ""
+    const match = header.match(/^Bearer\s+(.+)$/i)
+    const presented = match?.[1] ?? ""
+
+    if (!constantTimeEqual(presented, deps.expected)) {
+      return c.text("unauthorized", 401)
+    }
+
+    return await next()
+  }
+}
+
+export const constantTimeEqual = (a: string, b: string): boolean => {
+  const bufA = Buffer.from(a, "utf-8")
+  const bufB = Buffer.from(b, "utf-8")
+  const maxLen = Math.max(bufA.length, bufB.length, 1)
+  const padA = Buffer.alloc(maxLen)
+  const padB = Buffer.alloc(maxLen)
+
+  bufA.copy(padA)
+  bufB.copy(padB)
+
+  // timingSafeEqual on equal-length padded buffers, then AND with length match
+  // so a length-only probe still requires the full comparison time.
+  const equal = timingSafeEqual(padA, padB)
+
+  return equal && bufA.length === bufB.length
+}

package/lib/gateway/broadcaster.ts

@@ -0,0 +1,319 @@
+import type { ServerWebSocket } from "bun"
+import { FunnelLogger } from "@/engine/logger/logger"
+import { NoopFunnelLogger } from "@/engine/logger/noop-logger"
+
+const byteLengthOf = (event: { content: string; meta?: Record<string, string> }): number => {
+  let bytes = Buffer.byteLength(event.content, "utf-8")
+
+  if (event.meta) {
+    for (const [k, v] of Object.entries(event.meta)) {
+      bytes += Buffer.byteLength(k, "utf-8") + Buffer.byteLength(v, "utf-8")
+    }
+  }
+
+  return bytes
+}
+
+type ClientData = {
+  /** Stable channel id (uuid) that the WS client subscribed to. */
+  channel: string
+  /** Human-facing channel name resolved at upgrade time, kept for log readability. */
+  channelName?: string | null
+  /** Connector names belonging to that channel; used by tap-all replay filtering. */
+  connectors: string[]
+  tapAll?: boolean
+  /** Routing mode resolved from channel config at upgrade time. Defaults to fanout. */
+  delivery?: "fanout" | "exclusive"
+}
+
+export type BroadcastEvent = {
+  content: string
+  meta?: Record<string, string>
+}
+
+export type ReplayableEvent = BroadcastEvent & { offset: number }
+
+export type BroadcastSubscriber = (event: ReplayableEvent) => void
+
+/**
+ * Optional persistent replay source. Wired in by the gateway-server with
+ * `FunnelEventStore` (SQLite-backed) so reconnects across daemon restarts
+ * can recover events older than the in-memory buffer via an indexed
+ * `seq > since` range scan.
+ */
+type ReplaySource = {
+  loadSince(since: number): ReplayableEvent[]
+}
+
+type Deps = {
+  logger?: FunnelLogger
+  maxBufferedBytes?: number
+  now?: () => number
+  /** Number of recent events kept in the in-memory replay buffer. */
+  replayBufferSize?: number
+  /** Hard byte cap on replay buffer payloads. Older events are evicted FIFO until under this cap. */
+  replayBufferMaxBytes?: number
+  /** Persistent replay source consulted when the in-memory buffer cannot satisfy `since`. */
+  persistentReplay?: ReplaySource
+}
+
+const DEFAULT_MAX_BUFFERED_BYTES = 1024 * 1024
+const DEFAULT_REPLAY_BUFFER_SIZE = 200
+const DEFAULT_REPLAY_BUFFER_MAX_BYTES = 4 * 1024 * 1024
+const defaultLogger = new NoopFunnelLogger()
+
+type BroadcasterMetrics = {
+  clients: number
+  subscribers: number
+  eventsBroadcast: number
+  droppedSlowClients: number
+  lastBroadcastAt: string | null
+  /** Latest emitted offset. Clients can `?since=<offset>` to ask for events strictly after this point. */
+  latestOffset: number
+  /** Oldest offset still held in the replay buffer. Older values cannot be replayed and trigger a full resync. */
+  oldestReplayableOffset: number | null
+}
+
+/**
+ * In-process pub/sub for connector events.
+ *
+ * Two outbound paths:
+ *   - WS clients connected via the gateway's `/ws` endpoint, scoped per channel
+ *   - In-process subscribers registered via `subscribe()` (programmable API)
+ *
+ * Backpressure: if a WS client's `bufferedAmount` exceeds `maxBufferedBytes`
+ * (default 1 MiB), the client is closed with code 1009 and dropped from the
+ * registry to keep one slow consumer from blocking the daemon.
+ *
+ * Replay: every emitted event gets a strictly increasing `offset`. The latest
+ * `replayBufferSize` events are kept in memory; reconnecting WS clients can
+ * pass `?since=<offset>` and the broadcaster resends matching events before
+ * resuming the live stream. The in-memory ring covers short reconnects;
+ * older history is served from the SQLite event store wired in as
+ * `persistentReplay`.
+ */
+export class FunnelBroadcaster {
+  private readonly clients: Map<ServerWebSocket<unknown>, ClientData> = new Map()
+  private readonly subscribers: Set<BroadcastSubscriber> = new Set()
+  private readonly logger: FunnelLogger
+  private readonly maxBufferedBytes: number
+  private readonly now: () => number
+  private readonly replayBufferSize: number
+  private readonly replayBufferMaxBytes: number
+  private readonly replayBuffer: ReplayableEvent[] = []
+  private readonly persistentReplay: ReplaySource | null
+  private readonly exclusiveCursor = new Map<string, number>()
+  private replayBufferBytes = 0
+  private eventsBroadcast = 0
+  private droppedSlowClients = 0
+  private lastBroadcastAt: number | null = null
+  private latestOffset = 0
+
+  constructor(deps: Deps = {}) {
+    this.logger = deps.logger ?? defaultLogger
+    this.maxBufferedBytes = deps.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES
+    this.now = deps.now ?? (() => Date.now())
+    this.replayBufferSize = Math.max(0, deps.replayBufferSize ?? DEFAULT_REPLAY_BUFFER_SIZE)
+    this.replayBufferMaxBytes = Math.max(
+      0,
+      deps.replayBufferMaxBytes ?? DEFAULT_REPLAY_BUFFER_MAX_BYTES,
+    )
+    this.persistentReplay = deps.persistentReplay ?? null
+  }
+
+  getMetrics(): BroadcasterMetrics {
+    return {
+      clients: this.clients.size,
+      subscribers: this.subscribers.size,
+      eventsBroadcast: this.eventsBroadcast,
+      droppedSlowClients: this.droppedSlowClients,
+      lastBroadcastAt: this.lastBroadcastAt ? new Date(this.lastBroadcastAt).toISOString() : null,
+      latestOffset: this.latestOffset,
+      oldestReplayableOffset: this.replayBuffer[0]?.offset ?? null,
+    }
+  }
+
+  /**
+   * Returns events with offset > since, filtered by the connector subscription
+   * rules of `data`. Used at WS upgrade time when the client passes `?since=<offset>`.
+   *
+   * Two-tier lookup:
+   *   1. The in-memory ring buffer (covers short reconnects, last `replayBufferSize` events).
+   *   2. If `since` predates the oldest in-memory entry and a persistent replay source
+   *      is wired in (SQLite), the gap is filled from disk. This covers reconnects across
+   *      daemon restarts where the in-memory buffer was lost.
+   *
+   * Result is sorted ascending by offset and de-duplicated against the in-memory buffer.
+   */
+  replaySince(since: number, data: ClientData): ReplayableEvent[] {
+    const oldestInMemory = this.replayBuffer[0]?.offset
+    const needFallback =
+      this.persistentReplay && (oldestInMemory === undefined || since < oldestInMemory - 1)
+    const fromMemory = this.replayBuffer.filter(
+      (event) => event.offset > since && this.matchesClient(event, data),
+    )
+
+    if (!needFallback) return fromMemory
+
+    const persisted = this.persistentReplay
+      ? this.persistentReplay.loadSince(since).filter((event) => this.matchesClient(event, data))
+      : []
+    const cutoff = oldestInMemory ?? Number.POSITIVE_INFINITY
+    const beforeMemory = persisted.filter((event) => event.offset < cutoff)
+
+    return [...beforeMemory, ...fromMemory]
+  }
+
+  private matchesClient(event: BroadcastEvent, data: ClientData): boolean {
+    if (data.tapAll) return true
+
+    const channelId = event.meta?.channelId
+
+    if (channelId && channelId !== data.channel) return false
+
+    const connector = event.meta?.connector
+
+    if (!connector) return true
+
+    return data.connectors.includes(connector)
+  }
+
+  /**
+   * Returns the list of WS clients that should receive `event`. Tap=all clients always
+   * receive (passive observation). For each per-channel group:
+   *   - fanout → every matching client receives
+   *   - exclusive → exactly one client receives, picked round-robin per channel
+   */
+  private pickRecipients(event: BroadcastEvent): ServerWebSocket<unknown>[] {
+    const exclusiveByChannel = new Map<string, ServerWebSocket<unknown>[]>()
+    const recipients: ServerWebSocket<unknown>[] = []
+
+    for (const [ws, data] of this.clients) {
+      if (!this.matchesClient(event, data)) continue
+
+      if (data.tapAll) {
+        recipients.push(ws)
+        continue
+      }
+
+      if (data.delivery === "exclusive") {
+        const list = exclusiveByChannel.get(data.channel) ?? []
+
+        list.push(ws)
+        exclusiveByChannel.set(data.channel, list)
+        continue
+      }
+
+      recipients.push(ws)
+    }
+
+    for (const [channel, candidates] of exclusiveByChannel) {
+      if (candidates.length === 0) continue
+
+      const cursor = this.exclusiveCursor.get(channel) ?? 0
+      const picked = candidates[cursor % candidates.length]
+
+      if (picked) recipients.push(picked)
+
+      this.exclusiveCursor.set(channel, cursor + 1)
+    }
+
+    return recipients
+  }
+
+  addClient(ws: ServerWebSocket<unknown>, data: ClientData): void {
+    this.clients.set(ws, data)
+  }
+
+  removeClient(ws: ServerWebSocket<unknown>): void {
+    this.clients.delete(ws)
+  }
+
+  getClientCount(): number {
+    return this.clients.size
+  }
+
+  listChannels(): { channel: string; connectors: string[] }[] {
+    return [...this.clients.values()].map((d) => ({ ...d }))
+  }
+
+  subscribe(handler: BroadcastSubscriber): () => void {
+    this.subscribers.add(handler)
+
+    return () => {
+      this.subscribers.delete(handler)
+    }
+  }
+
+  broadcast(content: string, meta?: Record<string, string>): ReplayableEvent {
+    this.latestOffset += 1
+    const event: ReplayableEvent = { content, meta, offset: this.latestOffset }
+    const payload = JSON.stringify(event)
+    const connector = meta?.connector
+
+    this.eventsBroadcast += 1
+    this.lastBroadcastAt = this.now()
+
+    if (this.replayBufferSize > 0) {
+      const eventBytes = byteLengthOf(event)
+
+      this.replayBuffer.push(event)
+      this.replayBufferBytes += eventBytes
+
+      while (
+        (this.replayBuffer.length > this.replayBufferSize ||
+          this.replayBufferBytes > this.replayBufferMaxBytes) &&
+        this.replayBuffer.length > 0
+      ) {
+        const dropped = this.replayBuffer.shift()
+
+        if (dropped) this.replayBufferBytes -= byteLengthOf(dropped)
+      }
+    }
+
+    const recipients = this.pickRecipients(event)
+
+    for (const ws of recipients) {
+      const buffered = ws.getBufferedAmount()
+
+      if (buffered > this.maxBufferedBytes) {
+        const data = this.clients.get(ws)
+
+        this.logger.warn("dropping slow WS client (backpressure)", {
+          channel: data?.channel,
+          buffered,
+          max: this.maxBufferedBytes,
+        })
+
+        try {
+          ws.close(1009, "backpressure")
+        } catch {
+          // ignore
+        }
+
+        this.clients.delete(ws)
+        this.droppedSlowClients += 1
+        continue
+      }
+
+      ws.send(payload)
+    }
+
+    for (const handler of this.subscribers) {
+      try {
+        handler(event)
+      } catch (error) {
+        this.logger.error("broadcast subscriber threw", {
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
+
+    return event
+  }
+
+  /** Forward-seed the offset counter (used at startup from the persisted event store). */
+  seedLatestOffset(offset: number): void {
+    if (offset > this.latestOffset) this.latestOffset = offset
+  }
+}

package/lib/gateway/daemon.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env bun
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { FUNNEL_DIR } from "@/engine/settings/settings-store"
+import { Funnel } from "@/funnel"
+import { NodeFunnelLogger } from "@/engine/logger/node-logger"
+
+const PORT = Number(process.env.FUNNEL_PORT) || 9742
+const PID_FILE = join(FUNNEL_DIR, "gateway.pid")
+const LOG_DIR = "/tmp/funnel/events"
+
+const logger = new NodeFunnelLogger()
+
+mkdirSync(FUNNEL_DIR, { recursive: true })
+
+if (existsSync(PID_FILE)) {
+  const existing = Number(readFileSync(PID_FILE, "utf-8").trim())
+
+  if (existing > 0) {
+    const check = Bun.spawnSync(["ps", "-p", String(existing), "-o", "state="], {
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+
+    if (check.exitCode === 0 && check.stdout.toString().trim()) {
+      logger.error("funnel gateway already running", { pid: existing })
+      process.exit(1)
+    }
+  }
+}
+
+writeFileSync(PID_FILE, String(process.pid))
+
+process.on("exit", () => {
+  try {
+    unlinkSync(PID_FILE)
+  } catch {
+    // ignore
+  }
+})
+process.on("SIGINT", () => process.exit(130))
+process.on("SIGTERM", () => process.exit(143))
+
+const funnel = new Funnel({ logger })
+const server = funnel.gatewayServer({ port: PORT, logDir: LOG_DIR })
+
+await server.start()