@huynle/hub 0.9.2 → 0.10.0

package/src/central/context-cards/store.ts

@@ -0,0 +1,67 @@
+// Context card storage: StateStore collection `context-cards`, tenant = hub user, key = session ID, one record per
+// session holding the newest card of each provider ({cards: {[provider]: ContextCard}}). One key per session keeps
+// a session's cards one read (the Details rail, the agent API) and its removal one delete (session deleted).
+// Writes are version-checked (updateVersioned), so two providers finishing at once both land.
+import type { ContextCard } from "../../protocol"
+import type { StateStore } from "../backend/types"
+import { updateVersioned } from "../agent/versioned"
+
+export const CONTEXT_CARDS = "context-cards"
+
+interface StoredCards {
+  readonly cards: Readonly<Record<string, ContextCard>>
+}
+
+const cardsOf = (record: StoredCards | undefined): ContextCard[] => Object.values(record?.cards ?? {})
+const newest = (record: StoredCards | undefined) => Math.max(0, ...cardsOf(record).map((c) => c.generatedAt))
+
+export class ContextCardStore {
+  constructor(private readonly deps: { readonly state: StateStore }) {}
+
+  /** Stores (replaces) the card of its provider. */
+  async put(userID: string, card: ContextCard): Promise<void> {
+    await updateVersioned<StoredCards>(this.deps.state, userID, CONTEXT_CARDS, card.sessionID, (current) => ({ cards: { ...current?.cards, [card.provider]: card } }))
+  }
+
+  /** A session's cards, primary first, then by provider id. */
+  async list(userID: string, sessionID: string): Promise<ContextCard[]> {
+    const record = (await this.deps.state.get<StoredCards>(userID, CONTEXT_CARDS, sessionID))?.value
+    return cardsOf(record).sort((a, b) => Number(b.primary === true) - Number(a.primary === true) || a.provider.localeCompare(b.provider))
+  }
+
+  async get(userID: string, sessionID: string, provider: string): Promise<ContextCard | undefined> {
+    return (await this.deps.state.get<StoredCards>(userID, CONTEXT_CARDS, sessionID))?.value?.cards[provider]
+  }
+
+  /** The primary card of each of these sessions that has one (one read each, concurrently). */
+  async primaries(userID: string, sessionIDs: Iterable<string>): Promise<Map<string, ContextCard>> {
+    const ids = [...new Set(sessionIDs)]
+    const records = await Promise.all(ids.map((id) => this.deps.state.get<StoredCards>(userID, CONTEXT_CARDS, id)))
+    const out = new Map<string, ContextCard>()
+    records.forEach((record, i) => {
+      const primary = cardsOf(record?.value).find((c) => c.primary)
+      if (primary) out.set(ids[i]!, primary)
+    })
+    return out
+  }
+
+  /** Drops a session's cards. */
+  async forget(userID: string, sessionID: string): Promise<void> {
+    await this.deps.state.delete(userID, CONTEXT_CARDS, sessionID)
+  }
+
+  /** Drops every card of a user (they turned cards off). */
+  async clear(userID: string): Promise<void> {
+    for (const { key } of await this.deps.state.list<StoredCards>(userID, CONTEXT_CARDS)) await this.deps.state.delete(userID, CONTEXT_CARDS, key)
+  }
+
+  /** Drops the records whose newest card is older than `before`; answers how many. */
+  async prune(userID: string, before: number): Promise<number> {
+    let dropped = 0
+    for (const { key, value, version } of await this.deps.state.list<StoredCards>(userID, CONTEXT_CARDS)) {
+      if (newest(value) >= before) continue
+      if ((await this.deps.state.delete(userID, CONTEXT_CARDS, key, { ifVersion: version })).ok) dropped++
+    }
+    return dropped
+  }
+}

package/src/central/context-cards/types.ts

@@ -0,0 +1,88 @@
+// Context card provider contract (docs/context-cards.md "Writing a provider"). A provider declares what makes it
+// run (triggers), how often at most (minIntervalMs), what it reads (needs) and generate(), which answers a draft
+// card (or undefined: nothing to show / skip). The engine (./engine.ts) gathers the inputs, hashes them, checks
+// the gates (kill switch, setting, human activity, throttle, budget), calls generate() and bounds the result.
+import type { ContextCardField, ContextCardTrigger } from "../../protocol"
+import type { ChatRequest, ChatResult } from "../llm/chat"
+
+/** Inputs a provider may need; the engine fetches only these (a spoke round trip each for transcript and changes). */
+export type InputNeed = "transcript" | "status" | "intent" | "changes"
+
+/** One transcript row, already sanitised and bounded by the gatherer (./inputs.ts). */
+export interface TranscriptRow {
+  readonly kind: "user" | "assistant" | "tool" | "error" | "message"
+  readonly text?: string
+  /** Tool rows: the tool's name. */
+  readonly name?: string
+  /** Tool rows: running | done | failed. */
+  readonly state?: string
+}
+
+export interface ChangesInput {
+  readonly branch?: string
+  readonly files: readonly { readonly file: string; readonly additions: number; readonly deletions: number }[]
+  readonly totalFiles: number
+  readonly additions: number
+  readonly deletions: number
+}
+
+/** What the engine gathered for a run (only the needs a provider declared are present). */
+export interface CardInputs {
+  readonly sessionID: string
+  /** status: the live title (may be a placeholder). */
+  readonly title?: string
+  /** status: idle | working | blocked | error. */
+  readonly state?: string
+  /** status: open blockers' one-line summaries. */
+  readonly blockers?: readonly string[]
+  /** intent: the session's effective intent text. */
+  readonly intent?: string
+  /** transcript: the newest rows, oldest first. */
+  readonly transcript?: readonly TranscriptRow[]
+  readonly changes?: ChangesInput
+}
+
+/** What generate() answers; the engine stamps the rest and bounds every field. */
+export interface CardDraft {
+  /** Default: the provider's label. */
+  readonly title?: string
+  readonly headline: string
+  readonly body?: string
+  readonly fields?: readonly ContextCardField[]
+  /** The model that wrote it. */
+  readonly model?: string
+}
+
+/** The model as a provider sees it: usage is counted against the user's daily budget by the engine. */
+export interface CardChat {
+  readonly model: string
+  complete(request: Omit<ChatRequest, "model">): Promise<ChatResult>
+}
+
+export interface GenerateContext {
+  readonly userID: string
+  readonly sessionID: string
+  readonly trigger: ContextCardTrigger
+  readonly inputs: CardInputs
+  /** Present for providers with usesModel (the engine skips them when no model is configured). */
+  readonly chat?: CardChat
+  readonly now: number
+}
+
+export interface ContextCardProvider {
+  /** Lowercase id, 2–32 characters (`pickup`). */
+  readonly id: string
+  readonly label: string
+  /** Bump when the output changes: cards of an older version are regenerated even with unchanged inputs. */
+  readonly version: number
+  /** The primary card (at most one provider): its headline is the session list's second line. */
+  readonly primary?: boolean
+  /** It calls the model (needs one configured; counts against the daily budget). */
+  readonly usesModel?: boolean
+  /** Automatic triggers it runs on ("manual" refreshes always may). */
+  readonly triggers: readonly ContextCardTrigger[]
+  /** At most one automatic run per session this often (later triggers run once the interval is over). */
+  readonly minIntervalMs: number
+  readonly needs: readonly InputNeed[]
+  generate(context: GenerateContext): Promise<CardDraft | undefined>
+}

package/src/central/fetcher.ts

@@ -139,13 +139,21 @@ export function isDeniedAddress(address: string, extra: readonly Cidr[] = []): b
   return false
 }
 
+/** Whether `address` (a plain IPv4/IPv6 address, IPv4-mapped IPv6 read as IPv4) lies in one of `blocks`. */
+export function inCidrs(address: string, blocks: readonly Cidr[]): boolean {
+  const raw = address.trim().replace(/^\[(.*)\]$/, "$1")
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(raw)
+  const ip = parseIP(mapped ? mapped[1]! : raw)
+  return ip !== undefined && blocks.some((block) => contains(block, ip))
+}
+
 /** HUB_FETCH_DENY_CIDRS: a comma list of CIDRs or bare addresses (v4 or v6). Throws on any invalid entry. */
