@huynle/hub 0.0.0-stage → 0.6.0

package/src/spoke/summary.ts

@@ -0,0 +1,117 @@
+// Right-rail summary of a session, computed on the spoke from OpenCode data: context usage (latest
+// assistant tokens against the model's context limit), MCP server status and working-tree changes.
+// Pure: the spoke passes in what it read from OpenCode.
+import type { ChangedFile, ContextUsage, FilePatch, McpStatus, SessionChanges } from "../protocol"
+
+/**
+ * Longest patch sent for one file, measured as JSON-encoded characters (quotes, backslashes and control
+ * characters count at their escaped size), so the reply always fits in one protocol frame. The rest is cut
+ * and marked truncated.
+ */
+export const MAX_PATCH_CHARS = 400 * 1024
+/** At most this many changed files are listed (the most-changed first); the totals still cover every file. */
+export const MAX_CHANGED_FILES = 500
+/** The listed files also stop once their JSON reaches this size, so the summary always fits in one frame. */
+const MAX_CHANGES_ENCODED_CHARS = 400 * 1024
+const MAX_MCP_SERVERS = 100
+const MAX_NAME_CHARS = 200
+const MAX_ERROR_CHARS = 200
+const MCP_STATUSES = new Set(["connected", "pending", "disabled", "failed", "needs_auth"])
+const FILE_STATUSES = new Set(["added", "deleted", "modified"])
+
+const record = (v: unknown): Record<string, any> => (typeof v === "object" && v !== null ? (v as Record<string, any>) : {})
+const count = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) && v > 0 ? v : 0)
+
+export function contextUsage(messages: ReadonlyArray<unknown>, models: ReadonlyArray<unknown>): ContextUsage | undefined {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = record(messages[i])
+    if (message.type !== "assistant" || !message.tokens) continue
+    const t = record(message.tokens)
+    const used = count(t.input) + count(t.output) + count(t.reasoning) + count(record(t.cache).read) + count(record(t.cache).write)
+    const ref = record(message.model)
+    const info = record(models.find((m) => record(m).providerID === ref.providerID && record(m).modelID === ref.id))
+    const limit = count(record(info.limit).context)
+    return {
+      used,
+      ...(limit ? { limit, percent: Math.min(100, Math.max(0, Math.round((used / limit) * 100))) } : {}),
+      ...(typeof info.name === "string" ? { model: info.name } : {}),
+    }
+  }
+  return undefined
+}
+
+export function mcpServers(raw: ReadonlyArray<unknown>): McpStatus[] {
+  return raw
+    .flatMap((value) => {
+      const server = record(value)
+      if (typeof server.name !== "string" || !server.name) return []
+      const status = record(server.status)
+      const name = MCP_STATUSES.has(status.status) ? (status.status as McpStatus["status"]) : "unknown"
+      const error = typeof status.error === "string" && status.error ? status.error.slice(0, MAX_ERROR_CHARS) : undefined
+      return [{ name: server.name.slice(0, MAX_NAME_CHARS), status: name, ...(error ? { error } : {}) }]
+    })
+    .slice(0, MAX_MCP_SERVERS)
+}
+
+function changedFile(value: unknown): (ChangedFile & { patch: string }) | undefined {
+  const d = record(value)
+  if (typeof d.file !== "string" || !d.file) return undefined
+  return {
+    file: d.file,
+    status: FILE_STATUSES.has(d.status) ? d.status : "modified",
+    additions: count(d.additions),
+    deletions: count(d.deletions),
+    patch: typeof d.patch === "string" ? d.patch : "",
+  }
+}
+
+export function changeStats(raw: ReadonlyArray<unknown>): SessionChanges {
+  const all: ChangedFile[] = raw.flatMap((value) => {
+    const file = changedFile(value)
+    if (!file) return []
+    const { patch: _patch, ...stats } = file
+    return [stats]
+  })
+  const ranked = all.length > MAX_CHANGED_FILES ? [...all].sort((a, b) => b.additions + b.deletions - (a.additions + a.deletions) || a.file.localeCompare(b.file)) : all
+  const files: ChangedFile[] = []
+  let size = 0
+  for (const file of ranked) {
+    if (files.length >= MAX_CHANGED_FILES || (size += JSON.stringify(file).length + 1) > MAX_CHANGES_ENCODED_CHARS) break
+    files.push(file)
+  }
+  return {
+    files,
+    additions: all.reduce((n, f) => n + f.additions, 0),
+    deletions: all.reduce((n, f) => n + f.deletions, 0),
+    totalFiles: all.length,
+    truncated: files.length < all.length,
+  }
+}
+
+const isHigh = (c: number) => c >= 0xd800 && c <= 0xdbff
+const isLow = (c: number) => c >= 0xdc00 && c <= 0xdfff
+const SHORT_ESCAPES = new Set([0x08, 0x09, 0x0a, 0x0c, 0x0d, 0x22, 0x5c])
+
+/** The longest prefix of `text` whose JSON encoding (with quotes) fits in `max` characters, never splitting a surrogate pair. */
+export function clipEncoded(text: string, max: number): { text: string; truncated: boolean } {
+  let size = 2
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i)
+    // A well-formed surrogate pair is written as-is (two units); lone surrogates and other control characters as \uXXXX.
+    const pair = isHigh(c) && isLow(text.charCodeAt(i + 1))
+    const width = pair ? 2 : SHORT_ESCAPES.has(c) ? 2 : c < 0x20 || isHigh(c) || isLow(c) ? 6 : 1
+    if ((size += width) > max) return { text: text.slice(0, i), truncated: true }
+    if (pair) i++
+  }
+  return { text, truncated: false }
+}
+
+export function filePatch(raw: ReadonlyArray<unknown>, file: string): FilePatch | undefined {
+  for (const value of raw) {
+    const found = changedFile(value)
+    if (found?.file !== file) continue
+    const { text, truncated } = clipEncoded(found.patch, MAX_PATCH_CHARS)
+    return { ...found, patch: text, truncated }
+  }
+  return undefined
+}

