@huynle/hub 0.6.1 → 0.7.2

package/src/central/token-keys.ts

@@ -0,0 +1,165 @@
+// HMAC signing keys for hub-minted session tokens, kept apart from state.json in `<stateDir>/token-keys.json`
+// (mode 0600, written atomically): {active: kid, keys: [{kid, secret (base64 of 32 random bytes), created}]}.
+// The file is created on first use. rotate() adds a new active key and keeps the older ones so tokens they
+// signed still verify. HUB_TOKEN_KEYS (same JSON shape) overrides the file, e.g. a Kubernetes secret shared by
+// several pods; the file is then never written and rotation happens where the secret is managed.
+// Secrets never appear in errors, logs, JSON or inspect output.
+import { randomBytes } from "node:crypto"
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+export const TOKEN_KEYS_FILE = "token-keys.json"
+export const TOKEN_KEYS_ENV = "HUB_TOKEN_KEYS"
+/** Bytes of a signing secret. */
+export const TOKEN_KEY_BYTES = 32
+
+export interface StoredTokenKey {
+  kid: string
+  /** Base64 of TOKEN_KEY_BYTES random bytes. */
+  secret: string
+  created: number
+}
+
+export interface TokenKeyFile {
+  active: string
+  keys: StoredTokenKey[]
+}
+
+export interface TokenKeysOptions {
+  readonly now?: () => number
+  /** Environment for the HUB_TOKEN_KEYS override (default process.env). */
+  readonly env?: Readonly<Record<string, string | undefined>>
+}
+
+interface Key {
+  kid: string
+  secret: Buffer
+  created: number
+}
+
+const newKid = (): string => `k_${randomBytes(6).toString("base64url")}`
+
+/** Parsed and validated key data; `source` names the origin in errors (never the content). */
+function parseKeys(text: string, source: string): { active: string; keys: Key[] } {
+  const fail = (why: string): never => {
+    throw new Error(`Invalid ${source}: ${why}. Fix or move it away.`)
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch {
+    return fail("not valid JSON")
+  }
+  if (typeof raw !== "object" || raw === null) return fail("not an object")
+  const { active, keys } = raw as Record<string, unknown>
+  if (typeof active !== "string" || !Array.isArray(keys)) return fail("expected {active, keys: [...]}")
+  const out: Key[] = []
+  for (const entry of keys as unknown[]) {
+    const { kid, secret, created } = (typeof entry === "object" && entry !== null ? entry : {}) as Record<string, unknown>
+    if (typeof kid !== "string" || !kid) return fail("a key has no kid")
+    if (out.some((key) => key.kid === kid)) return fail(`duplicate kid ${kid}`)
+    const bytes = typeof secret === "string" ? Buffer.from(secret, "base64") : Buffer.alloc(0)
+    if (typeof secret !== "string" || bytes.toString("base64") !== secret || bytes.length < TOKEN_KEY_BYTES) {
+      return fail(`key ${kid} needs a base64 secret of at least ${TOKEN_KEY_BYTES} bytes`)
+    }
+    out.push({ kid, secret: bytes, created: typeof created === "number" ? created : 0 })
+  }
+  if (!out.some((key) => key.kid === active)) return fail("the active kid is not among the keys")
+  return { active, keys: out }
+}
+
+export class TokenKeys {
+  #active = ""
+  #keys: Key[] = []
+  #loaded = false
+
+  private constructor(
+    private readonly file: string,
+    private readonly now: () => number,
+    private readonly override: string | undefined,
+  ) {}
+
+  /** Nothing is read or written until a key is needed. */
+  static open(dir: string, options: TokenKeysOptions = {}): TokenKeys {
+    const env = options.env ?? process.env
+    const override = env[TOKEN_KEYS_ENV]?.trim() || undefined
+    return new TokenKeys(path.join(dir, TOKEN_KEYS_FILE), options.now ?? Date.now, override)
+  }
+
+  /** The key new tokens are signed with (created on first use). */
+  active(): { kid: string; secret: Buffer } {
+    this.load()
+    const key = this.#keys.find((k) => k.kid === this.#active)!
+    return { kid: key.kid, secret: Buffer.from(key.secret) }
+  }
+
+  /** The secret for a kid, to verify a token; undefined when unknown. */
+  key(kid: string): Buffer | undefined {
+    this.load()
+    const key = this.#keys.find((k) => k.kid === kid)
+    return key ? Buffer.from(key.secret) : undefined
+  }
+
+  /** Every kid, oldest first. */
+  kids(): string[] {
+    this.load()
+    return this.#keys.map((k) => k.kid)
+  }
+
+  /** Adds a new active key, keeping the previous ones for verification. Returns its kid. */
+  rotate(): string {
+    if (this.override) throw new Error(`Signing keys come from ${TOKEN_KEYS_ENV}; rotate them where that is managed`)
+    this.load(false)
+    let kid = newKid()
+    while (this.#keys.some((k) => k.kid === kid)) kid = newKid()
+    this.#keys.push({ kid, secret: randomBytes(TOKEN_KEY_BYTES), created: this.now() })
+    this.#active = kid
+    this.save()
+    return kid
+  }
+
+  toJSON(): { file: string; active: string; kids: string[] } {
+    return { file: this.file, active: this.#active, kids: this.#keys.map((k) => k.kid) }
+  }
+
+  toString(): string {
+    return `TokenKeys(${this.override ? TOKEN_KEYS_ENV : this.file})`
+  }
+
+  [Symbol.for("nodejs.util.inspect.custom")](): string {
+    return this.toString()
+  }
+
+  /** Reads the keys once; with `create`, a missing file gets its first key. */
+  private load(create = true): void {
+    if (this.#loaded) return
+    if (this.override) {
+      this.set(parseKeys(this.override, TOKEN_KEYS_ENV))
+      return
+    }
+    if (existsSync(this.file)) {
+      this.set(parseKeys(readFileSync(this.file, "utf8"), this.file))
+      return
+    }
+    this.#loaded = true
+    if (create) this.rotate()
+  }
+
+  private set(data: { active: string; keys: Key[] }): void {
+    this.#active = data.active
+    this.#keys = data.keys
+    this.#loaded = true
+  }
+
+  private save(): void {
+    const data: TokenKeyFile = {
+      active: this.#active,
+      keys: this.#keys.map((k) => ({ kid: k.kid, secret: k.secret.toString("base64"), created: k.created })),
+    }
+    mkdirSync(path.dirname(this.file), { recursive: true, mode: 0o700 })
+    const tmp = `${this.file}.${process.pid}.tmp`
+    writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 })
+    chmodSync(tmp, 0o600)
+    renameSync(tmp, this.file)
+  }
+}

package/src/config.ts

@@ -1,10 +1,12 @@
 // Per-machine spoke configuration, shared by every OpenCode process on the machine and edited
 // from the /hub dialog. Holds the machine token, so it is written with mode 0600.
-import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { randomBytes } from "node:crypto"
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync } from "node:fs"
 import { homedir } from "node:os"
 import path from "node:path"
 import { hubEnv, type Env } from "./env"
 import { APP_DIR, configBase, legacyPaths, migrateFirst } from "./migrate"
+import { isHubURL } from "./protocol"
 
 export type Mode = "off" | "always" | "session"
 
@@ -141,13 +143,75 @@ export function readConfig(file: string, machineName: string): VoiceConfig {
   }
 }
 
