dsh-live-trace 0.1.0

package/bin/dsh-glyph-probe.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Print a sample sheet for each way a terminal cell can carry pixels.
+ *
+ * Whether your font has these glyphs decides what resolution is available, and
+ * a missing glyph does not error — it silently substitutes a box or a blank.
+ * Run this and look.
+ */
+import { cellsForWindow, queryTerminalSize } from '../src/cli/cellsize.js'
+import { PACKINGS, probe } from '../src/cli/working/packing.js'
+
+const argv = process.argv.slice(2)
+if (argv.includes('--help') || argv.includes('-h')) {
+  process.stdout.write('usage: dsh-glyph-probe [--raw]\n\n')
+  process.stdout.write('Prints a sample of half-block, quadrant and braille glyphs.\n')
+  process.stdout.write('--raw  write the characters without colour\n')
+  process.exit(0)
+}
+
+const dim = (text) => `\u001b[38;5;245m${text}\u001b[0m`
+
+// How big the cells really are decides how much can be drawn at all, so ask.
+const geometry = await queryTerminalSize({ stdin: process.stdin, stdout: process.stdout })
+const cols = process.stdout.columns ?? 80
+const rows = process.stdout.rows ?? 24
+process.stdout.write('\n')
+if (geometry.cell === undefined) {
+  process.stdout.write('The terminal did not report its cell size (CSI 16t); most do not.\n')
+  process.stdout.write(`Known: ${cols}x${rows} cells.\n`)
+} else {
+  const { width, height } = geometry.cell
+  const here = cellsForWindow(geometry.cell, geometry.textArea ?? { width: width * cols, height: height * rows })
+  const smaller = cellsForWindow({ width: Math.max(1, Math.round(width / 2)), height: Math.max(1, Math.round(height / 2)) }, geometry.textArea ?? { width: width * cols, height: height * rows })
+  process.stdout.write(`Cell size      ${width}x${height} px   (aspect ${(width / height).toFixed(2)})\n`)
+  process.stdout.write(`Cells          ${cols}x${rows}\n`)
+  process.stdout.write(`Drawing budget ${here.artPixels.toLocaleString()} pixels (two per cell)\n`)
+  process.stdout.write(`Half the font  ${smaller.cols}x${smaller.rows} cells -> ${smaller.artPixels.toLocaleString()} pixels\n`)
+  process.stdout.write('\nA terminal will not change its own font: there is no escape sequence.\n')
+  process.stdout.write('Shrink it yourself and this number is what you gain.\n')
+}
+
+
+for (const packing of Object.values(PACKINGS)) {
+  process.stdout.write(`\n${dim(`── ${packing.name} ─ ${packing.cols}x${packing.rows} ─ ${packing.square ? 'square' : 'non-square'} pixels ─ ${packing.solid ? 'solid' : 'dotted'} glyphs`)}\n\n`)
+  const { rows } = probe(packing)
+  for (const row of rows) process.stdout.write(`${row}\n`)
+  process.stdout.write('\n')
+}
+
+process.stdout.write('Compare the three discs. The one that comes out round and seamless is the one\n')
+process.stdout.write('your font supports; a row of boxes or question marks means it does not.\n')

package/bin/dsh-live-trace.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * `dsh-live-trace` executable.
+ *
+ * Thin wrapper: resolve the version, hand the arguments to the CLI, and map the
+ * returned code onto the process exit status.
+ */
+
+import { readFileSync } from 'node:fs'
+
+import { run } from '../src/cli/main.js'
+
+const version = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version ?? '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+})()
+
+run(process.argv.slice(2), { version }).then(
+  (code) => {
+    process.exitCode = code
+  },
+  (error) => {
+    process.stderr.write(`dsh-live-trace: ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`)
+    process.exitCode = 1
+  }
+)

package/bin/dsh-live-working.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * `dsh-live-working` — the orca at its desk, animated for the live session.
+ */
+
+import { run } from '../src/cli/working/main.js'
+
+const code = await run({
+  stdout: process.stdout,
+  stdin: process.stdin,
+  stderr: process.stderr,
+  argv: process.argv.slice(2)
+})
+process.exit(code)

package/cordis.patch.yml