package/src/spoke/timeline.ts

@@ -0,0 +1,93 @@
+import { PROMPT_IMAGE_MIMES, type PromptImage } from "../protocol"
+
+/** An attachment of a user message: its position in the message's files (for timelineFile), type and name. */
+export interface TimelineFile {
+  readonly index: number
+  readonly mime: string
+  readonly name?: string
+}
+
+export interface TimelineItem {
+  readonly key: string
+  readonly messageID: string
+  readonly partID?: string
+  readonly sessionID: string
+  readonly kind: "user" | "assistant" | "reasoning" | "tool"
+  readonly text?: string
+  readonly name?: string
+  readonly state?: "running" | "done" | "failed"
+  readonly at?: number
+  readonly completed?: number
+  readonly files?: readonly TimelineFile[]
+}
+
+const record = (value: unknown): Record<string, any> => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : {}
+
+/** Projects OpenCode messages into stable, ordered, payload-light phone timeline rows. */
+export function timelineItems(sessionID: string, messages: readonly unknown[]): TimelineItem[] {
+  const out: TimelineItem[] = []
+  for (const raw of messages) {
+    const message = record(raw)
+    if (typeof message.id !== "string") continue
+    const at = typeof message.time?.created === "number" ? message.time.created : undefined
+    if (message.type === "user") {
+      const text = typeof message.text === "string" ? message.text : Array.isArray(message.content) ? message.content.filter((p: any) => p?.type === "text").map((p: any) => p.text).join("") : ""
+      const files = userFiles(message.files)
+      if (text || files.length) out.push({ key: `${message.id}:text`, messageID: message.id, sessionID, kind: "user", text, ...(at === undefined ? {} : { at }), ...(files.length ? { files } : {}) })
+      continue
+    }
+    if (message.type !== "assistant" || !Array.isArray(message.content)) continue
+    message.content.forEach((part: any, index: number) => {
+      if (!part || typeof part !== "object") return
+      const partID = String(index)
+      const base = { key: `${message.id}:${partID}`, messageID: message.id, partID, sessionID, ...(at === undefined ? {} : { at }) }
+      if (part.type === "text" && typeof part.text === "string" && part.text) out.push({ ...base, kind: "assistant", text: part.text })
+      if (part.type === "reasoning") out.push({ ...base, kind: "reasoning", text: String(part.text ?? ""), state: part.time?.completed === undefined ? "running" : "done", ...(typeof part.time?.created === "number" ? { at: part.time.created } : {}), ...(typeof part.time?.completed === "number" ? { completed: part.time.completed } : {}) })
+      if (part.type === "tool") {
+        const status = part.state?.status
+        out.push({ ...base, kind: "tool", name: String(part.name ?? "tool"), state: status === "error" ? "failed" : status === "completed" ? "done" : "running", ...(typeof part.time?.created === "number" ? { at: part.time.created } : {}), ...(typeof part.time?.completed === "number" ? { completed: part.time.completed } : {}) })
+      }
+    })
+  }
+  return out
+}
+
+/** Attachment metadata (never the bytes) of a user message's files. */
+function userFiles(raw: unknown): TimelineFile[] {
+  if (!Array.isArray(raw)) return []
+  return raw.flatMap((file, index) => {
+    const f = record(file)
+    if (typeof f.mime !== "string") return []
+    return [{ index, mime: f.mime, ...(typeof f.name === "string" && f.name ? { name: f.name.slice(0, 200) } : {}) }]
+  })
+}
+
+/** Largest attachment served (base64 characters), so the answer fits in one frame. */
+export const TIMELINE_FILE_MAX_BASE64 = 900_000
+
+/**
+ * The image at `index` of a user message: only the prompt image types are served (never SVG or other
+ * files); nothing when there is no such image; `tooLarge` when its bytes would not fit in a frame.
+ */
+export function timelineFile(messages: readonly unknown[], messageID: string, index: number): { file?: PromptImage; tooLarge?: boolean } {
+  const message = messages.map(record).find((item) => item.id === messageID && item.type === "user")
+  const file = Array.isArray(message?.files) ? record(message.files[index]) : {}
+  if (typeof file.mime !== "string" || !PROMPT_IMAGE_MIMES.includes(file.mime) || typeof file.data !== "string" || !file.data) return {}
+  if (file.data.length > TIMELINE_FILE_MAX_BASE64) return { tooLarge: true }
+  return { file: { mime: file.mime, data: file.data, ...(typeof file.name === "string" && file.name ? { name: file.name.slice(0, 200) } : {}) } }
+}
+
+export function timelinePart(messages: readonly unknown[], messageID: string, partID: string): unknown {
+  const message = messages.map(record).find((item) => item.id === messageID)
+  const index = Number(partID)
+  const part = Number.isInteger(index) && Array.isArray(message?.content) ? message.content[index] : undefined
+  if (!part || part.type !== "tool") throw new Error("Timeline part not found")
+  return { name: part.name, state: structuredClone(part.state), time: structuredClone(part.time) }
+}
+
+const DETAIL_MAX_BYTES = 750_000
+export function boundedTimelinePart(messages: readonly unknown[], messageID: string, partID: string): unknown {
+  const detail = timelinePart(messages, messageID, partID)
+  if (JSON.stringify(detail).length > DETAIL_MAX_BYTES) throw new Error("Timeline part is too large to display")
+  return detail
+}