-/** Atomic write with 0600 permissions. */
-export function writeConfig(file: string, config: VoiceConfig): void {
+/** The keys VoiceConfig owns in config.json; every other key belongs to someone else and is preserved. */
+const CONFIG_KEYS = ["server", "mode", "sessions", "machineName", "subagent", "autoStartLocalHub", "herdr", "list", "voiceModel", "workModel", "machineID", "token"] as const satisfies readonly (keyof VoiceConfig)[]
+
+type RawConfig = Record<string, unknown>
+
+const isObject = (v: unknown): v is RawConfig => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** The raw JSON object in `file` (every key, known or not); undefined when the file does not exist. */
+export function readRawConfig(file: string): RawConfig | undefined {
+  let text: string
+  try {
+    text = readFileSync(file, "utf8")
+  } catch (cause) {
+    if ((cause as NodeJS.ErrnoException).code === "ENOENT") return undefined
+    throw cause
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    parsed = undefined
+  }
+  if (!isObject(parsed)) throw new Error(`${file} is not a JSON object; fix or remove it first`)
+  return parsed
+}
+
+/** Writes `content` to `file` atomically (a private temp file in the same directory, fsync, rename), mode 0600. */
+function writePrivate(file: string, content: string): void {
   mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
-  const tmp = `${file}.${process.pid}.tmp`
-  writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
-  chmodSync(tmp, 0o600)
-  renameSync(tmp, file)
+  const tmp = `${file}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`
+  let fd: number | undefined
+  try {
+    fd = openSync(tmp, "wx", 0o600)
+    writeSync(fd, content)
+    fsyncSync(fd)
+    closeSync(fd)
+    fd = undefined
+    chmodSync(tmp, 0o600)
+    renameSync(tmp, file)
+  } catch (cause) {
+    if (fd !== undefined) closeSync(fd)
+    rmSync(tmp, { force: true })
+    throw cause
+  }
+}
+
+const serialize = (raw: RawConfig) => `${JSON.stringify(raw, null, 2)}\n`
+
+/**
+ * Lossless read-modify-write of config.json: `update` gets the raw object (every key, {} for a missing file) and
+ * returns the next one, written atomically with 0600. Refuses (throws, file untouched) when the file is not a JSON
+ * object, so a hand-edited config is never replaced.
+ */
+export function updateRawConfig(file: string, update: (raw: RawConfig) => RawConfig): void {
+  writePrivate(file, serialize(update(readRawConfig(file) ?? {})))
+}
+
+/**
+ * Atomic write with 0600 permissions. Lossless: keys config.json holds that VoiceConfig does not know are kept; the
+ * known keys come from `config` (a known key it lacks is removed). A file that is not a JSON object is replaced.
+ */
+export function writeConfig(file: string, config: VoiceConfig): void {
+  let previous: RawConfig = {}
+  try {
+    previous = readRawConfig(file) ?? {}
+  } catch {}
+  const next: RawConfig = { ...previous }
+  for (const key of CONFIG_KEYS) delete next[key]
+  writePrivate(file, serialize({ ...next, ...config }))
 }
 
 /** Changing the server URL drops the machine credentials, which belong to the old server. */
@@ -168,3 +232,50 @@ export function setSession(config: VoiceConfig, sessionID: string, on: boolean):
   const sessions = on ? [...new Set([...config.sessions, sessionID])] : config.sessions.filter((id) => id !== sessionID)
   return { ...config, sessions }
 }
