@huynle/hub 0.6.0 → 0.7.1

package/src/spoke/spoke.ts

@@ -2,10 +2,20 @@
 // keeps the WebSocket to the central server, forwards exposed events, and executes the server's
 // requests (voice turns, permission replies, context reads) through the plugin context.
 import path from "node:path"
-import { readConfig, setSession, withServer, writeConfig, type Mode, type VoiceConfig, explicitVariant, formatModelRef, parseModelRef, plainModelRef, type ModelRef } from "../config"
+import { defaults, readConfig, setSession, withServer, writeConfig, type LaunchConfig, type Mode, type VoiceConfig, explicitVariant, formatModelRef, parseModelRef, plainModelRef, type ModelRef } from "../config"
 import { isLoopbackURL } from "../loopback"
 import {
   compactActivity,
+  COMPACTED_EVENTS,
+  FORWARDED_EVENTS,
+  HARNESS_OPENCODE,
+  isLaunchCreate,
+  SEED_JOBS_MAX,
+  SPOKE_FEATURES,
+  type DeliverRequest,
+  type DeliverResult,
+  type DeliveryMode,
+  type JobInfo,
   type HerdrWorkspace,
   type FormAnswer,
   type PermissionDecision,
@@ -13,6 +23,9 @@ import {
   type PromptImage,
   type ResultFor,
   type ServerRequest,
+  type SessionTokensRequest,
+  type ActTokensRequest,
+  type CreateRequest,
   type SessionModelPrefs,
   type SpokeRequest,
   type TerminalInfo,
@@ -20,15 +33,19 @@ import {
 } from "../protocol"
 import { extractReply } from "../reply"
 import { TurnTracker } from "../turns"
-import { boundedTimelinePart, timelineFile, timelineItems } from "./timeline"
+import { TimelineCache, boundedTimelinePart, newestPage, timelineFile, timelineItems } from "./timeline"
 import { SpokeConnection, type Backoff, type ConnectionState } from "./client"
 import { PROMPT_SOURCE, VOICE_AGENT } from "./conversation"
+import { DeliveryLedger, deliverMetadata, deliverText, harnessMessageID, InboxOrigins, planDelivery } from "./deliver"
 import { pollEnrollment, startEnrollment } from "./enroll"
 import { HerdrWatcher, openInHerdr, type HerdrRunner } from "./herdr"
 import type { LocalHubResult } from "./localhub"
+import { launchDirectoryProblem } from "./node-roots"
 import { PresenceBook } from "./presence"
+import { SessionTokenStore } from "./session-tokens"
 import { changeStats, contextUsage, filePatch, mcpServers } from "./summary"
 import { browserSessions, isExposed, isReported, SessionTracker, shouldForward, type EventLike, type SessionDetails } from "./tracker"
+import { renderTaskBoard, TaskBoard } from "./taskboard"
 import { watchConfig, type ConfigWatcher } from "./watch"
 
 export type SpokeErrorName = "not_connected" | "not_enrolled" | "invalid" | "unreachable"
@@ -76,15 +93,23 @@ export interface SpokeHost {
   readonly directory: string
   readonly opencodeVersion: string
   events(signal: AbortSignal): AsyncIterable<EventLike>
-  prompt(input: { sessionID: string; text: string; files?: readonly PromptFile[]; metadata: Record<string, unknown>; delivery?: "steer" }): Promise<{ id: string }>
+  /** `id`: a client message id (msg_…, OpenCode applies it once); `resume: false` admits without waking. */
+  prompt(input: { sessionID: string; text: string; files?: readonly PromptFile[]; metadata: Record<string, unknown>; delivery?: DeliveryMode; id?: string; resume?: boolean }): Promise<{ id: string }>
+  /**
+   * Admits text as a synthetic user message (OpenCode's session.synthetic): the model sees only `text`; the
+   * prompt hook does not run. `id` (msg_…) makes it idempotent; `resume: false` admits without waking.
+   * Absent: this OpenCode cannot take hub messages (no "deliver" feature).
+   */
+  synthetic?(input: { sessionID: string; id: string; text: string; metadata: Record<string, unknown>; delivery: DeliveryMode; resume: boolean }): Promise<{ id?: string }>
   context(sessionID: string): Promise<ReadonlyArray<unknown>>
   listModels?(): Promise<ReadonlyArray<unknown>>
   getSession(sessionID: string): Promise<HostSession>
   /**
    * Replies to a pending permission; "gone" when it is not pending here any more (answered, expired).
-   * `directory` is the session's directory when known (permissions are pending per location).
+   * `directory` is the session's directory when known (permissions are pending per location). `message`: a
+   * reject's reason, which OpenCode gives the model as the rejection's feedback.
    */
-  replyPermission(input: { sessionID: string; requestID: string; decision: PermissionDecision; directory?: string }): Promise<unknown>
+  replyPermission(input: { sessionID: string; requestID: string; decision: PermissionDecision; message?: string; directory?: string }): Promise<unknown>
   /**
    * Answers or cancels a pending form through OpenCode's API: "gone" when it is not pending any more,
    * "unavailable" when this process cannot reach its own server (then a TUI relays it, see formActions).
@@ -92,11 +117,25 @@ export interface SpokeHost {
    */
   replyForm?(input: FormAction): Promise<"replied" | "gone" | "unavailable">
   interrupt(sessionID: string): Promise<unknown>
+  /** Changes a session's settings in OpenCode (session.update); only the title is used. */
+  updateSession?(sessionID: string, input: { title?: string }): Promise<unknown>
+  /**
+   * Has OpenCode regenerate the session's title with its title agent (session.update with an empty title on
+   * this process's own server; the plugin API's update would set an empty title instead). Resolves when
+   * OpenCode is done ("done", whether or not the title changed); "unavailable" when the server cannot be reached.
+   */
+  generateTitle?(sessionID: string): Promise<"done" | "unavailable">
   switchAgent(sessionID: string, agent: string): Promise<unknown>
   switchModel(sessionID: string, model: ModelRef): Promise<unknown>
   hasAgent(id: string): Promise<boolean>
   /** The agent a session without an explicit selection runs with. */
   defaultAgent(): Promise<string | undefined>
+  /**
+   * What runs right now, from this process's own OpenCode server: sessions with a run in progress
+   * (session.active) and running shells in the given directories (shell.list). Used to show sessions that
+   * were already running when this process started, or while its event stream was down.
+   */
+  activity?(directories: readonly string[]): Promise<{ readonly active: readonly string[]; readonly jobs: ReadonlyArray<JobInfo & { readonly sessionID: string }> }>
   /**
    * Recent root sessions from the local service with their workspace (service processes only): those in
    * the history window (`days`, at most `max`), plus `include` (always listed: open, running, ...).
@@ -159,6 +198,21 @@ export interface SpokeOptions {
   readonly herdrSettleMs?: number
   /** How often expired TUI presence is checked (default 5 s). */
   readonly presenceCheckMs?: number
+  /** How long autoName waits for OpenCode's generated title before answering "pending" (default 20 s). */
+  readonly autoNameWaitMs?: number
+  /** After generation returns without a session.renamed event, how long to wait for it (default 1.5 s). */
+  readonly autoNameSettleMs?: number
+  /**
+   * The machine's node workspace roots (node.json, src/spoke/node-roots.ts), read on each launch create: a launch's
+   * directory must be under one. Absent: no roots, so launch creates are refused.
+   */
+  readonly workspaceRoots?: () => readonly string[]
+  /**
+   * Launch-bound mode (a spoke inside a launch's sandbox, src/config.ts LaunchConfig): connect to `hubURL` with the
+   * launch token and announce `launchID` in the hello; the machine config is never read, watched or written, and the
+   * spoke never enrols, starts a local hub or reads Herdr.
+   */
+  readonly launch?: LaunchConfig
 }
 
 export type EnrollmentState = "pending" | "approved" | "denied" | "expired" | "error"
@@ -215,11 +269,21 @@ const FALLBACK_AGENT = "build"
 const LOCAL_HUB_MAX_RETRY_MS = 15 * 60_000
 const ENROLL_RETRY_MS = 500
 const NOT_SHARED = "This session is not shared with voice"
+const CANNOT_AUTO_NAME = "This OpenCode process cannot auto-name sessions (its server cannot be reached); use /rename in its terminal"
+export const AUTO_NAME_WAIT_MS = 20_000
+/** Longest session title the hub sets (OpenCode's own titles are shorter). */
+export const MAX_TITLE_CHARS = 200
 const UNKNOWN_SESSION = "Unknown session"
 /** Events after which the service re-lists its sessions (other processes' sessions appear, change, go). */
 const LISTING_EVENTS = new Set(["session.created", "session.renamed", "session.deleted"])
 
 const errorText = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause))