package/src/spoke/tracker.ts

@@ -0,0 +1,345 @@
+// Sessions this OpenCode process knows about, built from the events it sees, plus which of them
+// are exposed to the central server (by mode). Pure: time is passed in.
+import type { Mode } from "../config"
+import { FORWARDED_EVENTS, type SessionInfo, type TerminalInfo } from "../protocol"
+
+/** A session is "owned" by this process while it viewed or ran it within this window. */
+export const OWNED_WINDOW_MS = 30 * 60 * 1000
+
+export interface EventLike {
+  readonly type: string
+  readonly data?: unknown
+  readonly created?: number
+}
+
+export interface SessionDetails {
+  readonly title: string
+  readonly directory: string
+  readonly parentID?: string
+  readonly updated: number
+  /** Workspace root and name (from the service's listing). */
+  readonly project?: string
+  readonly projectName?: string
+}
+
+interface Entry {
+  id: string
+  title: string
+  directory: string
+  parentID?: string
+  updated: number
+  lastActivity?: number
+  /** Title/directory are known (from session.created, a lookup, or the listing). */
+  info: boolean
+  project?: string
+  projectName?: string
+  /** Came from the service's listing of recent sessions (dropped when it leaves the listing). */
+  listed?: boolean
+}
+
+const ACTIVITY = new Set([
+  "session.viewed",
+  "session.execution.started",
+  "session.execution.succeeded",
+  "session.execution.failed",
+  "session.execution.interrupted",
+  "session.inbox.delivered",
+  "permission.asked",
+])
+
+const record = (v: unknown): Record<string, any> => (typeof v === "object" && v !== null ? (v as Record<string, any>) : {})
+
+/** The session an event belongs to, if any. */
+export function eventSessionID(event: EventLike): string | undefined {
+  const data = record(event.data)
+  if (typeof data.sessionID === "string" && data.sessionID) return data.sessionID
+  const form = record(data.form)
+  if (typeof form.sessionID === "string" && form.sessionID) return form.sessionID
+  return undefined
+}
+
+const RUN_END = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"])
+
+export class SessionTracker {
+  private readonly entries = new Map<string, Entry>()
+  /** Sessions with a run in progress. */
+  private readonly running = new Set<string>()
+  /** Pending permission or form ID → its session. */
+  private readonly waiting = new Map<string, string>()
+
+  /** Applies an event seen in this process. Returns true when the snapshot may have changed. */
+  observe(event: EventLike, now: number): boolean {
+    this.trackActive(event)
+    const data = record(event.data)
+    const id = typeof data.sessionID === "string" && data.sessionID ? data.sessionID : undefined
+    if (!id) return false
+    const at = typeof event.created === "number" ? event.created : now
+
+    switch (event.type) {
+      case "session.created": {
+        const entry = this.entry(id, at)
+        entry.title = typeof data.title === "string" ? data.title : entry.title
+        entry.directory = typeof data.location?.directory === "string" ? data.location.directory : entry.directory
+        if (typeof data.parentID === "string" && data.parentID) entry.parentID = data.parentID
+        entry.info = true
+        entry.lastActivity = now
+        return true
+      }
+      case "session.renamed": {
+        const entry = this.entries.get(id)
+        if (!entry || typeof data.title !== "string") return false
+        entry.title = data.title
+        entry.updated = Math.max(entry.updated, at)
+        return true
+      }
+      case "session.deleted":
+        this.running.delete(id)
+        for (const [key, sessionID] of this.waiting) if (sessionID === id) this.waiting.delete(key)
+        return this.entries.delete(id)
+      default: {
+        if (!ACTIVITY.has(event.type)) return false
+        const entry = this.entry(id, at)
+        entry.updated = Math.max(entry.updated, at)
+        entry.lastActivity = now
+        return true
+      }
+    }
+  }
+
+  /**
+   * Applies a full listing of the service's recent root sessions. Sessions known only from listings
+   * follow it (renames, removal); live sessions keep their live details and only gain the workspace.
+   * Returns true when the snapshot may have changed.
+   */
+  applyListing(sessions: ReadonlyArray<{ readonly id: string } & SessionDetails>, now: number, keep: ReadonlySet<string> = new Set()): boolean {
+    let changed = false
+    const ids = new Set(sessions.map((s) => s.id))
+    for (const entry of [...this.entries.values()]) {
+      if (!entry.listed || ids.has(entry.id) || keep.has(entry.id)) continue
+      if (entry.lastActivity !== undefined && now - entry.lastActivity <= OWNED_WINDOW_MS) {
+        entry.listed = false
+        continue
+      }
+      this.entries.delete(entry.id)
+      changed = true
+    }
+    for (const s of sessions) {
+      const existing = this.entries.get(s.id)
+      if (!existing) {
+        this.entries.set(s.id, {
+          id: s.id,
+          title: s.title,
+          directory: s.directory,
+          ...(s.parentID ? { parentID: s.parentID } : {}),
+          updated: s.updated,
+          info: true,
+          listed: true,
+          ...workspace(s),
+        })
+        changed = true
+        continue
+      }
+      const listingOnly = existing.info && existing.lastActivity === undefined
+      const next = listingOnly
+        ? { title: s.title, directory: s.directory, updated: s.updated }
+        : { updated: Math.max(existing.updated, s.updated) }
+      const update = { ...next, ...workspace(s), listed: true }
+      for (const [key, value] of Object.entries(update) as Array<[keyof Entry, never]>) {
+        if (existing[key] === value) continue
+        existing[key] = value
+        changed = true
+      }
+    }
+    return changed
+  }
+
+  /** Fills in details fetched for a session that was first seen through an activity event. */
+  setInfo(id: string, details: SessionDetails): boolean {
+    const entry = this.entries.get(id)
+    if (!entry) return false
+    entry.title = details.title
+    entry.directory = details.directory
+    if (details.parentID) entry.parentID = details.parentID
+    else delete entry.parentID
+    if (details.project) entry.project = details.project
+    if (details.projectName) entry.projectName = details.projectName
+    entry.updated = Math.max(entry.updated, details.updated)
+    entry.info = true
+    return true
+  }
+
+  /**
+   * Adds a session known only by ID (e.g. open in a terminal), not owned; its details (and last update)
+   * are fetched later. `_now` is accepted for symmetry with observe.
+   */
+  ensure(id: string, _now: number): boolean {
+    if (this.entries.has(id)) return false
+    this.entry(id, 0)
+    return true
+  }
+
+  /** Root sessions with a run in progress or a pending permission or form somewhere in their tree. */
+  active(): string[] {
+    const roots = new Set<string>()
+    for (const id of [...this.running, ...this.waiting.values()]) roots.add(this.rootOf(id))
+    return [...roots]
+  }
+
+  private trackActive(event: EventLike): void {
+    const data = record(event.data)
+    const sessionID = eventSessionID(event)
+    if (event.type === "session.execution.started" && sessionID) this.running.add(sessionID)
+    else if (RUN_END.has(event.type) && sessionID) this.running.delete(sessionID)
+    else if (event.type === "permission.asked" && sessionID && typeof data.id === "string") this.waiting.set(`per ${data.id}`, sessionID)
+    else if (event.type === "permission.replied" && typeof data.requestID === "string") this.waiting.delete(`per ${data.requestID}`)
+    else if (event.type === "form.created" && sessionID && typeof record(data.form).id === "string") this.waiting.set(`frm ${record(data.form).id}`, sessionID)
+    else if ((event.type === "form.replied" || event.type === "form.cancelled") && typeof (record(data.form).id ?? data.formID ?? data.id) === "string") {
+      this.waiting.delete(`frm ${record(data.form).id ?? data.formID ?? data.id}`)
+    }
+  }
+
+  /** A form (question) this process saw asked and not yet replied or cancelled. */
+  formPending(formID: string): boolean {
+    return this.waiting.has(`frm ${formID}`)
+  }
+
+  /** Running sessions strictly below a root, deepest first. */
+  runningBelow(root: string): string[] {
+    return [...this.running]
+      .filter((id) => id !== root && this.lineage(id).includes(root))
+      .sort((a, b) => this.lineage(b).length - this.lineage(a).length)
+  }
+
+  needsInfo(): string[] {
+    return [...this.entries.values()].filter((e) => !e.info).map((e) => e.id)
+  }
+
+  has(id: string): boolean {
+    return this.entries.has(id)
+  }
+
+  directoryOf(id: string): string | undefined {
+    return this.entries.get(id)?.directory || undefined
+  }
+
+  parentOf(id: string): string | undefined {
+    return this.entries.get(id)?.parentID
+  }
+
+  /** The top-most known ancestor of a session (itself when it has no known parent). */
+  rootOf(id: string): string {
+    let current = id
+    const seen = new Set<string>([id])
+    for (;;) {
+      const parent = this.parentOf(current)
+      if (!parent || seen.has(parent)) return current
+      seen.add(parent)
+      current = parent
+    }
+  }
+
+  /** Lineage from the session up to its root, cycle-safe. */
+  lineage(id: string): string[] {
+    const out = [id]
+    let current = id
+    for (;;) {
+      const parent = this.parentOf(current)
+      if (!parent || out.includes(parent)) return out
+      out.push(parent)
+      current = parent
+    }
+  }
+
+  snapshot(now: number): SessionInfo[] {
+    return [...this.entries.values()]
+      .filter((e) => e.info)
+      .map((e) => ({
+        id: e.id,
+        title: e.title,
+        directory: e.directory,
+        ...(e.parentID ? { parentID: e.parentID } : {}),
+        updated: e.updated,
+        owned: e.lastActivity !== undefined && now - e.lastActivity <= OWNED_WINDOW_MS,
+        ...(e.project ? { project: e.project } : {}),
+        ...(e.projectName ? { projectName: e.projectName } : {}),
+      }))
+  }
+
+  private entry(id: string, at: number): Entry {
+    let entry = this.entries.get(id)
+    if (!entry) {
+      entry = { id, title: "", directory: "", updated: at, info: false }
+      this.entries.set(id, entry)
+    }
+    return entry
+  }
+}
+
+const workspace = (s: SessionDetails) => ({
+  ...(s.project ? { project: s.project } : {}),
+  ...(s.projectName ? { projectName: s.projectName } : {}),
+})
+
+export interface ExposureConfig {
+  readonly mode: Mode
+  readonly sessions: readonly string[]
+}
+
+/** off: nothing; always: everything; session: listed sessions and their descendants. */
+export function isExposed(config: ExposureConfig, tracker: SessionTracker, sessionID: string): boolean {
+  if (config.mode === "always") return true
+  if (config.mode !== "session") return false
+  return tracker.lineage(sessionID).some((id) => config.sessions.includes(id))
+}
+
+/** Remote inspection and control: any session this process knows while connected (mode not "off"). Voice is separate. */
+export function isReported(config: ExposureConfig, tracker: SessionTracker, sessionID: string): boolean {
+  return config.mode !== "off" && (tracker.has(sessionID) || isExposed(config, tracker, sessionID))
+}
+
+export function shouldForward(config: ExposureConfig, tracker: SessionTracker, event: EventLike): boolean {
+  if (!FORWARDED_EVENTS.has(event.type)) return false
+  const sessionID = eventSessionID(event)
+  return sessionID !== undefined && isReported(config, tracker, sessionID)
+}
+
+/** Most sessions in one snapshot frame, and its size budget (the protocol refuses frames over 1 MB). */
+export const SNAPSHOT_MAX = 500
+export const SNAPSHOT_MAX_BYTES = 900_000
+
+/**
+ * The snapshot for the session browser: every known session with its Voice exposure. Over the limits,
+ * open, then exposed, then most recent sessions are kept.
+ */
+export function browserSessions(
+  config: ExposureConfig,
+  tracker: SessionTracker,
+  now: number,
+  limits: {
+    readonly max?: number
+    readonly maxBytes?: number
+    /** Where a session is open right now (Herdr pane or TUI), if it is. */
+    readonly terminal?: (sessionID: string) => TerminalInfo | undefined
+  } = {},
+): Array<SessionInfo & { exposed: boolean }> {
+  if (config.mode === "off") return []
+  const all = tracker
+    .snapshot(now)
+    .map((s) => {
+      const terminal = limits.terminal?.(s.id)
+      return { ...s, exposed: isExposed(config, tracker, s.id), ...(terminal ? { open: true, terminal } : {}) }
+    })
+  const max = limits.max ?? SNAPSHOT_MAX
+  const maxBytes = limits.maxBytes ?? SNAPSHOT_MAX_BYTES
+  if (all.length <= max && JSON.stringify(all).length <= maxBytes) return all
+  const ranked = [...all].sort((a, b) => Number(b.open === true) - Number(a.open === true) || Number(b.exposed) - Number(a.exposed) || b.updated - a.updated)
+  const keep = new Set<string>()
+  let bytes = 2
+  for (const s of ranked) {
+    const size = JSON.stringify(s).length + 1
+    if (keep.size >= max || bytes + size > maxBytes) break
+    bytes += size
+    keep.add(s.id)
+  }
+  return all.filter((s) => keep.has(s.id))
+}

