@huynle/hub 0.8.7 → 0.9.0

package/src/central/registry.ts

@@ -14,6 +14,7 @@ import path from "node:path"
 import { HARNESS_OPENCODE, helloHarness, spokeFeatures, type EvidenceLevel, type ForwardedEvent, type Hello, type HerdrWorkspace, type ProcessKind, type SessionInfo, type RevertCommitted, type SessionRevertInfo, type SpokeFeature, type SpokeMode, type TerminalInfo, type Terminals } from "../protocol"
 import { BLOCKER_ID_MAX, StatusBoard, askBlocker, errorTypeLabel, permissionRequest, providerFailureNeedsUser, providerRetryNeedsUser, type Blocker, type BlockerRecommendation, type PermissionRequest, type SessionStatus } from "../status"
 import { sanitizeLabel } from "./agent/envelope"
+import { redactCredentials } from "../../packages/protocol/src/credentials.ts"
 import { DoneWatch } from "./done"
 import { SentenceStream } from "./say-stream"
 import type { ActivityStep, NotificationKind } from "./push"
@@ -82,7 +83,11 @@ export type RegistryMessage =
   | { readonly type: "delta"; readonly sessionID: string; readonly rootID: string; readonly messageID?: string; readonly ordinal?: number; readonly text: string }
   /** Reasoning text streamed in a root or subagent session. */
   | { readonly type: "reasoning"; readonly sessionID: string; readonly rootID: string; readonly messageID?: string; readonly delta: string }
-  | { readonly type: "conversation"; readonly sessionID: string; readonly on: boolean }
+  /**
+   * Conversation mode changed. `front` (voice front P1): present once the voice front was asked for: whether a front
+   * session is in front of this one now; `reason` "front_failed": it failed and utterances go to the session itself.
+   */
+  | { readonly type: "conversation"; readonly sessionID: string; readonly on: boolean; readonly front?: boolean; readonly reason?: "front_failed" }
   /**
    * Assistant text of a root session in conversation mode, to be spoken. Root text is spoken while it streams:
    * one say per completed sentence, `seq` counting the sentences of the message's text part (`ordinal`) from 0.
@@ -431,6 +436,60 @@ const eventSessionID = (event: ForwardedEvent): string | undefined => {
   return typeof id === "string" ? id : undefined
 }
 
+/** (voice front P1) A front session ID as a spoke answers it (bounded). */
+const FRONT_ID_MAX = 300
+/** (voice front P1) A voice-front session no conversation maps for this long is deleted (through its reporter). */
+export const FRONT_STALE_MS = 60_000
+/** (voice front P1) A mapped front that no process reports (and none links) for this long has failed. */
+export const FRONT_GONE_MS = 10_000
+
+/**
+ * (voice front P1) What the hub asks a spoke to do about fronts: re-link a conversation's known front through the
+ * process that owns main now (its linking process went), or delete a stale front (removeFront).
+ */
+export type FrontAction =
+  | { readonly kind: "adopt"; readonly mainID: string; readonly connID: string; readonly frontID: string }
+  | { readonly kind: "remove"; readonly connID: string; readonly sessionID: string }
+
+/** (voice front P1) The front in front of a main session: who created it, and whether a sessions frame listed it yet. */
+interface Front {
+  readonly frontID: string
+  /** The connection that answered the conversation op, then the last one that reported the front. */
+  connID: string
+  /** Reported in a sessions frame: from then on, a frame of `connID` without it means it is gone. */
+  seen: boolean
+}
+
+/** (voice front P1) What a permission lets the session do, as spoken: "run a command", "edit files", "use webfetch". */
+const PERMISSION_PHRASES: Record<string, string> = {
+  shell: "run a command",
+  bash: "run a command",
+  edit: "edit files",
+  write: "edit files",
+  patch: "edit files",
+  read: "read files",
+  webfetch: "fetch a web page",
+  websearch: "search the web",
+  external_directory: "work outside its folder",
+  task: "start a worker",
+  subagent: "start a worker",
+}
+function permissionPhrase(action: string | undefined): string {
+  if (!action) return "go on"
+  return PERMISSION_PHRASES[action] ?? `use ${action.replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim().slice(0, 40)}`
+}
+
+/** A question's title as spoken: one line, short, ending with its punctuation (or a period). */
+function spokenTitle(title: string | undefined): string {
+  const t = (title ?? "").replace(/\s+/g, " ").trim()
+  if (!t || t === "question") return ""
+  const short = t.length > ANNOUNCE_REASON_MAX ? `${t.slice(0, ANNOUNCE_REASON_MAX - 1).trimEnd()}…` : t
+  return /[.?!…]$/.test(short) ? short : `${short}.`
+}
+
+/** (voice front P1) A voice front as a spoke reports it: with voiceFrontOf, or on the voice-front agent (an unlinked one). */
+const isFrontInfo = (s: SessionInfo) => s.voiceFrontOf !== undefined || s.agent === "voice-front"
+
 /** Older spokes reported exposed sessions only, without the field. */
 const isOn = (s: SessionInfo) => s.exposed !== false
 