@@ -0,0 +1,31 @@
+# Bundle patch for dsh-live-trace.
+#
+# Inserting this row adds the Host-side observer to whichever profile loads the
+# bundle. It is inert until the standalone `dsh-live-trace` viewer connects:
+# the plugin only publishes normalized session events on a local socket, so it
+# never changes what the agent does.
+- insert:
+    - id: dsh-live-trace
+      name: dsh-live-trace
+      config:
+        # Set to false to keep the observer from starting at all.
+        enabled: true
+        # How often coalesced streaming text is pushed, in milliseconds.
+        streamIntervalMs: 500
+        # Recent normalized entries retained per session for late-joining viewers.
+        backlogSize: 2000
+        # Command output retained per call, for the commands panel and tool blocks.
+        outputLines: 200
+        outputChars: 20000
+        # Emit the rendered system prompt as a trace entry (noisy; off by default).
+        showSystemMessages: false
+        # Emit request/header and request/context bookkeeping as trace entries.
+        showRequestMetadata: false
+        # Emit unrecognized event types as generic entries instead of dropping
+        # them. Off by default: most unknown events are plugin bookkeeping.
+        showUnknownEvents: false
+        # Event types to hide; `*` is a prefix match. Built in:
+        # ['session-log-deepseek/*'].
+        # mutedEventTypes:
+        #   - 'session-log-deepseek/*'
+        #   - 'some-plugin/*'

package/icon.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" role="img" aria-label="dsh-live-trace">
+  <rect x="2" y="6" width="60" height="52" rx="6" fill="none" stroke="#4cc9f0" stroke-width="3"/>
+  <line x1="2" y1="18" x2="62" y2="18" stroke="#4cc9f0" stroke-width="3"/>
+  <line x1="2" y1="48" x2="62" y2="48" stroke="#4cc9f0" stroke-width="3"/>
+  <circle cx="10" cy="12" r="2" fill="#4cc9f0"/>
+  <rect x="10" y="24" width="14" height="3" rx="1.5" fill="#4cc9f0"/>
+  <rect x="28" y="24" width="22" height="3" rx="1.5" fill="#4cc9f0" opacity="0.55"/>
+  <rect x="16" y="31" width="30" height="3" rx="1.5" fill="#f9c74f"/>
+  <rect x="16" y="38" width="20" height="3" rx="1.5" fill="#43aa8b"/>
+  <rect x="10" y="53" width="9" height="3" rx="1.5" fill="#4cc9f0" opacity="0.8"/>
+  <rect x="23" y="53" width="18" height="3" rx="1.5" fill="#4cc9f0" opacity="0.45"/>
+</svg>

package/index.js