package/src/spoke/watch.ts

@@ -0,0 +1,78 @@
+// Keeps the per-machine config live: fs.watch on the config's directory (atomic writes replace
+// the file, so watching the file itself would go stale) plus a slow poll as a fallback.
+import { watch, type FSWatcher } from "node:fs"
+import path from "node:path"
+import { readConfig, type VoiceConfig } from "../config"
+
+export interface ConfigWatcher {
+  current(): VoiceConfig
+  /** Re-reads now (e.g. after this process wrote the file) and notifies when it changed. */
+  refresh(): VoiceConfig
+  stop(): void
+}
+
+export function watchConfig(
+  file: string,
+  machineName: string,
+  onChange: (config: VoiceConfig) => void,
+  options: { pollMs?: number } = {},
+): ConfigWatcher {
+  let config = readConfig(file, machineName)
+  let key = JSON.stringify(config)
+  let stopped = false
+  let watcher: FSWatcher | undefined
+  let debounce: ReturnType<typeof setTimeout> | undefined
+
+  const refresh = () => {
+    if (stopped) return config
+    const next = readConfig(file, machineName)
+    const nextKey = JSON.stringify(next)
+    if (nextKey !== key) {
+      config = next
+      key = nextKey
+      try {
+        onChange(config)
+      } catch (cause) {
+        console.error("[hub] config change handler failed", cause)
+      }
+    }
+    return config
+  }
+
+  const startWatcher = () => {
+    if (watcher || stopped) return
+    try {
+      const base = path.basename(file)
+      watcher = watch(path.dirname(file), { persistent: false }, (_event, name) => {
+        if (name && name !== base) return
+        clearTimeout(debounce)
+        debounce = setTimeout(refresh, 50)
+      })
+      watcher.on("error", () => {
+        watcher?.close()
+        watcher = undefined
+      })
+    } catch {
+      watcher = undefined // directory missing; the poll keeps trying
+    }
+  }
+
+  startWatcher()
+  const poll = setInterval(() => {
+    startWatcher()
+    refresh()
+  }, options.pollMs ?? 5000)
+  ;(poll as { unref?: () => void }).unref?.()
+
+  return {
+    current: () => config,
+    refresh,
+    stop: () => {
+      stopped = true
+      clearInterval(poll)
+      clearTimeout(debounce)
+      watcher?.close()
+      watcher = undefined
+    },
+  }
+}