switchroom 0.14.8 → 0.14.10

package/telegram-plugin/gateway/gateway.ts

@@ -53,14 +53,7 @@ import { OutboundDedupCache } from '../recent-outbound-dedup.js'
 import { createInboundCoalescer, inboundCoalesceKey } from './inbound-coalesce.js'
 import { StatusReactionController } from '../status-reactions.js'
 import { isTelegramReplyTool, isTelegramSurfaceTool } from '../tool-names.js'
-import {
-  makeEmptyActivityState,
-  registerAndRender,
-  describeToolUse,
-  appendActivityLine,
-  appendActivityLabel,
-  type ActivityState,
-} from '../tool-activity-summary.js'
+import { appendActivityLabel } from '../tool-activity-summary.js'
 import { toolLabel } from '../tool-labels.js'
 import { createTypingWrapper } from '../typing-wrap.js'
 import { type DraftStreamHandle } from '../draft-stream.js'
@@ -270,6 +263,8 @@ import { formatUpdateStatusLine } from './update-status-line.js'
 import type { HostdRequest } from '../../src/host-control/protocol.js'
 import type { AgentAudit } from '../welcome-text.js'
 import { shouldSweepChatAtBoot } from './boot-sweep-filter.js'
+import { startWebhookIngestServer } from './webhook-ingest-server.js'
+import { recordWebhookEvent } from '../../src/web/webhook-gateway-record.js'
 
 import { createIpcServer, type IpcClient, type IpcServer } from './ipc-server.js'
 import { handleRequestDriveApproval } from './drive-write-approval.js'
