@agfpd/iapeer 0.1.0

package/src/daemon/index.ts

@@ -0,0 +1,439 @@
+// Daemon — the always-on HTTP-MCP router. Serves the single agent-facing tool
+// (send_to_peer) host-wide over MCP Streamable HTTP, resolving the caller identity
+// PER REQUEST from the X-IAPeer-Identity header. (list_online_peers is deprecated by
+// contract — it ate context; liveness is the CLI `list` verb, not an agent tool.)
+//
+// Transport: the CANONICAL SDK StreamableHTTPServerTransport in stateless mode
+// (a fresh Server + transport per request, sessionIdGenerator: undefined). The
+// caller header is read from `extra.requestInfo.headers` in the CallTool handler
+// — verified end-to-end on @modelcontextprotocol/sdk@1.29.0 (the earlier
+// "SDK does not surface per-request headers" was a wrong inference from grepping
+// streamableHttp.js; requestInfo is built in the web-standard transport layer
+// at webStandardStreamableHttp.js:388 and threaded through protocol.js:351).
+// Using the canonical transport guarantees on-wire compatibility with real
+// claude/codex http MCP clients, so there is no hand-rolled handshake to defend.
+//
+// Ф1 scope: route + deliver + liveness. Wake-on-miss / spawn (Ф2) are not wired
+// yet — a miss returns an explicit "peer offline". H4 (READ-ONLY for launchd
+// peers) concerns reap/respawn (Ф2 supervision); Ф1 routing delivers to any live
+// peer. H8: a unix socket is the same-uid base; a TCP loopback listener (which
+// real http MCP clients require, since they connect to a URL) is broader than
+// same-uid and should add a bearer token before production exposure — OPEN.
+
+import { createServer as createHttpServer, type IncomingMessage, type ServerResponse } from 'http'
+import { chmodSync, existsSync, mkdirSync, unlinkSync } from 'fs'
+import { dirname, join } from 'path'
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type CallToolResult,
+} from '@modelcontextprotocol/sdk/types.js'
+import {
+  ALWAYS_LOAD_META,
+  MAX_ATTACHMENTS,
+  MAX_MESSAGE_LEN,
+  MAX_TOPIC_LEN,
+  NAME_RE_SOURCE,
+  RUNTIME_RE_SOURCE,
+} from '../core/constants.ts'
+import { parseSessionName } from '../core/socket.ts'
+import { IapError } from '../core/errors.ts'
+import { pluginStateDir, writeFileAtomic, type StorageOptions } from '../storage/index.ts'
+import { publicPeerSummary, readPeersIndex, type PeersIndex } from '../registry/index.ts'
+import { resolveCallerIdentity, type CallerIdentity, type ResolvedCaller } from '../identity/index.ts'
+import { routeSend, type SendToPeerInput, type WakeFn } from '../transport/index.ts'
+
+export const CALLER_HEADER = 'x-iapeer-identity'
+const SERVER_INFO = { name: 'iapeer', version: '0.0.0' }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Caller identity from the request header
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Parse an `X-IAPeer-Identity: <runtime>-<personality>` header into a caller. */
+export function parseCallerHeader(value: string | undefined): CallerIdentity | null {
+  const raw = value?.trim()
+  if (!raw) return null
+  const parsed = parseSessionName(raw) // splits on the first '-': runtime | personality
+  if (!parsed) return null
+  return { personality: parsed.personality, runtime: parsed.runtime }
+}
+
+export function resolveCallerFromHeader(value: string | undefined, index: PeersIndex): ResolvedCaller {
+  const caller = parseCallerHeader(value)
+  if (!caller) {
+    throw new IapError(
+      `missing or malformed ${CALLER_HEADER} header — expected "<runtime>-<personality>"`,
+    )
+  }
+  return resolveCallerIdentity(caller, index)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool definitions (ported verbatim from IAP server.ts)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function buildSendDescription(index: PeersIndex): string {
+  const lines = [
+    'Send a message to a known IAPeer peer through Inter-Agent-Protocol.',
+    'Peers can be agents, humans, or services. Runtime is the delivery surface, not the peer type.',
+    'Current delivery supports any runtime endpoint that follows the IAP tmux socket convention. Claude/Codex are built-in local runtimes; external runtimes such as telegram can be exposed by runtime-router packages.',
+    '',
+    'Known peers on this host:',
+  ]
+  if (index.peers.length === 0) {
+    lines.push('- none yet')
+  } else {
+    for (const peer of index.peers) {
+      const p = publicPeerSummary(peer)
+      const desc = p.description ? ` — ${p.description}` : ''
+      lines.push(`- ${p.personality}${desc}`)
+      lines.push(`  Runtime: ${p.runtime}`)
+      lines.push(`  Runtimes: ${p.runtimes.join(', ')}`)
+      lines.push(`  Intelligence: ${p.intelligence}`)
+    }
+  }
+  lines.push(
+    '',
+    "Use `personality`, not a runtime-prefixed identity. Set `runtime` only for a current-send override. Descriptions identify the peer's role; runtimes identify reachable delivery endpoints; intelligence identifies the nature of the peer (artificial / natural / absent). Inbound peer messages arrive as <iap from-personality=\"...\" from-runtime=\"...\" from-intelligence=\"...\"> blocks. The topic attribute is optional.",
+  )
+  return lines.join('\n')
+}
+
+// The daemon serves the AGENT exactly ONE MCP tool: send_to_peer. list_online_peers
+// is DEPRECATED by contract (docs/Примитивы и CLI: "list_online_peers УПРАЗДНЁН —
+// ел контекст; список живых пиров — через CLI verb `list`, не через tool агента").
+// Every extra tool occupies the context window of EVERY session, so the agent-facing
+// tool-set is kept minimal. The liveness scan itself (transport.listOnlinePeers) stays
+// — the future `iapeer list` verb and the multi-runtime delivery resolver use it — it
+// is simply no longer exposed to the agent as a tool.
+export function listTools(index: PeersIndex): unknown[] {
+  return [
+    {
+      name: 'send_to_peer',
+      description: buildSendDescription(index),
+      inputSchema: {
+        type: 'object',
+        properties: {
+          personality: { type: 'string', description: 'Known peer personality.', pattern: NAME_RE_SOURCE },
+          runtime: {
+            type: 'string',
+            description:
+              'Optional delivery runtime override for this send. Runtime ids are short channel names such as claude, codex, telegram.',
+            pattern: RUNTIME_RE_SOURCE,
+          },
+          message: {
+            type: 'string',
+            description: 'Plain-text message body. Keep concise; long messages enter the recipient context.',
+            minLength: 1,
+            maxLength: MAX_MESSAGE_LEN,
+          },
+          topic: { type: 'string', description: 'Optional short topic for threading related peer messages.', maxLength: MAX_TOPIC_LEN },
+          attachments: {
+            type: 'array',
+            description: 'Optional absolute local file paths. IAP delivers them as a separate <attachments> field, not as part of message text.',
+            maxItems: MAX_ATTACHMENTS,
+            items: { type: 'string' },
+          },
+        },
+        required: ['personality', 'message'],
+        additionalProperties: false,
+      },
+      _meta: ALWAYS_LOAD_META,
+      annotations: { title: 'Send to IAP peer', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+  ]
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool dispatch
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface ToolResult {
+  content: { type: 'text'; text: string }[]
+  isError?: boolean
+  structuredContent?: unknown
+}
+
+function jsonResult(value: unknown): ToolResult {
+  const result: ToolResult = { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] }
+  // MCP structuredContent must be a record (object), not an array. send_to_peer
+  // returns an object, so it travels in structuredContent; the guard stays as a
+  // belt-and-suspenders against a future array-returning result.
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    result.structuredContent = value
+  }
+  return result
+}
+function errResult(text: string): ToolResult {
+  return { isError: true, content: [{ type: 'text', text }] }
+}
+
+export async function callTool(
+  caller: ResolvedCaller,
+  name: string,
+  args: Record<string, unknown>,
+  wake?: WakeFn,
+): Promise<ToolResult> {
+  if (name === 'send_to_peer') {
+    const input: SendToPeerInput = {
+      personality: typeof args.personality === 'string' ? args.personality : '',
+      runtime: typeof args.runtime === 'string' ? args.runtime : undefined,
+      message: typeof args.message === 'string' ? args.message : '',
+      topic: typeof args.topic === 'string' ? args.topic : undefined,
+      attachments: Array.isArray(args.attachments) ? (args.attachments as string[]) : undefined,
+    }
+    const sent = await routeSend(caller, input, { wake })
+    return sent.ok ? jsonResult(sent.value) : errResult(sent.error.message)
+  }
+  return errResult(`unknown tool: ${name}`)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MCP server (canonical SDK) — one fresh instance per request (stateless)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function headerFromRequestInfo(extra: { requestInfo?: { headers?: Record<string, unknown> } }): string | undefined {
+  const headers = extra.requestInfo?.headers
+  const value = headers?.[CALLER_HEADER]
+  return Array.isArray(value) ? (value[0] as string) : (value as string | undefined)
+}
+
+export function createMcpServer(wake?: WakeFn): Server {
+  const server = new Server(SERVER_INFO, { capabilities: { tools: {} } })
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: listTools(readPeersIndex()) }))
+
+  server.setRequestHandler(CallToolRequestSchema, async (req, extra): Promise<CallToolResult> => {
+    // Per-request identity: read the caller from THIS request's HTTP header,
+    // surfaced by the SDK transport as extra.requestInfo.headers.
+    const headerIdentity = headerFromRequestInfo(extra as never)
+    let caller: ResolvedCaller
+    try {
+      caller = resolveCallerFromHeader(headerIdentity, readPeersIndex())
+    } catch (e) {
+      // No silent default — reject the CallTool when identity is missing/invalid.
+      if (process.env.IAPEER_DAEMON_LOG) {
+        process.stderr.write(`[iapeer-daemon] tools/call REJECTED tool=${req.params.name} caller=${headerIdentity ?? '-'}\n`)
+      }
+      return errResult(e instanceof Error ? e.message : String(e)) as CallToolResult
+    }
+    if (process.env.IAPEER_DAEMON_LOG) {
+      process.stderr.write(`[iapeer-daemon] tools/call tool=${req.params.name} caller=${caller.address}\n`)
+    }
+    const args = (req.params.arguments ?? {}) as Record<string, unknown>
+    return (await callTool(caller, req.params.name, args, wake)) as CallToolResult
+  })
+
+  return server
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// HTTP server (unix socket base, or TCP loopback for real http MCP clients)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function defaultDaemonSocketPath(options: StorageOptions = {}): string {
+  return join(pluginStateDir('iapeer', options), 'router.sock')
+}
+
+/** The discovery file `<root>/state/iapeer/router.json` — a daemon-aware `iap send`
+ *  reads it to route through the daemon. Sits next to router.sock. */
+export function daemonDiscoveryPath(options: StorageOptions = {}): string {
+  return join(pluginStateDir('iapeer', options), 'router.json')
+}
+
+export interface DaemonHandle {
+  socketPath?: string
+  host?: string
+  port?: number
+  url?: string
+  close: () => Promise<void>
+}
+
+export interface StartDaemonOptions extends StorageOptions {
+  /**
+   * Unix-socket path (H8 base: 0600, same-uid local callers — CLI / pane /
+   * notifier / telegram). Bound when given; when NEITHER socketPath NOR port is
+   * given, a bare startDaemon() defaults to the same-uid router.sock.
+   */
+  socketPath?: string
+  /**
+   * TCP loopback port (0 = ephemeral). REQUIRED for real http MCP clients
+   * (claude/codex `--transport http <url>`), which connect to a URL, not a unix
+   * socket. NOT mutually exclusive with socketPath — give BOTH for dual-listen
+   * (local callers via the 0600 socket, agents via TCP). H8 on the TCP surface is
+   * gated by the optional bearer seam (off by default).
+   */
+  port?: number
+  /** TCP bind host, default 127.0.0.1 (loopback). */
+  host?: string
+  /**
+   * Wake-on-miss primitive (Ф2). When provided, a send to a DEAD peer wakes it
+   * (spawns the session, delivers the message as its boot first-message) instead
+   * of returning offline. Opt-in: omit it (Ф1) and a miss returns an explicit
+   * "offline" — so tests never spawn a real session by accident. The daemon is
+   * the composition point: it wires lifecycle.wakeOrSpawn here (§2).
+   */
+  wake?: WakeFn
+  /**
+   * Optional supervision timer (Ф2): `tick` runs every `intervalMs` — the daemon
+   * owns fleet supervision (idle-reap / zombie-sweep) instead of launchd. The
+   * caller wires `tick: () => superviseTick(cfg)` (H4-guarded inside).
+   */
+  supervise?: { intervalMs: number; tick: () => void | Promise<void> }
+  /**
+   * Optional bearer token (H8). When set, EVERY request must carry
+   * `Authorization: Bearer <token>` or it is rejected 401 BEFORE any MCP dispatch.
+   * Unset → no auth (the same-uid unix-socket base / loopback default). This is the
+   * structural layer for closing H8 on the TCP loopback listener — kept OFF until
+   * Артур enables it (the production main reads IAPEER_BEARER_TOKEN). Loopback is
+   * broader than same-uid, so a token gates it without changing the on-wire MCP.
+   */
+  bearerToken?: string
+  /**
+   * Write the discovery file (router.json) at <root>/state/iapeer/router.json with
+   * the active addresses `{sock, tcp}` — atomically on listen, removed on close.
+   * This is the contract a daemon-aware `iap send` reads to route through the
+   * daemon. OFF by default (library/test callers); the production main enables it.
+   */
+  discovery?: boolean
+}
+
+export async function startDaemon(opts: StartDaemonOptions = {}): Promise<DaemonHandle> {
+  const tcpEnabled = opts.port !== undefined
+  // Bind a unix socket when one is given, OR when no TCP is requested at all
+  // (legacy default: a bare startDaemon() serves the same-uid router.sock).
+  const socketPath = opts.socketPath ?? (tcpEnabled ? undefined : defaultDaemonSocketPath(opts))
+  const host = opts.host ?? '127.0.0.1'
+  const bearer = opts.bearerToken?.trim() || undefined
+
+  // ONE MCP request handler, shared by EVERY listener (socket + TCP). Stateless:
+  // a fresh Server + transport per request, fully isolated.
+  const handle = (req: IncomingMessage, res: ServerResponse): void => {
+    // H8 bearer layer (FIRST, before any MCP work): when a token is configured,
+    // reject anything not carrying `Authorization: Bearer <token>`. Off when unset.
+    if (bearer && req.headers.authorization !== `Bearer ${bearer}`) {
+      res.writeHead(401, { 'content-type': 'application/json', 'www-authenticate': 'Bearer' })
+      res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32001, message: 'unauthorized' } }))
+      return
+    }
+    const server = createMcpServer(opts.wake)
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
+    res.on('close', () => {
+      transport.close()
+      server.close()
+    })
+    server
+      .connect(transport)
+      .then(() => transport.handleRequest(req, res))
+      .catch(() => {
+        if (!res.headersSent) {
+          res.writeHead(500, { 'content-type': 'application/json' })
+          res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32603, message: 'internal error' } }))
+        }
+      })
+  }
+
+  // Supervision timer (Ф2): the daemon drives idle-reap / zombie-sweep (one shared
+  // timer regardless of how many listeners are bound).
+  let supervisor: ReturnType<typeof setInterval> | undefined
+  if (opts.supervise) {
+    const { intervalMs, tick } = opts.supervise
+    supervisor = setInterval(() => {
+      try {
+        void Promise.resolve(tick()).catch(() => {})
+      } catch {
+        /* a supervise tick must never crash the daemon */
+      }
+    }, intervalMs)
+    supervisor.unref?.()
+  }
+
+  const servers: ReturnType<typeof createHttpServer>[] = []
+
+  // Unix-socket listener (H8 same-uid base, 0600).
+  if (socketPath) {
+    mkdirSync(dirname(socketPath), { recursive: true, mode: 0o700 })
+    if (existsSync(socketPath)) unlinkSync(socketPath)
+    const s = createHttpServer(handle)
+    await new Promise<void>((resolve, reject) => {
+      s.once('error', reject)
+      s.listen(socketPath, () => {
+        s.removeListener('error', reject)
+        resolve()
+      })
+    })
+    chmodSync(socketPath, 0o600)
+    servers.push(s)
+  }
+
+  // TCP loopback listener (real http MCP clients connect to a URL).
+  let port: number | undefined
+  let url: string | undefined
+  if (tcpEnabled) {
+    const s = createHttpServer(handle)
+    await new Promise<void>((resolve, reject) => {
+      s.once('error', reject)
+      s.listen(opts.port, host, () => {
+        s.removeListener('error', reject)
+        resolve()
+      })
+    })
+    const addr = s.address()
+    port = addr && typeof addr === 'object' ? addr.port : (opts.port as number)
+    url = `http://${host}:${port}/mcp`
+    servers.push(s)
+  }
+
+  // Discovery file (atomic temp+rename) — both active addresses for `iap send`.
+  let discoveryPath: string | undefined
+  if (opts.discovery) {
+    discoveryPath = daemonDiscoveryPath(opts)
+    writeFileAtomic(discoveryPath, `${JSON.stringify({ sock: socketPath ?? null, tcp: url ?? null })}\n`)
+  }
+
+  const removeArtifacts = (): void => {
+    if (socketPath && existsSync(socketPath)) {
+      try {
+        unlinkSync(socketPath)
+      } catch {
+        /* already gone */
+      }
+    }
+    if (discoveryPath && existsSync(discoveryPath)) {
+      try {
+        unlinkSync(discoveryPath)
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+
+  return {
+    socketPath,
+    host: tcpEnabled ? host : undefined,
+    port,
+    url,
+    close: () =>
+      new Promise<void>(resolve => {
+        if (supervisor) clearInterval(supervisor)
+        for (const s of servers) s.closeAllConnections?.() // drop lingering keep-alive/SSE conns
+        let pending = servers.length
+        if (pending === 0) {
+          removeArtifacts()
+          resolve()
+          return
+        }
+        for (const s of servers) {
+          s.close(() => {
+            if (--pending === 0) {
+              removeArtifacts()
+              resolve()
+            }
+          })
+        }
+      }),
+  }
+}

package/src/daemon/main.test.ts

@@ -0,0 +1,194 @@
+// Daemon production main — the daemon's OWN launchd plist (com.agfpd.iapeer),
+// the composition smoke (startConfiguredDaemon returns a live TCP handle), and the
+// DORMANT H8 bearer seam (off by default → no auth; on only when a token is set).
+// All plist writes go under IAPEER_LAUNCHAGENTS_DIR so the suite never touches the
+// real ~/Library/LaunchAgents.
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { spawnSync } from 'child_process'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import {
+  buildDaemonPlistSpec,
+  daemonPlistPath,
+  installDaemonPlist,
+  startConfiguredDaemon,
+  DEFAULT_DAEMON_PORT,
+} from './main.ts'
+import { daemonDiscoveryPath, defaultDaemonSocketPath, startDaemon, type DaemonHandle } from './index.ts'
+import { isFoundationOwnedPlist } from '../launch/index.ts'
+import { DAEMON_PLIST_LABEL } from '../core/constants.ts'
+
+const tmpDirs: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-daemon-main-'))
+  tmpDirs.push(d)
+  return d
+}
+afterEach(() => {
+  while (tmpDirs.length) rmSync(tmpDirs.pop()!, { recursive: true, force: true })
+})
+
+function plutilLint(path: string): boolean {
+  return spawnSync('plutil', ['-lint', path], { encoding: 'utf8' }).status === 0
+}
+
+describe('buildDaemonPlistSpec / installDaemonPlist (com.agfpd.iapeer)', () => {
+  test('spec carries the daemon label, default port env, and the INSTALLED iapeer entrypoint (Ф-F)', () => {
+    const spec = buildDaemonPlistSpec({ env: { HOME: '/Users/x' } as NodeJS.ProcessEnv })
+    expect(spec.label).toBe(DAEMON_PLIST_LABEL) // com.agfpd.iapeer — NOT com.iapeer.*
+    expect(spec.environment.IAPEER_PORT).toBe(String(DEFAULT_DAEMON_PORT))
+    // Ф-F: runs the INSTALLED binary `iapeer daemon`, NOT `bun <src>/main.ts` — prod
+    // decoupled from the mutable src tree.
+    expect(spec.programArguments).toEqual(['/Users/x/.local/bin/iapeer', 'daemon'])
+  })
+
+  test('NO bearer token in the plist env by default (H8 seam dormant)', () => {
+    expect(buildDaemonPlistSpec({ env: {} as NodeJS.ProcessEnv }).environment.IAPEER_BEARER_TOKEN).toBeUndefined()
+  })
+
+  test('bearer token is baked into the plist env only when explicitly provided', () => {
+    const spec = buildDaemonPlistSpec({ bearerToken: 's3cret', env: {} as NodeJS.ProcessEnv })
+    expect(spec.environment.IAPEER_BEARER_TOKEN).toBe('s3cret')
+  })
+
+  test('installs a valid, foundation-owned plist under IAPEER_LAUNCHAGENTS_DIR', () => {
+    const root = mkTmp()
+    const env = {
+      IAPEER_LAUNCHAGENTS_DIR: join(root, 'LaunchAgents'),
+      IAPEER_ROOT: join(root, 'iapeer'),
+      HOME: root,
+      PATH: '/usr/bin:/bin',
+    } as NodeJS.ProcessEnv
+    const path = installDaemonPlist({ env, port: 8765, throttleIntervalSecs: 10 })
+    expect(path).toBe(daemonPlistPath(env))
+    expect(existsSync(path)).toBe(true)
+    expect(isFoundationOwnedPlist(path)).toBe(true)
+    expect(plutilLint(path)).toBe(true) // live plutil: valid plist
+    const xml = readFileSync(path, 'utf8')
+    expect(xml).toContain(`<string>${DAEMON_PLIST_LABEL}</string>`)
+    expect(xml).toContain('<key>RunAtLoad</key>')
+    expect(xml).toContain('<key>KeepAlive</key>')
+  })
+
+  test('REFUSES to overwrite a foreign com.agfpd.iapeer.plist (collision guard)', () => {
+    const root = mkTmp()
+    const laDir = join(root, 'LaunchAgents')
+    mkdirSync(laDir, { recursive: true })
+    const env = { IAPEER_LAUNCHAGENTS_DIR: laDir, IAPEER_ROOT: join(root, 'iapeer'), HOME: root } as NodeJS.ProcessEnv
+    const path = daemonPlistPath(env)
+    const foreign = '<?xml version="1.0"?>\n<plist><dict><key>Label</key><string>com.agfpd.iapeer</string></dict></plist>\n'
+    writeFileSync(path, foreign)
+    expect(() => installDaemonPlist({ env })).toThrow(/foundation-managed|refus/i)
+    expect(readFileSync(path, 'utf8')).toBe(foreign) // untouched
+  })
+})
+
+describe('startConfiguredDaemon (composition smoke — TCP loopback)', () => {
+  test('returns a live http handle and closes cleanly', async () => {
+    const root = mkTmp()
+    const env = { IAPEER_ROOT: join(root, 'iapeer'), HOME: root, PATH: '/usr/bin:/bin' } as NodeJS.ProcessEnv
+    const handle = await startConfiguredDaemon({ port: 0, host: '127.0.0.1', env })
+    try {
+      expect(handle.url).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/mcp$/)
+    } finally {
+      await handle.close()
+    }
+  })
+})
+
+// The H8 bearer seam: a validator LAYER on the listener, OFF unless a token is set
+// (Артур 07.06 — H8 DEFERRED, no token provisioning yet). These tests prove the
+// seam is dormant by default and would gate every request once a token is wired.
+describe('H8 bearer seam (dormant by default)', () => {
+  const INIT = JSON.stringify({
+    jsonrpc: '2.0', id: 1, method: 'initialize',
+    params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 't', version: '0' } },
+  })
+  const headers = (auth?: string): Record<string, string> => ({
+    'content-type': 'application/json',
+    accept: 'application/json, text/event-stream',
+    ...(auth ? { authorization: auth } : {}),
+  })
+
+  async function withDaemon(opts: Parameters<typeof startDaemon>[0], fn: (h: DaemonHandle) => Promise<void>) {
+    const h = await startDaemon(opts)
+    try {
+      await fn(h)
+    } finally {
+      await h.close()
+    }
+  }
+
+  test('NO token → request is NOT 401 (auth layer off)', async () => {
+    await withDaemon({ port: 0, host: '127.0.0.1' }, async h => {
+      const res = await fetch(h.url!, { method: 'POST', headers: headers(), body: INIT })
+      expect(res.status).not.toBe(401)
+    })
+  })
+
+  test('token set → no Authorization is 401, correct Bearer passes the layer', async () => {
+    await withDaemon({ port: 0, host: '127.0.0.1', bearerToken: 'secret' }, async h => {
+      const noAuth = await fetch(h.url!, { method: 'POST', headers: headers(), body: INIT })
+      expect(noAuth.status).toBe(401)
+      const wrong = await fetch(h.url!, { method: 'POST', headers: headers('Bearer nope'), body: INIT })
+      expect(wrong.status).toBe(401)
+      const ok = await fetch(h.url!, { method: 'POST', headers: headers('Bearer secret'), body: INIT })
+      expect(ok.status).not.toBe(401) // passed the auth layer (MCP handles the rest)
+      await ok.body?.cancel()
+    })
+  })
+})
+
+// Dual-listen (Ф2 consolidation): the daemon serves a 0600 unix socket (local
+// same-uid callers: notifier/telegram/CLI) AND TCP (agent MCP) over ONE handler,
+// and writes router.json (both addresses) for daemon-aware `iap send`.
+describe('dual-listen + router.json discovery', () => {
+  const INIT = JSON.stringify({
+    jsonrpc: '2.0', id: 1, method: 'initialize',
+    params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 't', version: '0' } },
+  })
+  const mcpHeaders = { 'content-type': 'application/json', accept: 'application/json, text/event-stream' }
+
+  test('binds socket + TCP over one handler; router.json carries both; close cleans up', async () => {
+    const root = mkTmp()
+    const env = { IAPEER_ROOT: join(root, 'iapeer') } as NodeJS.ProcessEnv
+    const sockExpected = defaultDaemonSocketPath({ env })
+    const h = await startDaemon({ port: 0, host: '127.0.0.1', socketPath: sockExpected, discovery: true, env })
+    try {
+      // TCP listener answers the MCP handler
+      const tcp = await fetch(h.url!, { method: 'POST', headers: mcpHeaders, body: INIT })
+      expect(tcp.ok).toBe(true)
+      await tcp.body?.cancel()
+      // unix-socket listener answers the SAME handler (bun fetch `unix` option)
+      const unixInit = { unix: h.socketPath!, method: 'POST', headers: mcpHeaders, body: INIT } as unknown as RequestInit
+      const sock = await fetch('http://localhost/mcp', unixInit)
+      expect(sock.ok).toBe(true)
+      await sock.body?.cancel()
+      // socket is 0600 (same-uid)
+      expect((statSync(h.socketPath!).mode & 0o777).toString(8)).toBe('600')
+      // router.json carries BOTH addresses
+      const rj = JSON.parse(readFileSync(daemonDiscoveryPath({ env }), 'utf8'))
+      expect(rj.sock).toBe(sockExpected)
+      expect(rj.tcp).toBe(h.url)
+    } finally {
+      await h.close()
+    }
+    // clean shutdown removed the socket file AND router.json
+    expect(existsSync(sockExpected)).toBe(false)
+    expect(existsSync(daemonDiscoveryPath({ env }))).toBe(false)
+  })
+
+  test('port-only stays TCP-only — no socket, no router.json (backward compat)', async () => {
+    const root = mkTmp()
+    const env = { IAPEER_ROOT: join(root, 'iapeer') } as NodeJS.ProcessEnv
+    const h = await startDaemon({ port: 0, host: '127.0.0.1', env })
+    try {
+      expect(h.socketPath).toBeUndefined()
+      expect(existsSync(daemonDiscoveryPath({ env }))).toBe(false)
+    } finally {
+      await h.close()
+    }
+  })
+})