@@ -468,6 +527,23 @@ export class Registry {
   private readonly providerAlerted = new Set<string>()
   /** Sessions in conversation mode → the connection last told so (re-sent when another one takes over). */
   private readonly conversations = new Map<string, string | undefined>()
+  /** (voice front P1) Sessions whose conversation asked for a voice front (a reconnect resend asks again). */
+  private readonly frontWanted = new Set<string>()
+  /** (voice front P1) Main session → its active front; front → main (the front's events speak as main). */
+  private readonly fronts = new Map<string, Front>()
+  private readonly frontMain = new Map<string, string>()
+  /** (voice front P1) Fronts that failed: never mapped again (a later report or resend answer naming one is ignored). */
+  private readonly failedFronts = new Set<string>()
+  /**
+   * (voice front P1) Main sessions whose front failed: until the user turns the conversation off or on again, no
+   * front is asked for (reconnect resends) or mapped (sessions frames); the session talks directly.
+   */
+  private readonly frontFellBack = new Set<string>()
+  /** (voice front P1) Unmapped voice-front sessions → when first reported so (removed after FRONT_STALE_MS). */
+  private readonly staleFronts = new Map<string, number>()
+  private readonly frontActionListeners = new Set<(action: FrontAction) => void>()
+  /** (voice front P1) Connection → front ops under way on it, and the sessions it reported when the first began. */
+  private readonly frontOps = new Map<string, { count: number; readonly known: ReadonlySet<string>; held: boolean }>()
   /** `messageID ordinal` of texts already sent as say events (several processes forward the same text). */
   private readonly spoken = new Map<string, true>()
   /** `messageID ordinal` → a root text part being spoken sentence by sentence as it streams. */
@@ -582,12 +658,55 @@ export class Registry {
 
   /** Sessions `conn` reports that belong to its tenant. */
   private visible(conn: Conn): SessionInfo[] {
-    return [...conn.sessions.values()].filter((s) => this.reports(conn, s.id))
+    return [...conn.sessions.values()].filter((s) => !isFrontInfo(s) && !this.frontMain.has(s.id) && !this.heldFront(conn.id, s) && this.reports(conn, s.id))
   }
 
-  /** True when the tenant owns the session (reported by one of its processes, or a subagent of such a session). */
+  /**
+   * (voice front P1) While a front op runs on a connection, a "Voice: " session it newly reports may be the front
+   * before the spoke linked it (an older spoke snapshots OpenCode's session.created first): held back until it answers.
+   */
+  private heldFront(connID: string, s: SessionInfo): boolean {
+    const op = this.frontOps.get(connID)
+    if (!op || op.known.has(s.id) || s.voiceFrontOf !== undefined || !(s.title ?? "").startsWith("Voice: ")) return false
+    op.held = true
+    return true
+  }
+
+  /** (voice front P1) A conversation op asking `connID` for a front starts: see heldFront. */
+  frontOpStarted(connID: string): void {
+    const op = this.frontOps.get(connID)
+    if (op) op.count++
+    else this.frontOps.set(connID, { count: 1, known: new Set(this.conns.get(connID)?.sessions.keys() ?? []), held: false })
+  }
+
+  /** (voice front P1) That op answered (or failed): what it held back is listed again, unless it is the front now. */
+  frontOpEnded(connID: string): void {
+    const op = this.frontOps.get(connID)
+    if (!op || --op.count > 0) return
+    this.frontOps.delete(connID)
+    if (op.held) this.emit({ type: "catalog" })
+  }
+
+  /**
+   * True when the tenant owns the session (reported by one of its processes, or a subagent of such a session). A
+   * hidden voice front belongs to nobody here: no route, list or agent reaches it.
+   */
   owns(tenant: string, sessionID: string): boolean {
-    return this.sessionTenant(sessionID) === tenant
+    return this.sessionTenant(sessionID) === tenant && !this.hidden(sessionID)
+  }
+
+  /**
+   * (voice front P1) A hidden voice-front session: one its tenant's processes report with `voiceFrontOf`, or the
+   * active front of a main session (before any sessions frame lists it). Never listed, boarded, pushed or named.
+   */
+  hidden(sessionID: string): boolean {
+    if (this.frontMain.has(sessionID)) return true
+    for (const conn of this.all()) {
+      const s = conn.sessions.get(sessionID)
+      if (s && isFrontInfo(s) && this.tenant(conn) === this.sessionTenant(sessionID)) return true
+      if (s && this.heldFront(conn.id, s)) return true
+    }
+    return false
   }
 
   /** Whether the connection's process belongs to the tenant. */
@@ -681,10 +800,27 @@ export class Registry {
       this.observeBoards({ type: "form.cancelled", data: { sessionID: origin.sessionID, id: formID } })
     }
     this.syncBoards()
+    this.frontLinkerGone(connID)
     this.changed(this.tenant(conn))
     this.emit({ type: "catalog" })
   }
 
+  /**
+   * (voice front P1) The process that linked fronts went: each one's main owner now (another process on the same
+   * data) re-links the same front; with nobody to, or if it is gone, the conversation fails over after FRONT_GONE_MS.
+   */
+  private frontLinkerGone(connID: string): void {
+    for (const [mainID, front] of this.fronts) {
+      if (front.connID !== connID || !this.conversations.has(mainID)) continue
+      const target = this.owner(mainID)
+      if (target !== undefined && this.frontWanted.has(mainID) && !this.frontFellBack.has(mainID) && this.supports(target, "voiceFront")) {
+        this.conversations.set(mainID, target)
+        this.frontAction({ kind: "adopt", mainID, connID: target, frontID: front.frontID })
+      }
+      this.watchFrontGone(mainID)
+    }
+  }
+
   touch(connID: string): void {
     const conn = this.conns.get(connID)
     if (conn) conn.lastSeen = this.now()
@@ -702,6 +838,7 @@ export class Registry {
       conn.sessionsKey = key
       conn.sessions = new Map(sessions.map((s) => [s.id, s]))
       this.syncBoards()
+      this.syncFronts(conn)
       this.changed(this.tenant(conn))
       this.emit({ type: "catalog" })
     }
@@ -740,6 +877,8 @@ export class Registry {
       const owner = this.sessionTenant(id)
       if (owner !== undefined && owner !== tenant) return
     }
+    // (voice front P1) A hidden front's events only speak, hear and record as its main session.
+    if (sessionID && this.hidden(sessionID)) return this.observeFront(connID, tenant, sessionID, event.type, data)
     // A question or permission whose ID no card can carry is never kept (no card, no answer; unbounded memory).
     if (oversizedBlockerID(event.type, data)) return
     if (sessionID) conn.activity.set(sessionID, this.tick())
@@ -799,7 +938,8 @@ export class Registry {
     }
 
     if (sessionID) this.trackRun(event.type, sessionID)
-    if (sessionID && this.recordingTap && TAPPED.has(event.type)) this.tap(connID, tenant, sessionID, event.type, data)
+    // While a front is active, the recording follows the front (tapped as main): main's own turn is not tapped.
+    if (sessionID && this.recordingTap && TAPPED.has(event.type) && !this.fronts.has(sessionID)) this.tap(connID, tenant, sessionID, event.type, data)
     const before = sessionID ? this.status(sessionID)?.find((s) => s.id === sessionID) : undefined
     this.observeBoards(event, tenant)
     if (sessionID) this.activitySteps(event.type, sessionID, data, before)
@@ -913,6 +1053,9 @@ export class Registry {
     const resend: string[] = []
     for (const [sessionID, told] of this.conversations) {
       if (told === connID || !this.reports(conn, sessionID) || this.owner(sessionID) !== connID) continue
+      // (voice front P1) The process that links the front is still here: it keeps serving the conversation.
+      const front = this.fronts.get(sessionID)
+      if (front && this.linker(front) !== undefined && front.connID !== connID) continue
       this.conversations.set(sessionID, connID)
       resend.push(sessionID)
     }
@@ -928,8 +1071,8 @@ export class Registry {
   }
 
   /** Root text streaming in conversation mode: each sentence is spoken as soon as it is complete. */
-  private speakDelta(connID: string, sessionID: string, data: Record<string, unknown>): void {
-    if (this.rootOf(sessionID) !== sessionID || !this.conversations.has(sessionID) || !this.boards.has(sessionID)) return
+  private speakDelta(connID: string, sessionID: string, data: Record<string, unknown>, fromFront = false): void {
+    if (!this.speaks(sessionID, fromFront)) return
     const { assistantMessageID: messageID, ordinal, delta } = data
     if (typeof messageID !== "string" || typeof ordinal !== "number" || typeof delta !== "string") return
     const key = `${messageID} ${ordinal}`
@@ -945,10 +1088,9 @@ export class Registry {
   }
 
   /** A root text part ended: speaks what the deltas did not (the ended text is authoritative), once. */
-  private say(sessionID: string, data: Record<string, unknown>): void {
-    if (this.rootOf(sessionID) !== sessionID) return
+  private say(sessionID: string, data: Record<string, unknown>, fromFront = false): void {
+    if (!this.speaks(sessionID, fromFront)) return
     const { assistantMessageID: messageID, ordinal, text } = data
-    if (!this.conversations.has(sessionID) || !this.boards.has(sessionID)) return
     if (typeof messageID !== "string" || typeof ordinal !== "number" || typeof text !== "string") return
     const key = `${messageID} ${ordinal}`
     if (this.spoken.has(key)) return
@@ -961,6 +1103,15 @@ export class Registry {
     if (text.trim() && !this.watched(sessionID)) this.alert("say", sessionID, { text })
   }
 
+  /**
+   * Whether root text of `sessionID` is spoken: a root session in conversation mode. While a voice front is active,
+   * only the front's text is (fromFront, spoken as main); main's own is not, the front reports it.
+   */
+  private speaks(sessionID: string, fromFront: boolean): boolean {
+    if (this.rootOf(sessionID) !== sessionID || !this.conversations.has(sessionID) || !this.boards.has(sessionID)) return false
+    return fromFront === this.fronts.has(sessionID)
+  }
+
   private emitSentence(state: RootSpeech, messageID: string, ordinal: number, text: string): void {
     this.heardFrom(state.sessionID, text)
     const seq = state.seq++
@@ -1033,18 +1184,25 @@ export class Registry {
     return rootID && rootID !== sessionID && this.conversations.has(rootID) && this.boards.has(rootID) ? rootID : undefined
   }
 
-  /** A worker that fails, needs a permission or asks a question is announced once ("Deploy check failed: …"). */
+  /**
+   * A worker that fails, needs a permission or asks a question is announced once ("Deploy check failed: …"). While a
+   * voice front is active, main's own failure, permission or question is too ("The session failed: …"): main is the
+   * one doing the work then.
+   */
   private observeWorkerBlockers(type: string, sessionID: string, data: Record<string, unknown>): void {
     if (type !== "session.execution.failed" && type !== "permission.asked" && type !== "form.created") return
-    const rootID = this.conversationRootOf(sessionID)
+    const own = this.fronts.has(sessionID) && this.speaks(sessionID, true)
+    if (own && type !== "session.execution.failed") return this.announceOwnAsk(type, sessionID, data)
+    const rootID = own ? sessionID : this.conversationRootOf(sessionID)
     if (!rootID) return
-    const title = this.workerTitle(rootID, sessionID)
+    const title = own ? "The session" : this.workerTitle(rootID, sessionID)
     if (type === "session.execution.failed") {
       const at = this.announcedFailures.get(sessionID)
       if (at !== undefined && this.now() - at <= FAILURE_DEDUPE_MS) return
       remember(this.announcedFailures, sessionID, this.now())
       const message = (data.error as { message?: unknown } | undefined)?.message
-      const reason = (typeof message === "string" ? message : "").replace(/\s+/g, " ").trim().replace(/[.!]+$/, "").slice(0, ANNOUNCE_REASON_MAX)
+      // Spoken (and pushed): never a credential the error text carries (the recordings' scrubber).
+      const reason = redactCredentials(typeof message === "string" ? message : "").text.replace(/\s+/g, " ").trim().replace(/[.!]+$/, "").slice(0, ANNOUNCE_REASON_MAX)
       return this.announce(rootID, `announce:failed:${sessionID}`, reason ? `${title} failed: ${reason}.` : `${title} failed.`, true)
     }
     const id = type === "permission.asked" ? data.id : (data.form as { id?: unknown } | undefined)?.id
@@ -1057,6 +1215,28 @@ export class Registry {
     else this.announce(rootID, `announce:form:${id}`, `${title} has a question.`, false)
   }
 
+  /**
+   * (voice front P1) Main's own permission or question while its front is active, once per request: "The session
+   * needs your permission to run a command." / "The session has a question: Which branch?" (no command line, as push).
+   */
+  private announceOwnAsk(type: string, sessionID: string, data: Record<string, unknown>): void {
+    const blocker = askBlocker({ type, data })
+    if (!blocker) return
+    const key = `${type} ${blocker.id}`
+    if (this.announcedBlockers.has(key)) return
+    remember(this.announcedBlockers, key, true)
+    if (blocker.kind === "permission") return this.announce(sessionID, `announce:permission:${blocker.id}`, `The session needs your permission to ${permissionPhrase(blocker.action)}.`, false)
+    // OpenCode's question tool titles its form "Questions": one question is read as itself (a field's description is
+    // the question, its title the short header), several are counted.
+    const fields = blocker.fields ?? []
+    if (blocker.question && fields.length > 1) return this.announce(sessionID, `announce:form:${blocker.id}`, `The session has ${fields.length} questions.`, false)
+    // The blocker may drop descriptions to stay small: the event's own field has it.
+    const raw = (data.form as { fields?: Array<{ description?: unknown }> } | undefined)?.fields?.[0]
+    const question = fields.length === 1 ? (typeof raw?.description === "string" && raw.description.trim() ? raw.description : fields[0]!.description || fields[0]!.title) : undefined
+    const title = spokenTitle(question || (blocker.question ? undefined : blocker.summary))
+    this.announce(sessionID, `announce:form:${blocker.id}`, title ? `The session has a question: ${title}` : "The session has a question.", false)
+  }
+
   /** Pairs a child session's latest assistant message with successful execution and speaks it once. */
   private observeWorkerSpeech(type: string, sessionID: string, data: Record<string, unknown>): void {
     const now = this.now()
@@ -1116,6 +1296,8 @@ export class Registry {
    */
   private flushWorkerSpeech(childID: string, state: WorkerSpeech): void {
     if (!state.succeeded || !state.messageID || state.parts.size === 0 || !this.conversations.has(state.rootID)) return
+    // (voice front P1) The front reports worker results itself.
+    if (this.fronts.has(state.rootID)) return state.parts.clear()
     const parts = [...state.parts].sort(([a], [b]) => a - b).filter(([ordinal]) => !this.spoken.has(`${state.messageID} ${ordinal}`))
     state.parts.clear()
     if (!parts.length) return
@@ -1378,6 +1560,7 @@ export class Registry {
 
   /** The session as reported by any process plus its live status; undefined when nobody reports it. */
   session(sessionID: string): SessionView | undefined {
+    if (this.hidden(sessionID)) return undefined
     let info: SessionInfo | undefined
     /** Open from any reporting process; a Herdr pane wins over a TUI. */
     let terminal: TerminalInfo | undefined
@@ -1599,7 +1782,8 @@ export class Registry {
     if (type === "session.text.delta" || type === "session.reasoning.delta") return
     const ended = type === "session.execution.succeeded" ? "succeeded" : type === "session.execution.failed" ? "failed" : type === "session.execution.interrupted" ? "interrupted" : undefined
     const reason = (data.error as { message?: unknown } | undefined)?.message
-    const error = typeof reason === "string" && reason.trim() ? reason : undefined
+    // Pushed: never a credential the error text carries (the recordings' scrubber).
+    const error = typeof reason === "string" && reason.trim() ? redactCredentials(reason).text : undefined
     const errorType = (data.error as { type?: unknown } | undefined)?.type
     // A provider error the user must act on replaces the root's "failed" (raised once per run).
     const providerFailure = ended === "failed" && typeof errorType === "string" && providerFailureNeedsUser(errorType)
@@ -1695,20 +1879,264 @@ export class Registry {
     return this.conversations.has(sessionID)
   }
 
-  /** Records conversation mode for a session; `connID` is the process that was just told. */
-  setConversation(sessionID: string, on: boolean, connID?: string): void {
-    const changed = on !== this.conversations.has(sessionID)
-    if (on) this.conversations.set(sessionID, connID)
-    else {
+  /**
+   * Records conversation mode for a session; `connID` is the process that was just told. `front` (voice front P1):
+   * undefined when no front was asked for (today's mode), else the front session the spoke answered (null: none, it
+   * fell back). Its messages carry `front` once one was asked for.
+   */
+  setConversation(sessionID: string, on: boolean, connID?: string, front?: string | null): void {
+    const was = this.conversations.has(sessionID)
+    const wanted = this.frontWanted.has(sessionID)
+    const had = this.fronts.has(sessionID)
+    this.frontFellBack.delete(sessionID)
+    if (on) {
+      this.conversations.set(sessionID, connID)
+      if (front === undefined) this.frontWanted.delete(sessionID)
+      else this.frontWanted.add(sessionID)
+      if (front && connID !== undefined) this.mapFront(sessionID, front, connID)
+      else this.unmapFront(sessionID)
+    } else {
       this.conversations.delete(sessionID)
+      this.frontWanted.delete(sessionID)
+      this.unmapFront(sessionID)
       for (const [childID, state] of this.workerSpeech) if (state.rootID === sessionID) this.clearWorkerSpeech(childID)
       this.dropRootSpeech(sessionID)
     }
+    const report = front !== undefined || wanted
+    const changed = on !== was || (front !== undefined && !wanted) || (front === undefined && wanted) || had !== this.fronts.has(sessionID)
     if (!changed) return
-    this.emit({ type: "conversation", sessionID, on })
+    this.emit({ type: "conversation", sessionID, on, ...(report ? { front: this.fronts.has(sessionID) } : {}) })
     this.emit({ type: "catalog" })
   }
 
+  /** (voice front P1) The active front of a main session, if any. */
+  frontOf(sessionID: string): string | undefined {
+    return this.fronts.get(sessionID)?.frontID
+  }
+
+  /**
+   * (voice front P1) Where the main session's utterances and interrupts go while its front is active: the front and
+   * its owner process (the one that created it, while no sessions frame lists it yet).
+   */
+  frontRoute(sessionID: string): { sessionID: string; connID: string } | undefined {
+    const front = this.fronts.get(sessionID)
+    if (!front) return undefined
+    const connID = this.linker(front) ?? this.owner(front.frontID)
+    return connID === undefined ? undefined : { sessionID: front.frontID, connID }
+  }
+
+  /** (voice front P1) The connected process that links the front (it relays and wakes it), if it is still here. */
+  private linker(front: Front): string | undefined {
+    return this.conns.has(front.connID) ? front.connID : undefined
+  }
+
+  /** (voice front P1) The front known for a conversation, named in a resend so a restarted spoke re-links it. */
+  resendFrontID(sessionID: string): string | undefined {
+    return this.fronts.get(sessionID)?.frontID
+  }
+
+  /** (voice front P1) The front failed while in use (e.g. a steer into it failed): the session talks directly. */
+  frontLost(mainID: string): void {
+    this.frontFailed(mainID)
+  }
+
+  /** (voice front P1) Listens to what the hub asks spokes to do about fronts (the SpokeHub sends it). */
+  subscribeFrontActions(listener: (action: FrontAction) => void): () => void {
+    this.frontActionListeners.add(listener)
+    return () => this.frontActionListeners.delete(listener)
+  }
+
+  private frontAction(action: FrontAction): void {
+    for (const listener of this.frontActionListeners) {
+      try {
+        listener(action)
+      } catch (cause) {
+        console.error(`[hub] front action failed: ${(cause as Error).message}`)
+      }
+    }
+  }
+
+  /** (voice front P1) Whether any connected process of the main's tenant reports the session. */
+  private frontReported(frontID: string): boolean {
+    return this.all().some((c) => c.sessions.has(frontID))
+  }
+
+  /** (voice front P1) After FRONT_GONE_MS: a mapped front nobody links or reports has failed (front_failed). */
+  private watchFrontGone(mainID: string): void {
+    const front = this.fronts.get(mainID)
+    if (!front) return
+    this.timers.set(() => {
+      if (this.fronts.get(mainID) !== front || this.linker(front) || this.frontReported(front.frontID)) return
+      this.frontFailed(mainID)
+    }, FRONT_GONE_MS)
+  }
+
+  /**
+   * (voice front P1) Voice-front sessions a frame reports that no conversation maps (another process's leftover, or
+   * one from before a restart): after FRONT_STALE_MS still unmapped, its reporter is asked to delete it. A mapped front,
+   * or one naming a main in conversation (its spoke links it), is never touched; user sessions are no fronts.
+   */
+  private noteStaleFronts(conn: Conn): void {
+    for (const s of conn.sessions.values()) {
+      if (!this.unusedFront(s)) continue
+      // A front that failed is never used again: no wait (its process forgot it, e.g. after a restart), also when it
+      // was noted as unmapped before (a new front is reported before its conversation maps it).
+      const failed = this.failedFronts.has(s.id)
+      const due = failed ? this.now() - FRONT_STALE_MS : this.now()
+      const since = this.staleFronts.get(s.id)
+      if (since !== undefined && since <= due) continue
+      this.staleFronts.set(s.id, due)
+      this.timers.set(() => this.sweepStaleFront(s.id), failed ? 0 : FRONT_STALE_MS)
+    }
+  }
+
+  private unusedFront(s: SessionInfo): boolean {
+    return isFrontInfo(s) && !this.frontMain.has(s.id) && !(s.voiceFrontOf !== undefined && this.conversations.has(s.voiceFrontOf))
+  }
+
+  private sweepStaleFront(sessionID: string): void {
+    const since = this.staleFronts.get(sessionID)
+    if (since === undefined) return
+    const reporter = this.all().find((c) => {
+      const s = c.sessions.get(sessionID)
+      return s !== undefined && this.unusedFront(s) && this.supports(c.id, "voiceFront")
+    })
+    if (!reporter) return void this.staleFronts.delete(sessionID)
+    const left = since + FRONT_STALE_MS - this.now()
+    if (left > 0) return void this.timers.set(() => this.sweepStaleFront(sessionID), left)
+    this.staleFronts.delete(sessionID)
+    console.warn(`[hub] asking for a stale voice front to be deleted: ${sessionID}`)
+    this.frontAction({ kind: "remove", connID: reporter.id, sessionID })
+  }
+
+  /** (voice front P1) Whether the session's conversation asked for a voice front. */
+  wantsFront(sessionID: string): boolean {
+    return this.frontWanted.has(sessionID)
+  }
+
+  /** (voice front P1) Whether a conversation resend to `connID` asks for the front again (it must serve "voiceFront"). */
+  resendFront(sessionID: string, connID: string): boolean {
+    return this.frontWanted.has(sessionID) && !this.frontFellBack.has(sessionID) && this.supports(connID, "voiceFront")
+  }
+
+  /**
+   * (voice front P1) A resent conversation op's answer: the front it names (a restarted spoke may name a new one),
+   * or none (an older spoke, or creating it failed): the session talks directly then.
+   */
+  frontAnswer(sessionID: string, connID: string, frontID: unknown): void {
+    if (!this.conversations.has(sessionID) || !this.frontWanted.has(sessionID) || this.frontFellBack.has(sessionID)) return
+    const had = this.fronts.has(sessionID)
+    if (typeof frontID === "string" && frontID) this.mapFront(sessionID, frontID, connID)
+    else this.unmapFront(sessionID)
+    if (had === this.fronts.has(sessionID)) return
+    this.emit({ type: "conversation", sessionID, on: true, front: !had })
+    this.emit({ type: "catalog" })
+  }
+
+  /** Maps main → front, unless the ID is unusable, failed before, or another tenant's session. */
+  private mapFront(mainID: string, frontID: string, connID: string): void {
+    const current = this.fronts.get(mainID)
+    if (current?.frontID === frontID) return void (current.connID = connID)
+    const tenant = this.sessionTenant(frontID)
+    const usable = frontID.length <= FRONT_ID_MAX && frontID !== mainID && !this.failedFronts.has(frontID) && (tenant === undefined || tenant === this.sessionTenant(mainID))
+    const owner = this.frontMain.get(frontID)
+    if (!usable || (owner !== undefined && owner !== mainID)) return this.unmapFront(mainID)
+    this.unmapFront(mainID)
+    const seen = this.all().some((c) => c.sessions.get(frontID)?.voiceFrontOf === mainID)
+    this.fronts.set(mainID, { frontID, connID, seen })
+    this.frontMain.set(frontID, mainID)
+  }
+
+  private unmapFront(mainID: string): void {
+    const front = this.fronts.get(mainID)
+    if (!front) return
+    this.fronts.delete(mainID)
+    if (this.frontMain.get(front.frontID) === mainID) this.frontMain.delete(front.frontID)
+  }
+
+  /**
+   * (voice front P1) A sessions frame: a front it lists for one of its tenant's main sessions (voiceFrontOf) becomes
+   * that session's front when it has none that is still listed (this covers reconnects); a listed front this
+   * process no longer lists is gone (the fallback).
+   */
+  private syncFronts(conn: Conn): void {
+    this.noteStaleFronts(conn)
+    const tenant = this.tenant(conn)
+    for (const s of conn.sessions.values()) {
+      const mainID = s.voiceFrontOf
+      if (typeof mainID !== "string" || mainID === s.id || this.failedFronts.has(s.id)) continue
+      if (!this.conversations.has(mainID) || !this.frontWanted.has(mainID) || this.frontFellBack.has(mainID)) continue
+      if (this.sessionTenant(s.id) !== tenant || this.sessionTenant(mainID) !== tenant) continue
+      const current = this.fronts.get(mainID)
+      if (current?.frontID === s.id) {
+        current.seen = true
+        current.connID = conn.id
+        continue
+      }
+      // A front just created (not listed yet), or one another process still lists, stays.
+      if (current && (!current.seen || this.all().some((c) => c.sessions.has(current.frontID)))) continue
+      const had = current !== undefined
+      this.mapFront(mainID, s.id, conn.id)
+      const mapped = this.fronts.get(mainID)
+      if (mapped) mapped.seen = true
+      if (!had && mapped) {
+        this.emit({ type: "conversation", sessionID: mainID, on: true, front: true })
+        this.emit({ type: "catalog" })
+      }
+    }
+    for (const [mainID, front] of [...this.fronts]) {
+      if (front.seen && front.connID === conn.id && !conn.sessions.has(front.frontID)) this.frontFailed(mainID)
+    }
+  }
+
+  /** (voice front P1) The front failed or is gone while active: the session talks directly (SSE front_failed). */
+  private frontFailed(mainID: string): void {
+    const front = this.fronts.get(mainID)
+    if (!front) return
+    rememberID(this.failedFronts, front.frontID)
+    this.frontFellBack.add(mainID)
+    this.unmapFront(mainID)
+    this.dropRootSpeech(mainID)
+    console.warn(`[hub] voice front of ${mainID} failed: talking to the session directly`)
+    if (!this.conversations.has(mainID)) return
+    this.emit({ type: "conversation", sessionID: mainID, on: true, front: false, reason: "front_failed" })
+    this.emit({ type: "catalog" })
+  }
+
+  /**
+   * (voice front P1) An event of a hidden front: from the process that runs it only (several may forward it), its
+   * text is spoken as main's say, its inbox deliveries are heard for main and its turn is recorded as main's; a
+   * failed or deleted front falls back. Anything else of it (and of an unmapped front) is dropped.
+   */
+  private observeFront(connID: string, tenant: string, frontID: string, type: string, data: Record<string, unknown>): void {
+    const mainID = this.frontMain.get(frontID)
+    const front = mainID === undefined ? undefined : this.fronts.get(mainID)
+    if (mainID === undefined || front?.frontID !== frontID) return
+    // From the linking process only (others forward the same events); a deletion from any of them.
+    if (type !== "session.deleted" && (this.linker(front) ?? this.owner(frontID) ?? front.connID) !== connID) return
+    if (this.recordingTap && TAPPED.has(type)) {
+      try {
+        if (this.recordingTap.wants(tenant, mainID, type)) this.recordingTap.event(tenant, mainID, type, data)
+      } catch (cause) {
+        console.error(`[hub] recording tap failed: ${(cause as Error).message}`)
+      }
+    }
+    switch (type) {
+      case "session.text.delta":
+        return this.speakDelta(connID, mainID, data, true)
+      case "session.text.ended":
+        return this.say(mainID, data, true)
+      case "session.execution.interrupted":
+        return this.dropRootSpeech(mainID)
+      case "session.execution.failed":
+      case "session.deleted":
+        return this.frontFailed(mainID)
+      case "session.inbox.delivered":
+        if (typeof data.inboxID === "string") this.delivered(data.inboxID)
+        return
+    }
+  }
+
   /**
    * Whether a connected process serves a feature (spokeFeatures): a core op (CORE_OPS: turn, steer, interrupt,
    * stop, permission, form), which an OpenCode spoke implies and a spoke of another harness serves only when it