+
+// ---------- launch-bound mode ----------
+// A spoke inside a launch's sandbox (OpenShell, design §6.4) connects with a credential bound to that launch. The node
+// writes {hubURL, token, launchID} next to node.json before the harness starts; the spoke only reads it: no enrolment,
+// no local hub, no config writes.
+
+export interface LaunchConfig {
+  readonly hubURL: string
+  /** The launch-bound credential (hlt1…); never logged. */
+  readonly token: string
+  readonly launchID: string
+}
+
+/** Where the node puts the launch config inside a sandbox. */
+export const LAUNCH_CONFIG_DEFAULT = "/sandbox/.hub/config.json"
+const LAUNCH_ID = /^[A-Za-z0-9_.:@/+~-]{1,300}$/
+const LAUNCH_TOKEN = /^[\x21-\x7e]{1,4096}$/
+
+/** A launch config, or undefined unless every field is present and valid. */
+export function parseLaunchConfig(raw: unknown): LaunchConfig | undefined {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined
+  const r = raw as Record<string, unknown>
+  if (!isHubURL(r.hubURL)) return undefined
+  if (typeof r.token !== "string" || !LAUNCH_TOKEN.test(r.token)) return undefined
+  if (typeof r.launchID !== "string" || !LAUNCH_ID.test(r.launchID)) return undefined
+  return { hubURL: r.hubURL.replace(/\/+$/, ""), token: r.token, launchID: r.launchID }
+}
+
+/** $HUB_LAUNCH_CONFIG, else LAUNCH_CONFIG_DEFAULT when it exists; undefined: not launch-bound. */
+export function launchConfigPath(env: Env = process.env, exists: (file: string) => boolean = existsSync): string | undefined {
+  const explicit = env.HUB_LAUNCH_CONFIG
+  if (explicit) return explicit
+  return exists(LAUNCH_CONFIG_DEFAULT) ? LAUNCH_CONFIG_DEFAULT : undefined
+}
+
+/** Reads a launch config; throws (without the token) when it is missing, unparsable or invalid. */
+export function readLaunchConfig(file: string): LaunchConfig {
+  let raw: unknown
+  try {
+    raw = JSON.parse(readFileSync(file, "utf8"))
+  } catch (cause) {
+    throw new Error(`Cannot read the launch config ${file}: ${cause instanceof SyntaxError ? "not JSON" : (cause as NodeJS.ErrnoException).code ?? "unreadable"}`)
+  }
+  const config = parseLaunchConfig(raw)
+  if (!config) throw new Error(`Invalid launch config ${file}: expected {hubURL, token, launchID}`)
+  return config
+}