@@ -1352,16 +1347,14 @@ type CurrentTurn = {
   //     repeats until the pending matches the last-sent.
   // Result: at most one Telegram call in flight at a time; the
   // final state always lands.
-  toolActivity: ActivityState
   activityMessageId: number | null
   activityInFlight: Promise<void> | null
   activityPendingRender: string | null
   activityLastSentRender: string | null
-  // Accumulating friendly-action feed for this turn (DRAFT_MIRROR only).
-  // Each non-surface tool_use appends a line via `appendActivityLine`; the
-  // feed renders (via `renderActivityFeed`) as a capped chronological list
-  // into the in-place edited activity message and clears on reply. Reset
-  // per turn.
+  // Accumulating friendly-action feed for this turn. Each non-surface
+  // tool_label appends a line via `appendActivityLabel`; the feed renders
+  // (via `renderActivityFeed`) as a capped chronological list into the
+  // in-place edited activity message and clears on reply. Reset per turn.
   mirrorLines: string[]
   // Issue #195 — answer-lane streaming. Lazily created on the first text
   // event of a turn (once enough text has accumulated, the stream itself
@@ -3254,25 +3247,16 @@ const ANSWER_STREAM_VISIBLE_ENABLED = (() => {
   return true
 })()
 
-// Activity-feed flag (RFC docs/rfcs/draft-mirror-preview.md). When enabled,
-// the gateway streams a live "what it's doing" tool-activity feed for the
-// turn. The PreToolUse sidecar emits a `tool_label` per tool call (flush-
-// independent, so it stays real-time on fast/clustered-tool turns); each
-// label appends to `turn.mirrorLines`, and `renderActivityFeed` renders the
-// capped list into an in-place EDITED message (sendMessage + editMessageText)
-// anchored as a native reply-quote to the user's question. The feed clears on
-// the first reply (hand-off to the answer) and again at turn_end (the no-reply
-// safety net). It does NOT touch the answer-stream's draft/visible lane — the
-// two render on separate surfaces, so they never collide. (The env name is
-// historical: an earlier design mirrored into the compose-area draft; the feed
-// is now a normal edited message.) Default OFF (canary). Kill switch:
-// SWITCHROOM_DRAFT_MIRROR unset/0/false/off/no.
-const DRAFT_MIRROR_ENABLED = (() => {
-  const raw = process.env.SWITCHROOM_DRAFT_MIRROR
-  if (raw == null) return false
-  const v = raw.trim().toLowerCase()
-  return !(v === '0' || v === 'false' || v === 'off' || v === 'no')
-})()
+// Activity feed. The gateway streams a live "what it's doing" tool-activity
+// feed for every turn. The PreToolUse sidecar emits a `tool_label` per tool
+// call (flush-independent, so it stays real-time on fast/clustered-tool
+// turns); each label appends to `turn.mirrorLines`, and `renderActivityFeed`
+// renders the capped list into an in-place EDITED message (sendMessage +
+// editMessageText) anchored as a native reply-quote to the user's question.
+// The feed clears on the first reply (hand-off to the answer) and again at
+// turn_end (the no-reply safety net). It does NOT touch the answer-stream's
+// draft/visible lane — the two render on separate surfaces, so they never
+// collide.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const progressDriver: any = null
 const unpinProgressCardForChat: ((chatId: string, threadId: number | undefined) => void) | null = null
@@ -4670,6 +4654,89 @@ const ipcServer: IpcServer = createIpcServer({
   log: (msg) => process.stderr.write(`telegram gateway: ipc — ${msg}\n`),
 })
 
+// ─── Webhook ingest server (RFC webhook-via-gateway-socket) ───────────────
+// Under the Docker runtime the host-side web receiver runs as the operator
+// UID and cannot write this agent's UID-owned dir (EACCES 500) nor connect
+// gateway.sock. When `channels.telegram.webhook_via_gateway` is set, the
+// receiver instead forwards verified+rendered events here over a dedicated
+// peercred-gated UDS; this gateway (agent UID) owns the jsonl append,
+// dedup, and dispatch firing. Wrapped so any failure is best-effort and can
+// NEVER crash gateway boot (which would take the agent down).
+;(() => {
+  try {
+    const selfAgent = process.env.SWITCHROOM_AGENT_NAME ?? ''
+    if (!selfAgent) return
+
+    let viaGateway = false
+    try {
+      const cfg = loadSwitchroomConfig()
+      const raw = cfg.agents?.[selfAgent]
+      viaGateway = raw
+        ? resolveAgentConfig(cfg.defaults, cfg.profiles, raw).channels?.telegram
+            ?.webhook_via_gateway === true
+        : false
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: webhook-ingest config probe failed: ${(err as Error).message}\n`,
+      )
+    }
+    if (!viaGateway) return
+
+    // Allowed peer UIDs: the agent's own UID (self-connections) + the
+    // operator/receiver UID emitted into the env by the compose generator
+    // (SWITCHROOM_WEBHOOK_RECEIVER_UID == operatorUid). Fail-closed: if the
+    // receiver UID is unset, only self can connect → receiver gets 503,
+    // surfacing the misconfiguration instead of silently accepting any UID.
+    const allowedUids: number[] = []
+    const ownUid = typeof process.getuid === 'function' ? process.getuid() : null
+    if (ownUid !== null) allowedUids.push(ownUid)
+    const receiverUidRaw = process.env.SWITCHROOM_WEBHOOK_RECEIVER_UID
+    const receiverUid = receiverUidRaw ? Number(receiverUidRaw) : NaN
+    if (Number.isInteger(receiverUid)) allowedUids.push(receiverUid)
+
+    const socketPath = join(STATE_DIR, 'webhook.sock')
+
+    // In-process delivery of a synthesized webhook turn — the same
+    // sendToAgent + buffer-on-failure primitive onInjectInbound uses, so a
+    // webhook fire landing mid bridge-reconnect is buffered, not dropped.
+    const webhookInject = (agentName: string, inbound: unknown): boolean => {
+      // The wire record is a structural mirror of the bridge's
+      // InboundMessage (same cast the scheduler's ipcDispatcher uses).
+      const msg = inbound as InboundMessage
+      const delivered = ipcServer.sendToAgent(agentName, msg)
+      if (delivered) markClaudeBusyForInbound(msg)
+      else pendingInboundBuffer.push(agentName, msg)
+      return delivered
+    }
+
+    startWebhookIngestServer({
+      socketPath,
+      allowedUids,
+      log: (s) => process.stderr.write(`telegram gateway: ${s}`),
+      onRecord: (req) =>
+        recordWebhookEvent(
+          {
+            agent: selfAgent,
+            source: req.source,
+            event_type: req.event_type,
+            ts: req.ts,
+            rendered_text: req.rendered_text,
+            payload: req.payload,
+            ...(req.delivery_id ? { delivery_id: req.delivery_id } : {}),
+          },
+          {
+            inject: webhookInject,
+            log: (s) => process.stderr.write(`telegram gateway: ${s}`),
+          },
+        ),
+    })
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: webhook-ingest server start failed (non-fatal): ${(err as Error).message}\n`,
+    )
+  }
+})()
+
 // ─── Opportunistic idle-drain of pendingInboundBuffer ─────────────────────
 // pendingInboundBuffer otherwise drains only on (a) bridge re-register
 // (onClientRegistered) or (b) the silence-poke framework fallback
@@ -6946,23 +7013,18 @@ async function drainActivitySummary(turn: CurrentTurn): Promise<void> {
     while (turn.activityPendingRender !== turn.activityLastSentRender) {
       const target = turn.activityPendingRender
       if (target == null) break
-      // Two mutually-exclusive producers feed `activityPendingRender`
-      // (gated on DRAFT_MIRROR_ENABLED in handleSessionEvent):
-      //  - feed ON: `renderActivityFeed` already emitted ready Telegram HTML
-      //    with per-line markup (<b>→ current</b> / <i>✓ done</i>) and escaped
-      //    each label's <,>,& itself (#1942 class) — send verbatim, do NOT
-      //    re-escape or re-wrap (double-escaping would surface literal tags).
-      //  - feed OFF: the legacy verb-count summary is plain text — escape and
-      //    wrap in a single <i>.
-      const html = DRAFT_MIRROR_ENABLED ? target : `<i>${escapeHtmlForTg(target)}</i>`
+      // `renderActivityFeed` already emitted ready Telegram HTML with per-line
+      // markup (<b>→ current</b> / <i>✓ done</i>) and escaped each label's
+      // <,>,& itself (#1942 class) — send verbatim, do NOT re-escape or
+      // re-wrap (double-escaping would surface literal tags).
+      const html = target
       const chat = turn.sessionChatId
       const thread = turn.sessionThreadId
       // Native reply-quote: anchor the feed message to the user's question so
       // it renders as a quoted header (reply_parameters renders on a real
-      // message; edits preserve it). Feed-only — the legacy summary is left
-      // visually unchanged. allow_sending_without_reply so a deleted source
-      // can't drop the send.
-      const replyAnchor = DRAFT_MIRROR_ENABLED && turn.sourceMessageId != null
+      // message; edits preserve it). allow_sending_without_reply so a deleted
+      // source can't drop the send.
+      const replyAnchor = turn.sourceMessageId != null
         ? { reply_parameters: { message_id: turn.sourceMessageId, allow_sending_without_reply: true } }
         : {}
       try {
@@ -7090,7 +7152,6 @@ function handleSessionEvent(ev: SessionEvent): void {
           lastAssistantMsgId: null,
           lastAssistantDone: false,
           toolCallCount: 0,
-          toolActivity: makeEmptyActivityState(),
           activityMessageId: null,
           activityInFlight: null,
           activityPendingRender: null,
@@ -7228,51 +7289,20 @@ function handleSessionEvent(ev: SessionEvent): void {
           turn.orphanedReplyTimeoutId = null
         }
         // The model's real reply takes over as the authoritative
-        // surface, so delete the activity summary message — the user
-        // sees the real reply land in the same beat the summary
-        // disappears. Applies to both producers (legacy verb-count and
-        // the DRAFT_MIRROR feed); turn_end is the no-reply safety net.
+        // surface, so delete the activity feed message — the user
+        // sees the real reply land in the same beat the feed
+        // disappears. turn_end is the no-reply safety net.
         if (wasFirstReply) {
           clearActivitySummary(turn)
         }
       }
-      // Tool-activity summary — same shape Claude Code natively renders
-      // in its CLI/chat UI ("Ran 5 commands, read a file"). The gateway
-      // accumulates non-reply tool_use events into `turn.toolActivity`
-      // and sends ONE Telegram message that edits in place as more tools
-      // land. Stops editing once the model calls `reply` — the summary
-      // line stays as the final state. No model-side prompting; no per-
-      // tool labels. Just surface what's already in the stream.
-      //
-      // Single-flight coalescing (PR #1926 review): modern Claude emits
-      // multiple tool_uses in a synchronous burst (parallel Reads,
-      // Bashes, etc.). All would otherwise race past the message-id
-      // capture and produce N messages. Pattern mirrors answer-stream:
-      // update `activityPendingRender` synchronously here; a single
-      // worker promise drains the pending state, sending or editing
-      // exactly once at a time and re-running until pending matches
-      // the last-sent. Captures `turn` so a late drain after turn-swap
-      // can't corrupt the next turn's atom.
-      //
-      // This (flush-gated) tool_use path drives the summary ONLY when
-      // DRAFT_MIRROR is OFF: the legacy generic verb-count summary
-      // ("Ran 5 commands") via registerAndRender. When DRAFT_MIRROR is
-      // ON the summary is instead driven by the real-time `tool_label`
-      // event (PreToolUse sidecar, fires at tool-call time regardless of
-      // when claude flushes the transcript) — see `case 'tool_label'`.
-      // That's the determinism fix: on a fast/clustered-tool turn the
-      // JSONL tool_use rows aren't on disk until ~turn-end, so sourcing
-      // the feed here lost it; the sidecar is flush-independent. Both
-      // producers feed `activityPendingRender` and clear on first reply.
-      if (!DRAFT_MIRROR_ENABLED && !turn.replyCalled && !isTelegramSurfaceTool(name)) {
-        const rendered = registerAndRender(turn.toolActivity, name)
-        if (rendered != null) {
-          turn.activityPendingRender = rendered
-          if (turn.activityInFlight == null) {
-            turn.activityInFlight = drainActivitySummary(turn)
-          }
-        }
-      }
+      // The live activity feed is driven by the real-time `tool_label`
+      // event (PreToolUse sidecar) rather than this flush-gated tool_use
+      // path — see `case 'tool_label'`. The sidecar fires at tool-call
+      // time regardless of when claude flushes the transcript, which is
+      // the determinism fix: on a fast/clustered-tool turn the JSONL
+      // tool_use rows aren't on disk until ~turn-end, so sourcing the
+      // feed here would lose them.
       if (!ctrl) return
       if (isTelegramSurfaceTool(name)) return
       ctrl.setTool(name)
@@ -7282,13 +7312,12 @@ function handleSessionEvent(ev: SessionEvent): void {
       return
     }
     case 'tool_label': {
-      // DRAFT_MIRROR real-time driver. The PreToolUse hook wrote this
+      // Real-time activity-feed driver. The PreToolUse hook wrote this
       // label synchronously at tool-call time; the sidecar surfaced it
       // here (~250ms) independent of the transcript flush. Accumulate it
       // into the live feed and edit the activity message in place — this
       // is what makes the feed deterministic on fast/clustered-tool turns
       // where the JSONL tool_use rows arrive too late.
-      if (!DRAFT_MIRROR_ENABLED) return
       const turn = currentTurn
       if (turn == null) return
       // Surface tools (reply/stream_reply/react) are the conversation, not
@@ -7582,13 +7611,13 @@ function handleSessionEvent(ev: SessionEvent): void {
         clearTimeout(turn.orphanedReplyTimeoutId)
         turn.orphanedReplyTimeoutId = null
       }
-      // DRAFT_MIRROR: clear the activity feed at the real end of the turn.
-      // This is the no-reply safety net — a turn that ends without ever
-      // calling reply (the answer is delivered by turn-flush / silent-end)
-      // still has its feed removed. On a normal turn the feed was already
-      // cleared at the first reply (the hand-off); clearActivitySummary is
-      // idempotent, so the second call is a no-op.
-      if (DRAFT_MIRROR_ENABLED && turn != null) {
+      // Clear the activity feed at the real end of the turn. This is the
+      // no-reply safety net — a turn that ends without ever calling reply
+      // (the answer is delivered by turn-flush / silent-end) still has its
+      // feed removed. On a normal turn the feed was already cleared at the
+      // first reply (the hand-off); clearActivitySummary is idempotent, so
+      // the second call is a no-op.
+      if (turn != null) {
         clearActivitySummary(turn)
       }
       // #549 fix — flush any pending preamble BEFORE the answer stream is

package/telegram-plugin/gateway/webhook-ingest-server.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Tests for the peercred-gated webhook ingest UDS server
+ * (RFC docs/rfcs/webhook-via-gateway-socket.md).
+ *
+ * MUST run under `bun test`: the peer-credential gate calls
+ * `getPeerCred` (bun:ffi getsockopt SO_PEERCRED), which returns null
+ * under node/vitest — so the allow path is only exercisable under bun.
+ * This file is excluded from the vitest run (see vitest.config.ts) and
+ * listed in the `test:bun` / `test` scripts in package.json.
+ *
+ * Sockets live in an isolated tmpdir — never `~/.switchroom`.
+ */
+
+import { describe, it, expect, afterEach } from 'bun:test'
+import net from 'node:net'
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  startWebhookIngestServer,
+  type WebhookIngestServer,
+  type WebhookIngestRequest,
+} from './webhook-ingest-server.js'
+import { forwardToGateway } from '../../src/web/webhook-ingest-client.js'
+
+const servers: WebhookIngestServer[] = []
+afterEach(() => {
+  for (const s of servers.splice(0)) s.close()
+})
+
+function tmpSocket(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'webhook-ingest-srv-'))
+  return join(dir, 'webhook.sock')
+}
+
+function sampleReq(): WebhookIngestRequest {
+  return {
+    agent: 'reggie',
+    source: 'github',
+    event_type: 'pull_request',
+    ts: 1_700_000_000_000,
+    rendered_text: 'PR opened',
+    payload: { action: 'opened', number: 7 },
+    delivery_id: 'd-7',
+  }
+}
+
+describe('startWebhookIngestServer (peercred-gated)', () => {
+  it('accepts a connection from an allowed uid and round-trips onRecord', async () => {
+    const socketPath = tmpSocket()
+    let received: WebhookIngestRequest | null = null
+    const server = startWebhookIngestServer({
+      socketPath,
+      allowedUids: [process.getuid!()], // our own uid → allowed
+      onRecord: (req) => {
+        received = req
+        return { status: 'ok', ts: req.ts, dispatched: 1 }
+      },
+      log: () => {},
+    })
+    servers.push(server)
+
+    const resp = await forwardToGateway(socketPath, sampleReq())
+
+    expect(resp).not.toBeNull()
+    expect(resp!.status).toBe('ok')
+    expect(resp!.ts).toBe(1_700_000_000_000)
+    expect(resp!.dispatched).toBe(1)
+    expect(received).not.toBeNull()
+    expect(received!.agent).toBe('reggie')
+    expect(received!.event_type).toBe('pull_request')
+    expect(received!.delivery_id).toBe('d-7')
+  })
+
+  it('denies a connection whose uid is not in allowedUids (onRecord never runs)', async () => {
+    const socketPath = tmpSocket()
+    let called = false
+    const server = startWebhookIngestServer({
+      socketPath,
+      allowedUids: [999_999], // definitely not our uid
+      onRecord: () => {
+        called = true
+        return { status: 'ok' }
+      },
+      log: () => {},
+    })
+    servers.push(server)
+
+    // The server destroys the connection in its accept callback BEFORE
+    // reading any bytes, so onRecord must never run. We assert the
+    // security property (no service for an unlisted uid) directly rather
+    // than via the client resolving: bun's net client does not observe a
+    // server-side destroy of a just-accepted UDS connection promptly, so
+    // awaiting forwardToGateway here would hang. Send raw bytes and give
+    // the server ample time to (not) process them.
+    const raw = net.createConnection(socketPath)
+    raw.on('connect', () => raw.write(JSON.stringify(sampleReq()) + '\n'))
+    raw.on('error', () => {})
+    await new Promise((r) => setTimeout(r, 300))
+    raw.destroy()
+
+    expect(called).toBe(false)
+  })
+
+  it('returns null when the socket does not exist (gateway down)', async () => {
+    const socketPath = tmpSocket() // never bound
+    const resp = await forwardToGateway(socketPath, sampleReq(), { timeoutMs: 2000 })
+    expect(resp).toBeNull()
+  })
+
+  it('surfaces a gateway-side error status from onRecord', async () => {
+    const socketPath = tmpSocket()
+    const server = startWebhookIngestServer({
+      socketPath,
+      allowedUids: [process.getuid!()],
+      onRecord: () => ({ status: 'error', error: 'write failed' }),
+      log: () => {},
+    })
+    servers.push(server)
+
+    const resp = await forwardToGateway(socketPath, sampleReq())
+    expect(resp).not.toBeNull()
+    expect(resp!.status).toBe('error')
+  })
+})

package/telegram-plugin/gateway/webhook-ingest-server.ts

@@ -0,0 +1,218 @@
+/**
+ * Webhook ingest UDS server (RFC docs/rfcs/webhook-via-gateway-socket.md).
+ *
+ * A dedicated, peercred-gated Unix socket the host-side web receiver
+ * forwards verified webhook events to. It is deliberately SEPARATE from
+ * the bridge IPC socket (`gateway.sock`):
+ *
+ *   - `gateway.sock` is bound via `Bun.listen`, whose accepted socket does
+ *     NOT expose a file descriptor — so SO_PEERCRED can't be read on it.
+ *     This server uses `node:net` (whose `Socket._handle.fd` IS readable
+ *     under Bun, verified empirically) precisely so the peer-credential
+ *     gate works.
+ *   - Keeping the chat-critical bridge socket untouched avoids any risk to
+ *     the bridge-flap-sensitive reconnect path.
+ *
+ * Auth model — two independent layers:
+ *   1. **Filesystem**: the socket is chmod 0o666 so the host operator UID
+ *      can connect at all (the agent dir itself is 0775/agent-UID, which
+ *      blocks the operator from writing files but not from connecting a
+ *      world-connectable socket).
+ *   2. **Peer credentials**: every connection's SO_PEERCRED UID must be in
+ *      `allowedUids` (the agent's own UID + the operator/receiver UID).
+ *      This is the load-bearing gate: it ensures only the trusted receiver
+ *      (which enforces per-event HMAC) — or the agent itself — can inject a
+ *      webhook turn. Fail-closed: unreadable creds or an unlisted UID is
+ *      denied.
+ *
+ * Wire protocol: one JSON line in (`WebhookIngestRequest`), one JSON line
+ * out (`WebhookIngestResponse`), then the connection closes. No framing
+ * beyond the trailing newline; requests are small (a rendered event +
+ * payload).
+ */
+
+import net from 'node:net'
+import { chmodSync, existsSync, unlinkSync } from 'node:fs'
+import { getPeerCred } from '../../src/vault/broker/peercred-ffi.js'
+
+/** Forwarded by the receiver; structural mirror of WebhookGatewayRecord. */
+export interface WebhookIngestRequest {
+  agent: string
+  source: string
+  event_type: string
+  ts: number
+  rendered_text: string
+  payload: Record<string, unknown>
+  delivery_id?: string
+}
+
+export interface WebhookIngestResponse {
+  status: 'ok' | 'deduped' | 'error'
+  ts?: number
+  error?: string
+  dispatched?: number
+}
+
+export interface WebhookIngestServerOptions {
+  socketPath: string
+  /** SO_PEERCRED UIDs permitted to inject. Connections from any other UID
+   *  (or with unreadable creds) are denied and the socket destroyed. */
+  allowedUids: number[]
+  /** Handle one verified, forwarded event. Synchronous return (the record
+   *  path is file I/O + an in-process inject) wrapped in Promise for the
+   *  server's await. */
+  onRecord: (req: WebhookIngestRequest) => WebhookIngestResponse | Promise<WebhookIngestResponse>
+  log?: (line: string) => void
+}
+
+export interface WebhookIngestServer {
+  close: () => void
+}
+
+const MAX_REQUEST_BYTES = 1024 * 1024 // 1 MiB — github payloads fit easily
+
+/** Read the accepted connection's fd via the undocumented `_handle.fd`.
+ *  Under Bun's node:net polyfill this is present (verified); returns null
+ *  if absent so the caller fails closed. */
+function fdOf(conn: net.Socket): number | null {
+  const handle = (conn as unknown as { _handle?: { fd?: number } })._handle
+  if (!handle || typeof handle.fd !== 'number' || handle.fd < 0) return null
+  return handle.fd
+}
+
+/**
+ * Start the webhook ingest server. Never throws — bind failures are logged
+ * and surfaced via the returned server still being usable as a no-op close.
+ * The CALLER (gateway boot) additionally wraps this so a failure here can
+ * never take the agent down; this function's own try/catch is belt-and-
+ * suspenders.
+ */
+export function startWebhookIngestServer(
+  opts: WebhookIngestServerOptions,
+): WebhookIngestServer {
+  const log = opts.log ?? ((s) => process.stderr.write(s))
+  const allowed = new Set(opts.allowedUids)
+
+  // Clear a stale socket from a previous (crashed) gateway. Safe: only this
+  // agent's gateway binds this path, and we're about to rebind it.
+  try {
+    if (existsSync(opts.socketPath)) unlinkSync(opts.socketPath)
+  } catch (err) {
+    log(`webhook-ingest-server: could not unlink stale socket: ${(err as Error).message}\n`)
+  }
+
+  const server = net.createServer((conn) => {
+    // ── Peer-credential gate (fail-closed) ──────────────────────────────────
+    const fd = fdOf(conn)
+    const cred = fd !== null ? getPeerCred(fd) : null
+    if (cred === null || !allowed.has(cred.uid)) {
+      log(
+        `webhook-ingest-server: DENY connection uid=${cred?.uid ?? 'unknown'} ` +
+          `(allowed=${[...allowed].join(',')})\n`,
+      )
+      conn.destroy()
+      return
+    }
+
+    let buf = ''
+    let handled = false
+    conn.setEncoding('utf8')
+
+    const reply = (resp: WebhookIngestResponse) => {
+      if (handled) return
+      handled = true
+      try {
+        conn.write(JSON.stringify(resp) + '\n')
+      } catch {
+        /* peer may have hung up */
+      }
+      conn.end()
+    }
+
+    conn.on('data', (chunk: string) => {
+      if (handled) return
+      buf += chunk
+      if (buf.length > MAX_REQUEST_BYTES) {
+        reply({ status: 'error', error: 'request too large' })
+        return
+      }
+      const nl = buf.indexOf('\n')
+      if (nl === -1) return // wait for the full line
+      const line = buf.slice(0, nl)
+
+      let req: WebhookIngestRequest
+      try {
+        req = JSON.parse(line) as WebhookIngestRequest
+      } catch {
+        reply({ status: 'error', error: 'malformed request' })
+        return
+      }
+      if (
+        !req ||
+        typeof req.agent !== 'string' ||
+        typeof req.source !== 'string' ||
+        typeof req.event_type !== 'string' ||
+        typeof req.rendered_text !== 'string' ||
+        typeof req.payload !== 'object' ||
+        req.payload === null
+      ) {
+        reply({ status: 'error', error: 'invalid request shape' })
+        return
+      }
+
+      Promise.resolve()
+        .then(() => opts.onRecord(req))
+        .then((resp) => reply(resp))
+        .catch((err: unknown) => {
+          log(`webhook-ingest-server: onRecord threw: ${String(err)}\n`)
+          reply({ status: 'error', error: 'internal error' })
+        })
+    })
+
+    conn.on('error', (err) => {
+      log(`webhook-ingest-server: conn error: ${err.message}\n`)
+    })
+
+    // Drop slow/idle clients so a stuck connection can't pin the socket.
+    conn.setTimeout(10_000, () => {
+      if (!handled) reply({ status: 'error', error: 'timeout' })
+      conn.destroy()
+    })
+  })
+
+  server.on('error', (err) => {
+    log(`webhook-ingest-server: server error: ${err.message}\n`)
+  })
+
+  try {
+    server.listen(opts.socketPath, () => {
+      try {
+        // World-connectable at the FS layer; peercred is the real gate.
+        chmodSync(opts.socketPath, 0o666)
+      } catch (err) {
+        log(`webhook-ingest-server: chmod failed: ${(err as Error).message}\n`)
+      }
+      log(
+        `webhook-ingest-server: listening at ${opts.socketPath} ` +
+          `(allowed uids: ${[...allowed].join(',')})\n`,
+      )
+    })
+  } catch (err) {
+    log(`webhook-ingest-server: listen failed: ${(err as Error).message}\n`)
+  }
+
+  return {
+    close: () => {
+      try {
+        server.close()
+      } catch {
+        /* ignore */
+      }
+      try {
+        if (existsSync(opts.socketPath)) unlinkSync(opts.socketPath)
+      } catch {
+        /* ignore */
+      }
+    },
+  }
+}