@huynle/hub 0.6.0 → 0.7.1

package/src/central/http.ts

@@ -1,26 +1,66 @@
 // Hub: HTTP routes (web UI, JSON API, SSE, enrollment) and the spoke WebSocket.
-// Phones authenticate with the `voice_device` cookie; spokes with machine bearer tokens. Source IPs
+// Phones authenticate with the `voice_device` cookie (or, in native apps, the same secret as a bearer device
+// token; see ./agent/actor.ts); spokes with machine bearer tokens. Source IPs
 // (including loopback) are never trusted.
 import type { Server } from "bun"
 import { diskAssets, type WebAssets } from "./assets"
 import path from "node:path"
-import { formAnswerProblem, PROMPT_IMAGE_MIMES, promptImagesProblem, type AvailableModel, type EnrollStart, type FormAnswer, type ModelSelection, type PermissionDecision, type PromptImage, type TurnResult } from "../protocol"
+import { promisify } from "node:util"
+import { brotliCompress, constants as zlib, gzip } from "node:zlib"
+import { formAnswerProblem, PROMPT_IMAGE_MIMES, promptImagesProblem, type AvailableModel, type CoreOp, type EnrollStart, type FormAnswer, type ModelSelection, type PermissionDecision, type PromptImage } from "../protocol"
 import { isLoopbackAddress, isLoopbackHost, isLoopbackURL, loopbackOrigins } from "../loopback"
 import { speakable } from "../speakable"
 import { Auth, RateLimitError, ValidationError } from "./auth"
 import { emailAllowed, type CentralConfig } from "./config"
 import { authPage, cookieValue, deviceName, OIDC_COOKIE, OidcClient, OidcError } from "./oidc"
-import { Push, type PushSender } from "./push"
+import { isNotificationKind, Push, type PushSender } from "./push"
 import { pushEndpointProblem, resolveHost as systemResolveHost, type ResolveHost } from "./push-target"
-import { BusyError, Registry } from "./registry"
+import { Webhooks } from "./agent/webhooks"
+import { WEBHOOK_SCOPE } from "./agent/webhook-routes"
+import { hubBackends, type Backends } from "./backend"
+import { createResolver, type AgentActor, type BearerVerifier, type CredentialMode } from "./agent/actor"
+import { ActingSwitch } from "./agent/acting-switch"
+import { AgentAudit } from "./agent/audit"
+import { Grants } from "./agent/grants"
+import { Decisions, type Decision } from "./agent/decisions"
+import type { Escalate } from "./agent/acting"
+import { Escalations } from "./agent/escalation"
+import { GrantRequests } from "./agent/grant-requests"
+import { partyFromActor } from "./agent/envelope"
+import { Delivery } from "./agent/delivery"
+import { AgentError, type AgentErrorCode } from "./agent/errors"
+import type { Launch } from "./agent/launch-store"
+import { decisionStateQuery, MessageFeed } from "./agent/message-routes"
+import { hubDirectory } from "./agent/directory-routes"
+import { agentApi, agentRoutes, agentVerifiers, isAgentPath, wellKnown, type AgentRoute } from "./agent/routes"
+import { SessionTokens } from "./agent/session-tokens"
+import { SessionTokenPush } from "./session-token-push"
+import { TokenKeys } from "./token-keys"
+import { EventLog } from "./events-log"
+import { BusyError, Registry, type RegistryMessage } from "./registry"
+import { createActions, type Unsupported, unsupportedMessage } from "./actions"
 import { audioFormat, SpeechError } from "./speech/provider"
 import { SpeechService } from "./speech/service"