+const LAUNCH_BOUND = "This spoke is bound to a launch; its hub connection is fixed by the launch config"
+
+/** The fixed config of a launch-bound spoke: always shared, no local hub, no Herdr. */
+function launchVoiceConfig(launch: LaunchConfig, machineName: string): VoiceConfig {
+  return { ...defaults(machineName), server: launch.hubURL, mode: "always", token: launch.token, autoStartLocalHub: false, herdr: false }
+}
 
 export class Spoke {
   private config: VoiceConfig
@@ -227,9 +291,24 @@ export class Spoke {
   private connection?: SpokeConnection
   private connectionKey = ""
   private readonly tracker = new SessionTracker()
+  /** Session tokens from the hub (sessionTokens op), for the sessions' shells (P1-T6). Never logged. */
+  private readonly tokens = new SessionTokenStore()
+  /**
+   * Act tokens from the hub (actTokens op): the credential for act verbs, kept apart from `tokens` so no shell
+   * ever gets one. Only actIdentity reads them (the OpenCode hub tool). Never logged, never in any environment.
+   */
+  private readonly actTokens = new SessionTokenStore()
+  /** The background workers each session started (the voice agent's task board). */
+  private readonly tasks = new TaskBoard()
   private readonly turns = new TurnTracker()
+  /** Timeline rows of sessions being paged through (30 s, dropped on any event of the session). */
+  private readonly timelines = new TimelineCache()
   private readonly voiceTurns = new Map<string, number>()
   private readonly running = new Set<string>()
+  /** Hub messages applied (by messageID), so a retry is not admitted again. */
+  private readonly deliveries = new DeliveryLedger()
+  /** Who put each inbox item into a session (forwarded with session.inbox.delivered). */
+  private readonly origins = new InboxOrigins()
   private readonly infoTried = new Map<string, number>()
   /** Sessions in conversation mode → the agent to restore when it ends (undefined: the default agent). */
   private readonly conversations = new Map<string, { previous?: string; previousModel?: ModelRef; voiceModel?: ModelRef }>()
@@ -237,6 +316,13 @@ export class Spoke {
   private readonly modelPrefs = new Map<string, SessionModelPrefs>()
   /** Per session with a Voice override applied: the model to restore when it is cleared, and the override. */
   private readonly voiceOverrides = new Map<string, { readonly previous?: ModelRef; readonly applied: ModelRef }>()
+  /**
+   * Session → its current model as last seen (getSession, our switchModel, OpenCode's session.model.selected),
+   * so an utterance needs no getSession round trip. Cleared when the event stream restarts (events may be lost).
+   */
+  private readonly sessionModels = new Map<string, { readonly model?: ModelRef }>()
+  /** Session → callbacks waiting for its next session.renamed event (autoName). */
+  private readonly renameWaiters = new Map<string, Set<(title: string) => void>>()
   private conversationChain: Promise<unknown> = Promise.resolve()
   private readonly abort = new AbortController()
   private snapshotTimer?: ReturnType<typeof setTimeout>
@@ -244,6 +330,8 @@ export class Spoke {
   private intervals: Array<ReturnType<typeof setInterval>> = []
   private enrollment?: { state: EnrollmentState; abort: AbortController }
   private started = false
+  /** A seedActivity call is in flight. */
+  private seeding = false
   /** Sessions shown by OpenCode TUIs (voice.presence). */
   private readonly presenceBook = new PresenceBook()
   /** Form replies waiting for a TUI to carry them out (when the plugin cannot reach its own server). */
@@ -275,19 +363,14 @@ export class Spoke {
     private readonly host: SpokeHost,
     private readonly options: SpokeOptions,
   ) {
-    this.config = readConfig(options.configFile, options.machineName)
+    this.config = options.launch ? launchVoiceConfig(options.launch, options.machineName) : readConfig(options.configFile, options.machineName)
     this.hub = { pending: false, nextAt: 0, cooldown: options.localHubRetryMs ?? 30_000 }
   }
 
   start(): void {
     if (this.started) return
     this.started = true
-    try {
-      this.watcher = watchConfig(this.options.configFile, this.options.machineName, (c) => this.apply(c), { pollMs: this.options.pollMs })
-      this.config = this.watcher.current()
-    } catch (cause) {
-      console.error("[hub] config watch failed", cause)
-    }
+    if (!this.options.launch) this.watch()
     void this.listen()
     this.apply(this.config)
     this.every(this.options.snapshotIntervalMs ?? 30_000, () => this.sendSnapshot())
@@ -298,6 +381,15 @@ export class Spoke {
     }
   }
 
+  private watch(): void {
+    try {
+      this.watcher = watchConfig(this.options.configFile, this.options.machineName, (c) => this.apply(c), { pollMs: this.options.pollMs })
+      this.config = this.watcher.current()
+    } catch (cause) {
+      console.error("[hub] config watch failed", cause)
+    }
+  }
+
   stop(): void {
     this.started = false
     this.abort.abort()
@@ -315,6 +407,8 @@ export class Spoke {
     this.connection?.stop()
     this.connection = undefined
     this.connectionKey = ""
+    this.tokens.clear()
+    this.actTokens.clear()
   }
 
   isVoiceTurn(sessionID: string): boolean {
@@ -335,6 +429,46 @@ export class Spoke {
     return this.config.workModel ?? (entry.previousModel ? formatModelRef(entry.previousModel) : undefined)
   }
 
+  /** The rendered task board of a session's workers (for the voice agent's context); undefined without any. */
+  taskBoard(sessionID: string): string | undefined {
+    return renderTaskBoard(this.tasks.children(sessionID), Date.now())
+  }
+
+  /**
+   * hub_task_stop: interrupts one of `callerID`'s workers (a session below it), or all its running workers, and
+   * whatever runs below them, deepest first. Never the caller itself, nor a session outside its tree.
+   */
+  async stopWorkers(callerID: string, input: { sessionID?: unknown; all?: unknown }): Promise<{ stopped: string[]; text: string }> {
+    let targets: string[]
+    if (input.all === true) {
+      targets = this.tasks
+        .children(callerID)
+        .filter((t) => t.state === "working" || t.state === "blocked")
+        .map((t) => t.id)
+      if (!targets.length) return { stopped: [], text: "None of your workers is running." }
+    } else if (typeof input.sessionID === "string" && input.sessionID) {
+      const id = input.sessionID
+      if (id === callerID || !this.tracker.lineage(id).slice(1).includes(callerID)) {
+        return { stopped: [], text: `${id} is not one of your workers; use a sessionID from your task board.` }
+      }
+      targets = [id]
+    } else return { stopped: [], text: "Pass the worker's sessionID from your task board, or all: true for every worker." }
+    const stopped: string[] = []
+    for (const target of targets) {
+      for (const id of [...this.tracker.runningBelow(target), target]) {
+        if (id === callerID) continue
+        try {
+          await this.host.interrupt(id)
+          stopped.push(id)
+        } catch {
+          // already settled
+        }
+      }
+    }
+    const names = targets.map((id) => `"${this.tasks.get(id)?.title ?? id}"`)
+    return { stopped, text: `Stopped ${names.join(", ")}.` }
+  }
+
   subagent(): string {
     return this.config.subagent
   }
@@ -456,6 +590,42 @@ export class Spoke {
     })
   }
 
+  /** Whether the hub this spoke is connected to announced `feature` in its welcome (older hubs announce none). */
+  /** The session's current (unexpired) hub session token, for its shells (HUB_SESSION_TOKEN). */
+  sessionToken(sessionID: string): string | undefined {
+    return this.tokens.get(sessionID)?.token
+  }
+
+  /**
+   * What a session's shells get (src/spoke/env-inject.ts): its current token, with HUB_URL the server this spoke
+   * reaches the hub at (same machine as the shells), else the URL the hub sent. Undefined without a token.
+   */
+  shellIdentity(sessionID: string): { token: string; url?: string } | undefined {
+    const token = this.sessionToken(sessionID)
+    if (!token) return undefined
+    const url = this.config.server || this.tokens.hubURL
+    return url ? { token, url } : { token }
+  }
+
+  /**
+   * The session's act token (actTokens op) with the hub URL, for the OpenCode hub tool's act verbs only. Never
+   * hand it to a shell, an environment, a log or a tool's output. Undefined without an act token or a hub URL.
+   */
+  actIdentity(sessionID: string): { token: string; url: string } | undefined {
+    const token = this.actTokens.get(sessionID)?.token
+    const url = this.config.server || this.tokens.hubURL
+    return token && url ? { token, url } : undefined
+  }
+
+  /** The URL the hub told this spoke its sessions' shells reach it at (HUB_URL), if it sent one. */
+  get hubURL(): string | undefined {
+    return this.tokens.hubURL
+  }
+
+  hubSupports(feature: string): boolean {
+    return this.connection?.hubSupports(feature) === true
+  }
+
   status(sessionID?: string): SpokeStatus {
     const connection = this.connection?.state ?? "off"
     const lastError = this.connection?.lastError
@@ -491,6 +661,7 @@ export class Spoke {
 
   /** Starts device enrollment; polling continues in the background and stores the token on approval. */
   async enroll(): Promise<EnrollResult> {
+    if (this.options.launch) throw new SpokeError("invalid", LAUNCH_BOUND)
     const { server, machineName, autoStartLocalHub } = this.current()
     this.enrollment?.abort.abort()
     const abort = new AbortController()
@@ -566,6 +737,7 @@ export class Spoke {
    * with autoStartLocalHub off, and reconnects at once when it answers.
    */
   async startLocalHub(): Promise<{ status: "started" | "running" | "busy" }> {
+    if (this.options.launch) throw new SpokeError("invalid", LAUNCH_BOUND)
     const { server } = this.current()
     const starter = this.options.localHub
     if (!isLoopbackURL(server)) throw new SpokeError("invalid", `${server} is not a local hub`)
@@ -606,10 +778,12 @@ export class Spoke {
   }
 
   private current(): VoiceConfig {
+    if (this.options.launch) return this.config
     return this.watcher?.refresh() ?? readConfig(this.options.configFile, this.options.machineName)
   }
 
   private write(config: VoiceConfig): void {
+    if (this.options.launch) throw new SpokeError("invalid", LAUNCH_BOUND)
     writeConfig(this.options.configFile, config)
     if (this.watcher) this.watcher.refresh()
     else this.apply(readConfig(this.options.configFile, this.options.machineName))
@@ -625,6 +799,9 @@ export class Spoke {
       this.connection?.stop()
       this.connection = undefined
       this.connectionKey = key
+      // Tokens belong to the hub and machine they came from; the next connection's hub sends its own.
+      this.tokens.clear()
+      this.actTokens.clear()
       if (active) this.connect(config)
     }
     if (previous.sessions.join() !== config.sessions.join()) this.scheduleSnapshot()
@@ -643,13 +820,21 @@ export class Spoke {
         directory: this.host.directory,
         pid: this.options.pid,
         mode: this.config.mode === "session" ? "session" : "always",
+        // Hubs that predate `harness` require opencodeVersion; newer ones read harness, harnessVersion, evidence.
         opencodeVersion: this.host.opencodeVersion,
         pluginVersion: this.options.pluginVersion,
+        // Hub messages and prompts need OpenCode's synthetic messages.
+        features: SPOKE_FEATURES.filter((f) => (f !== "deliver" && f !== "hubPrompt") || this.host.synthetic !== undefined),
+        harness: HARNESS_OPENCODE,
+        harnessVersion: this.host.opencodeVersion,
+        evidence: "native",
+        ...(this.options.launch ? { launchID: this.options.launch.launchID } : {}),
       }),
       handle: (req) => this.handle(req),
       onWelcome: () => {
         this.sendSnapshot()
         this.sendTerminals(true)
+        void this.seedActivity()
       },
       onState: (state, error) => {
         if (state === "revoked") console.error("[hub] this machine was revoked by the hub")
@@ -671,7 +856,7 @@ export class Spoke {
 
   /** After a failed connection to a loopback server: maybe start the local hub (see SpokeOptions.localHub). */
   private maybeStartLocalHub(server: string): void {
-    const starter = this.options.localHub
+    const starter = this.options.launch ? undefined : this.options.localHub
     if (!starter || !this.config.autoStartLocalHub || !isLoopbackURL(server)) return
     if (this.hub.pending || Date.now() < this.hub.nextAt) return
     this.hub.pending = true
@@ -719,6 +904,7 @@ export class Spoke {
   private async conversationOn(sessionID: string): Promise<ResultFor["conversation"]> {
     const entry = this.conversations.get(sessionID)
     const session = await this.host.getSession(sessionID)
+    this.rememberModel(sessionID, session.model)
     const current = session.agent
     const models = await this.voiceModelOn(sessionID, session, entry)
     if (!(await this.host.hasAgent(VOICE_AGENT))) {
@@ -747,7 +933,7 @@ export class Spoke {
     const current = session.model
     const onVoice = current !== undefined && sameModel(current, voiceModel)
     const previousModel = entry?.voiceModel ? entry.previousModel : onVoice || !current ? undefined : plainModelRef(current)
-    if (!onVoice) await this.host.switchModel(sessionID, voiceModel)
+    if (!onVoice) await this.switchModel(sessionID, voiceModel)
     return { voiceModel, ...(previousModel ? { previousModel } : {}) }
   }
 
@@ -755,9 +941,10 @@ export class Spoke {
     const entry = this.conversations.get(sessionID)
     this.conversations.delete(sessionID)
     const session = await this.host.getSession(sessionID)
+    this.rememberModel(sessionID, session.model)
     // Restore the model only if the session is still on the voice model (the user may have picked another).
     if (entry?.voiceModel && entry.previousModel && session.model && sameModel(session.model, entry.voiceModel)) {
-      await this.host.switchModel(sessionID, entry.previousModel)
+      await this.switchModel(sessionID, entry.previousModel)
     }
     const current = session.agent
     if (current !== VOICE_AGENT) return { agent: current ?? (await this.defaultAgent()) }
@@ -778,7 +965,9 @@ export class Spoke {
   private async handle(req: ServerRequest): Promise<unknown> {
     // Session browser ops are not gated by exposure: they are how a session gets exposed.
     if (req.op === "expose") return this.expose(req.sessionID, req.on)
-    if (req.op === "create") return this.create(req.directory, req.title, req.herdrWorkspace)
+    if (req.op === "create") return this.create(req)
+    if (req.op === "sessionTokens") return this.storeTokens(this.tokens, req)
+    if (req.op === "actTokens") return this.storeTokens(this.actTokens, req)
     // Inspection and control need a session this process knows; Voice (conversation) is gated separately.
     if (!isReported(this.config, this.tracker, req.sessionID) && !(await this.adopt(req.sessionID))) throw new Error(UNKNOWN_SESSION)
     switch (req.op) {
@@ -786,7 +975,13 @@ export class Spoke {
         return this.turn(req.sessionID, req.text, req.voiceStyle, req.images)
       case "permission": {
         const directory = this.tracker.directoryOf(req.sessionID)
-        const outcome = await this.host.replyPermission({ sessionID: req.sessionID, requestID: req.requestID, decision: req.decision, ...(directory ? { directory } : {}) })
+        const outcome = await this.host.replyPermission({
+          sessionID: req.sessionID,
+          requestID: req.requestID,
+          decision: req.decision,
+          ...(req.message !== undefined ? { message: req.message } : {}),
+          ...(directory ? { directory } : {}),
+        })
         return outcome === "gone" ? { gone: true } : {}
       }
       case "form":
@@ -827,7 +1022,10 @@ export class Spoke {
         return this.modelPrefsResult(req.sessionID)
       }
       case "timeline": {
-        const items = timelineItems(req.sessionID, await this.host.context(req.sessionID))
+        // A first page reads OpenCode (it shows the newest state); following pages reuse those rows briefly.
+        const first = req.cursor === undefined && req.before === undefined
+        const items = await this.timelines.get(req.sessionID, async () => timelineItems(req.sessionID, await this.host.context(req.sessionID)), first)
+        if (req.before !== undefined || req.order === "desc") return newestPage(items, req.limit ?? 50, req.before) satisfies ResultFor["timeline"]
         const offset = req.cursor === undefined ? 0 : Number(req.cursor)
         if (!Number.isInteger(offset) || offset < 0) throw new Error("Invalid timeline cursor")
         const page = items.slice(offset, offset + (req.limit ?? 50))
@@ -853,6 +1051,10 @@ export class Spoke {
       case "interrupt":
         await this.host.interrupt(req.sessionID)
         return {}
+      case "rename":
+        return this.rename(req.sessionID, req.title)
+      case "autoName":
+        return this.autoName(req.sessionID)
       case "stop":
         return this.stopTree(req.sessionID)
       case "summary":
@@ -864,6 +1066,101 @@ export class Spoke {
       }
       case "conversation":
         return this.setConversation(req.sessionID, req.on)
+      case "deliver":
+        return this.deliver(req)
+    }
+  }
+
+  /**
+   * Admits a hub message as a synthetic message (plan in ./deliver). Never touches the session's voice
+   * settings, model or agent, and takes no turn lock: OpenCode queues it for busy sessions and open forms.
+   */
+  private async deliver(req: DeliverRequest): Promise<DeliverResult> {
+    const synthetic = this.host.synthetic?.bind(this.host)
+    if (!synthetic) throw new Error("This OpenCode process cannot take hub messages")
+    return this.deliveries.run(req.messageID, req.wake, async () => {
+      const subagent = (this.tracker.parentOf(req.sessionID) ?? (await this.host.getSession(req.sessionID).catch(() => undefined))?.parentID) !== undefined
+      const plan = planDelivery(req, {
+        busy: this.running.has(req.sessionID) || this.tracker.isBusy(req.sessionID),
+        formOpen: this.tracker.formOpenIn(req.sessionID),
+        subagent,
+      })
+      const id = harnessMessageID(req.messageID)
+      // Marked before sending: OpenCode may report it delivered before the call returns.
+      this.origins.hub(id)
+      const admitted = await synthetic({ sessionID: req.sessionID, id, text: deliverText(req), metadata: deliverMetadata(req), delivery: plan.delivery, resume: plan.resume })
+      this.timelines.invalidate(req.sessionID)
+      return { result: { delivered: plan.delivered, inboxID: typeof admitted?.id === "string" && admitted.id ? admitted.id : id }, resumed: plan.resume }
+    })
+  }
+
+  /**
+   * Stores the hub's session tokens for sessions this process reports (the tracker knows them). Never adopts or
+   * exposes a session: a token for any other session is skipped as "unknown", an expired one as "expired".
+   */
+  private storeTokens(store: SessionTokenStore, req: SessionTokensRequest | ActTokensRequest): ResultFor["sessionTokens"] {
+    const applied: string[] = []
+    const skipped: Array<ResultFor["sessionTokens"]["skipped"][number]> = []
+    for (const { sessionID, token, exp } of req.tokens) {
+      if (this.config.mode === "off" || !this.tracker.has(sessionID)) skipped.push({ sessionID, reason: "unknown" })
+      else if (store.set(sessionID, token, exp)) applied.push(sessionID)
+      else skipped.push({ sessionID, reason: "expired" })
+    }
+    if (req.op === "sessionTokens" && req.hubURL !== undefined && applied.length > 0) this.tokens.hubURL = req.hubURL
+    store.prune()
+    return { applied, skipped }
+  }
+
+  /**
+   * Renames a session in OpenCode and reports the new title at once (the snapshot goes out before the reply,
+   * on the same socket), without waiting for OpenCode's session.renamed event.
+   */
+  private async rename(sessionID: string, raw: string): Promise<ResultFor["rename"]> {
+    const title = raw.trim()
+    if (!title) throw new Error("Title is empty")
+    if (title.length > MAX_TITLE_CHARS) throw new Error(`Title is longer than ${MAX_TITLE_CHARS} characters`)
+    if (!this.host.updateSession) throw new Error("This OpenCode process cannot rename sessions")
+    await this.host.updateSession(sessionID, { title })
+    if (this.tracker.observe({ type: "session.renamed", data: { sessionID, title } }, Date.now())) this.sendSnapshot()
+    return { title }
+  }
+
+  /**
+   * Has OpenCode regenerate the title with its title agent, then reports the outcome: the new title (from
+   * session.renamed, or read back when the event is late), `unchanged` (OpenCode kept it or produced nothing),
+   * or `pending` when generation outlasts the wait (the catalog updates when the event arrives).
+   */
+  private async autoName(sessionID: string): Promise<ResultFor["autoName"]> {
+    const generate = this.host.generateTitle?.bind(this.host)
+    if (!generate) throw new Error(CANNOT_AUTO_NAME)
+    const before = (await this.host.getSession(sessionID)).title
+    let resolveRenamed!: (title: string) => void
+    const renamed = new Promise<string>((resolve) => (resolveRenamed = resolve))
+    const waiters = this.renameWaiters.get(sessionID) ?? new Set()
+    waiters.add(resolveRenamed)
+    this.renameWaiters.set(sessionID, waiters)
+    const timers: Array<ReturnType<typeof setTimeout>> = []
+    const after = <T>(ms: number, value: T) => new Promise<T>((resolve) => timers.push(setTimeout(() => resolve(value), ms)))
+    try {
+      const first = await Promise.race([
+        renamed.then((title) => ({ title })),
+        generate(sessionID).then((outcome) => ({ outcome })),
+        after(this.options.autoNameWaitMs ?? AUTO_NAME_WAIT_MS, { pending: true as const }),
+      ])
+      if ("title" in first) return { title: first.title }
+      if ("pending" in first) return { pending: true }
+      if (first.outcome === "unavailable") throw new Error(CANNOT_AUTO_NAME)
+      // Generation is done; its session.renamed event may still be on its way.
+      const late = await Promise.race([renamed, after(this.options.autoNameSettleMs ?? 1500, undefined)])
+      if (late !== undefined) return { title: late }
+      const title = (await this.host.getSession(sessionID)).title
+      if (title === before) return { unchanged: true, title }
+      if (this.tracker.observe({ type: "session.renamed", data: { sessionID, title } }, Date.now())) this.sendSnapshot()
+      return { title }
+    } finally {
+      for (const timer of timers) clearTimeout(timer)
+      waiters.delete(resolveRenamed)
+      if (waiters.size === 0) this.renameWaiters.delete(sessionID)
     }
   }
 
@@ -999,11 +1296,11 @@ export class Spoke {
     const selected = this.modelPrefs.get(sessionID)?.voice
     const override = this.voiceOverrides.get(sessionID)
     if ((!selected && !override) || this.tracker.active().includes(this.tracker.rootOf(sessionID))) return
-    const current = (await this.host.getSession(sessionID)).model
+    const current = await this.currentModel(sessionID)
     const onOverride = override !== undefined && current !== undefined && sameModel(current, override.applied)
     if (!selected) {
       this.voiceOverrides.delete(sessionID)
-      if (onOverride && override.previous) await this.host.switchModel(sessionID, override.previous)
+      if (onOverride && override.previous) await this.switchModel(sessionID, override.previous)
       return
     }
     const target = { providerID: selected.providerID, id: selected.modelID, ...(selected.variant ? { variant: selected.variant } : {}) }
@@ -1013,7 +1310,32 @@ export class Spoke {
     }
     const previous = onOverride ? override.previous : current ? plainModelRef(current) : undefined
     this.voiceOverrides.set(sessionID, { ...(previous ? { previous } : {}), applied: target })
-    await this.host.switchModel(sessionID, target)
+    await this.switchModel(sessionID, target)
+  }
+
+  /** The session's current model: remembered, else asked from OpenCode (and remembered). */
+  private async currentModel(sessionID: string): Promise<ModelRef | undefined> {
+    const known = this.sessionModels.get(sessionID)
+    if (known) return known.model
+    const { model } = await this.host.getSession(sessionID)
+    this.rememberModel(sessionID, model)
+    return model
+  }
+
+  private rememberModel(sessionID: string, model: ModelRef | undefined): void {
+    this.sessionModels.delete(sessionID)
+    this.sessionModels.set(sessionID, model ? { model } : {})
+    if (this.sessionModels.size > SESSION_MODELS_LIMIT) this.sessionModels.delete(this.sessionModels.keys().next().value!)
+  }
+
+  private async switchModel(sessionID: string, model: ModelRef): Promise<void> {
+    try {
+      await this.host.switchModel(sessionID, model)
+      this.rememberModel(sessionID, model)
+    } catch (cause) {
+      this.sessionModels.delete(sessionID) // unknown now: ask next time
+      throw cause
+    }
   }
 
   /** Enables or disables voice for a session this process reported (mode "session" only). */
@@ -1029,15 +1351,23 @@ export class Spoke {
    * of a Herdr pane. With `herdrWorkspace`, also opens it in a new tab of that Herdr workspace; if that
    * fails the session still exists and the result carries a warning instead of `openedIn`.
    */
-  private async create(directory: string, title?: string, herdrWorkspace?: string): Promise<ResultFor["create"] & { warning?: string }> {
+  private async create(req: CreateRequest): Promise<ResultFor["create"] & { warning?: string }> {
+    const { directory, title, herdrWorkspace } = req
     if (this.options.kind !== "service" || !this.host.createSession) {
       throw new Error("Only the background service creates sessions")
     }
     const target = path.resolve(directory)
-    const workspace =
-      this.workspaces().get(target) ?? (this.herdr?.hasDirectory(target) ? { project: target, projectName: path.basename(target) || target } : undefined)
+    const launch = isLaunchCreate(req)
+    const workspace = launch
+      ? await this.launchWorkspace(req, target)
+      : this.workspaces().get(target) ?? (this.herdr?.hasDirectory(target) ? { project: target, projectName: path.basename(target) || target } : undefined)
     if (!workspace) throw new Error("unknown workspace")
     const session = await this.host.createSession({ directory: target, ...(title ? { title } : {}) })
+    if (launch) {
+      // Agent first: switching the agent may reset the model.
+      if (req.agent) await this.host.switchAgent(session.id, req.agent)
+      if (req.model) await this.switchModel(session.id, { providerID: req.model.providerID, id: req.model.modelID, ...(req.model.variant ? { variant: req.model.variant } : {}) })
+    }
     const now = Date.now()
     this.tracker.observe({ type: "session.created", data: { sessionID: session.id, title: title ?? "", location: { directory: target } } }, now)
     this.tracker.setInfo(session.id, { title: title ?? "", directory: target, updated: now, ...workspace })
@@ -1048,6 +1378,33 @@ export class Spoke {
     return warning ? { sessionID: session.id, warning } : { sessionID: session.id, openedIn: "herdr" }
   }
 
+  /**
+   * The workspace of a launch create (feature "launch"): its directory must exist under the node workspace roots
+   * (a worktree or clone `hub node` prepared need not be one this process reported), and its agent and model must
+   * be ones this OpenCode has. Checked before the session is created.
+   */
+  private async launchWorkspace(req: CreateRequest, target: string): Promise<{ project: string; projectName: string }> {
+    const problem = launchDirectoryProblem(target, this.options.workspaceRoots?.() ?? [])
+    if (problem) throw new Error(problem)
+    if (req.agent && !(await this.host.hasAgent(req.agent))) throw new Error(`Unknown agent ${req.agent}`)
+    if (req.model && !(await this.hasModel(req.model))) {
+      throw new Error(`Unknown model ${req.model.providerID}/${req.model.modelID}${req.model.variant ? `#${req.model.variant}` : ""}`)
+    }
+    return this.workspaces().get(target) ?? { project: target, projectName: path.basename(target) || target }
+  }
+
+  /** Whether OpenCode's model list has `model` (and its variant); true when this OpenCode cannot list models. */
+  private async hasModel(model: NonNullable<CreateRequest["model"]>): Promise<boolean> {
+    if (!this.host.listModels) return true
+    return (await this.host.listModels()).some((value: any) => {
+      const id = typeof value?.id === "string" && value.id ? value.id : value?.modelID
+      if (value?.providerID !== model.providerID || id !== model.modelID) return false
+      if (!model.variant) return true
+      const variants = Array.isArray(value.variants) ? value.variants : []
+      return variants.some((v: any) => (typeof v === "string" ? v : v?.id) === model.variant)
+    })
+  }
+
   /** Opens a session in a new Herdr tab; returns a warning when that did not work. */
   private async openInHerdr(workspaceID: string, directory: string, sessionID: string, title?: string): Promise<string | undefined> {
     const herdr = this.herdr
@@ -1105,7 +1462,11 @@ export class Spoke {
 
   private async listen(): Promise<void> {
     while (!this.abort.signal.aborted) {
+      // Model changes may have been missed while the stream was down: ask OpenCode again.
+      this.sessionModels.clear()
       try {
+        // Events may have been missed while the stream was down (or before it opened): ask what runs now.
+        if (this.connection?.state === "connected") void this.seedActivity()
         for await (const event of this.host.events(this.abort.signal)) this.observe(event)
       } catch (cause) {
         if (this.abort.signal.aborted) return
@@ -1118,7 +1479,15 @@ export class Spoke {
 
   private observe(event: EventLike): void {
     try {
+      const sessionID = (event.data as Record<string, unknown> | undefined)?.sessionID
+      if (typeof sessionID === "string") this.timelines.invalidate(sessionID)
       this.turns.observe(event)
+      this.observeModel(event)
+      this.origins.observe(event)
+      if (event.type === "session.deleted" && typeof sessionID === "string") {
+        this.tokens.delete(sessionID)
+        this.actTokens.delete(sessionID)
+      }
       if (event.type === "form.replied" || event.type === "form.cancelled") {
         const formID = (event.data as Record<string, unknown> | undefined)?.id
         if (typeof formID === "string") {
@@ -1126,21 +1495,49 @@ export class Spoke {
           this.relay.settled.delete(formID)
         }
       }
+      this.tasks.observe(event, Date.now())
+      if (event.type === "session.renamed" && typeof sessionID === "string") {
+        const title = (event.data as Record<string, unknown>).title
+        if (typeof title === "string") for (const waiter of this.renameWaiters.get(sessionID) ?? []) waiter(title)
+      }
       if (this.tracker.observe(event, Date.now())) this.scheduleSnapshot()
       if (this.options.kind === "service" && this.host.listRecent && LISTING_EVENTS.has(event.type) && !(event.data as any)?.parentID) {
         this.scheduleSeed()
       }
       void this.fetchInfo()
-      if (this.connection?.state === "connected" && shouldForward(this.config, this.tracker, event)) {
-        // Activity events go out compact: tool inputs become a short summary, outputs are dropped.
-        const compact = compactActivity({ type: event.type, data: (event.data ?? {}) as Record<string, unknown> })
-        if (compact) this.connection.send({ t: "event", event: compact })
+      if (this.connection?.state === "connected" && (FORWARDED_EVENTS.has(event.type) || COMPACTED_EVENTS.has(event.type))) {
+        // Activity events go out compact: tool inputs become a short summary, outputs are dropped; job exits
+        // get their session from the job.
+        const compact = this.withOrigin(compactActivity({ type: event.type, data: (event.data ?? {}) as Record<string, unknown> }, (id) => this.tracker.jobSession(id)))
+        if (compact && shouldForward(this.config, this.tracker, compact)) this.connection.send({ t: "event", event: compact })
       }
     } catch (cause) {
       console.error("[hub] event handling failed", cause)
     }
   }
 
+  /**
+   * Adds who put the item in the inbox (user or hub) to session.inbox.delivered, for hubs that route messages
+   * (they reset reply-chain hops on a user's turn); when unknown, the event goes out unchanged.
+   */
+  private withOrigin<E extends { type: string; data: Record<string, unknown> }>(event: E | undefined): E | undefined {
+    if (event?.type !== "session.inbox.delivered" || typeof event.data.inboxID !== "string") return event
+    const origin = this.origins.take(event.data.inboxID)
+    return origin && this.hubSupports("messaging") ? { ...event, data: { ...event.data, origin } } : event
+  }
+
+  /** Keeps the remembered session models current from OpenCode's events. */
+  private observeModel(event: EventLike): void {
+    const data = (event.data ?? {}) as { sessionID?: unknown; model?: unknown }
+    if (typeof data.sessionID !== "string") return
+    if (event.type === "session.deleted") this.sessionModels.delete(data.sessionID)
+    else if (event.type === "session.model.selected") {
+      const model = data.model as Partial<ModelRef> | undefined
+      if (model && typeof model.providerID === "string" && typeof model.id === "string") this.rememberModel(data.sessionID, model as ModelRef)
+      else this.sessionModels.delete(data.sessionID)
+    }
+  }
+
   private async fetchInfo(): Promise<void> {
     const now = Date.now()
     for (const id of this.tracker.needsInfo()) {
@@ -1163,6 +1560,40 @@ export class Spoke {
     }
   }
 
+  /**
+   * Sends each running (or formerly running) session's current status and running jobs as a session.seed event,
+   * from the host's snapshot. Sessions the tracker thought working that are not active any more are seeded idle.
+   */
+  private async seedActivity(): Promise<void> {
+    const activity = this.host.activity
+    if (!activity || this.seeding) return
+    this.seeding = true
+    try {
+      const snapshot = await activity.call(this.host, this.tracker.directories(SEED_DIRECTORIES))
+      const active = new Set(snapshot.active)
+      const ids = new Set([...snapshot.active, ...snapshot.jobs.map((j) => j.sessionID), ...this.tracker.working()])
+      const now = Date.now()
+      for (const id of ids) {
+        if (active.has(id)) this.tracker.ensure(id, now)
+        if (!this.tracker.has(id)) continue
+        const jobs = snapshot.jobs
+          .filter((j) => j.sessionID === id && j.status === "running")
+          .slice(0, SEED_JOBS_MAX)
+          .map(({ sessionID: _, ...job }) => job)
+        const status = active.has(id) ? "busy" : "idle"
+        this.tracker.seed(id, { status, jobs })
+        const event = { type: "session.seed", data: { sessionID: id, status: { type: status }, jobs } }
+        if (this.connection?.state === "connected" && shouldForward(this.config, this.tracker, event)) this.connection.send({ t: "event", event })
+      }
+      void this.fetchInfo()
+      this.scheduleSnapshot()
+    } catch (cause) {
+      console.error("[hub] could not read running sessions", errorText(cause))
+    } finally {
+      this.seeding = false
+    }
+  }
+
   private async seed(): Promise<void> {
     try {
       const keep = this.keep()
@@ -1202,11 +1633,17 @@ export class Spoke {
   }
 }
 
+/** Directories whose shells are listed when seeding. */
+const SEED_DIRECTORIES = 20
+
 /** Keeps the terminals frame within the protocol's limits. */
 function limitWorkspaces(workspaces: readonly HerdrWorkspace[]): HerdrWorkspace[] {
   return workspaces.slice(0, 200).map((w) => ({ id: w.id, label: w.label, directories: w.directories.slice(0, 20) }))
 }
 
+/** Sessions whose current model is remembered. */
+const SESSION_MODELS_LIMIT = 500
+
 function sameModel(a: ModelRef, b: ModelRef): boolean {
   return a.providerID === b.providerID && a.id === b.id && (explicitVariant(a) ?? "") === (explicitVariant(b) ?? "")
 }