@@ -0,0 +1,328 @@
+/**
+ * dsh-live-trace — Host-side observer plugin.
+ *
+ * The plugin subscribes to the Harness event bus in-process, normalizes what it
+ * sees into flat display records, and publishes them on a Unix domain socket.
+ * It is strictly read-only: it never appends a session event, never changes a
+ * tool decision, never touches the model request, and never writes to stdout
+ * (which belongs to whatever surface the Harness is driving). The standalone
+ * `dsh-live-trace` viewer is a separate process that renders those records in
+ * a different terminal.
+ *
+ * Cleanup is owned by the plugin's Cordis fiber: every `ctx.on` registration
+ * returns a disposer, every timer is cleared, the socket is closed and unlinked,
+ * and the discovery record is removed. Unloading the plugin leaves nothing
+ * behind.
+ *
+ * @module dsh-live-trace
+ */
+
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { disconnectExistingInstance, registerInstance, releaseInstance } from './lib/instance.js'
+import { resolveRuntimeDir, serversDir, socketsDir } from './lib/paths.js'
+import { DEFAULT_MUTED_EVENT_TYPES } from './lib/normalize.js'
+import { MAX_REPLAY_ENTRIES, PROTOCOL_VERSION, SERVER_KIND } from './lib/protocol.js'
+import { removeServerRecordIfOwner, writeServerRecord } from './lib/registry.js'
+import { TraceHub } from './lib/tracker.js'
+import { createTraceServer, defaultSocketPath, DEFAULT_REPLAY_LIMIT, HEARTBEAT_MS } from './lib/transport.js'
+
+/** Cordis plugin name. */
+export const name = 'dsh-live-trace'
+
+/** This package's version, read lazily so the manifest stays the single source of truth. */
+export const version = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version ?? '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+})()
+
+/** Plugin defaults; every one is overridable from `cordis.patch.yml`. */
+export const CONFIG_DEFAULTS = {
+  enabled: true,
+  streamIntervalMs: 500,
+  backlogSize: 2000,
+  heartbeatMs: HEARTBEAT_MS,
+  replayLimit: DEFAULT_REPLAY_LIMIT,
+  showSystemMessages: false,
+  showRequestMetadata: false,
+  showUnknownEvents: false,
+  mutedEventTypes: undefined,
+  textLimit: undefined,
+  outputLines: undefined,
+  outputChars: undefined,
+  runtimeDir: undefined,
+  socketPath: undefined
+}
+
+/**
+ * Coerce the loader's config row into a validated options object.
+ *
+ * The plugin deliberately declares no `Config` schema: the observer must load
+ * even in a profile that cannot resolve the schema package, and a mistyped
+ * option should degrade to its default rather than refuse to start.
+ *
+ * @param {unknown} config
+ * @returns {typeof CONFIG_DEFAULTS}
+ */
+export function resolveConfig(config) {
+  const raw = config !== null && typeof config === 'object' ? /** @type {any} */ (config) : {}
+  return {
+    enabled: raw.enabled !== false,
+    streamIntervalMs: clampInt(raw.streamIntervalMs, CONFIG_DEFAULTS.streamIntervalMs, 50, 60_000),
+    backlogSize: clampInt(raw.backlogSize, CONFIG_DEFAULTS.backlogSize, 10, 100_000),
+    heartbeatMs: clampInt(raw.heartbeatMs, CONFIG_DEFAULTS.heartbeatMs, 500, 300_000),
+    replayLimit: clampInt(raw.replayLimit, CONFIG_DEFAULTS.replayLimit, 1, MAX_REPLAY_ENTRIES),
+    showSystemMessages: raw.showSystemMessages === true,
+    showRequestMetadata: raw.showRequestMetadata === true,
+    showUnknownEvents: raw.showUnknownEvents === true,
+    mutedEventTypes: resolveMutedEventTypes(raw.mutedEventTypes),
+    textLimit: clampInt(raw.textLimit, undefined, 120, 100_000),
+    outputLines: clampInt(raw.outputLines, undefined, 1, 100_000),
+    outputChars: clampInt(raw.outputChars, undefined, 200, 1_000_000),
+    runtimeDir: typeof raw.runtimeDir === 'string' && raw.runtimeDir.trim().length > 0 ? resolve(raw.runtimeDir) : undefined,
+    socketPath: typeof raw.socketPath === 'string' && raw.socketPath.trim().length > 0 ? resolve(raw.socketPath) : undefined
+  }
+}
+
+/** Accept an override list, or keep the built-in bookkeeping filter. */
+function resolveMutedEventTypes(value) {
+  if (value === undefined) return DEFAULT_MUTED_EVENT_TYPES
+  if (Array.isArray(value)) return value.filter((entry) => typeof entry === 'string')
+  // `false` turns the filter off entirely, which is what debugging wants.
+  if (value === false || value === null) return []
+  return DEFAULT_MUTED_EVENT_TYPES
+}
+
+function clampInt(value, fallback, min, max) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback
+  return Math.max(min, Math.min(max, Math.floor(value)))
+}
+
+/** Resolve a logger without assuming the Cordis logger service exists. */
+function makeLogger(ctx) {
+  const noop = { info() {}, warn() {}, error() {}, debug() {} }
+  try {
+    const service = ctx?.logger ?? ctx?.get?.('logger')
+    if (typeof service === 'function') {
+      const scoped = service('dsh-live-trace')
+      if (scoped !== null && typeof scoped === 'object') return scoped
+    }
+    if (service !== null && typeof service === 'object' && typeof service.warn === 'function') return service
+  } catch {
+    /* fall through to the no-op logger */
+  }
+  return noop
+}
+
+/**
+ * Cordis plugin entry.
+ *
+ * @param {any} ctx plugin fiber context
+ * @param {object} [config] the `cordis.patch.yml` row's `config`
+ * @returns {any} an effect disposer so Cordis owns teardown
+ */
+export function apply(ctx, config) {
+  const options = resolveConfig(config)
+  if (options.enabled === false) return undefined
+
+  const logger = makeLogger(ctx)
+  const runtimeDir = options.runtimeDir ?? resolveRuntimeDir()
+  const socketPath = options.socketPath ?? defaultSocketPath(runtimeDir, process.pid)
+  const startedAt = Date.now()
+
+  const hub = new TraceHub({
+    backlogSize: options.backlogSize,
+    streamIntervalMs: options.streamIntervalMs,
+    normalizeOptions: {
+      showSystemMessages: options.showSystemMessages,
+      showRequestMetadata: options.showRequestMetadata,
+      showUnknownEvents: options.showUnknownEvents,
+      mutedEventTypes: options.mutedEventTypes,
+      ...(options.textLimit === undefined ? {} : { textLimit: options.textLimit }),
+      ...(options.outputLines === undefined && options.outputChars === undefined
+        ? {}
+        : {
+            outputLimits: {
+              ...(options.outputLines === undefined ? {} : { maxLines: options.outputLines }),
+              ...(options.outputChars === undefined ? {} : { maxChars: options.outputChars })
+            }
+          })
+    }
+  })
+
+  return ctx.effect(async () => {
+    /** @type {Array<() => void>} */
+    const disposers = []
+    /** @type {ReturnType<typeof createTraceServer> | null} */
+    let server = null
+    /** @type {NodeJS.Timeout | null} */
+    let flushTimer = null
+    /** @type {NodeJS.Timeout | null} */
+    let registryTimer = null
+
+    const listen = (event, handler) => {
+      try {
+        const dispose = ctx.on(event, handler)
+        if (typeof dispose === 'function') disposers.push(dispose)
+      } catch (error) {
+        logger.warn?.(`could not subscribe to ${event}: ${describe(error)}`)
+      }
+    }
+
+    listen('session/created', (session) => {
+      safe(() => hub.onSessionCreated(session, 'live'))
+    })
+    listen('session/disposed', (session) => {
+      safe(() => hub.onSessionDisposed(session))
+    })
+    listen('session/event', (session, event) => {
+      safe(() => hub.onSessionEvent(session, event))
+    })
+    listen('agent/created', (payload) => {
+      safe(() => hub.onAgentCreated(payload?.agent, payload?.source))
+    })
+    listen('agent/status', (payload) => {
+      safe(() => hub.onAgentStatus(payload?.agent, payload?.status))
+    })
+    listen('agent/assistant-stream', (payload) => {
+      safe(() => hub.onAssistantStream(payload?.agent, payload?.frame))
+    })
+    listen('agent/error', (payload) => {
+      safe(() => hub.onAgentError(payload))
+    })
+
+    // Adopt sessions that already exist, so a viewer attached before the next
+    // event still sees the current session list.
+    try {
+      const sessions = ctx.get?.('sessions')
+      for (const session of sessions?.list?.() ?? []) hub.onSessionCreated(session, 'startup')
+    } catch (error) {
+      logger.debug?.(`session list unavailable at startup: ${describe(error)}`)
+    }
+
+    // Coalesced streaming text is pushed on a fixed cadence instead of per
+    // chunk, so a fast model cannot flood the viewer.
+    flushTimer = setInterval(() => {
+      safe(() => hub.flushStreams())
+    }, Math.max(50, Math.min(options.streamIntervalMs, 250)))
+    flushTimer.unref?.()
+
+    const serverInfo = () => ({
+      pid: process.pid,
+      version,
+      protocol: PROTOCOL_VERSION,
+      profile: process.env.DSH_PROFILE ?? null,
+      cwd: process.cwd(),
+      runtimeDir,
+      socket: socketPath,
+      startedAt,
+      hubActive: true
+    })
+
+    const publishRegistry = () => {
+      try {
+        writeServerRecord(serversDir(runtimeDir), {
+          ...serverInfo(),
+          heartbeat: Date.now(),
+          activeSessionId: hub.activeSessionId,
+          sessions: hub.sessionsInfo()
+        })
+      } catch (error) {
+        logger.debug?.(`could not write discovery record: ${describe(error)}`)
+      }
+    }
+
+    try {
+      // A previous instance in this same process (hot reload) must release the
+      // socket path before the new one binds it.
+      await disconnectExistingInstance(process.pid)
+      server = createTraceServer({
+        socketPath,
+        runtimeDir,
+        hub,
+        serverInfo,
+        heartbeatMs: options.heartbeatMs,
+        onError: (error) => logger.warn?.(`socket error: ${describe(error)}`)
+      })
+      await server.ready
+      registerInstance(process.pid, server)
+      publishRegistry()
+      // A session appearing or disappearing is exactly when a viewer's
+      // discovery view must change, so refresh the record immediately rather
+      // than waiting for the next heartbeat.
+      disposers.push(
+        hub.subscribe((record) => {
+          if (record.kind === SERVER_KIND.SESSIONS) publishRegistry()
+        })
+      )
+      registryTimer = setInterval(publishRegistry, Math.max(1000, Math.floor(options.heartbeatMs / 2)))
+      registryTimer.unref?.()
+      logger.info?.(`observing on ${socketPath}`)
+    } catch (error) {
+      logger.warn?.(`observer transport unavailable: ${describe(error)}`)
+      if (server !== null) {
+        try {
+          await server.close()
+        } catch {
+          /* already unusable */
+        }
+        server = null
+      }
+    }
+
+    return async () => {
+      for (const dispose of disposers.reverse()) {
+        try {
+          dispose()
+        } catch {
+          /* a partially registered listener is not a teardown failure */
+        }
+      }
+      disposers.length = 0
+      if (flushTimer !== null) clearInterval(flushTimer)
+      if (registryTimer !== null) clearInterval(registryTimer)
+      flushTimer = null
+      registryTimer = null
+      if (server !== null) {
+        const owned = server
+        try {
+          await owned.close()
+        } catch (error) {
+          logger.debug?.(`socket close reported ${describe(error)}`)
+        }
+        // Only now is the in-process registration safe to drop: close() is what
+        // releases the socket, and the identity guard keeps a stale disposer
+        // from evicting a newer generation that already registered.
+        releaseInstance(process.pid, owned)
+        server = null
+      }
+      try {
+        removeServerRecordIfOwner(serversDir(runtimeDir), process.pid, socketPath)
+      } catch {
+        /* nothing to remove */
+      }
+      logger.info?.('observer stopped')
+    }
+  }, 'dsh-live-trace')
+}
+
+/** Run a hub mutation without letting an observer bug escape into the Harness. */
+function safe(run) {
+  try {
+    run()
+  } catch {
+    /* observation must never disturb the observed */
+  }
+}
+
+function describe(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export { TraceHub } from './lib/tracker.js'
+export { normalizeSessionEvent } from './lib/normalize.js'
+export { socketsDir, serversDir, resolveRuntimeDir }

package/lib/client.js

@@ -0,0 +1,178 @@
+/**
+ * The viewer-side socket client: connects to the observer's socket, decodes
+ * records, and reconnects automatically when the Harness restarts.
+ *
+ * @module dsh-live-trace/client
+ */
+
+import { connect } from 'node:net'
+
+import { CLIENT_KIND, createLineDecoder, encodeRecord, SERVER_KIND } from './protocol.js'
+
+const RETRY_MIN_MS = 250
+const RETRY_MAX_MS = 4000
+
+/**
+ * Connect to a running observer.
+ *
+ * `onRecord` receives every decoded server record, including the initial
+ * `hello`. `onOpen` fires on every successful connection and again after a
+ * reconnect, so the caller can reset derived view state.
+ *
+ * @param {object} options
+ * @param {string} options.socketPath
+ * @param {string | null} [options.sessionId] desired session; `null` follows the server default
+ * @param {number} [options.replayLimit]
+ * @param {(record: any) => void} options.onRecord
+ * @param {(record: any) => void} [options.onOpen]
+ * @param {(info: { willRetry: boolean }) => void} [options.onClose]
+ * @param {(error: Error) => void} [options.onError]
+ * @param {boolean} [options.retry]
+ * @returns {{ close: () => void, select: (sessionId: string | null) => void, replay: (limit?: number) => void, isOpen: () => boolean, socketPath: string }}
+ */
+export function connectTrace(options) {
+  const {
+    socketPath,
+    replayLimit,
+    onRecord,
+    onOpen,
+    onClose,
+    onError,
+    retry = true,
+    retryMinMs = RETRY_MIN_MS,
+    retryMaxMs = RETRY_MAX_MS
+  } = options
+
+  let desiredSession = options.sessionId ?? null
+  let boundSession = null
+  let selectPending = false
+  let socket = null
+  let decoder = createLineDecoder()
+  let closedByCaller = false
+  let retryDelay = retryMinMs
+  let timer = null
+  let open = false
+
+  const send = (record) => {
+    if (socket === null || socket.destroyed) return
+    try {
+      socket.write(encodeRecord(record))
+    } catch {
+      /* the close handler owns recovery */
+    }
+  }
+
+  /** Ask the server to bind us to its own default session. */
+  const requestDefault = () => {
+    if (closedByCaller || selectPending) return
+    selectPending = true
+    send({ v: 1, kind: CLIENT_KIND.SELECT, limit: replayLimit })
+  }
+
+  const scheduleRetry = () => {
+    if (closedByCaller || retry === false || timer !== null) return
+    timer = setTimeout(() => {
+      timer = null
+      attempt()
+    }, retryDelay)
+    timer.unref?.()
+    retryDelay = Math.min(retryMaxMs, Math.round(retryDelay * 1.7))
+  }
+
+  const handle = (record) => {
+    const isSelectionAnswer =
+      record !== null &&
+      typeof record === 'object' &&
+      (record.kind === SERVER_KIND.SESSIONS || record.kind === SERVER_KIND.ERROR) &&
+      Array.isArray(record.sessions)
+    if (isSelectionAnswer) {
+      // `sessions` records are the authoritative answer to a selection: they
+      // carry the list, the server's default, and the binding this viewer
+      // actually holds. The opening `hello` is deliberately not one of them:
+      // treating it as an answer would clear the pending flag and duplicate the
+      // selection, which shows up as a replayed backlog.
+      selectPending = false
+      const list = record.sessions
+      const reported = record.boundSessionId === undefined ? null : (record.boundSessionId ?? null)
+      const wanted = desiredSession ?? reported
+      if (record.kind === SERVER_KIND.ERROR || (wanted !== null && !list.some((session) => session.id === wanted))) {
+        // The session being followed is gone, or the server refused the one
+        // that was requested: fall back to following the server's default.
+        desiredSession = null
+        boundSession = null
+      } else {
+        boundSession = wanted
+      }
+      // A viewer with no binding keeps asking until one exists, so a dashboard
+      // opened before the first session still starts following it.
+      if (boundSession === null && desiredSession === null && list.length > 0) requestDefault()
+    }
+    onRecord(record)
+  }
+
+  function attempt() {
+    if (closedByCaller) return
+    decoder = createLineDecoder()
+    const connection = connect(socketPath)
+    socket = connection
+    connection.setNoDelay(true)
+    connection.setEncoding('utf8')
+
+    connection.on('connect', () => {
+      open = true
+      retryDelay = retryMinMs
+      boundSession = null
+      selectPending = true
+      send({ v: 1, kind: CLIENT_KIND.SELECT, sessionId: desiredSession ?? undefined, limit: replayLimit })
+      onOpen?.({ socketPath })
+    })
+
+    connection.on('data', (chunk) => {
+      let records
+      try {
+        records = decoder.push(chunk)
+      } catch (error) {
+        onError?.(/** @type {Error} */ (error))
+        connection.destroy()
+        return
+      }
+      for (const record of records) handle(record)
+    })
+
+    connection.on('error', (error) => {
+      onError?.(/** @type {Error} */ (error))
+    })
+
+    connection.on('close', () => {
+      const wasOpen = open
+      open = false
+      socket = null
+      boundSession = null
+      selectPending = false
+      if (closedByCaller) return
+      onClose?.({ willRetry: retry !== false })
+      if (wasOpen) retryDelay = retryMinMs
+      scheduleRetry()
+    })
+  }
+
+  attempt()
+
+  return {
+    socketPath,
+    isOpen: () => open,
+    select(sessionId) {
+      desiredSession = sessionId
+      selectPending = true
+      send({ v: 1, kind: CLIENT_KIND.SELECT, sessionId: sessionId ?? undefined, limit: replayLimit })
+    },
+    replay(limit) {
+      send({ v: 1, kind: CLIENT_KIND.REPLAY, limit })
+    },
+    close() {
+      closedByCaller = true
+      if (timer !== null) clearTimeout(timer)
+      if (socket !== null) socket.destroy()
+    }
+  }
+}