-import { RequestTimeoutError, RequestTooLargeError, SpokeError, SpokeHub, type Notifier, type SpokeSocketData } from "./spoke-ws"
-import { LOCAL_USER, PUSH_PREF_KEYS, quietHoursInput, Store, VIEW_PREF_KEYS, type DeviceRecord, type LegacyPushPrefs, type PushPrefs, type UserRecord, type ViewPrefs } from "./store"
+import { NodeRegistry } from "./nodes"
+import { ConnDirectory } from "./cluster/directory"
+import { PodRpc } from "./cluster/rpc"
+import { ClusterView } from "./cluster/view"
+import { LeaderLoop, NoLeaderError } from "./cluster/leader"
+import { ClusterRecommendations } from "./cluster/recommend"
+import { LiveFanout, type LiveEvent } from "./cluster/live"
+import { randomBytes, randomUUID } from "node:crypto"
+import { LaunchEngine } from "./agent/launch-engine"
+import { LaunchTokens } from "./agent/launch-tokens"
+import { LaunchFeed, launchInfo } from "./agent/launch-routes"
+import type { WatchRegistry } from "./agent/watch"
+import { DRAIN_RETRY_AFTER_MS, DRAIN_TIMEOUT_MS, RequestTimeoutError, RequestTooLargeError, SpokeError, SpokeHub, type DrainOptions, type Notifier, type SpokeHubOptions, type SpokeSocketData } from "./spoke-ws"
+import { ACTIVITY_INTERVAL_MAX, ACTIVITY_INTERVAL_MIN, LOCAL_USER, PUSH_PREF_KEYS, quietHoursInput, Store, VIEW_PREF_KEYS, type DeviceRecord, type LegacyPushPrefs, type PushPrefs, type UserRecord, type ViewPrefs } from "./store"
 
 export interface Speech {
   transcribe(audio: Uint8Array, format: string): Promise<string>
   speak(text: string): Promise<Uint8Array<ArrayBuffer>>
+  /** Streams the audio as it is synthesized (the built-in providers do; an override may only buffer). */
+  speakStream?(text: string, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>
 }
 
 export interface CentralOptions {
@@ -37,16 +77,36 @@ export interface CentralOptions {
   readonly notifier?: Notifier
   /** Overrides web-push delivery (tests; web-push itself needs https push services). */
   readonly pushSender?: PushSender
-  /** Resolves push endpoint hosts at subscribe time (SSRF check); the system resolver by default. */
+  /** Resolves push endpoint and webhook hosts (SSRF checks); the system resolver by default. */
   readonly resolveHost?: ResolveHost
-  /** Clock for sign-in expiry and the store (tests). */
+  /** Clock for sign-in expiry, the store, the registry and the backends (tests). */
   readonly now?: () => number
+  /** Shared state for new code (default: in memory, see ./backend). */
+  readonly backends?: Backends
+  /** More bearer verifiers and /api/agent routes, after the built-in ones (tests). */
+  readonly agent?: { readonly verifiers?: readonly BearerVerifier[]; readonly routes?: readonly AgentRoute[] }
   readonly timing?: {
     readonly helloTimeoutMs?: number
     readonly requestTimeoutMs?: number
     readonly turnGraceMs?: number
+    /** `Prefer: respond-async` turns: how long the hub waits for a quick result before answering 202. */
+    readonly turnAcceptMs?: number
     readonly heartbeatMs?: number
     readonly staleMs?: number
+    /** Per node op request timeouts (see NODE_TIMEOUTS_MS). */
+    readonly nodeTimeoutsMs?: SpokeHubOptions["nodeTimeoutsMs"]
+    /** Cluster mode: how often each pod re-checks its sockets' machines and owners (see RECHECK_MS). */
+    readonly recheckMs?: number
+    /** Cluster mode: the cluster view's heartbeat and slice TTL (see VIEW_HEARTBEAT_MS, VIEW_TTL_MS). */
+    readonly viewHeartbeatMs?: number
+    readonly viewTtlMs?: number
+    /** Leader leases of the timed jobs (see LEADER_TTL_MS). */
+    readonly leaderTtlMs?: number
+    /** How often the decision deadline and message re-wake loops run (see DECISION_TICK_MS, REWAKE_TICK_MS). */
+    readonly loopTickMs?: number
+    /** drain(): how long it waits for requests in flight, and the bye's retryAfterMs (see DRAIN_TIMEOUT_MS, DRAIN_RETRY_AFTER_MS). */
+    readonly drainTimeoutMs?: number
+    readonly drainRetryAfterMs?: number
   }
 }
 
@@ -56,11 +116,36 @@ export interface Central {
   readonly store: Store
   readonly auth: Auth
   readonly registry: Registry
+  /** Connected `hub node` daemons (never in the registry). */
+  readonly nodes: NodeRegistry
   readonly spokes: SpokeHub
   readonly push: Push
   readonly speechSettings: SpeechService
+  /** Backends for new code (state, bus, event log, counters, locks, catalog, kv). */
+  readonly backends: Backends
+  /** Agent messages: store and delivery to sessions (the message routes use it). */
+  readonly delivery: Delivery
+  /** Decisions (ask @me): answered by the user on /api/decisions. */
+  readonly decisions: Decisions
+  /** Kill switches (per user and hub-wide) and hub.json agents.never, for the acting verbs. */
+  readonly acting: ActingSwitch
+  /** Launches (design §6): accept, list, stop; placement onto nodes and each launch's run to its end. */
+  readonly launches: LaunchEngine
+  /** Every launch change, per user (SSE 'launch' events and the agent watch subscribe; webhooks hang off it). */
+  readonly launchFeed: LaunchFeed
+  /** Launch-bound (hlt1) tokens: what a sandboxed harness connects back to /spoke/ws with (phase 5). */
+  readonly launchTokens: LaunchTokens
+  /** Webhooks (P4-T10): registrations and the outbox sender; launch changes are published to it. */
+  readonly webhooks: Webhooks
   /** The JSON API's route table (method, path, access), for audits and tests. */
   readonly routes: readonly RouteInfo[]
+  /**
+   * Draining before a shutdown (design §10; SIGTERM): /readyz fails, new /spoke/ws upgrades are refused, spokes and
+   * nodes get bye{reason:"draining", retryAfterMs} (once their requests in flight are answered), the leader leases
+   * are released, cluster view slices withdrawn, SSE streams end with a `retry:` hint, and it resolves when requests
+   * in flight are done (at most timeoutMs; the rest fail as offline). Call stop() after it. Repeated calls share one.
+   */
+  drain(options?: DrainOptions): Promise<void>
   stop(): Promise<void>
 }
 
@@ -69,12 +154,25 @@ type Message = { type: string; [key: string]: unknown }
 interface Listener {
   readonly userID: string
   readonly deviceID: string
-  send(message: Message): void
+  /** Leaves out streamed text and reasoning (except of `session`'s tree). */
+  readonly lite: boolean
+  /** The session the page shows: its tree's text and reasoning stream even when lite. */
+  readonly session?: string
+  /** Sends a message; `id` is its event id (EventSource's lastEventId). */
+  send(message: Message, id?: string): void
   close(): void
+  /** Draining: tells the browser to reconnect after retryMs (`retry:`), then ends the stream. */
+  end(retryMs: number): void
 }
 
-/** Who may call a route: anyone, any signed-in user, admins, or the owner of the :session / :machine in the path. */
-export type Access = "public" | "user" | "admin" | "session" | "machine"
+/** Messages a lite stream leaves out (unless they are of the listener's session tree). */
+const STREAMED = new Set(["delta", "reasoning"])
+
+/**
+ * Who may call a route: anyone, any signed-in user, admins, or the owner of the :session / :machine in the path;
+ * "agent": an /api/agent route (src/central/agent), checked per credential kind there.
+ */
+export type Access = "public" | "user" | "admin" | "session" | "machine" | "agent"
 
 export interface RouteInfo {
   readonly method: string
@@ -107,7 +205,23 @@ const NO_STORE = { "cache-control": "no-store" }
 export const COOKIE = "voice_device"
 const COOKIE_MAX_AGE = 400 * 24 * 60 * 60
 const SSE_HEARTBEAT_MS = 20_000
+/** Draining: the `retry:` an ending SSE stream sends (the browser reconnects, through the load balancer, after it). */
+const SSE_RETRY_MS = 2_000
+const SSE_RETRY = `retry: ${SSE_RETRY_MS}\n\n`
+/** /readyz in cluster mode: how long the database and Valkey get to answer. */
+const READY_CHECK_MS = 2_000
+/** Cluster mode: how much longer than the turn timeout a turn's cluster-wide lease lasts (it is released at its end). */
+const TURN_LEASE_SLACK_MS = 120_000
+/** Cluster mode: how long a stop sent to the launches leader may take (it waits for the node's collect and cleanup). */
+const LAUNCH_STOP_TIMEOUT_MS = 180_000
+/**
+ * `POST …/turn` with `Prefer: respond-async`: a turn that has not settled after this long is answered 202 and
+ * finishes in the background (result as an SSE `turn` event). Long enough for the quick refusals (busy, unknown
+ * session, spoke error), short enough that no proxy cuts the request (Traefik's default readTimeout is 60 s).
+ */
+export const TURN_ACCEPT_MS = 1500
 const NO_OWNER = "No OpenCode process for this session is connected"
+const AUTO_NAME_OUTDATED = "Update the Hub plugin to use Auto-name"
 const NOT_EXPOSED = "Voice is not enabled for this session"
 /** A permission or question that is not pending any more: someone answered it elsewhere, or it expired. */
 const PERMISSION_GONE = "This request was already answered or expired"
@@ -118,6 +232,8 @@ const MAX_TITLE_CHARS = 200
 const MAX_HERDR_WORKSPACE_CHARS = 100
 /** View preferences: entries per list and characters per entry. */
 const VIEW_PREF_MAX_ENTRIES = 500
+/** hiddenSessions holds archived sessions (Archive in the console), which add up over time. */
+const VIEW_PREF_MAX_ARCHIVED = 5000
 const VIEW_PREF_MAX_CHARS = 4096
 const DECISIONS = new Set<PermissionDecision>(["once", "always", "reject"])
 /** Longest utterance accepted for conversation mode (characters, after trimming). */
@@ -149,6 +265,29 @@ const CONTENT_TYPES: Record<string, string> = {
   ".svg": "image/svg+xml",
   ".png": "image/png",
   ".ico": "image/x-icon",
+  // Voice mode's on-device speech detection (Silero VAD through onnxruntime-web)
+  ".wasm": "application/wasm",
+  ".onnx": "application/octet-stream",
+}
+/** Vite's content-hashed build output: a changed file gets a new name, so it can be cached for good. */
+const HASHED_ASSET = /^assets\//
+const IMMUTABLE = "public, max-age=31536000, immutable"
+/** Hashed assets sent compressed when the browser accepts it (onnxruntime's wasm: 12 MB → 2.3 MB with Brotli). */
+const COMPRESSIBLE = new Set([".js", ".mjs", ".css", ".wasm", ".json", ".svg"])
+const MIN_COMPRESS_BYTES = 1024
+const brotli = promisify(brotliCompress)
+const gzipAsync = promisify(gzip)
+
+/** "br" or "gzip" when the Accept-Encoding header allows it (q=0 refuses), else undefined. */
+function pickEncoding(header: string | null): "br" | "gzip" | undefined {
+  const accepted = new Map<string, number>()
+  for (const part of (header ?? "").toLowerCase().split(",")) {
+    const [name, ...params] = part.trim().split(";")
+    const q = params.map((p) => /^\s*q=([\d.]+)\s*$/.exec(p)?.[1]).find(Boolean)
+    if (name) accepted.set(name.trim(), q === undefined ? 1 : Number(q))
+  }
+  for (const encoding of ["br", "gzip"] as const) if ((accepted.get(encoding) ?? 0) > 0) return encoding
+  return undefined
 }
 
 class HttpError extends Error {
@@ -162,38 +301,111 @@ class HttpError extends Error {
   }
 }
 
+/** A core op the session's spoke does not serve (another harness's spoke): 409 code unsupported, like plugin_outdated. */
+const unsupportedError = (lacking: Pick<Unsupported, "feature" | "harness">) => new HttpError(409, unsupportedMessage(lacking), "unsupported")
+
 const error = (status: number, message: string, code?: string) =>
   Response.json({ error: message, ...(code ? { code } : {}) }, { status })
 
 export function startCentral(options: CentralOptions): Central {
   const { config } = options
+  const heartbeatMs = options.timing?.heartbeatMs ?? SSE_HEARTBEAT_MS
   const web: WebAssets = options.web ?? diskAssets(options.webDir ?? path.join(import.meta.dir, "..", "..", "web", "dist"))
   const now = options.now ?? Date.now
-  const store = Store.open(config.stateDir, now, { mode: config.auth.mode })
+  /** The bundle for the config (or the one given). Cluster mode never touches the state dir. */
+  const ownBackends = !options.backends
+  const backends = options.backends ?? hubBackends(config, { now })
+  // Cluster mode: the records are rows in the shared StateStore, cached per pod (loaded on first use; no data
+  // migration runs on start). Otherwise state.json in the state dir.
+  const store = config.cluster
+    ? Store.shared({ state: backends.state, bus: backends.bus, now, instanceID: `${config.cluster.podID}-${randomUUID().slice(0, 8)}` })
+    : Store.open(config.stateDir, now, { mode: config.auth.mode })
   // A machine's tenant is its owner (read live: ownership moves on migration).
-  const registry = new Registry(Date.now, undefined, (machineID) => store.machines().find((m) => m.id === machineID)?.ownerID)
-  const push = new Push({ store, subject: config.vapidSubject, sender: options.pushSender })
+  const registry = new Registry(now, undefined, (machineID) => store.machines().find((m) => m.id === machineID)?.ownerID)
+  const nodes = new NodeRegistry((machineID) => store.machines().find((m) => m.id === machineID)?.ownerID, now)
+  const push = new Push({ store, subject: config.vapidSubject, sender: options.pushSender, kv: backends.kv })
   const notifier = options.notifier ?? push
   /** SSE subscribers, one user each. */
   const listeners = new Set<Listener>()
+  /** Recent messages per user, replayed to a stream that reconnects with Last-Event-ID. */
+  const eventLog = new EventLog()
+  /** Whether a listener wants a message (lite streams skip other sessions' streamed text). */
+  const wants = (listener: Listener, message: Message): boolean => {
+    if (!listener.lite || !STREAMED.has(message.type)) return true
+    if (!listener.session) return false
+    const root = registry.status(listener.session)?.[0]?.id ?? listener.session
+    return message.sessionID === listener.session || message.rootID === root || message.sessionID === root
+  }
+  /**
+   * Cluster mode (design §9): a user's events go to every pod over the Bus (user.<id>.live), logged in the shared
+   * EventLog first (except streamed text), so consoles on any pod get them and resume by Last-Event-ID on any pod.
+   */
+  const live = config.cluster ? new LiveFanout({ bus: backends.bus, events: backends.events, podID: config.cluster.podID }) : undefined
+  /** Sends a message to this process's streams of a user (except `exceptDevice`'s); a catalog is built per user. */
+  const deliver = (userID: string, message: Message, id?: string, exceptDevice?: string) => {
+    for (const listener of [...listeners]) {
+      if (listener.userID !== userID || listener.deviceID === exceptDevice) continue
+      if (message.type === "catalog") listener.send({ type: "catalog", machines: machines(userID) }, id)
+      else if (wants(listener, message)) listener.send(message, id)
+    }
+  }
+  /** Logs a message for one user and sends it to their streams (except `exceptDevice`'s). */
+  const toUser = (userID: string, message: Message, exceptDevice?: string) => {
+    if (live) {
+      // A catalog is this pod's own view (its registry covers the cluster): never logged, never sent to other pods.
+      if (message.type === "catalog") deliver(userID, message)
+      // Failures are logged by the fan-out.
+      else live.send(userID, message, exceptDevice).catch(() => {})
+      return
+    }
+    // A catalog is logged as a marker: a replay sends one fresh catalog for any number of them.
+    const id = eventLog.append(userID, message.type === "catalog" ? { type: "catalog" } : message, exceptDevice)
+    deliver(userID, message, id, exceptDevice)
+  }
+  /** Closes the streams of users who were disabled or removed. */
+  const closeDisabled = () => {
+    for (const listener of [...listeners]) {
+      const user = store.user(listener.userID)
+      if (!user || user.disabled) listener.close()
+    }
+  }
+  /** Users that may receive an `audience` message (cluster mode: whether or not they stream on this pod). */
+  const audienceUsers = (audience: { tenant?: string; admins?: true }): string[] => {
+    if (audience.admins) return store.users().filter((u) => u.role === "admin" && !u.disabled).map((u) => u.id)
+    if (audience.tenant === undefined) return []
+    const user = store.user(audience.tenant)
+    return user && !user.disabled ? [user.id] : []
+  }
   /**
    * Sends to SSE subscribers: catalog to everyone (each gets their own machines), `admins` messages to
    * admins only, anything else only to `tenant` (the session's owner). Streams of users who were
    * disabled are closed.
    */
   const broadcast = (message: Message, audience: { tenant?: string; admins?: true } = {}) => {
-    for (const listener of [...listeners]) {
-      const user = store.user(listener.userID)
-      if (!user || user.disabled) {
-        listener.close()
-        continue
-      }
-      if (message.type === "catalog") listener.send({ type: "catalog", machines: machines(user.id) })
+    closeDisabled()
+    if (live) {
+      // Stored machines changed: every pod sends its streams a fresh catalog (catalogHere).
+      if (message.type === "catalog") live.publishCatalog().catch((cause) => console.error(`[hub] catalog announcement failed: ${(cause as Error).message}`))
+      else for (const userID of audienceUsers(audience)) toUser(userID, message)
+      return
+    }
+    const users = new Set([...eventLog.users(), ...[...listeners].map((l) => l.userID)])
+    for (const userID of users) {
+      const user = store.user(userID)
+      if (!user || user.disabled) continue
+      if (message.type === "catalog") toUser(userID, message)
       else if (audience.admins) {
-        if (user.role === "admin") listener.send(message)
-      } else if (audience.tenant !== undefined && audience.tenant === user.id) listener.send(message)
+        if (user.role === "admin") toUser(userID, message)
+      } else if (audience.tenant !== undefined && audience.tenant === userID) toUser(userID, message)
     }
   }
+  /** Cluster mode: a fresh catalog to this pod's streams (the registry's cluster-wide view changed). */
+  const catalogHere = () => {
+    closeDisabled()
+    for (const userID of new Set([...listeners].map((l) => l.userID))) toUser(userID, { type: "catalog" })
+  }
+  live?.onCatalog(catalogHere)
+  live?.start().catch((cause) => console.error(`[hub] live fan-out did not start: ${(cause as Error).message}`))
   const speechSettings = new SpeechService({
     store,
     defaults: {
@@ -210,6 +422,10 @@ export function startCentral(options: CentralOptions): Central {
   let publicURL = config.publicURL
   let auth!: Auth
   let spokes!: SpokeHub
+  /** Set by drain() (design §10): /readyz fails and new SSE streams are sent away. */
+  let draining: Promise<void> | undefined
+  /** Aborted by drain(): the agent watch streams end with a `retry:` hint. */
+  const drainSignal = new AbortController()
   /** At most one machine per hub process is approved without confirmation (see localAutoApprove). */
   let autoApproved = false
 
@@ -233,22 +449,62 @@ export function startCentral(options: CentralOptions): Central {
   const origins = loopbackOrigins(publicURL)
   const secure = publicURL.startsWith("https:")
 
-  auth = new Auth({ store, publicURL, now, mode: config.auth.mode })
+  auth = new Auth({ store, publicURL, now, mode: config.auth.mode, kv: backends.kv, counters: backends.counters })
   // options.fetch is for speech providers only; sign-in always talks to the real issuer.
-  const oidc = config.auth.mode === "oidc" ? new OidcClient({ config: config.auth, publicURL, now }) : undefined
+  const oidc = config.auth.mode === "oidc" ? new OidcClient({ config: config.auth, publicURL, now, kv: backends.kv, counters: backends.counters }) : undefined
   /** Speech settings scope of a user: "local" (pairing mode) uses the server default directly. */
   const speechScope = (userID: string) => (userID === LOCAL_USER ? undefined : userID)
   const speechFor = (userID: string): Speech => options.speech ?? speechSettings.forUser(speechScope(userID))
+  const tokenKeys = TokenKeys.open(config.stateDir)
+  // Launch-bound tokens (phase 5): checked against the launch engine's store (created below; read only at use).
+  const launchTokens: LaunchTokens = new LaunchTokens({ keys: tokenKeys, store, launches: { launch: (userID, launchID) => launches.store.get(userID, launchID) }, publicURL, now })
   spokes = new SpokeHub({
     store,
     auth,
     registry,
+    nodes,
     publicURL,
     notifier,
     broadcast: (message, tenant) => broadcast(message, { tenant }),
     turnTimeoutMs: config.turnTimeoutMs,
+    launchTokens,
+    // Cluster mode: connections are found through the shared directory and reached over pod RPC (design §9).
+    ...(config.cluster
+      ? { cluster: { directory: new ConnDirectory({ kv: backends.kv, podID: config.cluster.podID }), rpc: new PodRpc({ bus: backends.bus, podID: config.cluster.podID }) } }
+      : {}),
     ...options.timing,
   })
+  spokes.ready().catch((cause) => console.error(`[hub] cluster routing did not start: ${(cause as Error).message}`))
+  // Cluster mode: this pod publishes its connections (spokes and nodes) per user and mirrors the other pods', so the
+  // registries' reads cover the whole cluster (design §9).
+  const view = config.cluster
+    ? new ClusterView({
+        catalog: backends.catalog,
+        bus: backends.bus,
+        podID: config.cluster.podID,
+        registry,
+        nodes,
+        users: async () => {
+          await store.ready()
+          return store.users().map((u) => u.id)
+        },
+        ...(options.timing?.viewHeartbeatMs !== undefined ? { heartbeatMs: options.timing.viewHeartbeatMs } : {}),
+        ...(options.timing?.viewTtlMs !== undefined ? { ttlMs: options.timing.viewTtlMs } : {}),
+      })
+    : undefined
+  view?.start().catch((cause) => console.error(`[hub] cluster view did not start: ${(cause as Error).message}`))
+  // Session tokens (design §1.3): minted for the sessions spokes report, pushed on their sessions frames.
+  const sessionTokens = new SessionTokens({ keys: tokenKeys, store, sessions: registry, publicURL, now })
+  const tokenPush = new SessionTokenPush({
+    registry,
+    tokens: sessionTokens,
+    send: (connID, req) => spokes.request(connID, req),
+    hubURL: publicURL,
+    now,
+    log: (message) => console.error(message),
+  })
+  registry.onSessions((connID) => void tokenPush.sessions(connID))
+  tokenPush.start()
 
   /** The user's machines with their live processes and sessions. */
   const machines = (userID: string) => {
@@ -267,12 +523,20 @@ export function startCentral(options: CentralOptions): Central {
       }))
   }
 
-  registry.subscribe((message, tenant) => broadcast({ ...message }, tenant !== undefined ? { tenant } : {}))
+  // Cluster mode: a catalog change stays on this pod (each pod's registry emits its own for remote slices); the rest
+  // goes to the tenant's streams on every pod.
+  registry.subscribe((message, tenant) => (live && message.type === "catalog" ? catalogHere() : broadcast({ ...message }, tenant !== undefined ? { tenant } : {})))
   registry.subscribeAlerts((alert) => {
     // Push goes to the session owner's devices only; an alert without an owner goes nowhere.
     if (!alert.owner) return
-    const extra = alert.requestID ? { requestID: alert.requestID } : undefined
-    notifier.notify(alert.kind, alert.sessionID, alert.title, alert.detail, alert.text, alert.owner, extra).catch((cause) => {
+    // Activity updates are collected and throttled per device by the push layer.
+    if (alert.kind === "activity") return push.activity(alert)
+    const extra = {
+      ...(alert.requestID ? { requestID: alert.requestID } : {}),
+      ...(alert.subject ? { subject: alert.subject } : {}),
+      ...(alert.key ? { key: alert.key } : {}),
+    }
+    notifier.notify(alert.kind, alert.sessionID, alert.title, alert.text, alert.owner, extra).catch((cause) => {
       console.error("[hub] push notification failed:", cause instanceof Error ? cause.message : cause)
     })
   })
@@ -284,6 +548,7 @@ export function startCentral(options: CentralOptions): Central {
       {
         prefs: store.pushPrefs(deviceID),
         quietHours: store.quietHours(deviceID) ?? null,
+        activityMinutes: store.activityMinutes(deviceID),
         muted: store.mutedSessions(userID),
         subscriptions: mine.length,
         ...(endpoint ? { subscribed: mine.some((s) => s.endpoint === endpoint) } : {}),
@@ -296,12 +561,19 @@ export function startCentral(options: CentralOptions): Central {
     `${COOKIE}=${token}; HttpOnly; SameSite=Lax; Path=/; Max-Age=${maxAge}${secure ? "; Secure" : ""}`
 
   /** The device of the voice_device cookie and its user; undefined when unknown or the user is disabled. */
-  const deviceFor = (request: Request): { device: DeviceRecord; user: UserRecord } | undefined => {
+  /** The device of a token (cookie value or device token), its owner re-read too (a shared store's security re-check). */
+  const deviceOfToken = async (token: string): Promise<DeviceRecord | undefined> => {
+    const device = await store.findDevice(token)
+    if (device) await store.recheck({ users: [device.ownerID] })
+    return device
+  }
+
+  const deviceFor = async (request: Request): Promise<{ device: DeviceRecord; user: UserRecord } | undefined> => {
     const header = request.headers.get("cookie") ?? ""
     for (const part of header.split(";")) {
       const [name, ...rest] = part.trim().split("=")
       if (name !== COOKIE) continue
-      const device = store.findDevice(rest.join("="))
+      const device = await deviceOfToken(rest.join("="))
       if (!device) continue
       const user = store.user(device.ownerID)
       return user && !user.disabled ? { device, user } : undefined
@@ -329,34 +601,34 @@ export function startCentral(options: CentralOptions): Central {
       result = await oidc!.callback(url.searchParams, cookieValue(request.headers.get("cookie"), OIDC_COOKIE))
     } catch (cause) {
       if (!(cause instanceof OidcError)) throw cause
-      if (cause.audited) store.audit({ actor: "system", action: "signin.denied", detail: cause.reason })
+      if (cause.audited) await store.audit({ actor: "system", action: "signin.denied", detail: cause.reason })
       else console.warn(`[hub] sign-in refused: ${cause.reason}`)
       return deny(cause.status, "Sign-in failed", cause.message)
     }
     const { identity, next } = result
     if (!emailAllowed(settings, identity.email)) {
-      store.audit({ actor: "system", action: "signin.denied", target: identity.email, detail: "not allowed" })
+      await store.audit({ actor: "system", action: "signin.denied", target: identity.email, detail: "not allowed" })
       return deny(403, "Not allowed", `${identity.email} is not allowed to use this hub. Ask its admin to add you.`)
     }
     const role = settings.admins.includes(identity.email) ? "admin" : "user"
     const existing = store.userByEmail(identity.email)
     if (existing?.disabled) {
-      store.audit({ actor: "system", action: "signin.denied", target: identity.email, detail: "disabled" })
+      await store.audit({ actor: "system", action: "signin.denied", target: identity.email, detail: "disabled" })
       return deny(403, "Account disabled", "Your account on this hub is disabled. Ask its admin.")
     }
-    const user = store.upsertUser({ email: identity.email, ...(identity.name ? { name: identity.name } : {}), role })
-    if (user.role === "admin" && store.migrateLocal(user.id)) broadcast({ type: "catalog" })
+    const user = await store.upsertUser({ email: identity.email, ...(identity.name ? { name: identity.name } : {}), role })
+    if (user.role === "admin" && await store.migrateLocal(user.id)) broadcast({ type: "catalog" })
     const headers = new Headers({ "cache-control": "no-store" })
     headers.append("set-cookie", cleared["set-cookie"])
-    const current = deviceFor(request)
+    const current = await deviceFor(request)
     let deviceID: string
     if (current && current.user.id === user.id) deviceID = current.device.id
     else {
-      const { device, token } = store.addDevice(deviceName(request.headers.get("user-agent")), user.id)
+      const { device, token } = await store.addDevice(deviceName(request.headers.get("user-agent")), user.id)
       deviceID = device.id
       headers.append("set-cookie", cookie(token))
     }
-    store.audit({ actor: user.id, action: "signin", target: deviceID })
+    await store.audit({ actor: user.id, action: "signin", target: deviceID })
     // Speech not usable yet (e.g. no key): land on the page's speech setup (the console opens Settings → Speech for #speech).
     const setup = !next.includes("#") && speechSettings.view(speechScope(user.id)).ready.reason ? "#speech" : ""
     headers.set("location", `${next}${setup}`)
@@ -376,17 +648,299 @@ export function startCentral(options: CentralOptions): Central {
     }
   }
 
+  /** A push to the user about one session (titled by it; "" opens the console), whatever device shows it. */
+  const pushUser = (kind: "decision" | "message", userID: string, sessionID: string, key: string, decisionID?: string) => {
+    const title = (sessionID && registry.status(sessionID)?.find((s) => s.id === sessionID)?.title) || "Hub"
+    notifier.notify(kind, sessionID, title, undefined, userID, { key, ...(decisionID ? { decisionID } : {}) }).catch((cause) => {
+      console.error("[hub] push notification failed:", cause instanceof Error ? cause.message : cause)
+    })
+  }
+
+  const directory = hubDirectory({ registry, store, now })
+  /** This process as owner of leases (leader loops, flushes, turns): `<pod>:<pid>-<random>`. */
+  const leaseOwner = `${config.cluster?.podID ?? "hub"}:${process.pid}-${randomBytes(4).toString("hex")}`
+  /** Every stored user (the leader loops look at all of them). */
+  const allUsers = async () => {
+    await store.ready()
+    return store.users().map((u) => u.id)
+  }
+  const loopTickMs = options.timing?.loopTickMs
+  // Timed jobs run on one pod at a time, under a fenced leader lease (design §9; a single hub always leads).
+  const leaders: LeaderLoop[] = []
+  const leader = (name: string, handlers: Pick<ConstructorParameters<typeof LeaderLoop>[0], "onElected" | "onDeposed" | "onKick" | "onRequest">) => {
+    const loop = new LeaderLoop({
+      locks: backends.locks,
+      bus: backends.bus,
+      name,
+      owner: leaseOwner,
+      ...(options.timing?.leaderTtlMs !== undefined ? { ttlMs: options.timing.leaderTtlMs } : {}),
+      ...handlers,
+    })
+    leaders.push(loop)
+    return loop
+  }
+  // Agent messages (design §3): delivered through spokes that announce "deliver"; pending ones flush on every
+  // sessions frame; human turns (console turn/utterance, prompts typed in the harness) reset hop chains.
+  const delivery = new Delivery({
+    state: backends.state,
+    counters: backends.counters,
+    registry,
+    directory,
+    send: (connID, req) => spokes.request(connID, req),
+    now,
+    describe: (userID, sessionID) => {
+      try {
+        const entry = directory.resolve(userID, sessionID).sessions[0]
+        const machine = entry?.machineID ? store.machines().find((m) => m.id === entry.machineID)?.name : undefined
+        return { ...(entry?.name ? { name: entry.name } : {}), ...(machine ? { machine } : {}) }
+      } catch {
+        return {}
+      }
+    },
+    // Push kind "message": a msg to @me, an ask left unanswered, a message loop (sent even while watched).
+    alert: (userID, alert) => pushUser("message", userID, alert.sessionID, `${alert.kind}:${alert.messageID}`),
+    ...(loopTickMs !== undefined ? { tickMs: loopTickMs } : {}),
+    // Cluster mode: the re-wake loop (leader) looks at every user; each pending flush holds a (user, session) lease.
+    ...(config.cluster ? { users: allUsers, locks: backends.locks, owner: leaseOwner } : {}),
+  })
+  /** Message events (watch, waiters), shared by the agent routes and the console's Decision answers. */
+  const feed = new MessageFeed()
+  // Cluster mode: messages stored on any pod reach this pod's listeners (ask waiters, agent watches).
+  if (config.cluster) feed.attach({ bus: backends.bus, podID: config.cluster.podID }).catch((cause) => console.error(`[hub] message feed did not attach: ${(cause as Error).message}`))
+  // Decisions (design §12.1): asks to @me; deadlines run over every user's Decisions (survive restarts).
+  const decisions = new Decisions({
+    state: backends.state,
+    delivery,
+    now,
+    users: () => store.users().map((u) => u.id),
+    notify: (userID, decision, reason) => pushUser("decision", userID, decision.sessionID ?? "", `${decision.id}:${reason}`, decision.id),
+    // The console's live Decision cards: opened, answered (here, by timeout), escalated, expired.
+    changed: (userID, decision) => broadcast({ type: "decision", decision }, { tenant: userID }),
+    // Escalations' Decisions reply to the permission as the user; grant requests' create the grant as the user
+    // (both are set up below).
+    act: (userID, decision, choice, by) => (decision.action?.kind === "grant" ? grantRequests.act(userID, decision, choice, by) : escalations.act(userID, decision, choice, by)),
+    ...(loopTickMs !== undefined ? { tickMs: loopTickMs } : {}),
+  })
+  leader("decisions", { onElected: () => decisions.start(), onDeposed: () => decisions.stop() })
+  /** The user prompted the session: its message hop chain starts over (never fails the prompt). */
+  const humanTurn = async (sessionID: string): Promise<void> => {
+    const tenant = registry.sessionTenant(sessionID)
+    if (tenant === undefined) return
+    await delivery.humanTurn(tenant, sessionID).catch((cause) => console.error(`[hub] hop reset failed: ${(cause as Error).message}`))
+  }
+  registry.onSessions((connID) => void delivery.onSessions(connID).catch((cause) => console.error(`[hub] message flush failed: ${(cause as Error).message}`)))
+  registry.onHumanTurn((sessionID) => void humanTurn(sessionID))
+  /** Permission, form, prompt and stop execution, shared by the console routes and the agent act verbs. */
+  const actions = createActions({
+    registry,
+    spokes,
+    humanTurn,
+    kv: backends.kv,
+    // Cluster mode: a turn also holds the session's lease, so two pods never start turns in it at once.
+    ...(config.cluster ? { turns: { locks: backends.locks, owner: leaseOwner, ttlMs: config.turnTimeoutMs + TURN_LEASE_SLACK_MS } } : {}),
+  })
+  leader("delivery", { onElected: () => delivery.start(), onDeposed: () => delivery.stop() })
+  // Launches (design §6): placement onto the user's nodes, prepare on the node, the session through the machine's
+  // service spoke, then its end; restart recovery runs on start. Every change goes to launchFeed: the owner's
+  // console streams get it as a 'launch' event.
+  const launchFeed = new LaunchFeed()
+  // Cluster mode: launch changes made on any pod reach this pod's agent watches. The console broadcast, closing a
+  // launch's connections and webhooks run only on the publishing pod (origin): they reach every pod themselves.
+  if (config.cluster) launchFeed.attach({ bus: backends.bus, podID: config.cluster.podID }).catch((cause) => console.error(`[hub] launch feed did not attach: ${(cause as Error).message}`))
+  launchFeed.subscribe((userID, launch) => broadcast({ type: "launch", launch: launchInfo(launch) }, { tenant: userID }), { origin: true })
+  const launches = new LaunchEngine({
+    state: backends.state,
+    counters: backends.counters,
+    locks: backends.locks,
+    owner: `hub-${process.pid}-${randomBytes(4).toString("hex")}`,
+    ...(config.launchCaps ? { caps: config.launchCaps } : {}),
+    nodes,
+    nodeOps: spokes,
+    registry,
+    spokes,
+    directory,
+    delivery,
+    decisions,
+    actions,
+    // openshell launches: the node starts the sandbox's harness with an hlt1 token and the hub's public URL.
+    launchTokens,
+    hubURL: publicURL,
+    users: () => store.users().map((u) => u.id),
+    now,
+    onLaunchChanged: (launch) => launchFeed.publish(launch.owner, launch),
+    // Cluster mode: the supervisor runs on the launches leader; other pods kick it and send it their stops.
+    ...(config.cluster
+      ? {
+          supervisor: {
+            kick: (userID: string) => void launchLeader.kick({ userID }).catch((cause) => console.error(`[hub] launch kick failed: ${(cause as Error).message}`)),
+            stop: async (userID: string, id: string, reason: string) => {
+              let reply: { launch?: Launch; error?: { code: AgentErrorCode; message: string } }
+              try {
+                reply = await launchLeader.request({ op: "stop", userID, id, reason }, { timeoutMs: LAUNCH_STOP_TIMEOUT_MS })
+              } catch (cause) {
+                if (cause instanceof NoLeaderError) return undefined
+                throw cause
+              }
+              if (reply.error) throw new AgentError(reply.error.code, reply.error.message)
+              return reply.launch
+            },
+          },
+        }
+      : {}),
+  })
+  // A launch-bound connection lives only while its launch is provisioning or running: it is closed (and refused from
+  // then on) when the launch ends. Not on queued: that would refuse the sandbox's spoke before it ever connects.
+  launchFeed.subscribe((_userID, launch) => {
+    if (launch.state === "ended") spokes.closeLaunch(launch.id)
+  }, { origin: true })
+  const launchLeader = leader("launches", {
+    onElected: () => launches.start().catch((cause) => console.error(`[hub] launches did not start: ${(cause as Error).message}`)),
+    onDeposed: () => launches.shutdown(),
+    onKick: (message) => {
+      const userID = (message as { userID?: unknown } | undefined)?.userID
+      if (typeof userID === "string") launches.kick(userID)
+    },
+    onRequest: async (message) => {
+      const { op, userID, id, reason } = (message ?? {}) as { op?: unknown; userID?: unknown; id?: unknown; reason?: unknown }
+      if (op !== "stop" || typeof userID !== "string" || typeof id !== "string" || typeof reason !== "string") throw new Error("Invalid launch supervisor request")
+      try {
+        return { launch: await launches.stop(userID, id, reason) }
+      } catch (cause) {
+        if (cause instanceof AgentError) return { error: { code: cause.code, message: cause.message } }
+        throw cause
+      }
+    },
+  })
+  // Webhooks (P4-T10): launch changes go to the owner's matching registrations through the durable outbox; URLs
+  // are checked again at every send; private targets only with hub.json agents.webhooks.allowPrivate.
+  const webhooks = new Webhooks({
+    state: backends.state,
+    locks: backends.locks,
+    now,
+    source: publicURL,
+    users: () => store.users().map((u) => u.id),
+    resolve: options.resolveHost ?? systemResolveHost,
+    ...(config.webhooksAllowPrivate ? { allowPrivate: true } : {}),
+    appAlive: (userID, tokenID) => store.agentData(userID).appTokens?.some((t) => t.id === tokenID && Array.isArray(t.scopes) && t.scopes.includes(WEBHOOK_SCOPE)) === true,
+    userAgent: `hub/${options.version ?? "0.0.0"}`,
+  })
+  launchFeed.subscribe((userID, launch) => {
+    void webhooks
+      .onLaunch(userID, launch, launchInfo(launch))
+      // Queued here, sent by the webhooks leader (kicked when that is another pod).
+      .then((queued) => (queued && !webhookLeader.isLeader() ? webhookLeader.kick() : undefined))
+      .catch((cause) => console.error(`[hub] webhook queue failed: ${(cause as Error).message}`))
+  }, { origin: true })
+  const webhookLeader = leader("webhooks", {
+    onElected: () => webhooks.start(),
+    onDeposed: () => webhooks.stop(),
+    onKick: () => void webhooks.drain().catch((cause) => console.error(`[hub] webhook delivery failed: ${(cause as Error).message}`)),
+  })
+  for (const loop of leaders) void loop.start()
+
+  // One credential resolver for every /api request: device cookie, device token, session and app tokens.
+  // Every stored agent message also goes to the user's console streams (live transcript rows).
+  feed.subscribe((userID, message) => broadcast({ type: "message", message }, { tenant: userID }), { origin: true })
+  const audit = new AgentAudit({ state: backends.state, now, admin: store, recorded: (userID, entry) => broadcast({ type: "agent", entry }, { tenant: userID }) })
+  const grants = new Grants({ state: backends.state, counters: backends.counters, directory, store, admin: store, now })
+  const acting = new ActingSwitch({ store, never: config.agentsNever, audit })
+  /** An agent as envelopes name it (a session by its directory name). */
+  const describeActor = (userID: string, actor: AgentActor) => {
+    if (actor.kind !== "session") return partyFromActor(actor)
+    try {
+      const name = directory.resolve(userID, actor.sessionID).sessions[0]?.name
+      return partyFromActor(actor, name ? { name } : {})
+    } catch {
+      return partyFromActor(actor)
+    }
+  }
+  // needs_user escalations (P3-T8): one Decision per (holder, request); answered as the user; closed when the
+  // request goes elsewhere.
+  // Cluster mode: a recommendation on a request another pod holds goes to that pod.
+  const recommendations = config.cluster ? new ClusterRecommendations({ bus: backends.bus, podID: config.cluster.podID, registry }) : undefined
+  recommendations?.start().catch((cause) => console.error(`[hub] cluster recommendations did not start: ${(cause as Error).message}`))
+  const escalations: Escalations = new Escalations({
+    state: backends.state,
+    counters: backends.counters,
+    decisions,
+    registry: {
+      sessionTenant: (sessionID) => registry.sessionTenant(sessionID),
+      recommend: (requestID, recommendation) => (recommendations ?? registry).recommend(requestID, recommendation),
+    },
+    actions,
+    audit,
+    now,
+    describe: describeActor,
+    published: (userID, message) => feed.publish(userID, message),
+  })
+  // Grant requests (P3-T9): an agent asks; the user's tap creates the grant as the user.
+  const grantRequests: GrantRequests = new GrantRequests({
+    state: backends.state,
+    counters: backends.counters,
+    decisions,
+    grants,
+    directory,
+    audit,
+    now,
+    describe: describeActor,
+    published: (userID, message) => feed.publish(userID, message),
+  })
+  registry.onPermissionClosed((requestID, _sessionID, tenant) => {
+    void escalations.closed(tenant, requestID).catch((cause) => console.error(`[hub] escalation close failed: ${(cause as Error).message}`))
+  })
+  const escalate: Escalate = (escalation) => escalations.escalate(escalation)
+  /** Cluster mode: what GET /api/agent/watch reads; status of sessions on any pod comes from the user's live events. */
+  const watchRegistry = live
+    ? (userID: string): WatchRegistry => ({
+        catalog: () => registry.catalog(),
+        sessionTenant: (sessionID) => registry.sessionTenant(sessionID),
+        subscribe: (listener) => {
+          const offCatalog = registry.subscribe((message) => {
+            if (message.type === "catalog") listener(message)
+          })
+          const subscription = live.subscribe(userID, (event) => {
+            if (event.message.type === "status") listener(event.message as unknown as RegistryMessage, userID)
+          })
+          return () => {
+            offCatalog()
+            subscription.close()
+          }
+        },
+      })
+    : undefined
+  const agentDeps = { draining: drainSignal.signal, store, sessionTokens, directory, registry, spokes, delivery, decisions, feed, heartbeatMs, now, audit, grants, grantRequests, acting, actions, escalate, launches, launchFeed, webhooks, maxPromptChars: MAX_PROMPT_CHARS, ...(watchRegistry ? { watchRegistry } : {}) }
+  const resolveActor = createResolver({
+    cookieName: COOKIE,
+    findDevice: (token) => deviceOfToken(token),
+    user: (id) => store.user(id),
+    verifiers: [...agentVerifiers(agentDeps), ...(options.agent?.verifiers ?? [])],
+  })
+  const agent = agentApi({
+    resolve: resolveActor,
+    cookieName: COOKIE,
+    sameOrigin,
+    touch: (user, device) => {
+      // Never rejects (lastSeen only).
+      if (device) void store.touchDevice(device.id)
+      void store.touchUser(user.id)
+    },
+    routes: [...agentRoutes(agentDeps), ...(options.agent?.routes ?? [])],
+  })
+
   async function handle(request: Request, server: Server<SpokeSocketData>): Promise<Response | undefined> {
     const url = new URL(request.url)
     const { pathname } = url
     const method = request.method
     try {
+      if (method === "GET" && pathname === "/readyz") return readyz()
       if (pathname === "/spoke/ws") return spokes.upgrade(request, server)
       if (method === "GET" && pathname === "/healthz") {
-        return Response.json({ ok: true, version: options.version ?? "0.0.0", spokes: registry.connections() })
+        return Response.json({ ok: true, version: options.version ?? "0.0.0", spokes: registry.connections(), nodes: nodes.count() })
       }
+      // A shared (cluster) store loads its records on first use; the file store is ready at once.
+      await store.ready()
       if (method === "POST" && pathname === "/spoke/enroll") {
-        const start = auth.startEnrollment((await body(request)).machineName)
+        const start = await auth.startEnrollment((await body(request)).machineName)
         const auto = config.auth.mode === "pairing" && localAutoApprove({
           host: config.host,
           publicURL,
@@ -396,7 +950,7 @@ export function startCentral(options: CentralOptions): Central {
           devices: store.devices().length,
           used: autoApproved,
         })
-        if (auto && auth.approveEnrollment(start.userCode)) {
+        if (auto && (await auth.approveEnrollment(start.userCode))) {
           autoApproved = true
           console.log(`[hub] local hub: approved the first machine (code ${start.userCode}) without confirmation; later machines need approval`)
           return Response.json({ ...start, autoApproved: true } satisfies EnrollStart)
@@ -405,25 +959,29 @@ export function startCentral(options: CentralOptions): Central {
         return Response.json(start)
       }
       if (method === "POST" && pathname === "/spoke/enroll/poll") {
-        const poll = auth.pollEnrollment((await body(request)).deviceCode)
+        const poll = await auth.pollEnrollment((await body(request)).deviceCode)
         if (poll.status === "approved") broadcast({ type: "catalog" })
         return Response.json(poll)
       }
+      if (method === "GET" && pathname === "/.well-known/hub") {
+        return wellKnown({ publicURL, version: options.version ?? "0.0.0", auth: config.auth.mode === "oidc" ? { mode: "oidc", issuer: config.auth.issuer } : { mode: "pairing" } })
+      }
       if (method === "GET" && pathname === "/login") return login(request, url)
       if (oidc && method === "GET" && pathname === "/auth/login") return await authLogin(url)
       if (oidc && method === "GET" && pathname === "/auth/callback") return await authCallback(request, url)
+      if (isAgentPath(pathname)) return await agent.handle(request, url)
       if (pathname.startsWith("/api/")) return await api(request, server, url)
-      if (method === "GET") return staticFile(pathname)
+      if (method === "GET") return await staticFile(pathname, request.headers.get("accept-encoding"))
       return error(404, "Not found")
     } catch (cause) {
       return failure(cause)
     }
   }
 
-  function login(request: Request, url: URL): Response {
+  async function login(request: Request, url: URL): Promise<Response> {
     const next = url.searchParams.get("next") ?? "/"
     if (!LOGIN_NEXT.test(next)) return error(400, "Invalid next path")
-    const ownerID = auth.redeemLogin(url.searchParams.get("code"))
+    const ownerID = await auth.redeemLogin(url.searchParams.get("code"))
     if (!ownerID) {
       return new Response("This sign-in link has expired or was already used. Run /hub again.", {
         status: 401,
@@ -434,9 +992,9 @@ export function startCentral(options: CentralOptions): Central {
     const setup = speechSettings.view(speechScope(ownerID)).ready.reason ? "#speech" : ""
     const headers = new Headers({ location: `${next}${setup}`, "cache-control": "no-store" })
     // A link signs in as the machine's owner: a browser signed in as someone else gets a new device.
-    if (deviceFor(request)?.user.id !== ownerID) {
-      const { device, token } = store.addDevice("Browser (sign-in link)", ownerID)
-      store.audit({ actor: ownerID, action: "device.pair", target: device.id, detail: "login link" })
+    if ((await deviceFor(request))?.user.id !== ownerID) {
+      const { device, token } = await store.addDevice("Browser (sign-in link)", ownerID)
+      await store.audit({ actor: ownerID, action: "device.pair", target: device.id, detail: "login link" })
       headers.set("set-cookie", cookie(token))
     }
     return new Response(null, { status: 302, headers })
@@ -447,6 +1005,11 @@ export function startCentral(options: CentralOptions): Central {
   const ownMachine = (userID: string, machineID: string) =>
     store.machines().find((m) => m.id === machineID && !m.revoked && m.ownerID === userID)
 
+  /** Session routes that also answer for the user's offline sessions the directory knows (hub-side data only). */
+  const OFFLINE_SESSION_ROUTES = new Set(["/api/sessions/:session/messages"])
+  /** No spoke reports the session (for anyone) and the user's directory has a record of it (not deleted). */
+  const knownOffline = (userID: string, sessionID: string) =>
+    registry.sessionTenant(sessionID) === undefined && (store.agentData(userID).sessions ?? []).some((s) => s.sessionID === sessionID && s.deletedAt === undefined)
   const route = (method: string, path: string, access: Access, handle: Handler, exposed = false): Route => {
     const keys: string[] = []
     const pattern = new RegExp(`^${path.replace(/:([a-z]+)/g, (_, key: string) => (keys.push(key), "([^/]+)"))}$`)
@@ -460,11 +1023,19 @@ export function startCentral(options: CentralOptions): Central {
     ),
     route("POST", "/api/pair", "public", async ({ request }) => {
       const input = await body(request)
-      const paired = auth.pair(input.code, input.deviceName)
+      const paired = await auth.pair(input.code, input.deviceName)
       if (!paired) return error(401, "Invalid or expired pairing code")
-      store.audit({ actor: paired.device.ownerID, action: "device.pair", target: paired.device.id })
+      await store.audit({ actor: paired.device.ownerID, action: "device.pair", target: paired.device.id })
       return Response.json({ device: deviceView(paired.device) }, { headers: { "set-cookie": cookie(paired.token) } })
     }),
+    // A native app trades a link code for a device token (kept by the app, sent as Authorization: Bearer): no cookie.
+    route("POST", "/api/devices/redeem", "public", async ({ request }) => {
+      const input = await body(request)
+      const linked = await auth.redeemLink(input.code, input.deviceName, input.publicKey)
+      if (!linked) return error(401, "Invalid or expired link code")
+      await store.audit({ actor: linked.device.ownerID, action: "device.pair", target: linked.device.id, detail: "app link" })
+      return Response.json({ device: deviceView(linked.device), token: linked.token }, { headers: NO_STORE })
+    }),
 
     // any signed-in user, own data only
     route("GET", "/api/me", "user", ({ device, user }) =>
@@ -477,18 +1048,21 @@ export function startCentral(options: CentralOptions): Central {
       }),
     ),
     route("GET", "/api/machines", "user", ({ user }) => Response.json({ machines: machines(user.id) })),
-    route("GET", "/api/events", "user", ({ request, server, user, device }) => {
+    route("GET", "/api/events", "user", ({ request, server, user, device, url }) => {
       server.timeout(request, 0)
-      return events(request.signal, user.id, device.id)
+      const session = url.searchParams.get("session")
+      return events(request.signal, user.id, device.id, {
+        lastID: request.headers.get("last-event-id") ?? url.searchParams.get("last") ?? undefined,
+        lite: url.searchParams.get("lite") === "1",
+        ...(session && session.length <= 300 && registry.owns(user.id, session) ? { session } : {}),
+      })
     }),
     // The phone's session view (hidden/pinned sessions and workspaces), per user, synced to their other devices.
     route("GET", "/api/prefs/view", "user", ({ user }) => Response.json({ prefs: store.viewPrefs(user.id) }, { headers: NO_STORE })),
     route("PUT", "/api/prefs/view", "user", async ({ request, user, device }) => {
-      const prefs = store.setViewPrefs(user.id, viewPrefsInput(await request.json()))
+      const prefs = await store.setViewPrefs(user.id, viewPrefsInput(await request.json()))
       // The user's other devices only: never another user, and not the device that made the change.
-      for (const listener of [...listeners]) {
-        if (listener.userID === user.id && listener.deviceID !== device.id) listener.send({ type: "prefs", prefs })
-      }
+      toUser(user.id, { type: "prefs", prefs }, device.id)
       return Response.json({ prefs }, { headers: NO_STORE })
     }),
     route("GET", "/api/reads", "user", ({ user }) => Response.json({ reads: store.reads(user.id) }, { headers: NO_STORE })),
@@ -502,23 +1076,33 @@ export function startCentral(options: CentralOptions): Central {
           .map((d) => ({ ...deviceView(d), current: d.id === device.id })),
       }),
     ),
-    route("DELETE", "/api/devices/:id", "user", ({ params, user }) => {
+    // A link code for a native app, shown as a QR code / deep link in Settings → Devices → Add app.
+    route("POST", "/api/devices/link", "user", async ({ user }) => {
+      const { code, expiresAt } = auth.issueLinkCode(user.id)
+      await store.audit({ actor: user.id, action: "device.link" })
+      const url = `${APP_SCHEME}://link?hub=${encodeURIComponent(publicURL)}&code=${code}`
+      return Response.json({ code, expiresAt, hub: publicURL, url }, { headers: NO_STORE })
+    }),
+    route("DELETE", "/api/devices/:id", "user", async ({ params, user }) => {
       const target = store.devices().find((d) => d.id === params.id && d.ownerID === user.id)
-      if (!target || !store.removeDevice(target.id)) return error(404, "No such device")
-      store.audit({ actor: user.id, action: "device.revoke", target: target.id })
+      if (!target || !await store.removeDevice(target.id)) return error(404, "No such device")
+      await store.audit({ actor: user.id, action: "device.revoke", target: target.id })
       return new Response(null, { status: 204 })
     }),
-    route("POST", "/api/logout", "user", ({ device }) => {
-      store.removeDevice(device.id)
+    route("POST", "/api/logout", "user", async ({ device }) => {
+      await store.removeDevice(device.id)
       return new Response(null, { status: 204, headers: { "set-cookie": cookie("", 0) } })
     }),
     route("POST", "/api/transcribe", "user", ({ request, user }) => transcribe(request, speechFor(user.id))),
     route("POST", "/api/speak", "user", async ({ request, user }) => {
       const text = speakable(String((await body(request)).text ?? ""), config.maxSpeechChars)
       if (!text) return error(400, "Nothing to speak")
-      return new Response(await speechFor(user.id).speak(text), { headers: { "content-type": "audio/mpeg" } })
+      const speech = speechFor(user.id)
+      // Passed through as the provider sends it, so the phone can start playing before synthesis ends.
+      const audio = speech.speakStream ? await speech.speakStream(text, request.signal) : await speech.speak(text)
+      return new Response(audio, { headers: { "content-type": "audio/mpeg" } })
     }),
-    route("GET", "/api/push/key", "user", () => Response.json({ publicKey: push.publicKey() })),
+    route("GET", "/api/push/key", "user", async () => Response.json({ publicKey: await push.publicKey() })),
     route("POST", "/api/push/subscribe", "user", async ({ request, device }) => {
       const input = await body(request)
       const target = pushTarget(input.subscription)
@@ -526,14 +1110,14 @@ export function startCentral(options: CentralOptions): Central {
       const problem = await pushEndpointProblem(target.endpoint, options.resolveHost ?? systemResolveHost)
       if (problem) return error(400, `Invalid push subscription: ${problem}`)
       // pushsubscriptionchange: the service worker sends the endpoint it replaces.
-      if (typeof input.oldEndpoint === "string" && input.oldEndpoint !== target.endpoint) store.removePushSubscription(device.id, input.oldEndpoint)
-      store.addPushSubscription(device.id, target)
+      if (typeof input.oldEndpoint === "string" && input.oldEndpoint !== target.endpoint) await store.removePushSubscription(device.id, input.oldEndpoint)
+      await store.addPushSubscription(device.id, target)
       const prefs = prefsInput(input.prefs)
-      return Response.json({ prefs: prefs ? store.setPushPrefs(device.id, prefs) : store.pushPrefs(device.id) })
+      return Response.json({ prefs: prefs ? await store.setPushPrefs(device.id, prefs) : store.pushPrefs(device.id) })
     }),
     route("POST", "/api/push/unsubscribe", "user", async ({ request, device }) => {
       const endpoint = (await body(request)).endpoint
-      if (typeof endpoint !== "string" || !store.removePushSubscription(device.id, endpoint)) {
+      if (typeof endpoint !== "string" || !await store.removePushSubscription(device.id, endpoint)) {
         return error(404, "No such subscription on this device")
       }
       return new Response(null, { status: 204 })
@@ -544,10 +1128,17 @@ export function startCentral(options: CentralOptions): Central {
       if ("quietHours" in input) {
         const quiet = input.quietHours === null ? null : quietHoursInput(input.quietHours)
         if (quiet === undefined) return error(400, "quietHours must be {start: \"HH:MM\", end: \"HH:MM\", timeZone} or null")
-        store.setQuietHours(device.id, quiet)
+        await store.setQuietHours(device.id, quiet)
+      }
+      if ("activityMinutes" in input) {
+        const minutes = input.activityMinutes
+        if (typeof minutes !== "number" || !Number.isInteger(minutes) || minutes < ACTIVITY_INTERVAL_MIN || minutes > ACTIVITY_INTERVAL_MAX) {
+          return error(400, `activityMinutes must be a whole number of minutes from ${ACTIVITY_INTERVAL_MIN} to ${ACTIVITY_INTERVAL_MAX}`)
+        }
+        await store.setActivityMinutes(device.id, minutes)
       }
       const prefs = prefsInput(input)
-      if (prefs) store.setPushPrefs(device.id, prefs)
+      if (prefs) await store.setPushPrefs(device.id, prefs)
       return pushPrefsView(device.id, user.id)
     }),
     route("PUT", "/api/push/mute", "user", async ({ request, user }) => {
@@ -556,12 +1147,15 @@ export function startCentral(options: CentralOptions): Central {
       if (typeof sessionID !== "string" || !sessionID || sessionID.length > 200 || typeof input.muted !== "boolean") {
         return error(400, "Expected {sessionID, muted}")
       }
-      return Response.json({ muted: store.setSessionMuted(user.id, sessionID, input.muted) })
+      return Response.json({ muted: await store.setSessionMuted(user.id, sessionID, input.muted) })
     }),
-    route("POST", "/api/push/test", "user", async ({ device }) => {
+    route("POST", "/api/push/test", "user", async ({ request, device }) => {
+      // The body is optional (older clients send none): {kind?} picks what the test looks like.
+      const kind = (await body(request).catch(() => ({}) as Record<string, unknown>)).kind
+      if (kind !== undefined && !isNotificationKind(kind)) return error(400, `kind must be one of ${PUSH_PREF_KEYS.join(", ")}`)
       const subscriptions = store.pushSubscriptions().filter((s) => s.deviceID === device.id).length
       if (subscriptions === 0) return Response.json({ sent: 0, failed: [], subscriptions })
-      const result = await push.test(device.id)
+      const result = await push.test(device.id, kind)
       if ("limited" in result) {
         return Response.json({ error: "Wait a few seconds before sending another test" }, { status: 429, headers: { "retry-after": String(result.retryAfter) } })
       }
@@ -571,7 +1165,7 @@ export function startCentral(options: CentralOptions): Central {
     route("GET", "/api/settings/speech", "user", ({ user }) => Response.json(speechSettings.view(speechScope(user.id)), { headers: NO_STORE })),
     // Raw JSON: anything but an object is refused by the validator.
     route("PUT", "/api/settings/speech", "user", async ({ request, user }) =>
-      Response.json(speechSettings.update(await request.json(), speechScope(user.id)), { headers: NO_STORE }),
+      Response.json(await speechSettings.update(await request.json(), speechScope(user.id)), { headers: NO_STORE }),
     ),
     route("GET", "/api/settings/speech/models", "user", async ({ url, user }) => {
       const kind = url.searchParams.get("kind")
@@ -605,16 +1199,18 @@ export function startCentral(options: CentralOptions): Central {
       "/api/sessions/:session/interrupt",
       "session",
       async ({ params }) => {
-        await spokes.request(ownerOf(params.session!), { op: "interrupt", sessionID: params.session! })
+        await spokes.request(ownerOf(params.session!, "interrupt"), { op: "interrupt", sessionID: params.session! })
         registry.cancelTurns(params.session!)
         return new Response(null, { status: 204 })
       },
     ),
     route("POST", "/api/sessions/:session/stop", "session", async ({ params }) => {
-      const result = await spokes.request(ownerOf(params.session!), { op: "stop", sessionID: params.session! })
-      registry.cancelTurns(params.session!)
-      return Response.json(result, { headers: NO_STORE })
+      const stopped = await actions.stop(params.session!)
+      if (stopped.outcome === "offline") throw new HttpError(409, NO_OWNER)
+      if (stopped.outcome === "unsupported") throw unsupportedError(stopped)
+      return Response.json(stopped.result, { headers: NO_STORE })
     }),
+    route("POST", "/api/sessions/:session/rename", "session", ({ request, params }) => rename(request, params.session!)),
     route("POST", "/api/sessions/:session/conversation", "session", ({ request, params }) => conversation(request, params.session!), true),
     route("GET", "/api/sessions/:session/models", "session", async ({ params }) =>
       Response.json(await spokes.request(ownerOf(params.session!), { op: "models", sessionID: params.session! }), { headers: NO_STORE })),
@@ -632,7 +1228,7 @@ export function startCentral(options: CentralOptions): Central {
       const change = modelPrefsInput(await request.json())
       await checkModelSelections(ownerOf(params.session!), params.session!, change)
       const reply = await spokes.request(ownerOf(params.session!), { op: "setModelPrefs", sessionID: params.session!, ...change })
-      const prefs = store.setModelPrefs(user.id, params.session!, change)
+      const prefs = await store.setModelPrefs(user.id, params.session!, change)
       return Response.json({ prefs, defaults: reply.defaults }, { headers: NO_STORE })
     }),
     route("GET", "/api/sessions/:session/timeline", "session", async ({ params, url }) => {
@@ -641,7 +1237,35 @@ export function startCentral(options: CentralOptions): Central {
       if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 200)) return error(400, "limit must be 1–200")
       const cursor = url.searchParams.get("cursor") ?? undefined
       if (cursor && cursor.length > 4096) return error(400, "cursor is too long")
-      return Response.json(await spokes.request(ownerOf(params.session!), { op: "timeline", sessionID: params.session!, ...(limit ? { limit } : {}), ...(cursor ? { cursor } : {}) }), { headers: NO_STORE })
+      // Newest-first mode: order=desc for the newest page, before=<older cursor> for the page before it.
+      const order = url.searchParams.get("order") ?? undefined
+      if (order !== undefined && order !== "asc" && order !== "desc") return error(400, "order must be asc or desc")
+      const before = url.searchParams.get("before") || undefined
+      if (before && before.length > 4096) return error(400, "before is too long")
+      if (cursor && (before || order === "desc")) return error(400, "cursor cannot be combined with before or order=desc")
+      try {
+        const page = await spokes.request(ownerOf(params.session!), {
+          op: "timeline",
+          sessionID: params.session!,
+          ...(limit ? { limit } : {}),
+          ...(cursor ? { cursor } : {}),
+          ...(order ? { order } : {}),
+          ...(before ? { before } : {}),
+        })
+        return Response.json(page, { headers: NO_STORE })
+      } catch (cause) {
+        // The row the cursor names is gone (history reverted or compacted): the console starts over.
+        if (cause instanceof SpokeError && cause.message.includes("Invalid timeline cursor")) return error(400, "Invalid timeline cursor")
+        throw cause
+      }
+    }),
+    // Agent messages the session sent or received (newest first), merged into the timeline by `at` (+ watch events).
+    route("GET", "/api/sessions/:session/messages", "session", async ({ params, url, user }) => {
+      const raw = url.searchParams.get("limit")
+      const limit = raw === null ? undefined : Number(raw)
+      if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 200)) return error(400, "limit must be 1–200")
+      const messages = await delivery.messages.list(user.id, { kind: "session", sessionID: params.session! }, limit === undefined ? {} : { limit })
+      return Response.json({ messages }, { headers: NO_STORE })
     }),
     route("GET", "/api/sessions/:session/timeline/messages/:message/parts/:part", "session", async ({ params }) =>
       Response.json(await spokes.request(ownerOf(params.session!), { op: "timelinePart", sessionID: params.session!, messageID: params.message!, partID: params.part! }), { headers: NO_STORE })),
@@ -662,11 +1286,9 @@ export function startCentral(options: CentralOptions): Central {
       const { patch } = await spokes.request(ownerOf(params.session!), { op: "diff", sessionID: params.session!, file })
       return patch ? Response.json(patch, { headers: NO_STORE }) : error(404, "No changes for that file")
     }),
-    route("POST", "/api/sessions/:session/read", "session", ({ params, user, device }) => {
-      const reads = store.markRead(user.id, params.session!, Date.now())
-      for (const listener of [...listeners]) {
-        if (listener.userID === user.id && listener.deviceID !== device.id) listener.send({ type: "reads", reads })
-      }
+    route("POST", "/api/sessions/:session/read", "session", async ({ params, user, device }) => {
+      const reads = await store.markRead(user.id, params.session!, Date.now())
+      toUser(user.id, { type: "reads", reads }, device.id)
       return Response.json({ reads }, { headers: NO_STORE })
     }),
 
@@ -675,7 +1297,7 @@ export function startCentral(options: CentralOptions): Central {
     route("DELETE", "/api/machines/:machine", "machine", ({ params, user }) => revokeMachine(params.machine!, user)),
 
     // admins: users, machines, devices, audit, enrollments, the server speech default
-    route("GET", "/api/enrollments", "admin", () => Response.json({ enrollments: auth.pendingEnrollments() })),
+    route("GET", "/api/enrollments", "admin", async () => Response.json({ enrollments: await auth.pendingEnrollments() })),
     route("GET", "/api/admin/users", "admin", () => Response.json(store.users().map(userRow))),
     route("PUT", "/api/admin/users/:id", "admin", async ({ request, params, user }) => updateUser(params.id!, await body(request), user)),
     route("GET", "/api/admin/machines", "admin", () => {
@@ -697,16 +1319,49 @@ export function startCentral(options: CentralOptions): Central {
       )
     }),
     route("DELETE", "/api/admin/machines/:id", "admin", ({ params, user }) => revokeMachine(params.id!, user)),
-    route("DELETE", "/api/admin/devices/:id", "admin", ({ params, user }) => {
-      if (!store.removeDevice(params.id!)) return error(404, "No such device")
-      store.audit({ actor: user.id, action: "device.revoke", target: params.id! })
+    route("DELETE", "/api/admin/devices/:id", "admin", async ({ params, user }) => {
+      if (!await store.removeDevice(params.id!)) return error(404, "No such device")
+      await store.audit({ actor: user.id, action: "device.revoke", target: params.id! })
       return new Response(null, { status: 204 })
     }),
     route("GET", "/api/admin/audit", "admin", () => Response.json(store.auditLog())),
+    // The hub-wide agent kill switch: pauses every agent action for every user (reading and messaging still work).
+    route("GET", "/api/admin/agents/acting", "admin", () => Response.json({ enabled: !store.actingPaused() }, { headers: NO_STORE })),
+    route("PUT", "/api/admin/agents/acting", "admin", async ({ request, user }) => {
+      const enabled = (await body(request)).enabled
+      if (typeof enabled !== "boolean") return error(400, "enabled must be true or false")
+      await store.setActingPaused(!enabled)
+      await store.audit({ actor: user.id, action: enabled ? "agents.acting.resume" : "agents.acting.pause" })
+      return Response.json({ enabled }, { headers: NO_STORE })
+    }),
+    // Decisions (asks to @me): the user's own; answered only here (tap: the console cookie, not a device token).
+    route("GET", "/api/decisions", "user", async ({ url, user }) => {
+      try {
+        return Response.json({ decisions: await decisions.list(user.id, { ...optionalState(url) }) }, { headers: NO_STORE })
+      } catch (cause) {
+        return decisionFailure(cause)
+      }
+    }),
+    route("GET", "/api/decisions/:id", "user", async ({ params, user }) => {
+      const decision = await decisions.get(user.id, params.id!)
+      return decision ? Response.json({ decision }, { headers: NO_STORE }) : error(404, "No such decision", "not_found")
+    }),
+    route("POST", "/api/decisions/:id/answer", "user", async ({ request, params, user, device }) => {
+      const input = await body(request)
+      const via = (await resolveActor.mode(request)) === "bearer" ? "device-token" : "cookie"
+      try {
+        const answered = await decisions.answer(user.id, params.id!, decisionAnswer(input), { kind: "user", userID: user.id, deviceID: device.id, via })
+        if (answered.reply) feed.publish(user.id, answered.reply)
+        await store.audit({ actor: user.id, action: "decision.answer", target: params.id!, detail: answered.decision.answer?.option ?? "text" })
+        return Response.json(answered, { headers: NO_STORE })
+      } catch (cause) {
+        return decisionFailure(cause)
+      }
+    }),
     route("GET", "/api/settings/speech/default", "admin", () => Response.json(speechSettings.view(), { headers: NO_STORE })),
     route("PUT", "/api/settings/speech/default", "admin", async ({ request, user }) => {
-      const view = speechSettings.update(await request.json())
-      store.audit({ actor: user.id, action: "speech.default" })
+      const view = await speechSettings.update(await request.json())
+      await store.audit({ actor: user.id, action: "speech.default" })
       return Response.json(view, { headers: NO_STORE })
     }),
   ]
@@ -725,7 +1380,11 @@ export function startCentral(options: CentralOptions): Central {
 
   async function api(request: Request, server: Server<SpokeSocketData>, url: URL): Promise<Response> {
     const method = request.method
-    if (method !== "GET" && method !== "HEAD" && !sameOrigin(request)) {
+    const mode = await resolveActor.mode(request)
+    if (mode === "mixed") return error(400, "Send the device cookie or a bearer token, not both", "invalid")
+    // Bearer requests (device tokens of native apps) are not CSRF-prone; cookie writes must be same-origin (a
+    // foreign bearer next to the cookie, e.g. from an auth proxy, is ignored: still a cookie request).
+    if (mode !== "bearer" && method !== "GET" && method !== "HEAD" && !sameOrigin(request) && !credentialFree(request, mode, url)) {
       return error(403, "Cross-origin request refused")
     }
     const found = findRoute(method, url.pathname)
@@ -734,11 +1393,16 @@ export function startCentral(options: CentralOptions): Central {
       return await found.route.handle({ request, server, url, params: found.params } as Context)
     }
 
-    const resolved = deviceFor(request)
-    if (!resolved) return error(401, "This device is not paired")
+    const resolved = await resolveActor(request)
+    if (!resolved.ok) {
+      if (resolved.reason === "expired") return error(401, "Token expired", "token_expired")
+      return resolved.bearer ? error(401, "Invalid or revoked token", "unauthorized") : error(401, "This device is not paired")
+    }
+    // Console routes are for the user's devices (cookie or device token) only, never session or app tokens.
+    if (resolved.actor.kind !== "user" || !resolved.device) return error(403, "This token cannot be used here", "forbidden")
     const { device, user } = resolved
-    store.touchDevice(device.id)
-    store.touchUser(user.id)
+    void store.touchDevice(device.id)
+    void store.touchUser(user.id)
     if (!found) return error(404, "Not found")
 
     const { route: matched, params } = found
@@ -748,7 +1412,7 @@ export function startCentral(options: CentralOptions): Central {
         break
       case "session":
         // Foreign and unknown sessions answer alike, so IDs don't leak.
-        if (!registry.owns(user.id, params.session!)) return error(404, "Not found")
+        if (!registry.owns(user.id, params.session!) && !(OFFLINE_SESSION_ROUTES.has(matched.path) && knownOffline(user.id, params.session!))) return error(404, "Not found")
         // Sessions listed for discovery only: nothing but enabling voice (and presence) reaches them.
         if (matched.exposed && registry.exposed(params.session!) === false) return error(403, NOT_EXPOSED, "not_exposed")
         break
@@ -759,17 +1423,18 @@ export function startCentral(options: CentralOptions): Central {
     return await matched.handle({ request, server, url, params, device, user })
   }
 
-  function decideEnrollment(code: string, status: "approved" | "denied", user: UserRecord): Response {
-    const machineName = auth.decide(code, status, user.id)
+  async function decideEnrollment(code: string, status: "approved" | "denied", user: UserRecord): Promise<Response> {
+    const machineName = await auth.decide(code, status, user.id)
     if (machineName === undefined) return error(404, "No pending enrollment with that code")
-    store.audit({ actor: user.id, action: status === "approved" ? "machine.approve" : "machine.deny", detail: machineName })
+    await store.audit({ actor: user.id, action: status === "approved" ? "machine.approve" : "machine.deny", detail: machineName })
     broadcast({ type: "enrollment" }, { admins: true })
     return new Response(null, { status: 204 })
   }
 
-  function revokeMachine(id: string, user: UserRecord): Response {
-    if (!store.revokeMachine(id)) return error(404, "No such machine")
-    store.audit({ actor: user.id, action: "machine.revoke", target: id })
+  async function revokeMachine(id: string, user: UserRecord): Promise<Response> {
+    if (!await store.revokeMachine(id)) return error(404, "No such machine")
+    await store.bumpMachineEpoch(id)
+    await store.audit({ actor: user.id, action: "machine.revoke", target: id })
     spokes.closeMachine(id, "revoked")
     broadcast({ type: "catalog" })
     return new Response(null, { status: 204 })
@@ -790,7 +1455,7 @@ export function startCentral(options: CentralOptions): Central {
   }
 
   /** PUT /api/admin/users/:id {role?, disabled?}: the last active admin can be neither demoted nor disabled. */
-  function updateUser(id: string, input: Record<string, unknown>, actor: UserRecord): Response {
+  async function updateUser(id: string, input: Record<string, unknown>, actor: UserRecord): Promise<Response> {
     const target = store.user(id)
     if (!target) return error(404, "No such user")
     const { role, disabled } = input
@@ -802,12 +1467,13 @@ export function startCentral(options: CentralOptions): Central {
     if (activeAdmin(target) && !activeAdmin(after) && store.users().filter(activeAdmin).length <= 1) {
       return error(409, "Cannot demote or disable the last active admin. Make someone else an admin first.")
     }
-    if (role && role !== target.role) store.audit({ actor: actor.id, action: "user.role", target: id, detail: role })
+    if (role && role !== target.role) await store.audit({ actor: actor.id, action: "user.role", target: id, detail: role })
     if (disabled !== undefined && disabled !== (target.disabled === true)) {
-      store.audit({ actor: actor.id, action: disabled ? "user.disable" : "user.enable", target: id })
+      await store.audit({ actor: actor.id, action: disabled ? "user.disable" : "user.enable", target: id })
     }
-    store.setUser(id, { ...(role ? { role: role as "admin" | "user" } : {}), ...(disabled !== undefined ? { disabled } : {}) })
+    await store.setUser(id, { ...(role ? { role: role as "admin" | "user" } : {}), ...(disabled !== undefined ? { disabled } : {}) })
     if (disabled === true) {
+      await store.bumpUserEpoch(id)
       // Their machines go offline at once; their browsers get 401 from now on and lose their event streams.
       for (const machine of store.machines()) if (machine.ownerID === id) spokes.closeMachine(machine.id, "revoked")
       broadcast({ type: "catalog" })
@@ -829,26 +1495,30 @@ export function startCentral(options: CentralOptions): Central {
       : undefined
     if (!text && !images) return error(400, "Empty prompt")
     if (text.length > MAX_PROMPT_CHARS) return error(400, `Prompt longer than ${MAX_PROMPT_CHARS} characters`)
-    const attached = images ? { images } : {}
-    const connID = ownerOf(sessionID)
-    // While anything in the tree runs, typed input redirects the current work instead of queueing.
-    if (registry.running(sessionID)) {
-      const { inboxID } = await spokes.request(connID, { op: "steer", sessionID, text, ...attached })
-      return Response.json({ mode: "steer", inboxID }, { status: 202 })
-    }
-    // A stop or interrupt releases the lock and answers this request at once, even if the spoke never does.
-    let cancel = () => {}
-    const stopped = new Promise<TurnResult>((resolve) => {
-      cancel = () => resolve({ outcome: "interrupted", message: "Stopped", reply: "" })
-    })
-    const release = registry.beginTurn(sessionID, () => cancel())
+    // A turn may run for minutes: this request never times out (a stop or interrupt still answers it at once).
     server.timeout(request, 0)
-    try {
-      const voiceStyle = registry.exposed(sessionID) === true
-      return Response.json(await Promise.race([spokes.request(connID, { op: "turn", sessionID, text, voiceStyle, ...attached }), stopped]))
-    } finally {
-      release()
+    const started = await actions.prompt({ sessionID, text, ...(images ? { images } : {}), resetHops: true })
+    if (started.outcome === "offline") throw new HttpError(409, NO_OWNER)
+    if (started.outcome === "unsupported") throw unsupportedError(started)
+    if (started.mode === "steer") return Response.json({ mode: "steer", inboxID: started.inboxID }, { status: 202 })
+    const result = started.result
+    if (!/(^|[\s,])respond-async\b/i.test(request.headers.get("prefer") ?? "")) return Response.json(await result)
+    // Asynchronous: answer quick results (and refusals) as usual; a turn still running is accepted (202) and its
+    // result goes to the owner's consoles as an SSE `turn` event (the reply itself streams as deltas meanwhile).
+    const early = await Promise.race([result.then((value) => ({ value }), (cause: unknown) => ({ cause })), sleep(options.timing?.turnAcceptMs ?? TURN_ACCEPT_MS)])
+    if (early) {
+      if ("cause" in early) throw early.cause
+      return Response.json(early.value)
     }
+    const tenant = registry.sessionTenant(sessionID)
+    void result.then(
+      (value) => broadcast({ type: "turn", sessionID, ...value }, { tenant }),
+      (cause: unknown) => {
+        const message = cause instanceof Error ? cause.message : String(cause)
+        broadcast({ type: "turn", sessionID, ...(cause instanceof RequestTimeoutError ? { outcome: "timeout" } : { outcome: "failed", message }), reply: "" }, { tenant })
+      },
+    )
+    return Response.json({ mode: "turn" }, { status: 202, headers: { "preference-applied": "respond-async" } })
   }
 
   /** GET …/timeline/messages/:message/files/:index: one image of a user message, as bytes. */
@@ -887,10 +1557,11 @@ export function startCentral(options: CentralOptions): Central {
     }
   }
 
-  /** Connection that owns the session, or a 409. */
-  function ownerOf(sessionID: string): string {
+  /** Connection that owns the session, or a 409; also a 409 (code unsupported) when it lacks the core op `feature`. */
+  function ownerOf(sessionID: string, feature?: CoreOp): string {
     const connID = registry.owner(sessionID)
     if (!connID) throw new HttpError(409, NO_OWNER)
+    if (feature && !registry.supports(connID, feature)) throw unsupportedError({ feature, harness: registry.harnessOf(connID) ?? "unknown" })
     return connID
   }
 
@@ -900,11 +1571,61 @@ export function startCentral(options: CentralOptions): Central {
     const text = typeof raw === "string" ? raw.trim() : ""
     if (!text) return error(400, "Empty utterance")
     if (text.length > MAX_UTTERANCE_CHARS) return error(400, `Utterance longer than ${MAX_UTTERANCE_CHARS} characters`)
-    const { inboxID } = await spokes.request(ownerOf(sessionID), { op: "steer", sessionID, text })
+    const connID = ownerOf(sessionID, "steer")
+    await humanTurn(sessionID)
+    const { inboxID } = await spokes.request(connID, { op: "steer", sessionID, text })
     registry.trackUtterance(sessionID, inboxID)
     return Response.json({ inboxID }, { status: 202 })
   }
 
+  /** Renames a session in OpenCode through its owner process, falling back to other processes that report it. */
+  async function rename(request: Request, sessionID: string): Promise<Response> {
+    const json = await body(request)
+    if (json.auto !== undefined) {
+      if (json.auto !== true) return error(400, "Expected {auto: true} or {title}")
+      return autoName(sessionID)
+    }
+    const raw = json.title
+    const title = typeof raw === "string" ? raw.trim() : ""
+    if (!title) return error(400, "Expected {title}: a non-empty title")
+    if (title.length > MAX_TITLE_CHARS) return error(400, `Title must be at most ${MAX_TITLE_CHARS} characters`)
+    const targets = registry.sessionTargets(sessionID)
+    if (!targets.length) throw new HttpError(409, NO_OWNER)
+    let failure: unknown
+    for (const connID of targets) {
+      try {
+        const result = await spokes.request(connID, { op: "rename", sessionID, title })
+        return Response.json({ title: typeof result?.title === "string" ? result.title : title }, { headers: NO_STORE })
+      } catch (cause) {
+        failure ??= cause
+      }
+    }
+    throw failure
+  }
+
+  /**
+   * Has OpenCode regenerate the title with its title agent, through the processes reporting the session that
+   * support it (older spokes drop the op): 200 {title} or {title, unchanged}, 202 {pending} while generating.
+   */
+  async function autoName(sessionID: string): Promise<Response> {
+    const reporters = registry.sessionTargets(sessionID)
+    if (!reporters.length) throw new HttpError(409, NO_OWNER)
+    const targets = reporters.filter((connID) => registry.supports(connID, "autoName"))
+    if (!targets.length) throw new HttpError(409, AUTO_NAME_OUTDATED, "plugin_outdated")
+    let failure: unknown
+    for (const connID of targets) {
+      try {
+        const result = await spokes.request(connID, { op: "autoName", sessionID })
+        if (result?.pending) return Response.json({ pending: true }, { status: 202, headers: NO_STORE })
+        if (typeof result?.title !== "string") throw new SpokeError("OpenCode did not report a title")
+        return Response.json({ title: result.title, ...(result.unchanged ? { unchanged: true } : {}) }, { headers: NO_STORE })
+      } catch (cause) {
+        failure ??= cause
+      }
+    }
+    throw failure
+  }
+
   async function conversation(request: Request, sessionID: string): Promise<Response> {
     const on = (await body(request)).on
     if (typeof on !== "boolean") return error(400, "Expected {on: boolean}")
@@ -968,22 +1689,9 @@ export function startCentral(options: CentralOptions): Central {
     const input = await body(request)
     const decision = input.decision as PermissionDecision
     if (typeof input.requestID !== "string" || !DECISIONS.has(decision)) return error(400, "Invalid decision")
-    const targets = registry.permissionTargets(rootID, input.requestID)
-    if (!targets.length) return error(409, PERMISSION_GONE, "gone")
-    // Try every process that saw the request: only the one (and the location) running the session holds it.
-    let failure: unknown
-    for (const target of targets) {
-      try {
-        const result = await spokes.request(target.connID, { op: "permission", sessionID: target.sessionID, requestID: input.requestID, decision })
-        if (!result?.gone) return new Response(null, { status: 204 })
-      } catch (cause) {
-        // Older spokes pass OpenCode's "Permission request not found" through as an error.
-        if (!/not found/i.test(cause instanceof Error ? cause.message : String(cause))) failure ??= cause
-      }
-    }
-    if (failure) throw failure
-    registry.dropPermission(input.requestID)
-    return error(409, PERMISSION_GONE, "gone")
+    const answered = await actions.answerPermission({ rootID, requestID: input.requestID, decision })
+    if (answered.outcome === "unsupported") throw unsupportedError(answered)
+    return answered.outcome === "done" ? new Response(null, { status: 204 }) : error(409, PERMISSION_GONE, "gone")
   }
 
   /** Answers or cancels a pending form (question) in the session's tree, through a process that holds it. */
@@ -996,23 +1704,11 @@ export function startCentral(options: CentralOptions): Central {
       const problem = formAnswerProblem(input.answer)
       if (problem) return error(400, problem)
     }
-    const targets = registry.formTargets(rootID, input.formID)
-    if (!targets.length) return error(409, PERMISSION_GONE, "gone")
-    let failure: unknown
-    for (const target of targets) {
-      const req = cancel
-        ? { op: "form" as const, sessionID: target.sessionID, formID: input.formID, cancel: true as const }
-        : { op: "form" as const, sessionID: target.sessionID, formID: input.formID, answer: input.answer as FormAnswer }
-      try {
-        const result = await spokes.request(target.connID, req)
-        if (!result?.gone) return new Response(null, { status: 204 })
-      } catch (cause) {
-        failure ??= cause
-      }
-    }
-    if (failure) throw failure
-    registry.dropForm(input.formID)
-    return error(409, PERMISSION_GONE, "gone")
+    const answered = await actions.answerForm(
+      cancel ? { rootID, formID: input.formID, cancel: true } : { rootID, formID: input.formID, answer: input.answer as FormAnswer },
+    )
+    if (answered.outcome === "unsupported") throw unsupportedError(answered)
+    return answered.outcome === "done" ? new Response(null, { status: 204 }) : error(409, PERMISSION_GONE, "gone")
   }
 
   async function transcribe(request: Request, speech: Speech): Promise<Response> {
@@ -1027,7 +1723,14 @@ export function startCentral(options: CentralOptions): Central {
     return Response.json({ text: await speech.transcribe(audio, format) })
   }
 
-  function events(signal: AbortSignal, userID: string, deviceID: string): Response {
+  /**
+   * The live stream. Every message has an id; with `lastID` (Last-Event-ID or ?last=) the hub replays what came
+   * after it when its log still covers the gap (one fresh catalog if catalogs changed meanwhile), else it starts
+   * over: the catalog, then a `resync` marker so the page refetches what it shows. Heartbeats are `ping` events.
+   */
+  function events(signal: AbortSignal, userID: string, deviceID: string, options: { lastID?: string; lite: boolean; session?: string }): Response {
+    // Draining: come back (to another pod) shortly.
+    if (draining) return new Response(SSE_RETRY, { headers: { "content-type": "text/event-stream", "cache-control": "no-cache" } })
     const encoder = new TextEncoder()
     let cleanup = () => {}
     const stream = new ReadableStream<Uint8Array>({
@@ -1042,17 +1745,38 @@ export function startCentral(options: CentralOptions): Central {
         const listener: Listener = {
           userID,
           deviceID,
-          send: (message) => write(`data: ${JSON.stringify(message)}\n\n`),
+          lite: options.lite,
+          ...(options.session ? { session: options.session } : {}),
+          send: (message, id) => write(`${id ? `id: ${id}\n` : ""}data: ${JSON.stringify(message)}\n\n`),
           close: () => {
             cleanup()
             try {
               controller.close()
             } catch {}
           },
+          end: (retryMs) => {
+            write(`retry: ${retryMs}\n\n`)
+            listener.close()
+          },
+        }
+        if (live) return clusterStream(listener, write)
+        eventLog.open(userID)
+        const missed = options.lastID ? eventLog.since(userID, options.lastID) : undefined
+        if (missed) {
+          let catalog = false
+          for (const { id, message, exceptDevice } of missed) {
+            if (exceptDevice === deviceID) continue
+            if (message.type === "catalog") catalog = true
+            else if (wants(listener, message)) listener.send(message, id)
+          }
+          if (catalog) listener.send({ type: "catalog", machines: machines(userID) }, eventLog.latest(userID))
+        } else {
+          listener.send({ type: "catalog", machines: machines(userID) }, eventLog.latest(userID))
+          if (options.lastID) listener.send({ type: "resync" }, eventLog.latest(userID))
         }
-        listener.send({ type: "catalog", machines: machines(userID) })
         listeners.add(listener)
-        const heartbeat = setInterval(() => write(": ping\n\n"), SSE_HEARTBEAT_MS)
+        // A named event (not a comment) so the page sees it and can tell a live stream from a dead one.
+        const heartbeat = setInterval(() => write("event: ping\ndata: 0\n\n"), heartbeatMs)
         cleanup = () => {
           clearInterval(heartbeat)
           listeners.delete(listener)
@@ -1063,12 +1787,104 @@ export function startCentral(options: CentralOptions): Central {
         cleanup()
       },
     })
+    /**
+     * Cluster mode: the user's live events from every pod; the replay comes from the shared EventLog. Events that
+     * arrive while it is read wait (in order) and then go out, except those the replay already sent.
+     */
+    async function clusterStream(listener: Listener, write: (chunk: string) => void): Promise<void> {
+      let pending: LiveEvent[] | undefined = []
+      const replayed = new Set<string>()
+      const forward = (event: LiveEvent) => {
+        if (event.exceptDevice === deviceID || (event.id !== undefined && replayed.has(event.id))) return
+        if (wants(listener, event.message)) listener.send(event.message, event.id)
+      }
+      const subscription = live!.subscribe(userID, (event) => (pending ? pending.push(event) : forward(event)))
+      listeners.add(listener)
+      const heartbeat = setInterval(() => write("event: ping\ndata: 0\n\n"), heartbeatMs)
+      cleanup = () => {
+        clearInterval(heartbeat)
+        listeners.delete(listener)
+        subscription.close()
+      }
+      signal.addEventListener("abort", () => cleanup(), { once: true })
+      try {
+        await subscription.ready
+        const missed = options.lastID ? await backends.events.since(userID, options.lastID) : undefined
+        if (missed && "events" in missed) {
+          for (const { id, message, exceptDevice } of missed.events) {
+            replayed.add(id)
+            if (exceptDevice !== deviceID && wants(listener, message)) listener.send(message, id)
+          }
+          // Catalogs are not logged in a cluster: a resumed stream always gets the current one.
+          listener.send({ type: "catalog", machines: machines(userID) })
+        } else {
+          const latest = await backends.events.latest(userID)
+          listener.send({ type: "catalog", machines: machines(userID) }, latest)
+          if (options.lastID) listener.send({ type: "resync" }, latest)
+        }
+      } catch (cause) {
+        console.error(`[hub] live stream did not start: ${(cause as Error).message}`)
+        listener.close()
+        return
+      }
+      const waiting = pending
+      pending = undefined
+      for (const event of waiting) forward(event)
+    }
     return new Response(stream, {
       headers: { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" },
     })
   }
 
-  function staticFile(pathname: string): Response {
+  /** /readyz (design §10): 503 while draining or (cluster mode) when the database or Valkey does not answer in time. */
+  async function readyz(): Promise<Response> {
+    if (draining) return Response.json({ ok: false, draining: true }, { status: 503, headers: NO_STORE })
+    if (config.cluster) {
+      let timer: ReturnType<typeof setTimeout> | undefined
+      const late = new Promise<never>((_, reject) => (timer = setTimeout(() => reject(new Error("timed out")), READY_CHECK_MS)))
+      try {
+        await Promise.race([Promise.all([backends.state.ping?.(), backends.kv.ping?.()]), late])
+      } catch {
+        // A public endpoint: no backend detail (hosts, users) in the answer.
+        return Response.json({ ok: false, error: "database or Valkey not reachable" }, { status: 503, headers: NO_STORE })
+      } finally {
+        clearTimeout(timer)
+      }
+    }
+    return Response.json({ ok: true }, { headers: NO_STORE })
+  }
+
+  async function runDrain(drainOptions: DrainOptions): Promise<void> {
+    const timeoutMs = drainOptions.timeoutMs ?? options.timing?.drainTimeoutMs ?? DRAIN_TIMEOUT_MS
+    const retryAfterMs = drainOptions.retryAfterMs ?? options.timing?.drainRetryAfterMs ?? DRAIN_RETRY_AFTER_MS
+    // Refuse new WebSockets and requests; bye each connection once its requests in flight are answered.
+    const connections = spokes.drain({ timeoutMs, retryAfterMs })
+    // Step down at once (releasing the leases), so another pod takes the timed jobs over.
+    await Promise.allSettled(leaders.map((loop) => loop.stop()))
+    // Withdraw this pod's slices: the other pods stop showing its connections (the new pod republishes them).
+    await view?.stop().catch((cause) => console.error(`[hub] cluster view not withdrawn: ${(cause as Error).message}`))
+    for (const listener of [...listeners]) listener.end(SSE_RETRY_MS)
+    drainSignal.abort()
+    await connections
+  }
+
+  /** Compressed copies of hashed assets, made once per file and encoding (they never change). */
+  const compressed = new Map<string, Promise<Uint8Array>>()
+  function compress(name: string, bytes: Uint8Array, encoding: "br" | "gzip"): Promise<Uint8Array> {
+    const key = `${encoding} ${name}`
+    let done = compressed.get(key)
+    if (!done) {
+      done =
+        encoding === "br"
+          ? brotli(bytes, { params: { [zlib.BROTLI_PARAM_QUALITY]: 6, [zlib.BROTLI_PARAM_SIZE_HINT]: bytes.length } })
+          : gzipAsync(bytes, { level: 9 })
+      done.catch(() => compressed.delete(key))
+      compressed.set(key, done)
+    }
+    return done
+  }
+
+  async function staticFile(pathname: string, acceptEncoding: string | null): Promise<Response> {
     const name = APP_ROUTES.test(pathname) ? "index.html" : STATIC_PATH.test(pathname) ? pathname.slice(1) : undefined
     const type = name && CONTENT_TYPES[path.extname(name).toLowerCase()]
     const bytes = name && type ? web.read(name) : undefined
@@ -1082,6 +1898,16 @@ export function startCentral(options: CentralOptions): Central {
       headers.set("service-worker-allowed", "/")
     } else if (type.startsWith("text/html")) {
       headers.set("cache-control", "no-cache")
+    } else if (HASHED_ASSET.test(name)) {
+      headers.set("cache-control", IMMUTABLE)
+      if (COMPRESSIBLE.has(path.extname(name).toLowerCase()) && bytes.length >= MIN_COMPRESS_BYTES) {
+        headers.set("vary", "Accept-Encoding")
+        const encoding = pickEncoding(acceptEncoding)
+        if (encoding) {
+          headers.set("content-encoding", encoding)
+          return new Response(new Uint8Array(await compress(name, bytes, encoding)), { headers })
+        }
+      }
     }
     return new Response(bytes, { headers })
   }
@@ -1092,20 +1918,85 @@ export function startCentral(options: CentralOptions): Central {
     store,
     auth,
     registry,
+    nodes,
     spokes,
     push,
     speechSettings,
-    routes: routes.map(({ method, path, access }) => ({ method, path, access })),
+    backends,
+    delivery,
+    decisions,
+    acting,
+    launches,
+    launchFeed,
+    launchTokens,
+    webhooks,
+    routes: [...routes.map(({ method, path, access }) => ({ method, path, access })), ...agent.routes.map(({ method, path }) => ({ method, path, access: "agent" as const }))],
+    drain(drainOptions: DrainOptions = {}) {
+      draining ??= runDrain(drainOptions)
+      return draining
+    },
     async stop() {
-      spokes.stop()
+      // Step down first (releasing the leases), so another pod takes the timed jobs over at once.
+      await Promise.allSettled([...leaders.map((loop) => loop.stop()), recommendations?.stop()])
+      launches.shutdown()
+      webhooks.stop()
+      tokenPush.stop()
+      delivery.stop()
+      decisions.stop()
+      await spokes.stop()
+      await view?.stop().catch((cause) => console.error(`[hub] cluster view not stopped: ${(cause as Error).message}`))
       for (const listener of [...listeners]) listeners.delete(listener)
+      await Promise.all([live?.stop(), feed.detach(), launchFeed.detach()]).catch((cause) => console.error(`[hub] live fan-out not stopped: ${(cause as Error).message}`))
       // Bun 1.3.5 quirk: once the server has closed a WebSocket itself, stop(true)'s promise never
       // resolves even though the listener is closed. Don't wait on it forever.
       await Promise.race([server.stop(true), Bun.sleep(250)])
+      await backends.state.flush?.().catch((cause) => console.error(`[hub] agent state not saved: ${(cause as Error).message}`))
+      await store.close()
+      if (ownBackends) await backends.close?.().catch((cause) => console.error(`[hub] backends not closed: ${(cause as Error).message}`))
     },
   }
 }
 
+/** The state filter of GET /api/decisions (throws invalid). */
+const optionalState = (url: URL): { state?: Decision["state"] } => {
+  const state = decisionStateQuery(url.searchParams.get("state"))
+  return state ? { state } : {}
+}
+
+/** {option?, text?} of a Decision answer (types only; Decisions validates). */
+function decisionAnswer(input: Record<string, unknown>): { option?: string; text?: string } {
+  for (const key of ["option", "text"] as const) {
+    if (input[key] !== undefined && typeof input[key] !== "string") throw new AgentError("invalid", `${key} must be a string`)
+  }
+  return { ...(typeof input.option === "string" ? { option: input.option } : {}), ...(typeof input.text === "string" ? { text: input.text } : {}) }
+}
+
+/** Console envelope for a Decision failure: gone → 409 (the web app's toast), the rest by code. */
+function decisionFailure(cause: unknown): Response {
+  if (!(cause instanceof AgentError)) throw cause
+  const status: Partial<Record<string, number>> = { gone: 409, not_found: 404, forbidden: 403, invalid: 400, rate_limited: 429, paused: 423 }
+  return Response.json({ error: cause.message, code: cause.code, ...(cause.options.hint ? { hint: cause.options.hint } : {}) }, { status: status[cause.code] ?? 500 })
+}
+
+/** Deep-link scheme of the native apps: `hubapp://link?hub=<public URL>&code=<link code>`. */
+export const APP_SCHEME = "hubapp"
+
+/**
+ * Public writes a native app makes with no ambient credential at all (no cookie, no bearer, no Origin or
+ * Referer): not CSRF-prone, the single-use code in the body is the credential. Every other write keeps the
+ * same-origin check, and so does any request carrying a cookie or a browser Origin.
+ */
+const CREDENTIAL_FREE = new Set(["POST /api/devices/redeem"])
+
+function credentialFree(request: Request, mode: CredentialMode, url: URL): boolean {
+  return (
+    mode === "none" &&
+    !request.headers.has("origin") &&
+    !request.headers.has("referer") &&
+    CREDENTIAL_FREE.has(`${request.method} ${url.pathname}`)
+  )
+}
+
 function userView(user: UserRecord) {
   return { id: user.id, ...(user.email ? { email: user.email } : {}), ...(user.name ? { name: user.name } : {}), role: user.role }
 }
@@ -1134,11 +2025,11 @@ function pushTarget(value: unknown): { endpoint: string; keys: { p256dh: string;
   return { endpoint, keys: { p256dh, auth } }
 }
 
-/** Boolean pref fields (and 0.5.0's `blocked`) from untrusted input; undefined when nothing applies. */
+/** Boolean pref fields (and the legacy `blocked` and `finished`) from untrusted input; undefined when nothing applies. */
 function prefsInput(value: unknown): (Partial<PushPrefs> & LegacyPushPrefs) | undefined {
   if (typeof value !== "object" || value === null) return undefined
   const prefs: Partial<PushPrefs> & LegacyPushPrefs = {}
-  for (const key of [...PUSH_PREF_KEYS, "blocked"] as const) {
+  for (const key of [...PUSH_PREF_KEYS, "blocked", "finished"] as const) {
     const v = (value as Record<string, unknown>)[key]
     if (typeof v === "boolean") prefs[key] = v
   }
@@ -1148,7 +2039,10 @@ function prefsInput(value: unknown): (Partial<PushPrefs> & LegacyPushPrefs) | un
 /** PUT /api/prefs/view body: any of the four lists, each replacing the stored one. */
 function viewPrefsInput(value: unknown): Partial<ViewPrefs> {
   const invalid = () =>
-    new HttpError(400, `Expected {${VIEW_PREF_KEYS.join("?, ")}?}: lists of at most ${VIEW_PREF_MAX_ENTRIES} strings of at most ${VIEW_PREF_MAX_CHARS} characters`)
+    new HttpError(
+      400,
+      `Expected {${VIEW_PREF_KEYS.join("?, ")}?}: lists of at most ${VIEW_PREF_MAX_ENTRIES} (hiddenSessions: ${VIEW_PREF_MAX_ARCHIVED}) strings of at most ${VIEW_PREF_MAX_CHARS} characters`,
+    )
   if (typeof value !== "object" || value === null || Array.isArray(value)) throw invalid()
   const record = value as Record<string, unknown>
   if (Object.keys(record).some((key) => !(VIEW_PREF_KEYS as readonly string[]).includes(key))) throw invalid()
@@ -1156,7 +2050,7 @@ function viewPrefsInput(value: unknown): Partial<ViewPrefs> {
   for (const key of VIEW_PREF_KEYS) {
     const list = record[key]
     if (list === undefined) continue
-    if (!Array.isArray(list) || list.length > VIEW_PREF_MAX_ENTRIES) throw invalid()
+    if (!Array.isArray(list) || list.length > (key === "hiddenSessions" ? VIEW_PREF_MAX_ARCHIVED : VIEW_PREF_MAX_ENTRIES)) throw invalid()
     if (!list.every((entry) => typeof entry === "string" && entry.length > 0 && entry.length <= VIEW_PREF_MAX_CHARS)) throw invalid()
     out[key] = [...new Set(list as string[])]
   }
@@ -1192,6 +2086,8 @@ function param(raw: string): string {
   }
 }
 
+const sleep = (ms: number) => new Promise<undefined>((resolve) => setTimeout(() => resolve(undefined), ms))
+
 async function body(request: Request): Promise<Record<string, unknown>> {
   const value = (await request.json()) as unknown
   return typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : {}