@huynle/hub 0.7.1 → 0.7.3

package/src/config.ts

@@ -1,6 +1,7 @@
 // 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, existsSync, 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"
@@ -142,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. */

package/src/index.ts

@@ -2,9 +2,10 @@
 // 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 { mkdirSync, readFileSync } from "node:fs"
-import { hostname } from "node:os"
+import { homedir, hostname } from "node:os"
 import { fileURLToPath } from "node:url"
-import { Plugin } from "@opencode/plugin"
+// 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"
@@ -15,7 +16,7 @@ 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 } from "./spoke/launchers"
+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"
@@ -27,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. " +
@@ -199,25 +212,29 @@ async function registerShellEnv(ctx: Context, identity: (sessionID: string) => {
     // 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 })
-    else console.error("[hub] no built hub CLI (packages/cli/dist/hub-cli.js): `hub` is not installed")
+    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
-  try {
+  await attempt("register the shell environment hooks", async () => {
     if (!tool?.hook || !shell?.hook) throw new Error("this OpenCode has no tool/shell hooks")
-    await tool.hook("execute.before", (event: any) => injector.toolBefore(event))
-    await tool.hook("execute.after", (event: any) => injector.toolAfter(event))
-    await shell.hook("create.before", (invocation: any) => injector.shellBefore(invocation))
-  } catch (cause) {
-    console.error("[hub] could not register the shell environment hooks", cause)
-  }
+    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 Plugin.define({
+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).
@@ -249,82 +266,69 @@ export default Plugin.define({
       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),
-          taskBoard: spoke?.taskBoard(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)
-    }
-
-    try {
+    // 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.
-      await (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." },
+      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,
             },
-            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 } }
-          },
-        }),
-      )
-    } catch (cause) {
-      console.error("[hub] could not register the task stop tool", cause)
-    }
-
-    try {
+            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).
-      await (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 } : {}) }),
-        }),
-      )
-    } catch (cause) {
-      console.error("[hub] could not register the hub tool", cause)
-    }
-
-    try {
+      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).
-      const references = new PromptReferences(() => membership.active())
-      await ctx.session.hook("prompt", (event) => references.onPrompt(event))
-    } catch (cause) {
-      console.error("[hub] could not register the prompt hook", cause)
-    }
-
-    await registerShellEnv(ctx, (sessionID) => membership.active()?.shellIdentity(sessionID))
+      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()
@@ -376,13 +380,8 @@ export default Plugin.define({
       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()
   },

package/src/spoke/launchers.ts

@@ -3,8 +3,19 @@
 // bundle shipped in this package with the runtime running the plugin: OpenCode is a Bun-compiled binary that acts
 // as bun under BUN_BE_BUN=1, so no `bun` (or node) needs to be on PATH. Without Bun the bundle runs on `node`.
 // The CLI deletes BUN_BE_BUN from its own env at start, so nothing it starts inherits it.
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs"
+//
+// A standalone hubctl at user-bin:hubctl (~/.local/bin/hubctl, what `hubctl setup` installs) wins: the launchers exec
+// it when it is there (checked at run time), so shells, services and MCP clients all run that one stable authority
+// rather than the bundle in the plugin's install (cache) directory.
+//
+// For the user's own terminals (a plugin-only install, where `hubctl setup` never ran), linkUserBin links
+// ~/.local/bin/hub to the `hub` launcher under the setup's user-bin rule (packages/cli/src/setup/user-bin.ts): only
+// when nothing is there or it is hub's own link, and never when another `hub` is on PATH. ~/.local/bin/hubctl is left
+// to `hubctl setup`: it is the standalone hubctl's install path (a link there would make that install refuse to write
+// through it, and the launchers would exec themselves).
+import { accessSync, chmodSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, readSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs"
 import path from "node:path"
+import { userBinLinkDecision, type UserBinEntry } from "../../packages/cli/src/setup/user-bin.ts"
 
 export const LAUNCHERS = ["hub", "hubctl"] as const
 
@@ -20,14 +31,22 @@ export interface LauncherOptions {
   readonly bun: boolean
   /** The CLI entry the runtime runs. */
   readonly entry: string
+  /** The standalone hubctl to prefer when it exists (standaloneHubctl(home)). */
+  readonly standalone?: string
 }
 
+/** Where `hubctl setup` installs the standalone hubctl (contract user-bin:hubctl). */
+export const standaloneHubctl = (home: string): string => path.join(home, ".local", "bin", "hubctl")
+
 /** A word quoted for sh. */
 const quote = (word: string) => `'${word.replaceAll("'", `'\\''`)}'`
 
-export function launcherScript({ execPath, bun, entry }: LauncherOptions): string {
+const LAUNCHER_HEADER = "#!/bin/sh\n# hub CLI launcher"
+
+export function launcherScript({ execPath, bun, entry, standalone }: LauncherOptions): string {
   const command = bun ? `exec env BUN_BE_BUN=1 ${quote(execPath)} ${quote(entry)} "$@"` : `exec node ${quote(entry)} "$@"`
-  return `#!/bin/sh\n# hub CLI launcher, written by the hub OpenCode plugin at start (edits are overwritten).\n${command}\n`
+  const prefer = standalone ? `if [ -x ${quote(standalone)} ]; then exec ${quote(standalone)} "$@"; fi\n` : ""
+  return `${LAUNCHER_HEADER}, written by the hub OpenCode plugin at start (edits are overwritten).\n${prefer}${command}\n`
 }
 
 /** The entry to run from the package at `root`: the bundle, else (Bun only) the TypeScript source. */
@@ -66,3 +85,90 @@ export function installLaunchers(options: LauncherOptions & { readonly binDir: s
   }
   return { written }
 }
+
+/** The user's own bin dir (contract root user-bin). */
+export const userBinDir = (home: string): string => path.join(home, ".local", "bin")
+
+function entryOf(file: string): UserBinEntry {
+  try {
+    const info = lstatSync(file)
+    return info.isSymbolicLink() ? "symlink" : info.isFile() ? "file" : info.isDirectory() ? "directory" : "other"
+  } catch {
+    return "missing"
+  }
+}
+
+/** A file that starts like the launchers hub writes. */
+function isLauncher(file: string): boolean {
+  let fd: number | undefined
+  try {
+    fd = openSync(file, "r")
+    const buffer = Buffer.alloc(LAUNCHER_HEADER.length)
+    return readSync(fd, buffer, 0, buffer.length, 0) === buffer.length && buffer.toString("utf8") === LAUNCHER_HEADER
+  } catch {
+    return false
+  } finally {
+    if (fd !== undefined) closeSync(fd)
+  }
+}
+
+/** The first executable `name` on `searchPath`, outside `skip`, as found (not followed). */
+function onPath(name: string, searchPath: string, skip: string): string | undefined {
+  for (const dir of searchPath.split(path.delimiter)) {
+    if (!dir || !path.isAbsolute(dir) || path.resolve(dir) === path.resolve(skip)) continue
+    const file = path.join(dir, name)
+    try {
+      if (!statSync(file).isFile()) continue
+      accessSync(file, constants.X_OK)
+      return file
+    } catch {}
+  }
+  return undefined
+}
+
+/**
+ * Links ~/.local/bin/hub to `binDir`/hub (see the header). Returns what it linked, and one hint when the user's
+ * terminal will not find it (~/.local/bin not on `path`, or another `hub` comes first). Small synchronous calls,
+ * nothing when converged (the plugin runs this at start).
+ */
+export function linkUserBin(options: { readonly home: string; readonly binDir: string; readonly path: string | undefined }): { linked: string[]; hint?: string } {
+  // Only the default hub bin dir (~/.local/state/hub/bin): a custom HUB_STATE_DIR (tests, containers, a throwaway
+  // state) must never leave ~/.local/bin pointing into it.
+  if (path.resolve(options.binDir) !== path.join(options.home, ".local", "state", "hub", "bin")) return { linked: [] }
+  const userBin = userBinDir(options.home)
+  const linkPath = path.join(userBin, "hub")
+  const target = path.join(options.binDir, "hub")
+  const entry = entryOf(linkPath)
+  let pointsTo: string | undefined
+  if (entry === "symlink") {
+    try {
+      pointsTo = path.resolve(userBin, readlinkSync(linkPath))
+    } catch {}
+  }
+  const searchPath = options.path ?? ""
+  const onUserPath = searchPath.split(path.delimiter).some((dir) => dir && path.resolve(dir) === path.resolve(userBin))
+  const pathHint = onUserPath ? undefined : `${userBin} is not on PATH: add it to use \`hub\` in your terminal (export PATH="$HOME/.local/bin:$PATH")`
+  // `hubctl setup` linked hub to the standalone hubctl: that is the better hub, keep it.
+  if (pointsTo === standaloneHubctl(options.home)) return { linked: [], ...(pathHint ? { hint: pathHint } : {}) }
+  const foundOnPath = onPath("hub", searchPath, options.binDir)
+  const decision = userBinLinkDecision({ entry, ...(pointsTo !== undefined ? { pointsTo } : {}), target, linkPath, hubOwned: isLauncher, ...(foundOnPath !== undefined ? { foundOnPath } : {}) })
+  if (decision === "foreign") return { linked: [] }
+  if (decision === "shadowed") return { linked: [], hint: `\`hub\` on your PATH is ${foundOnPath}, not hub's CLI; hub's is ${target}` }
+  if (decision === "in-place") return { linked: [], ...(pathHint ? { hint: pathHint } : {}) }
+  mkdirSync(userBin, { recursive: true, mode: 0o755 })
+  // A new link never replaces what may have appeared meanwhile (EEXIST); hub's own is re-pointed atomically.
+  if (decision === "create") {
+    symlinkSync(target, linkPath)
+    return { linked: ["hub"], ...(pathHint ? { hint: pathHint } : {}) }
+  }
+  const tmp = `${linkPath}.${process.pid}.tmp`
+  rmSync(tmp, { force: true })
+  symlinkSync(target, tmp)
+  try {
+    renameSync(tmp, linkPath)
+  } catch (cause) {
+    rmSync(tmp, { force: true })
+    throw cause
+  }
+  return { linked: ["hub"], ...(pathHint ? { hint: pathHint } : {}) }
+}

package/src/spoke/spoke.ts

@@ -15,6 +15,7 @@ import {
   type DeliverRequest,
   type DeliverResult,
   type DeliveryMode,
+  type CompactSessionStatus,
   type JobInfo,
   type HerdrWorkspace,
   type FormAnswer,
@@ -1571,7 +1572,7 @@ export class Spoke {
     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 ids = new Set([...snapshot.active, ...snapshot.jobs.map((j) => j.sessionID), ...this.tracker.working(), ...this.tracker.failed()])
       const now = Date.now()
       for (const id of ids) {
         if (active.has(id)) this.tracker.ensure(id, now)
@@ -1580,9 +1581,12 @@ export class Spoke {
           .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 } }
+        // An active session waiting to retry is seeded with its retry (attempt, reason, next try); the last failure
+        // (no run started since) goes along so a reconnected hub still shows it.
+        const status: CompactSessionStatus = active.has(id) ? (this.tracker.retryOf(id) ?? { type: "busy" }) : { type: "idle" }
+        const error = this.tracker.errorOf(id)
+        this.tracker.seed(id, { status: status.type, jobs })
+        const event = { type: "session.seed", data: { sessionID: id, status, jobs, ...(error ? { error } : {}) } }
         if (this.connection?.state === "connected" && shouldForward(this.config, this.tracker, event)) this.connection.send({ t: "event", event })
       }
       void this.fetchInfo()

package/src/spoke/timeline.ts

@@ -14,7 +14,8 @@ export interface TimelineItem {
   readonly partID?: string
   readonly sessionID: string
   /** "message": a hub message delivered to the session (TimelineMessageItem). */
-  readonly kind: "user" | "assistant" | "reasoning" | "tool" | "message"
+  /** "error": the turn failed; "retry": the provider call is being retried (until the message completes or fails). */
+  readonly kind: "user" | "assistant" | "reasoning" | "tool" | "message" | "error" | "retry"
   readonly text?: string
   readonly name?: string
   readonly state?: "running" | "done" | "failed"
@@ -39,12 +40,20 @@ export interface TimelineItem {
   readonly direction?: TimelineMessageItem["direction"]
   /** Message rows: who sent it, how it was addressed, what it answers. */
   readonly message?: TimelineMessageItem["message"]
+  /** Error and retry rows: the error's type (bounded) and HTTP status (100–599). */
+  readonly errorType?: string
+  readonly errorStatus?: number
+  /** Retry rows: the attempt number and when the next attempt starts (epoch ms). */
+  readonly attempt?: number
+  readonly next?: number
 }
 
 /** Parts of one message a position leaves room for (later parts share the last slot). */
 const POS_PARTS = 1000
 const SUBAGENT_TOOLS = new Set(["subagent", "task"])
 const TITLE_MAX = 160
+const ERROR_TEXT_MAX = 1000
+const ERROR_TYPE_MAX = 64
 
 const record = (value: unknown): Record<string, any> => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : {}
 
@@ -55,7 +64,7 @@ export function timelineItems(sessionID: string, messages: readonly unknown[]):
   for (const raw of messages) {
     const message = record(raw)
     if (typeof message.id !== "string") continue
-    const at = typeof message.time?.created === "number" ? message.time.created : undefined
+    const at = millis(message.time?.created)
     // Messages keep the session's order even when one was created earlier than the one before it (a queued prompt).
     const start = Math.max(at === undefined ? -Infinity : at * POS_PARTS, previous + POS_PARTS)
     const first = (previous = Number.isFinite(start) ? start : 0)
@@ -71,7 +80,12 @@ export function timelineItems(sessionID: string, messages: readonly unknown[]):
       if (row) out.push(row)
       continue
     }
-    if (message.type !== "assistant" || !Array.isArray(message.content)) continue
+    if (message.type !== "assistant") continue
+    const status = statusRow(sessionID, message, at, pos(Array.isArray(message.content) ? message.content.length : 0))
+    if (!Array.isArray(message.content)) {
+      if (status) out.push(status)
+      continue
+    }
     let texts = 0
     message.content.forEach((part: any, index: number) => {
       if (!part || typeof part !== "object") return
@@ -98,10 +112,52 @@ export function timelineItems(sessionID: string, messages: readonly unknown[]):
         })
       }
     })