package/src/index.ts

@@ -1,16 +1,26 @@
 // Hub server plugin: a thin "spoke" that connects this OpenCode process to the hub. The web
 // console, phones and (optional) Voice speech live on the hub; this side only exposes sessions, forwards
 // their events, and runs remote / voice turns and permission replies on request.
-import { readFileSync } from "node:fs"
-import { hostname } from "node:os"
-import { Plugin } from "@opencode/plugin"
+import { mkdirSync, readFileSync } from "node:fs"
+import { homedir, hostname } from "node:os"
+import { fileURLToPath } from "node:url"
+// Types only: @opencode/plugin's runtime entry loads its whole schema graph (~1 s cold) for an identity define().
+import type { Plugin } from "@opencode/plugin"
 import { DEFAULT_SUBAGENT, prepareConfigPath } from "./config"
 import { HubRpc, VoiceRpc } from "./rpc"
+import { jobFromInfo, type JobInfo } from "./protocol"
 import { checkServer, parseServerInput } from "./setup"
-import { defineVoiceAgent, orchestratorParts } from "./spoke/conversation"
+import { defineVoiceAgent, orchestratorParts, STOP_TOOL, STOP_TOOL_DESCRIPTION } from "./spoke/conversation"
+import { envInjector, hubBinDir, ShellCorrelator, stripInheritedHubEnv } from "./spoke/env-inject"
 import { herdrRunner } from "./spoke/herdr"
+import { launchSource } from "./spoke/launch-source"
+import { HubRpcError, hubMsg, hubWho } from "./spoke/hub-rpc"
+import { HUB_TOOL, HUB_TOOL_DESCRIPTION, HUB_TOOL_INPUT, runHubTool } from "./spoke/hub-tool"
+import { cliEntry, installLaunchers, linkUserBin, standaloneHubctl } from "./spoke/launchers"
 import { listServiceSessions } from "./spoke/listing"
 import { ensureLocalHub } from "./spoke/localhub"
+import { nodeConfigPath, readWorkspaceRoots } from "./spoke/node-roots"
+import { PromptReferences } from "./spoke/prompt-refs"
 import { replyPermission, type PermissionLocation } from "./spoke/locations"
 import { foregroundEndpoint, formOutcome } from "./spoke/own-server"
 import { joinProcess, type Membership } from "./spoke/singleton"