-export function parseDenyCidrs(text: string | undefined): Cidr[] {
+export function parseDenyCidrs(text: string | undefined, setting = "HUB_FETCH_DENY_CIDRS"): Cidr[] {
   const out: Cidr[] = []
   for (const raw of (text ?? "").split(",")) {
     const entry = raw.trim()
     if (!entry) continue
-    const invalid = () => new Error(`HUB_FETCH_DENY_CIDRS: ${JSON.stringify(entry)} is not an IPv4 or IPv6 CIDR (e.g. 10.42.0.0/16, fd00::/8)`)
+    const invalid = () => new Error(`${setting}: ${JSON.stringify(entry)} is not an IPv4 or IPv6 CIDR (e.g. 10.42.0.0/16, fd00::/8)`)
     const match = /^([^/\s]+)(?:\/(\d{1,3}))?$/.exec(entry)
     if (!match) throw invalid()
     const ip = parseIP(match[1]!)

package/src/central/front-relays.ts

@@ -0,0 +1,423 @@
+// (voice front P2, contract "P2: Concierge mode", decision el64mka7) The hub's side of a Concierge front's
+// relay_to_session, as the Registry uses it:
+// - Utterance bindings. Each utterance the hub steers into a front is recorded (inbox ID, device, time), and the
+//   front's latest delivered input (session.inbox.delivered from its linking process: the user's utterances and the
+//   spoke's wakes alike). A relay is allowed only while that latest input is a recorded utterance, at most
+//   RELAY_WINDOW_MS old, with fewer than RELAYS_PER_UTTERANCE relays made for it. A wake (or anything else) delivered
+//   after the utterance ends its relays: a front never relays on its own initiative.
+// - Relayed sessions. A session the front relayed to is tracked for RELAY_TRACK_MS after the latest relay: its root's
+//   turn ends become updates for the front (frontUpdate), with only text written after the relay (no stale news). While
+//   a steered relay is not delivered yet, a turn end is held and folded into the next one (a held "finished" report is
+//   superseded; failures and interruptions kept), capped at RELAY_HOLD_MS: one report per job, as the session-mode
+//   front's fix C.
+import type { Timers } from "./backend/types"
+import { redactCredentials } from "../../packages/protocol/src/credentials.ts"
+
+export const RELAYS_PER_UTTERANCE = 2
+export const RELAY_WINDOW_MS = 120_000
+export const RELAY_TRACK_MS = 30 * 60_000
+export const RELAY_HOLD_MS = 60_000
+/** The audit reason of a relayed prompt (the user's own, through the Concierge front). */
+export const RELAY_REASON = "Relayed by voice from you (Concierge front)"
+/** (guard tuning) The audit reason of a relay the front confirmed after the hub's soft question refusal. */
+export const RELAY_REASON_CONFIRMED = "Relayed by voice from you (Concierge front), confirmed after a question check"
+/** A relayed session's final text in an update, at most. */
+const TEXT_MAX = 1500
+/** Utterances remembered per front. */
+const UTTERANCES_KEPT = 10
+const FRONTS_KEPT = 1000
+const TARGETS_KEPT = 1000
+
+export class RelayRefused extends Error {
+  /** The device of the utterance the refused relay answered, when known (for the audit). */
+  constructor(
+    message: string,
+    readonly deviceID?: string,
+  ) {
+    super(message)
+  }
+}
+
+/** (hardening) The plain marker every relayed message starts with. */
+export const RELAY_MARKER = "(by voice, via the Concierge, for you)"
+
+/** (hands-on 2026-11-09) What the front reads when the hub refuses a status question as a relay. */
+export const STATUS_QUESTION_REFUSAL =
+  "That's a question about the session, not a request for it: answer the user from the board in a sentence or two, or pass it to the Concierge with voice_main_send. Nothing was sent"
+/**
+ * (guard tuning) The refusal of a question that also has a work verb ("did hub run the tests?" may be "have hub run
+ * the tests"): the front may retry once with confirm.
+ */
+export const STATUS_QUESTION_SOFT_REFUSAL = `${STATUS_QUESTION_REFUSAL}. If the user did ask for work to be done there, you may retry ONCE with confirm: true, after saying aloud exactly what you will send, for example "Sending 'update the changelog' to docs."`
+
+/** Verbs that ask for work (imperatives, and the verb after a modal or "should"); "check" is special (check on = status). */
+const WORK_VERBS: ReadonlySet<string> = new Set(
+  ("tell ask have make get let send run rerun fix create add update review commit merge push pull squash rebase release deploy " +
+    "restart start stop retry rename delete remove refactor implement install bump prepare draft edit move write lint summarize " +
+    "summarise investigate debug keep continue open close undo revert build test scale clean sync generate document look check " +
+    "finish change reply answer post publish upload download copy split format rewrite optimize optimise migrate pin unpin tag").split(" "),
+)
+/** After "can/could you" (or "we"): verbs that ask the assistant for information, not work in a session. */
+const INFO_VERBS: ReadonlySet<string> = new Set(["check", "see", "find", "tell", "let", "show", "give", "remind", "look", "hear", "say", "know", "confirm"])
+/** Words that open a question about a session. */
+const QUESTION_START = /^(?:did|has|is|are|was|were|does|do|what|where|when|why|who|whose|which|how|any)\b/
+const LEADING_FILLER = /^(?:ok(?:ay)?|so|hey|hi|uh|um|er|erm|please|and|alright|right|well|also|now|then|oh|yeah|yes|concierge)\b[\s,.!]*/
+/** Status phrases anywhere (a question about a session, if no request was found first). */
+const STATUS_PHRASE = /\b(?:check(?:ing)?\s+(?:in\s+)?(?:up\s+)?on|how(?:'s|\s+is|\s+are)|status|any\s+(?:news|update)|news\s+from|hear(?:d)?\s+from|what\s+happened|where\s+is\b.*\bat\b|is\b.*\b(?:done|finished|waiting|stuck|ready)|working\s+on|doing|up\s+to)\b/
+/** A delegation inside a question ("how about you tell hub to run the tests"). */
+const DELEGATION = /\b(?:tell|ask)\s+(?!me\b|us\b|you\b)[^?]*?\bto\b|\b(?:have|get|make)\s+(?!you\b|we\b|me\b|us\b|i\b|it\b|the\b|any\b)\w+(?:\s+\w+){0,2}\s+(?:to\s+)?\w+/
+
+const normalise = (words: string) =>
+  words
+    .normalize("NFKC")
+    .replace(/\p{Cf}/gu, "")
+    .replace(/[\u2018\u2019]/g, "'")
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .trim()
+
+const stripFillers = (text: string) => {
+  let t = text
+  for (let i = 0; i < 6; i++) {
+    const next = t.replace(LEADING_FILLER, "")
+    if (next === t) break
+    t = next
+  }
+  return t
+}
+
+const firstWord = (text: string) => /^[a-z']+/.exec(text)?.[0] ?? ""
+
+/** A request at the start of `text`: an imperative, a modal request, "<subject> should …", "keep …". */
+function requestAt(text: string): boolean {
+  const t = stripFillers(text)
+  const w = firstWord(t)
+  // "check on X", "check in on X": status; any other "check …" (check in X whether…, check the logs) is work.
+  if (w === "check") return !/^check(?:ing)?\s+(?:in\s+)?(?:up\s+)?on\b/.test(t)
+  // "have you / have the tests …" is a question; "have hub fix …" a request.
+  if (w === "have") return !/^have\s+(?:you|we|i|they|the|it|any)\b/.test(t)
+  if (w === "tell" || w === "ask") return !/^(?:tell|ask)\s+(?:me|us)\b/.test(t)
+  if (WORK_VERBS.has(w)) return true
+  // Modal requests: "can hub merge …", "could billing lead review …", "can you get hub to …", "can we squash …".
+  const modal = /^(?:can|could|would|will|should)\s+(.*)$/.exec(t)
+  if (modal) {
+    const rest = modal[1]!
+    const self = /^(?:you|we|u)\s+(?:please\s+)?([a-z']+)/.exec(rest)
+    if (self) return !INFO_VERBS.has(self[1]!) || /^(?:you|we|u)\s+(?:please\s+)?(?:tell|ask)\s+(?!me\b|us\b)/.test(rest)
+    // Another subject: a request unless it only asks about a state ("will hub be done").
+    return !/^(?:i|it|they|there)\b/.test(rest) && !/\bbe\s+(?:done|finished|ready|waiting|stuck)\b/.test(rest)
+  }
+  // "<subject> should|needs to|must|has to <verb>" (not "be"): "billing lead should add a currency field".
+  if (/^[a-z' ]{1,40}?\b(?:should|needs?\s+to|must|has\s+to|ought\s+to)\s+(?!be\b)[a-z]/.test(t)) return true
+  return false
+}
+
+/**
+ * (guard tuning, verify round 7) Whether what the user said is a request FOR a session (relay it) or a question ABOUT
+ * one (refuse it: the front answers from the board or asks the Concierge). Deterministic and cheap; it works on the
+ * user's own words (normalised: NFKC, no format characters, lower case), with or without a "?". In order:
+ * 1. A question start (did/has/is/are/was/does/do, what/where/when/why/who/which/how, any) is a question, unless a
+ *    delegation follows ("how about you tell hub to …"). "have" is a question only before you/we/the/it/any.
+ * 2. A request: an imperative or a modal request at the start, also after fillers ("ok so"), a vocative ("hub, merge
+ *    …") or an "in X," / "in X …" prefix ("in hub can we squash …"); a modal ("can/could/would/will/should") with any
+ *    subject and any verb; "can/could you (get/have/make/tell/ask) …" and any work verb after "you/we"; "<subject>
+ *    should|needs to|must … <verb>"; "keep working on".
+ * 3. Otherwise a status phrase (check on, check in on, how's, status, any news, what happened, where is … at, is …
+ *    done/waiting/stuck, working on, doing) or a final "?" makes it a question; anything else is a request.
+ * `workVerb`: a work verb appears (such a question may be a request after all: the soft refusal allows a confirm).
+ */
+export function classifyRelay(words: string): { readonly kind: "request" | "question"; readonly workVerb: boolean } {
+  const text = stripFillers(normalise(words))
+  // Not a work verb: "tell me", "ask us", "have you/the …" (an auxiliary), "check" (check on is status).
+  const notWork = (w: string, next: string) => w === "check" || ((w === "tell" || w === "ask") && /^(?:me|us)$/.test(next)) || (w === "have" && /^(?:you|we|i|they|the|it|any)$/.test(next))
+  const workVerb = (text.match(/[a-z']+/g) ?? []).some((w, i, all) => WORK_VERBS.has(w) && !notWork(w, all[i + 1] ?? ""))
+  const question = (kind: "request" | "question") => ({ kind, workVerb })
+  // A negative imperative ("do not delete …", "don't push …", "never force push …") is a request, never a "do …?".
+  if (/^(?:do\s+not|don't|dont|never)\s+[a-z]/.test(text)) return question("request")
+  if (QUESTION_START.test(text) || /^have\s+(?:you|we|i|they|the|it|any)\b/.test(text)) {
+    return question(DELEGATION.test(text.replace(QUESTION_START, "")) ? "request" : "question")
+  }
+  const clauses = [text]
+  // A vocative or an "in X," prefix: the request follows the first comma.
+  const comma = text.indexOf(",")
+  if (comma > 0 && text.slice(0, comma).split(" ").length <= 5) clauses.push(text.slice(comma + 1).trim())
+  // "in hub can we squash …": the request after the place.
+  const place = /^in\s+(.+)$/.exec(text)
+  if (place) {
+    const words = place[1]!.split(" ")
+    for (let i = 1; i < Math.min(words.length, 6); i++) clauses.push(words.slice(i).join(" "))
+  }
+  if (clauses.some((c) => requestAt(c) && !QUESTION_START.test(stripFillers(c)))) return question("request")
+  return question(STATUS_PHRASE.test(text) || /[?？]\s*$/.test(text) ? "question" : "request")
+}
+
+/**
+ * (hands-on 2026-11-09, tuned after verify round 7) The refusal for a relay of a question about a session, else
+ * undefined: STATUS_QUESTION_REFUSAL, or STATUS_QUESTION_SOFT_REFUSAL when the question also has a work verb (the
+ * front may retry once with confirm after saying aloud what it sends).
+ */
+export function relayQuestionProblem(words: string): string | undefined {
+  const { kind, workVerb } = classifyRelay(words)
+  if (kind === "request") return undefined
+  return workVerb ? STATUS_QUESTION_SOFT_REFUSAL : STATUS_QUESTION_REFUSAL
+}
+
+/**
+ * A line that starts (after spaces, zero-width or other format characters, in any Unicode compatibility form such as
+ * fullwidth "［hub］") with "[hub]" gets "(hub)" instead: relayed text never poses as a hub envelope. Such a line is
+ * kept in its NFKC form, without format characters; every other line is unchanged.
+ */
+const neutralize = (text: string) =>
+  text
+    .split("\n")
+    .map((line) => {
+      const plain = line.normalize("NFKC").replace(/\p{Cf}/gu, "")
+      const m = /^(\s*)\[hub\]/i.exec(plain)
+      return m ? `${m[1]}(hub)${plain.slice(m[0].length)}` : line
+    })
+    .join("\n")
+
+/**
+ * (hardening, verify rounds 4 and 5) The message a relay delivers, built by the HUB from the user's own words only
+ * (the utterance the relay answers; for a redirect, the same device's earlier one first, then "Then: …"). The front's
+ * text is never delivered, not even as a summary: board text that steers the front cannot put words into another
+ * session, and the front cannot restate (or invert) the request. The message starts with RELAY_MARKER.
+ */
+export function relayMessage(input: { readonly words: string; readonly previous?: string }): { readonly message: string } {
+  const words = neutralize(input.words.trim())
+  const previous = input.previous?.trim() ? neutralize(input.previous.trim()) : undefined
+  return { message: `${RELAY_MARKER} ${previous ? `${previous}\nThen: ${words}` : words}` }
+}
+
+interface Utterance {
+  readonly at: number
+  readonly deviceID?: string
+  /** What the user said (the hub's own record: the relay delivers these words). */
+  readonly text: string
+  relays: number
+  /** (guard tuning) The session a soft question refusal named: one confirmed retry to it is allowed. */
+  softTarget?: string
+}
+
+interface Update {
+  readonly text: string
+  readonly finished?: boolean
+}
+
+interface Target {
+  readonly mainID: string
+  readonly title: string
+  at: number
+  /** Steered relays not delivered yet: inbox ID → when relayed. */
+  readonly inflight: Map<string, number>
+  /** Root text written since the latest relay (or the turn's start after it). */
+  text?: string
+  deferred: Update[]
+  hold?: unknown
+}
+
+export interface RelayUpdate {
+  readonly mainID: string
+  readonly text: string
+  readonly finished?: boolean
+}
+
+export interface FrontRelaysDeps {
+  readonly now: () => number
+  readonly timers: Timers
+  /** Sends an update to the front of `mainID` (frontUpdate through its linking process). */
+  readonly send: (update: RelayUpdate) => void
+}
+
+const trim = (text: string) => {
+  const t = text.replace(/\s+/g, " ").trim()
+  return t.length > TEXT_MAX ? `${t.slice(0, TEXT_MAX - 1)}…` : t
+}
+
+function bound<K, V>(map: Map<K, V>, limit: number): void {
+  while (map.size > limit) map.delete(map.keys().next().value!)
+}
+
+export class FrontRelays {
+  /** Front → its recent utterances by inbox ID. */
+  private readonly utterances = new Map<string, Map<string, Utterance>>()
+  /** Front → the inbox ID of the latest input delivered to it. */
+  private readonly latest = new Map<string, string>()
+  private readonly targets = new Map<string, Target>()
+  /** Inbox items delivered lately (a delivery can be seen before the relay that made it is recorded). */
+  private readonly deliveredIDs = new Map<string, true>()
+
+  constructor(private readonly deps: FrontRelaysDeps) {}
+
+  /** The hub steered an utterance of the user's (from `deviceID`) into `frontID`. */
+  utterance(frontID: string, inboxID: string, deviceID?: string, text = ""): void {
+    const list = this.utterances.get(frontID) ?? new Map<string, Utterance>()
+    list.set(inboxID, { at: this.deps.now(), ...(deviceID ? { deviceID } : {}), text, relays: 0 })
+    bound(list, UTTERANCES_KEPT)
+    this.utterances.delete(frontID)
+    this.utterances.set(frontID, list)
+    bound(this.utterances, FRONTS_KEPT)
+  }
+
+  /** An inbox item was delivered to `frontID` (its latest input now). */
+  frontDelivered(frontID: string, inboxID: string): void {
+    this.latest.delete(frontID)
+    this.latest.set(frontID, inboxID)
+    bound(this.latest, FRONTS_KEPT)
+  }
+
+  /**
+   * Takes one relay of the utterance the front is answering; RelayRefused when its latest input is no utterance of
+   * the user's, the utterance is too old, or it made RELAYS_PER_UTTERANCE relays already. `release` gives it back
+   * (the relay was refused for its target). `words`: what the user said; `previous`: the utterance before it (within
+   * the window, from the same device), for a redirect ("no, the other one").
+   */
+  take(frontID: string): {
+    readonly deviceID?: string
+    readonly words: string
+    readonly previous?: string
+    /** The session the hub's soft question refusal of this utterance named, if any (one confirmed retry). */
+    readonly softTarget?: string
+    /** A soft question refusal for `targetID`: one retry with confirm may follow, for this utterance only. */
+    markSoft(targetID: string): void
+    /** The confirmed retry is used (once). */
+    useConfirm(): void
+    release(): void
+  } {
+    const inboxID = this.latest.get(frontID)
+    const list = this.utterances.get(frontID)
+    const utterance = inboxID === undefined ? undefined : list?.get(inboxID)
+    if (!utterance) throw new RelayRefused("relay_to_session is only for what the user just said: the front's latest input is not the user's speech")
+    if (this.deps.now() - utterance.at > RELAY_WINDOW_MS) throw new RelayRefused("The user's request is too old to relay; ask them again", utterance.deviceID)
+    if (utterance.relays >= RELAYS_PER_UTTERANCE) throw new RelayRefused(`No more relays for this request: at most ${RELAYS_PER_UTTERANCE} per thing the user says`, utterance.deviceID)
+    utterance.relays++
+    const order = [...list!.entries()]
+    const before = order[order.findIndex(([id]) => id === inboxID) - 1]?.[1]
+    // (round 5) Only the same device's earlier words: another device in the conversation may be another speaker.
+    const sameDevice = before?.deviceID !== undefined && before.deviceID === utterance.deviceID
+    const previous = before && sameDevice && this.deps.now() - before.at <= RELAY_WINDOW_MS && before.text ? before.text : undefined
+    let released = false
+    return {
+      ...(utterance.deviceID ? { deviceID: utterance.deviceID } : {}),
+      words: utterance.text,
+      previous,
+      ...(utterance.softTarget !== undefined ? { softTarget: utterance.softTarget } : {}),
+      markSoft: (targetID) => void (utterance.softTarget = targetID),
+      useConfirm: () => void (utterance.softTarget = undefined),
+      release: () => {
+        if (!released) utterance.relays--
+        released = true
+      },
+    }
+  }
+
+  /** A relay reached `targetID` (a root session): its results go to the front of `mainID` from now on. */
+  relayed(mainID: string, targetID: string, title: string, inboxID?: string): void {
+    const now = this.deps.now()
+    const known = this.targets.get(targetID)
+    const target: Target = known && known.mainID === mainID ? known : { mainID, title, at: now, inflight: new Map(), deferred: [] }
+    if (known && known !== target) this.drop(targetID)
+    target.at = now
+    target.text = undefined
+    if (inboxID !== undefined && !this.deliveredIDs.has(inboxID)) target.inflight.set(inboxID, now)
+    this.targets.delete(targetID)
+    this.targets.set(targetID, target)
+    bound(this.targets, TARGETS_KEPT)
+  }
+
+  /** The front of `mainID` is gone (off, failed, replaced): its relayed sessions are no longer tracked. */
+  forget(mainID: string, frontID?: string): void {
+    for (const [id, target] of [...this.targets]) if (target.mainID === mainID) this.drop(id)
+    if (frontID !== undefined) {
+      this.utterances.delete(frontID)
+      this.latest.delete(frontID)
+    }
+  }
+
+  /** The tracked target a session belongs to (its root), if still tracked; the title it is announced with. */
+  target(rootID: string): { readonly mainID: string; readonly title: string } | undefined {
+    const target = this.targets.get(rootID)
+    if (!target) return undefined
+    if (this.deps.now() - target.at > RELAY_TRACK_MS) {
+      this.drop(rootID)
+      return undefined
+    }
+    return target
+  }
+
+  /** An event of a tracked target's ROOT session (from its owning process). */
+  observe(rootID: string, type: string, data: Record<string, unknown>): void {
+    if (type === "session.inbox.delivered" && typeof data.inboxID === "string") {
+      this.deliveredIDs.set(data.inboxID, true)
+      bound(this.deliveredIDs, 500)
+    }
+    if (!this.target(rootID)) return
+    const target = this.targets.get(rootID)!
+    switch (type) {
+      case "session.execution.started":
+        target.text = undefined
+        return
+      case "session.text.ended":
+        if (typeof data.text === "string" && data.text.trim()) target.text = trim(data.text)
+        return
+      case "session.inbox.delivered":
+        if (typeof data.inboxID === "string") target.inflight.delete(data.inboxID)
+        return
+      case "session.execution.succeeded":
+      case "session.execution.failed":
+      case "session.execution.interrupted": {
+        const reply = target.text ? ` Its final reply: ${target.text}` : ""
+        target.text = undefined
+        if (type === "session.execution.succeeded") return this.ended(rootID, target, { text: `${target.title} finished its turn.${reply}`, finished: true })
+        if (type === "session.execution.interrupted") return this.ended(rootID, target, { text: `${target.title}'s turn was interrupted.${reply}` })
+        const message = (data.error as { message?: unknown } | undefined)?.message
+        const reason = trim(redactCredentials(typeof message === "string" && message.trim() ? message : "unknown error").text).replace(/[.!]+$/, "")
+        return this.ended(rootID, target, { text: `${target.title}'s turn failed (already announced to the user; don't say it failed again): ${reason}.${reply}` })
+      }
+    }
+  }
+
+  stop(): void {
+    for (const target of this.targets.values()) if (target.hold !== undefined) this.deps.timers.clear(target.hold)
+  }
+
+  private drop(targetID: string): void {
+    const target = this.targets.get(targetID)
+    if (target?.hold !== undefined) this.deps.timers.clear(target.hold)
+    this.targets.delete(targetID)
+  }
+
+  /** Relays older than the hold cap count as delivered (a lost event never holds later reports). */
+  private prune(target: Target): void {
+    const cutoff = this.deps.now() - RELAY_HOLD_MS
+    for (const [id, at] of target.inflight) if (at <= cutoff) target.inflight.delete(id)
+  }
+
+  private ended(rootID: string, target: Target, update: Update): void {
+    this.prune(target)
+    if (target.inflight.size) {
+      target.deferred = [...target.deferred.filter((u) => !u.finished || !update.finished), update]
+      target.hold ??= this.deps.timers.set(() => {
+        target.hold = undefined
+        if (this.targets.get(rootID) !== target) return
+        this.prune(target)
+        const held = target.deferred.splice(0)
+        if (target.inflight.size) held.push({ text: `A later request you relayed to ${target.title} is still running or waiting; its result comes in a later update.` })
+        for (const u of held) this.send(target, u)
+      }, RELAY_HOLD_MS)
+      return
+    }
+    if (target.hold !== undefined) this.deps.timers.clear(target.hold)
+    target.hold = undefined
+    const held = target.deferred.splice(0).filter((u) => !u.finished || !update.finished)
+    for (const u of [...held, update]) this.send(target, u)
+  }
+
+  private send(target: Target, update: Update): void {
+    try {
+      this.deps.send({ mainID: target.mainID, text: update.text, ...(update.finished ? { finished: true } : {}) })
+    } catch (cause) {
+      console.error(`[hub] front update failed: ${(cause as Error).message}`)
+    }
+  }
+}