+    if (status) out.push(status)
   }
   return out
 }
 
+/** Epoch milliseconds of an OpenCode timestamp: a number (ms) or an ISO date string. */
+function millis(value: unknown): number | undefined {
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined
+  if (typeof value !== "string") return undefined
+  const ms = Date.parse(value)
+  return Number.isNaN(ms) ? undefined : ms
+}
+
+/** The bounded type and HTTP status of an OpenCode error, and its trimmed message (else `fallback`). */
+function errorFields(raw: unknown, fallback: string): { text: string; errorType?: string; errorStatus?: number } {
+  const error = record(raw)
+  const message = typeof error.message === "string" ? error.message.trim().slice(0, ERROR_TEXT_MAX) : ""
+  const type = typeof error.type === "string" ? error.type.trim().slice(0, ERROR_TYPE_MAX) : ""
+  const status = error.status
+  return {
+    text: message || fallback,
+    ...(type ? { errorType: type } : {}),
+    ...(Number.isInteger(status) && status >= 100 && status <= 599 ? { errorStatus: status } : {}),
+  }
+}
+
+/**
+ * The status row of an assistant message, after its parts: "error" when the turn failed, "retry" while the
+ * provider call is being retried (no error yet and not completed), else none.
+ */
+function statusRow(sessionID: string, message: Record<string, any>, at: number | undefined, pos: number): TimelineItem | undefined {
+  const base = { messageID: message.id as string, sessionID, ...(at === undefined ? {} : { at }), pos }
+  if (message.error != null) return { key: `${message.id}:error`, kind: "error", ...errorFields(message.error, "failed"), ...base }
+  if (message.retry == null || message.time?.completed != null) return undefined
+  const retry = record(message.retry)
+  const next = millis(retry.at)
+  return {
+    key: `${message.id}:retry`,
+    kind: "retry",
+    ...errorFields(retry.error, "retrying"),
+    ...(Number.isInteger(retry.attempt) && retry.attempt >= 0 ? { attempt: retry.attempt } : {}),
+    ...(next === undefined ? {} : { next }),
+    ...base,
+  }
+}
+
 /** A message the hub delivered (synthetic, with deliverMetadata): a "message" row; other synthetic messages: none. */
 function hubMessageRow(sessionID: string, message: Record<string, any>, at: number | undefined, pos: number): TimelineMessageItem | undefined {
   const meta = record(message.metadata)