@@ -18,6 +28,18 @@ import { detectKind, Spoke, SpokeError, type FormAction, type SpokeHost } from "
 
 type Context = Parameters<Parameters<typeof Plugin.define>[0]["setup"]>[0]
 
+/** Plugin.define without importing it (it returns its argument). */
+const definePlugin = (plugin: Plugin.Plugin): Plugin.Plugin => plugin
+
+/** One registration with OpenCode; a failure is logged and never stops the others. */
+async function attempt(what: string, register: () => Promise<unknown> | undefined): Promise<void> {
+  try {
+    await register()
+  } catch (cause) {
+    console.error(`[hub] could not ${what}`, cause)
+  }
+}
+
 const VOICE_STYLE =
   "This message came from a voice conversation and your reply will be read aloud. " +
   "Answer in at most three short sentences of plain speech: no markdown, code blocks, tables, or lists. " +
@@ -70,6 +92,45 @@ async function replyForm(kind: "service" | "standalone", action: FormAction): Pr
   }
 }
 
+/**
+ * Has OpenCode regenerate a session's title with its title agent: session.update with an empty title over
+ * the own server's HTTP API (the handler runs SessionTitle.generate and returns when it is done). The plugin
+ * API's session.update would rename the session to "" instead. "unavailable" when the server cannot be reached.
+ */
+async function generateTitle(kind: "service" | "standalone", sessionID: string): Promise<"done" | "unavailable"> {
+  const client = await ownClient(kind).catch(() => undefined)
+  if (!client) return "unavailable"
+  await client.session.update({ sessionID, title: "" })
+  return "done"
+}
+
+/**
+ * What runs now on this process's own server: session.active (sessions with a run in progress) and the running
+ * shells of the given directories (shell.list, per location) that belong to a session. Empty when the server
+ * cannot be reached.
+ */
+async function activity(kind: "service" | "standalone", directories: readonly string[]) {
+  const client = await ownClient(kind).catch(() => undefined)
+  if (!client) return { active: [], jobs: [] }
+  const active = unwrap<Record<string, unknown>>(await client.session.active(), (v) => v && typeof v === "object" && !("data" in v))
+  const jobs: Array<JobInfo & { sessionID: string }> = []
+  const seen = new Set<string>()
+  for (const directory of directories) {
+    try {
+      const list = unwrap<unknown[]>(await client.shell.list({ location: { directory } }), Array.isArray)
+      for (const raw of Array.isArray(list) ? list : []) {
+        const job = jobFromInfo(raw, "shell")
+        if (!job?.sessionID || job.status !== "running" || seen.has(job.id)) continue
+        seen.add(job.id)
+        jobs.push(job as JobInfo & { sessionID: string })
+      }
+    } catch {
+      // a location this server does not serve
+    }
+  }
+  return { active: Object.keys(active ?? {}), jobs }
+}
+
 /** Plugin API results may arrive bare or wrapped as { location, data }. */
 function unwrap<T>(value: unknown, isBare: (v: any) => boolean): T {
   const v = value as any
@@ -97,12 +158,18 @@ function hostFrom(ctx: Context, locations: () => PermissionLocation[], kind: "se
     opencodeVersion: ctx.app?.version ?? "unknown",
     events: (signal) => ctx.event.subscribe({ signal }) as AsyncIterable<any>,
     prompt: (input) => session.prompt(input),
+    // OpenCode's native synthetic messages (hub deliveries); without them the spoke does not announce "deliver".
+    ...(typeof session.synthetic === "function"
+      ? { synthetic: async (input: Parameters<NonNullable<SpokeHost["synthetic"]>>[0]) => unwrap<{ id?: string }>(await session.synthetic(input), (v) => typeof v.id === "string") }
+      : {}),
     context: (sessionID) => session.context({ sessionID }),
     listModels: async () => unwrap<ReadonlyArray<unknown>>(await (ctx.model as any).list({}), Array.isArray),
     getSession: async (sessionID) => unwrap(await session.get({ sessionID }), (v) => typeof v.id === "string"),
     replyPermission: ({ directory, ...input }) => replyPermission(locations(), input, directory),
     replyForm: (action) => replyForm(kind, action),
     interrupt: (sessionID) => session.interrupt({ sessionID }),
+    updateSession: (sessionID, input) => session.update({ sessionID, ...input }),
+    generateTitle: (sessionID) => generateTitle(kind, sessionID),
     switchAgent: (sessionID, id) => session.switchAgent({ sessionID, agent: id }),
     switchModel: (sessionID, model) => session.switchModel({ sessionID, model }),
     hasAgent: async (id) => {
@@ -118,6 +185,7 @@ function hostFrom(ctx: Context, locations: () => PermissionLocation[], kind: "se
       return list?.find((a) => a.mode !== "subagent" && !a.hidden)?.id
     },
     listRecent,
+    activity: (directories) => activity(kind, directories),
     createSession: async ({ directory, title }) =>
       unwrap<{ id: string }>(await session.create({ location: { directory }, ...(title ? { title } : {}) }), (v) => typeof v.id === "string"),
     ...(mcp?.list ? { mcpList: async (directory: string) => unwrap<ReadonlyArray<unknown>>(await mcp.list({ location: { directory } }), Array.isArray) } : {}),
@@ -133,49 +201,134 @@ function hostFrom(ctx: Context, locations: () => PermissionLocation[], kind: "se
   }
 }
 
-export default Plugin.define({
+/**
+ * Gives every shell the agent runs through the shell tool its session's HUB_URL/HUB_SESSION_TOKEN and puts the hub
+ * bin dir first on PATH (src/spoke/env-inject.ts). Known gap: user `!` commands have no tool call, so get no token.
+ */
+async function registerShellEnv(ctx: Context, identity: (sessionID: string) => { token: string; url?: string } | undefined) {
+  const binDir = hubBinDir()
+  try {
+    mkdirSync(binDir, { recursive: true, mode: 0o700 })
+    // The `hub`/`hubctl` launchers run the CLI with this runtime (OpenCode's binary as bun; src/spoke/launchers.ts).
+    const bun = typeof process.versions.bun === "string"
+    const entry = cliEntry(fileURLToPath(new URL("..", import.meta.url)), bun)
+    if (entry) {
+      installLaunchers({ binDir, execPath: process.execPath, bun, entry, standalone: standaloneHubctl(homedir()) })
+      // `hub` in the user's own terminals too (~/.local/bin/hub, never over anything of theirs).
+      const { hint } = linkUserBin({ home: homedir(), binDir, path: process.env.PATH })
+      if (hint) console.error(`[hub] ${hint}`)
+    } else console.error("[hub] no built hub CLI (packages/cli/dist/hub-cli.js): `hub` is not installed")
+  } catch (cause) {
+    console.error("[hub] could not install the hub CLI launchers", cause)
+  }
+  const injector = envInjector({ correlator: new ShellCorrelator(), binDir, identity })
+  const tool = (ctx as any).tool
+  const shell = (ctx as any).shell
+  await attempt("register the shell environment hooks", async () => {
+    if (!tool?.hook || !shell?.hook) throw new Error("this OpenCode has no tool/shell hooks")
+    await Promise.all([
+      tool.hook("execute.before", (event: any) => injector.toolBefore(event)),
+      tool.hook("execute.after", (event: any) => injector.toolAfter(event)),
+      shell.hook("create.before", (invocation: any) => injector.shellBefore(invocation)),
+    ])
+  })
+}
+
+export default definePlugin({
   id: "hub",
   async setup(ctx) {
+    // An OpenCode started from a session's shell must not act as that session (nor hand its token to its shells).
+    stripInheritedHubEnv(process.env)
     const kind = detectKind(process.argv)
+    // Inside a launch's sandbox the spoke is launch-bound: the node's read-only launch config and node.json, no
+    // machine config, enrolment, local hub or Herdr (src/spoke/launch-source.ts). A broken one leaves no spoke.
+    const source = launchSource()
     const membership: Membership<Spoke> = joinProcess(
-      (processID) =>
-        new Spoke(hostFrom(ctx, () => membership.locals<PermissionLocation>(), kind), {
+      (processID) => {
+        if (source.kind === "invalid") throw new Error(`${source.error}; the hub spoke is off in this process`)
+        const host = hostFrom(ctx, () => membership.locals<PermissionLocation>(), kind)
+        const common = { machineName: hostname(), kind, processID, pid: process.pid, pluginVersion: pluginVersion() }
+        if (source.kind === "launch") {
+          const nodeConfig = source.nodeConfig
+          return new Spoke(host, { ...common, configFile: source.file, launch: source.launch, workspaceRoots: () => readWorkspaceRoots(nodeConfig) })
+        }
+        return new Spoke(host, {
+          ...common,
           configFile: prepareConfigPath(),
-          machineName: hostname(),
-          kind,
-          processID,
-          pid: process.pid,
-          pluginVersion: pluginVersion(),
           // Loopback servers only, and only when autoStartLocalHub is on (see src/spoke/localhub.ts).
           localHub: (server) => ensureLocalHub(server),
-          // One Herdr reader per machine: the background service's spoke (see src/spoke/herdr.ts).
-          ...(kind === "service" ? { herdr: herdrRunner() } : {}),
-        }),
+          // One Herdr reader per machine: the background service's spoke (see src/spoke/herdr.ts). Launch creates
+          // (service only) need the node workspace roots, read from node.json each time (src/spoke/node-roots.ts).
+          ...(kind === "service" ? { herdr: herdrRunner(), workspaceRoots: () => readWorkspaceRoots(nodeConfigPath()) } : {}),
+        })
+      },
       undefined,
       permissionLocation(ctx),
     )
 
-    try {
-      await ctx.agent.transform((editor) => defineVoiceAgent(editor as any))
-    } catch (cause) {
-      console.error("[hub] could not register the voice agent", cause)
-    }
-
-    try {
-      await ctx.session.hook("context", (event) => {
-        const spoke = membership.active()
-        if (spoke?.isVoiceTurn(event.sessionID)) event.system.push({ type: "text", text: VOICE_STYLE })
-        const parts = orchestratorParts({
-          agent: event.agent,
-          conversation: spoke?.inConversation(event.sessionID) ?? false,
-          subagent: spoke?.subagent() ?? DEFAULT_SUBAGENT,
-          workModel: spoke?.workModelFor(event.sessionID),
-        })
-        for (const text of parts) event.system.push({ type: "text", text })
-      })
-    } catch (cause) {
-      console.error("[hub] could not register the context hook", cause)
-    }
+    // Every registration is independent: they run together, so OpenCode's plugin activation (bounded at ~5 s on a
+    // cold start) waits for about one of them, not their sum.
+    const registrations: Promise<void>[] = [
+      attempt("register the voice agent", () => ctx.agent.transform((editor) => defineVoiceAgent(editor as any))),
+      attempt("register the context hook", () =>
+        ctx.session.hook("context", (event) => {
+          const spoke = membership.active()
+          if (spoke?.isVoiceTurn(event.sessionID)) event.system.push({ type: "text", text: VOICE_STYLE })
+          const parts = orchestratorParts({
+            agent: event.agent,
+            conversation: spoke?.inConversation(event.sessionID) ?? false,
+            subagent: spoke?.subagent() ?? DEFAULT_SUBAGENT,
+            workModel: spoke?.workModelFor(event.sessionID),
+            taskBoard: spoke?.taskBoard(event.sessionID),
+          })
+          for (const text of parts) event.system.push({ type: "text", text })
+        }),
+      ),
+      // The voice agent stops one worker ("cancel the deploy one") without stopping itself or the others.
+      attempt("register the task stop tool", () =>
+        (ctx as any).tool?.transform?.((editor: any) =>
+          editor.add({
+            name: STOP_TOOL,
+            description: STOP_TOOL_DESCRIPTION,
+            input: {
+              type: "object",
+              properties: {
+                sessionID: { type: "string", description: "The worker's sessionID, from your task board or the subagent tool's result." },
+                all: { type: "boolean", description: "true: stop every worker of yours that is still running." },
+              },
+              additionalProperties: false,
+            },
+            options: { codemode: false },
+            execute: async (value: unknown, context: { sessionID: string }) => {
+              const spoke = membership.active()
+              if (!spoke) return { content: "The hub is not running in this OpenCode process; nothing was stopped." }
+              const { stopped, text } = await spoke.stopWorkers(context.sessionID, (value ?? {}) as Record<string, unknown>)
+              return { content: text, metadata: { stopped } }
+            },
+          }),
+        ),
+      ),
+      // Agents message and ask other sessions as themselves (the session's own hub token; src/spoke/hub-tool.ts).
+      attempt("register the hub tool", () =>
+        (ctx as any).tool?.transform?.((editor: any) =>
+          editor.add({
+            name: HUB_TOOL,
+            description: HUB_TOOL_DESCRIPTION,
+            input: HUB_TOOL_INPUT,
+            options: { codemode: false },
+            execute: (value: unknown, context: { sessionID: string; signal?: AbortSignal }) =>
+              runHubTool(() => membership.active(), value, { sessionID: context.sessionID, ...(context.signal ? { signal: context.signal } : {}) }),
+          }),
+        ),
+      ),
+      // @name / @@role in a prompt get context from the hub as an attached text file; the text is never changed
+      // and the harness's own @ meanings win (src/spoke/prompt-refs.ts, design §2.4).
+      attempt("register the prompt hook", () => {
+        const references = new PromptReferences(() => membership.active())
+        return ctx.session.hook("prompt", (event) => references.onPrompt(event))
+      }),
+      registerShellEnv(ctx, (sessionID) => membership.active()?.shellIdentity(sessionID)),
+    ]
 
     const run = async <T>(rpc: { error: (...args: any[]) => any }, action: (spoke: Spoke) => T | Promise<T>) => {
       const spoke = membership.active()
@@ -184,6 +337,7 @@ export default Plugin.define({
         return await action(spoke)
       } catch (cause) {
         if (cause instanceof SpokeError) return rpc.error(cause.name, cause.message, {})
+        if (cause instanceof HubRpcError) return rpc.error(cause.code, cause.message, {})
         return rpc.error("server_error", cause instanceof Error ? cause.message : String(cause), {})
       }
     }
@@ -221,15 +375,13 @@ export default Plugin.define({
           s.presence(sessionIDs.filter((id): id is string => typeof id === "string").slice(0, 200), typeof reporter === "string" ? reporter.slice(0, 100) : undefined)
           return {}
         }),
+      // The TUI's /who and /msg, as its current session (src/spoke/hub-rpc.ts).
+      hubWho: (value, rpc) => run(rpc, (s) => hubWho(s, value)),
+      hubMsg: (value, rpc) => run(rpc, (s) => hubMsg(s, value)),
     } satisfies Parameters<typeof ctx.rpc.register<typeof HubRpc>>[1]
     // "hub", plus the opencode-voice id "voice" for clients built against the old name (see src/rpc.ts).
-    for (const definition of [HubRpc, VoiceRpc]) {
-      try {
-        await ctx.rpc.register(definition, handlers)
-      } catch (cause) {
-        console.error(`[hub] could not register RPC methods (${definition.id})`, cause)
-      }
-    }
+    for (const definition of [HubRpc, VoiceRpc]) registrations.push(attempt(`register RPC methods (${definition.id})`, () => ctx.rpc.register(definition, handlers)))
+    await Promise.all(registrations)
 
     return () => membership.leave()
   },