@huynle/hub 0.8.1 → 0.8.2

package/src/spoke/locations.ts

@@ -11,6 +11,7 @@ export interface PermissionLocation {
   /** `message`: a reject's reason (OpenCode's reply message). */
   reply(input: { sessionID: string; requestID: string; decision: PermissionDecision; message?: string }): Promise<unknown>
   vcs?: { diff(): Promise<ReadonlyArray<unknown>>; branch(): Promise<string | undefined> }
+  names?(): Promise<LocalNames>
 }
 
 /**
@@ -73,3 +74,82 @@ export function vcsReader(locations: () => readonly PermissionLocation[], server
     },
   }
 }
+
+
+/** A directory's local skill and command names (a hub profile's of the same name give way to them). */
+export interface LocalNames {
+  readonly skills: readonly string[]
+  readonly commands: readonly string[]
+}
+
+/** A directory's local names; undefined: nothing could read that directory's. */
+export type NamesSource = (directory: string) => Promise<LocalNames | undefined>
+
+/** How long two reads of a directory's names must agree before they count (OpenCode loads them one source at a time). */
+export const NAMES_SETTLE_MS = 500
+
+/**
+ * Reads a directory's local skill and command names like vcsReader reads its VCS state: through the plugin
+ * instance whose location is that directory, else the own server's API (which honours the location), else not
+ * at all (undefined). OpenCode's plugin skill.list / command.list answer for the instance's own location whatever
+ * location is passed, so the first instance would report another directory's names. A location OpenCode is still
+ * loading lists nothing, then its built-ins, then its own commands and skills one source at a time: the names
+ * count once they list a command (OpenCode always has built-in ones) and two reads `settleMs` apart agree. A read
+ * that fails, or does not settle within `timeoutMs`, is unknown.
+ */
+export function namesReader(
+  locations: () => readonly PermissionLocation[],
+  server: () => Promise<NamesSource | undefined>,
+  timeoutMs: number = VCS_READ_TIMEOUT_MS,
+  settleMs: number = NAMES_SETTLE_MS,
+): NamesSource {
+  return (directory) => {
+    const local = locations().find((l) => l.directory === directory && l.names)
+    let done = false
+    const settled = async (read: NamesSource): Promise<LocalNames | undefined> => {
+      let previous = await read(directory)
+      while (!done) {
+        await new Promise((resolve) => setTimeout(resolve, settleMs))
+        const next = await read(directory)
+        if (next === undefined) return undefined
+        if (next.commands.length && previous && sameNames(previous, next)) return next
+        previous = next
+      }
+      return undefined
+    }
+    const reading = local?.names ? settled(() => local.names!()) : server().then((read) => (read ? settled(read) : undefined))
+    return within(reading, timeoutMs).finally(() => (done = true))
+  }
+}
+
+function sameNames(a: LocalNames, b: LocalNames): boolean {
+  const same = (x: readonly string[], y: readonly string[]) => x.length === y.length && x.every((name, i) => name === y[i])
+  return same(a.skills, b.skills) && same(a.commands, b.commands)
+}
+
+/** The `name` of each item of a plugin or HTTP API list (bare, or wrapped as { location, data }). */
+export function listedNames(value: unknown): string[] {
+  const v = value as any
+  const list = Array.isArray(v) ? v : Array.isArray(v?.data) ? v.data : []
+  return list.flatMap((item: any) => (typeof item?.name === "string" ? [item.name] : []))
+}
+
+interface ListApi {
+  list(input: { location: { directory: string } }): Promise<unknown>
+}
+
+/** A directory's names over the own server's API (skill.list / command.list honour the location there); an answer for another directory is unknown. */
+export function serverNames(client: { skill: ListApi; command: ListApi }): NamesSource {
+  return async (directory) => {
+    const location = { directory }
+    const [skills, commands] = await Promise.all([client.skill.list({ location }), client.command.list({ location })])
+    if ([skills, commands].some((answer) => answeredFor(answer) !== undefined && answeredFor(answer) !== directory)) return undefined
+    return { skills: listedNames(skills), commands: listedNames(commands) }
+  }
+}
+
+/** The directory a wrapped { location, data } answer is for (undefined: a bare answer). */
+function answeredFor(answer: unknown): string | undefined {
+  const directory = (answer as any)?.location?.directory
+  return typeof directory === "string" ? directory : undefined
+}

package/src/spoke/profile-apply.ts

@@ -7,9 +7,11 @@
 // - Skills and commands: listed in that system part and served by the `hub_profile` tool (registered once per
 //   process like the `hub` tool; the context hook hides it from sessions without a profile, and it answers only
 //   the calling session's layer). OpenCode's skill/command registries are location-wide, so they are not used.
-//   Same-named local skills/commands win (partial). Commands that reference `{{secret:NAME}}` are skipped: a
-//   rendered command becomes a persisted prompt or tool result in OpenCode, and resolved secrets must never be
-//   written (renderAtInvocation false). The model preference is ignored (the user's model is never switched).
+//   Same-named local skills/commands win (partial); their names are read in the session's own folder, and when they
+//   cannot be read the profile's skills and commands are not offered (partial with a note; the instructions apply).
+//   Commands that reference `{{secret:NAME}}` are skipped: a rendered command becomes a persisted prompt or tool
+//   result in OpenCode, and resolved secrets must never be written (renderAtInvocation false). The model preference
+//   is ignored (the user's model is never switched).
 // - Next-turn boundary: an idle session's layer is replaced at once (its next turn reads it). For a busy session
 //   the new layer is staged, the running turn keeps the previous one, and the answer waits for the turn to end
 //   (Spoke.observe calls settle; a poll backs it up). The answer echoes exactly the version that became
@@ -41,11 +43,19 @@ export const PROFILE_TOOL_INPUT = {
   additionalProperties: false,
 } as const
 
+/** The note of an apply whose session's local skill and command names could not be read. */
+const UNKNOWN_NAMES_NOTE = "skills and commands not offered: the session's local skills and commands could not be read"
+/** The planner's notes for skills/commands this adapter did not offer (replaced by UNKNOWN_NAMES_NOTE). */
+const ADAPTER_UNSUPPORTED = /^(skills|commands) not supported by this harness adapter$/
+
 export interface OpenCodeProfilesOptions {
   /** The session has a turn running (OpenCode busy, or a hub turn in progress). */
   readonly isBusy: (sessionID: string) => boolean
-  /** The session's local skill and command names; absent: skills and commands are not applied. */
-  readonly localNames?: (sessionID: string) => Promise<ProfileLocalNames>
+  /**
+   * The session's local skill and command names, read in its own folder; absent: skills and commands are not
+   * applied. Undefined or a failure: unknown, so the instructions apply and the skills and commands are not offered.
+   */
+  readonly localNames?: (sessionID: string) => Promise<ProfileLocalNames | undefined>
   /** The hub_profile tool is available in this OpenCode. */
   readonly tool: () => boolean
   /** How long a busy session's answer waits for the boundary (default 120 s). */
@@ -177,20 +187,20 @@ export class OpenCodeProfiles {
       this.supersede(sessionID, req)
       return { result: current.result }
     }
+    // Local names are read only when there is something they could shadow. Unknown names (unreadable in the
+    // session's own folder) never reject the apply: the skills and commands are just not offered.
+    const tool = this.options.tool()
+    const wantsBindings = tool && (req.content.skills.length > 0 || req.content.commands.length > 0)
     let local: ProfileLocalNames | undefined
-    if (this.options.localNames) {
-      try {
-        local = await this.options.localNames(sessionID)
-      } catch {
-        return { result: profileApplyResult(req, "rejected", ["could not read the session's local skills and commands (they take precedence); nothing applied"]) }
-      }
-    }
-    const bindings = this.options.tool() && local !== undefined
+    if (wantsBindings && this.options.localNames) local = await this.options.localNames(sessionID).catch(() => undefined)
+    const unknown = wantsBindings && this.options.localNames !== undefined && local === undefined
+    const bindings = tool && local !== undefined
     const plan = planProfileApplication(req, {
       capabilities: { instructions: true, skills: bindings, commands: bindings, model: false, live: true, renderAtInvocation: false },
       ...(local ? { local } : {}),
     })
-    const result = profileApplyResult(req, plan.status, plan.notes)
+    const notes = unknown ? [UNKNOWN_NAMES_NOTE, ...plan.notes.filter((note) => !ADAPTER_UNSUPPORTED.test(note))] : plan.notes
+    const result = profileApplyResult(req, plan.status, notes)
     if (plan.status === "unsupported") return { result }
     const layer: Layer = { result, ...(plan.instructions !== undefined ? { instructions: plan.instructions } : {}), skills: plan.skills, commands: plan.commands }
     this.supersede(sessionID, req)

package/src/spoke/session-context.ts

@@ -1,8 +1,11 @@
 // CON-04 session contexts (spoke feature "sessionContext"; contract packages/protocol/src/concierge.ts). The hub pushes
 // a session's per-turn context; the spoke keeps it in this process's memory (like profile layers, profile-apply.ts):
 //
-// - parts: appended by the plugin's context hook after the profile parts, in key order (instructions, board,
-//   notes). The whole set replaces the previous one.
+// - parts: instructions then notes are appended by the plugin's context hook after the profile parts; the board goes
+//   after the conversation as a system message (V-01: it changes between turns, and OpenCode sends tools, system,
+//   then messages, so a board in the system prompt made every push re-write the cached conversation; see
+//   applySessionContext). The whole set replaces the previous one.
+// - The kept tools are put in name order (the request lists them in the hook's record order).
 // - tools.allow: the exact tool names the session keeps; the hook deletes every other tool on every turn (unknown
 //   future tools included: fail closed). tools.deny: globs of tool names deleted as well.
 // - Revisions: an older revision than the effective one is refused ("stale"); the same one is answered again.
@@ -18,15 +21,76 @@
 // another agent.
 import { closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs"
 import path from "node:path"
-import { CONCIERGE_TOOLS, SESSION_CONTEXT_KEYS, type SessionContextRequest, type SessionContextResult, toolDenied } from "../../packages/protocol/src/concierge.ts"
+import { CONCIERGE_TOOLS, type SessionContextKey, type SessionContextRequest, type SessionContextResult, toolDenied } from "../../packages/protocol/src/concierge.ts"
 
 interface Context {
   readonly revision: number
+  /** The stable parts (instructions, notes): the end of the system prompt. */
   readonly parts: readonly string[]
+  /** The changing parts (board): after the conversation. */
+  readonly tail: readonly string[]
   readonly deny: readonly string[]
   readonly allow?: ReadonlySet<string>
 }
 
+/** Parts at the end of the system prompt (stable between turns), in this order. */
+const SYSTEM_KEYS: readonly SessionContextKey[] = ["instructions", "notes"]
+/** Parts after the conversation (they change between turns). */
+const TAIL_KEYS: readonly SessionContextKey[] = ["board"]
+const EPHEMERAL = { type: "ephemeral" } as const
+
+interface HookPart {
+  type: string
+  text?: string
+  cache?: unknown
+}
+interface HookMessage {
+  role: string
+  content: HookPart[]
+}
+
+/** The tools in name order (OpenCode sends them in the record's order: the request's prefix must not move). */
+export function sortTools(tools: Record<string, unknown>): void {
+  const entries = Object.entries(tools).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+  for (const [name] of entries) delete tools[name]
+  for (const [name, tool] of entries) tools[name] = tool
+}
+
+/** An OpenCode effort message (a system message carrying only the reasoning effort). */
+const isEffort = (m: HookMessage) => m.role === "system" && m.content.length === 1 && m.content[0]?.type === "effort"
+
+/** The index of the last item matching (-1: none). */
+const lastIndex = <T>(items: readonly T[], match: (item: T) => boolean) => {
+  for (let i = items.length - 1; i >= 0; i--) if (match(items[i]!)) return i
+  return -1
+}
+
+/** A cache hint on the message's last text part (else its last part that is not compaction or effort). */
+function hint(message: HookMessage): void {
+  const text = lastIndex(message.content, (p) => p.type === "text")
+  const index = text >= 0 ? text : lastIndex(message.content, (p) => p.type !== "compaction" && p.type !== "effort")
+  const part = message.content[index]
+  if (part && part.cache === undefined) message.content[index] = { ...part, cache: EPHEMERAL }
+}
+
+/**
+ * (V-01) Adds a session context to a context hook's request so the provider's prompt cache survives a board change.
+ * OpenCode sends tools, the system parts, then the messages; it puts cache breakpoints on the last tool, the first and
+ * last system part and the last message (4 at most). The stable parts end the system prompt (the last one carries a
+ * hint); the board follows the conversation as one system message (with a hint), and the conversation's last message
+ * gets a hint, so the next turn reads everything up to it from the cache whatever the board says. Without a board
+ * nothing is added after the conversation; a request without messages gets the board in its system prompt.
+ */
+export function applySessionContext(event: { system: HookPart[]; messages?: HookMessage[] }, system: readonly string[], tail: readonly string[]): void {
+  const messages = Array.isArray(event.messages) ? event.messages : undefined
+  const ending = messages ? system : [...system, ...tail]
+  ending.forEach((text, i) => event.system.push(i === ending.length - 1 ? { type: "text", text, cache: EPHEMERAL } : { type: "text", text }))
+  if (!messages || !tail.length) return
+  const last = messages[lastIndex(messages, (m) => !isEffort(m))]
+  if (last) hint(last)
+  messages.push({ role: "system", content: [{ type: "text", text: tail.join("\n\n"), cache: EPHEMERAL }] })
+}
+
 /** Locked sessions kept at most (oldest dropped; the hub keeps 20 Concierge sessions per user). */
 const LOCKS_MAX = 1000
 const LOCKED_TOOLS: ReadonlySet<string> = new Set(CONCIERGE_TOOLS)
@@ -191,9 +255,9 @@ export class SessionContexts {
     this.cleared.delete(req.sessionID)
     if (req.lockAgent) this.lock(req.sessionID)
     const byKey = new Map(req.parts.map((p) => [p.key, p.text]))
-    const parts = SESSION_CONTEXT_KEYS.flatMap((key) => (byKey.has(key) ? [byKey.get(key)!] : []))
+    const pick = (keys: readonly SessionContextKey[]) => keys.flatMap((key) => (byKey.has(key) ? [byKey.get(key)!] : []))
     const allow = req.tools?.allow
-    this.contexts.set(req.sessionID, { revision: req.revision, parts, deny: [...(req.tools?.deny ?? [])], ...(allow ? { allow: new Set(allow) } : {}) })
+    this.contexts.set(req.sessionID, { revision: req.revision, parts: pick(SYSTEM_KEYS), tail: pick(TAIL_KEYS), deny: [...(req.tools?.deny ?? [])], ...(allow ? { allow: new Set(allow) } : {}) })
     this.bound(this.contexts)
     return { revision: req.revision }
   }
@@ -207,11 +271,16 @@ export class SessionContexts {
     while (map.size > this.maxSessions) map.delete(map.keys().next().value as string)
   }
 
-  /** The session's parts for its system prompt (none without a context). */
+  /** The session's stable parts for the end of its system prompt: instructions, notes (none without a context). */
   systemParts(sessionID: string): string[] {
     return [...(this.contexts.get(sessionID)?.parts ?? [])]
   }
 
+  /** The session's changing parts, sent after its conversation: the board (none without a context). */
+  tailParts(sessionID: string): string[] {
+    return [...(this.contexts.get(sessionID)?.tail ?? [])]
+  }
+
   /** A Concierge session: only CONCIERGE_TOOLS, its agent and model kept, no conversation mode. */
   locked(sessionID: string): boolean {
     if (!this.locks.has(sessionID)) this.refresh()
@@ -234,6 +303,7 @@ export class SessionContexts {
   filterTools(sessionID: string, tools: Record<string, unknown>): void {
     if (!this.contexts.has(sessionID) && !this.locked(sessionID)) return
     for (const name of Object.keys(tools)) if (this.denied(sessionID, name)) delete tools[name]
+    sortTools(tools)
   }
 
   /** Records the agent a locked session runs on; true when it changed (a new report is due). */

package/src/spoke/spoke.ts

@@ -33,12 +33,12 @@ import {
   type TurnResult,
 } from "../protocol"
 import { extractReply } from "../reply"
-import { busyError, NOT_A_USER_MESSAGE, REVERT_BUSY, revertPreview, revertSummary, userContent, userIndex, visibleMessages } from "./fork-revert"
+import { copiesHubIdentity, forkIdentityNote, notAUserMessage, opError, REVERT_BUSY, REVERT_END_BUSY, revertPreview, revertSummary, userContent, userIndex, visibleMessages, withStagedAt } from "./fork-revert"
 import { TurnTracker } from "../turns"
 import { TimelineCache, boundedTimelinePart, newestPage, timelineFile, timelineItems } from "./timeline"
-import { SpokeConnection, type Backoff, type ConnectionState } from "./client"
+import { CodedError, SpokeConnection, type Backoff, type ConnectionState } from "./client"
 import { PROMPT_SOURCE, VOICE_AGENT } from "./conversation"
-import { DeliveryLedger, deferredWhileBusy, deliverMetadata, deliverText, harnessMessageID, InboxOrigins, planDelivery, QUIET_WHILE_BUSY } from "./deliver"
+import { DeliveryLedger, deferredWhileBusy, deliverMetadata, deliverText, harnessMessageID, InboxOrigins, planDelivery, QUIET_WHILE_BUSY, REVERT_STAGED } from "./deliver"
 import { pollEnrollment, startEnrollment } from "./enroll"
 import { HerdrWatcher, openInHerdr, type HerdrRunner } from "./herdr"
 import type { LocalHubResult } from "./localhub"
@@ -157,8 +157,11 @@ export interface SpokeHost {
   vcsDiff?(directory: string): Promise<ReadonlyArray<unknown> | undefined>
   /** Current branch of a directory. */
   vcsBranch?(directory: string): Promise<string | undefined>
-  /** (HWA-16) A location's local skill and command names (they win over a hub profile's); absent: none applied. */
-  localNames?(directory: string): Promise<{ skills: readonly string[]; commands: readonly string[] }>
+  /**
+   * (HWA-16) A location's local skill and command names (they win over a hub profile's), read in that folder;
+   * undefined: unknown (the profile's skills and commands are not offered). Absent: none applied.
+   */
+  localNames?(directory: string): Promise<{ skills: readonly string[]; commands: readonly string[] } | undefined>
   /** (HWA-16) The plugin registered the hub_profile tool (profile skills and commands need it). */
   readonly profileTool?: boolean
   /**
@@ -198,6 +201,8 @@ export interface SpokeOptions {
   readonly pluginVersion: string
   readonly turnTimeoutMs?: number
   readonly snapshotDebounceMs?: number
+  /** How long a fork waits for its hub identity note to go in (default FORK_NOTE_TIMEOUT_MS). */
+  readonly forkNoteTimeoutMs?: number
   readonly snapshotIntervalMs?: number
   readonly seedIntervalMs?: number
   /** Delay before re-listing the service's sessions after a session event (default 2 s). */
@@ -298,6 +303,8 @@ 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"
+/** How long a fork waits for its hub identity note (a synthetic message) before it answers without it. */
+export const FORK_NOTE_TIMEOUT_MS = 5_000
 const CANNOT_FORK = "This OpenCode process cannot fork sessions (its server cannot be reached)"
 const CANNOT_REVERT = "This OpenCode process cannot revert sessions (its server cannot be reached)"
 /** OpenCode's revert events (session.revert.staged, .cleared, .committed). */
@@ -340,6 +347,8 @@ export class Spoke {
   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()
+  /** Per session: a counter of revert events (a staged event's late read must not undo a later one). */
+  private readonly revertSeq = new Map<string, number>()
   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. */
@@ -1058,7 +1067,8 @@ export class Spoke {
       case "form":
         return this.form("cancel" in req ? { sessionID: req.sessionID, formID: req.formID, cancel: true } : { sessionID: req.sessionID, formID: req.formID, answer: req.answer })
       case "context":
-        return { messages: contextMessages(await this.host.context(req.sessionID)) }
+        // A staged revert's hidden messages are not part of the conversation any more.
+        return { messages: contextMessages(await this.shownMessages(req.sessionID)) }
       case "models": {
         const raw = await this.host.listModels?.() ?? []
         return {
@@ -1152,27 +1162,45 @@ export class Spoke {
         // Only a session this process reports (mode "always" exposes any ID; a profile needs a real session).
         if (!this.tracker.has(req.sessionID)) throw new Error(UNKNOWN_SESSION)
         return this.profiles.handle(req)
+      // Fork and revert: OpenCode's busy and not-found failures answer coded refusals (Res.code).
       case "fork":
-        return this.fork(req.sessionID, req.messageID)
-      case "revertPreview": {
-        const messages = await this.host.context(req.sessionID)
-        const index = userIndex(messages, req.messageID)
-        if (index < 0) throw new Error(NOT_A_USER_MESSAGE)
-        return revertPreview(messages, index) satisfies ResultFor["revertPreview"]
-      }
+        return this.fork(req.sessionID, req.messageID).catch((cause) => {
+          throw opError(cause, REVERT_BUSY)
+        })
+      case "revertPreview":
+        return this.revertPreview(req.sessionID, req.messageID).catch((cause) => {
+          throw opError(cause, REVERT_BUSY)
+        })
       case "revert":
-        return this.revert(req.sessionID, req.messageID, req.files)
+        return this.revert(req.sessionID, req.messageID, req.files).catch((cause) => {
+          throw opError(cause, REVERT_BUSY)
+        })
       case "revertRestore":
-        if (!this.canRevert()) throw new Error(CANNOT_REVERT)
-        await this.host.revertClear!(req.sessionID)
-        return this.revertDone(req.sessionID)
       case "revertCommit":
-        if (!this.canRevert()) throw new Error(CANNOT_REVERT)
-        await this.host.revertCommit!(req.sessionID)
-        return this.revertDone(req.sessionID)
+        return this.revertEnd(req.sessionID, req.op).catch((cause) => {
+          throw opError(cause, REVERT_END_BUSY)
+        })
     }
   }
 
+  private async revertPreview(sessionID: string, messageID: string): Promise<ResultFor["revertPreview"]> {
+    const messages = await this.host.context(sessionID)
+    const index = userIndex(messages, messageID)
+    if (index < 0) throw notAUserMessage()
+    return revertPreview(messages, index)
+  }
+
+  /** Restores (revert.clear) or commits a staged revert; refused while the session runs (OpenCode refuses it too). */
+  private async revertEnd(sessionID: string, op: "revertRestore" | "revertCommit"): Promise<Record<string, never>> {
+    if (!this.canRevert()) throw new Error(CANNOT_REVERT)
+    if (op === "revertRestore") await this.host.revertClear!(sessionID)
+    else {
+      await this.host.revertCommit!(sessionID)
+      this.recordCommit(sessionID)
+    }
+    return this.revertDone(sessionID)
+  }
+
   private canRevert(): boolean {
     return this.host.revertStage !== undefined && this.host.revertClear !== undefined && this.host.revertCommit !== undefined
   }
@@ -1186,7 +1214,7 @@ export class Spoke {
     if (!fork) throw new Error(CANNOT_FORK)
     const messages = await this.host.context(sessionID)
     const index = userIndex(messages, messageID)
-    if (index < 0) throw new Error(NOT_A_USER_MESSAGE)
+    if (index < 0) throw notAUserMessage()
     const session = await fork({ sessionID, before: messageID })
     if (typeof session?.id !== "string" || !session.id) throw new Error("OpenCode did not report the forked session")
     const title = typeof session.title === "string" ? session.title : ""
@@ -1203,9 +1231,34 @@ export class Spoke {
     })
     if (this.config.mode === "session") this.setSession(session.id, true)
     this.sendSnapshot()
+    if (copiesHubIdentity(messages, index)) await this.forkNote(session.id, forkIdentityNote(sessionID, source?.title))
     return { sessionID: session.id, ...(title ? { title } : {}), ...userContent(messages[index]) }
   }
 
+  /**
+   * OpenCode's fork copies the source's hub primer (its hub name and roles), and has no way to drop a message: the
+   * fork gets a hub note (admitted without a turn, like a primer) that the identity is not its own. Best effort.
+   */
+  private async forkNote(forkID: string, text: string): Promise<void> {
+    const synthetic = this.host.synthetic?.bind(this.host)
+    if (!synthetic) return
+    const id = harnessMessageID(`fork-note:${forkID}`)
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const ms = this.options.forkNoteTimeoutMs ?? FORK_NOTE_TIMEOUT_MS
+    try {
+      this.origins.hub(id)
+      // Never holds the fork's answer for long: a note that is slow to go in is given up (logged).
+      await Promise.race([
+        synthetic({ sessionID: forkID, id, text, metadata: { source: PROMPT_SOURCE, messageID: id, kind: "primer", from: "hub", to: forkID }, delivery: "steer", resume: false }),
+        new Promise((_, reject) => (timer = setTimeout(() => reject(new Error(`no answer in ${ms} ms`)), ms))),
+      ])
+    } catch (cause) {
+      console.error("[hub] could not tell a fork that its hub identity is not its own", cause)
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
   /**
    * Stages a revert from one of the session's user messages (feature "revert"), with the files restored when
    * `files`, and reports it at once. Refused while the session runs (OpenCode refuses it too).
@@ -1214,16 +1267,10 @@ export class Spoke {
     if (!this.canRevert()) throw new Error(CANNOT_REVERT)
     const messages = await this.host.context(sessionID)
     const index = userIndex(messages, messageID)
-    if (index < 0) throw new Error(NOT_A_USER_MESSAGE)
-    if (this.running.has(sessionID) || this.tracker.isBusy(sessionID)) throw new Error(REVERT_BUSY)
-    let staged: unknown
-    try {
-      staged = await this.host.revertStage!({ sessionID, messageID, files })
-    } catch (cause) {
-      if (busyError(cause)) throw new Error(REVERT_BUSY)
-      throw cause
-    }
-    const revert = revertSummary(staged, messages) ?? revertSummary({ messageID }, messages)!
+    if (index < 0) throw notAUserMessage()
+    if (this.running.has(sessionID) || this.tracker.isBusy(sessionID)) throw new CodedError(REVERT_BUSY, "busy")
+    const staged = await this.host.revertStage!({ sessionID, messageID, files })
+    const revert = withStagedAt(revertSummary(staged, messages) ?? revertSummary({ messageID }, messages)!, this.tracker.revertOf(sessionID), Date.now())
     this.timelines.invalidate(sessionID)
     // Sent at once even when OpenCode's staged event already set it (its snapshot may still be debounced).
     this.tracker.setRevert(sessionID, revert)
@@ -1250,21 +1297,52 @@ export class Spoke {
     ])
     if (!this.canRevert()) return messages
     const raw = session ? (session as { revert?: unknown }).revert : undefined
-    const revert = session ? revertSummary(raw, messages) : this.tracker.revertOf(sessionID)
+    const known = this.tracker.revertOf(sessionID)
+    const read = session ? revertSummary(raw, messages) : known
+    const revert = session && read ? withStagedAt(read, known, Date.now()) : read
     if (session && this.tracker.setRevert(sessionID, revert)) this.scheduleSnapshot()
     return visibleMessages(messages, revert?.messageID)
   }
 
-  /** A revert staged, restored or committed anywhere (this hub, the terminal, another client): reported. */
+  /**
+   * Records a commit of the session's revert (op or OpenCode's committed event) as its removed window
+   * (SessionInfo.revertCommitted). Without a known staged revert: the event of a commit already recorded changes
+   * nothing; otherwise a window without a start (the console still reloads on it). Returns true when it changed.
+   */
+  private recordCommit(sessionID: string, to?: string): boolean {
+    const staged = this.tracker.revertOf(sessionID)
+    const messageID = staged?.messageID ?? to
+    if (!messageID) return false
+    if (!staged && this.tracker.committedOf(sessionID)?.messageID === messageID) return false
+    const now = Date.now()
+    return this.tracker.setCommitted(sessionID, { messageID, ...(staged?.at === undefined ? {} : { from: staged.at }), until: staged?.stagedAt ?? now, at: now })
+  }
+
+  /**
+   * A revert staged, restored or committed anywhere (this hub, the terminal, another client): reported. A staged
+   * event reads the history; a later event that arrives meanwhile (a prompt committing it at once) wins, and the
+   * late read only fills in the commit's window start.
+   */
   private async observeRevert(event: EventLike, sessionID: string): Promise<void> {
     if (!this.tracker.has(sessionID)) return
+    const seq = (this.revertSeq.get(sessionID) ?? 0) + 1
+    this.revertSeq.set(sessionID, seq)
     if (event.type !== "session.revert.staged") {
-      if (this.tracker.setRevert(sessionID, undefined)) this.scheduleSnapshot()
+      const data = event.data as Record<string, unknown>
+      const committed = event.type === "session.revert.committed" && this.recordCommit(sessionID, typeof data.to === "string" && data.to ? data.to : undefined)
+      if (committed) this.timelines.invalidate(sessionID)
+      if (this.tracker.setRevert(sessionID, undefined) || committed) this.scheduleSnapshot()
       return
     }
     try {
       const raw = (event.data as Record<string, unknown>).revert
-      const revert = revertSummary(raw, await this.host.context(sessionID))
+      const read = revertSummary(raw, await this.host.context(sessionID))
+      if (this.revertSeq.get(sessionID) !== seq) {
+        const commit = this.tracker.committedOf(sessionID)
+        if (commit && commit.from === undefined && read?.at !== undefined && read.messageID === commit.messageID && this.tracker.setCommitted(sessionID, { ...commit, from: read.at })) this.scheduleSnapshot()
+        return
+      }
+      const revert = read && withStagedAt(read, this.tracker.revertOf(sessionID), Date.now())
       if (this.tracker.setRevert(sessionID, revert)) this.scheduleSnapshot()
     } catch (cause) {
       console.error("[hub] could not read a staged revert", cause)
@@ -1279,6 +1357,8 @@ export class Spoke {
     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 () => {
+      // Defence in depth: the hub holds deliveries while it sees the revert; this process may know it first.
+      if (this.tracker.revertOf(req.sessionID)) throw new Error(REVERT_STAGED)
       const subagent = (this.tracker.parentOf(req.sessionID) ?? (await this.host.getSession(req.sessionID).catch(() => undefined))?.parentID) !== undefined
       const busy = this.running.has(req.sessionID) || this.tracker.isBusy(req.sessionID)
       // A routine quiet message into a running turn would still cost a model call: refused, the hub keeps it
@@ -1454,7 +1534,7 @@ export class Spoke {
     }
     const host = this.host
     const [messages, models, mcp, diffs, branch] = await Promise.all([
-      optional(() => host.context(sessionID)),
+      optional(() => this.shownMessages(sessionID)),
       optional(host.listModels && (() => host.listModels!())),
       optional(host.mcpList && (() => host.mcpList!(directory))),
       optional(host.vcsDiff && (() => host.vcsDiff!(directory))),

package/src/spoke/timeline.ts

@@ -1,4 +1,4 @@
-import { DELIVER_ID_MAX, MESSAGE_KINDS, PROMPT_IMAGE_MIMES, summarizeToolInput, type MessageKind, type PromptImage, type TimelineMessageItem } from "../protocol"
+import { DELIVER_ID_MAX, MESSAGE_KINDS, PROMPT_IMAGE_MIMES, redactEmbeddedMedia, summarizeToolInput, type MessageKind, type PromptImage, type TimelineMessageItem } from "../protocol"
 import { PROMPT_SOURCE } from "./conversation"
 
 /** An attachment of a user message: its position in the message's files (for timelineFile), type and name. */
@@ -45,6 +45,11 @@ export interface TimelineItem {
   /** Error and retry rows: the error's type (bounded) and HTTP status (100–599). */
   readonly errorType?: string
   readonly errorStatus?: number
+  /**
+   * (R-04) Error rows: a permission was denied and that stopped the turn (OpenCode fails the declined tool call with
+   * "The user declined this tool call" and the step with "Step interrupted"). Whoever denied it is the hub's audit's.
+   */
+  readonly declined?: true
   /** Retry rows: the attempt number and when the next attempt starts (epoch ms). */
   readonly attempt?: number
   readonly next?: number
@@ -56,6 +61,14 @@ const SUBAGENT_TOOLS = new Set(["subagent", "task"])
 const TITLE_MAX = 160
 const ERROR_TEXT_MAX = 1000
 const ERROR_TYPE_MAX = 64
+/**
+ * OpenCode's error on a tool call the user (or an agent answering for them) denied, and on the step it then ends
+ * (2.2.3, SessionStep: failTool(call, {type: "aborted", message: DECLINED_TOOL}), failAssistant({type: "aborted",
+ * message: "Step interrupted"})). Both types are matched, so a tool that throws the same text (tool.execution) cannot
+ * mark its turn denied.
+ */
+const DECLINED_TOOL = "The user declined this tool call"
+const ABORTED = "aborted"
 
 const record = (value: unknown): Record<string, any> => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : {}
 
@@ -149,7 +162,7 @@ function errorFields(raw: unknown, fallback: string): { text: string; errorType?
  */
 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.error != null) return { key: `${message.id}:error`, kind: "error", ...errorFields(message.error, "failed"), ...(declinedTool(message) ? { declined: true as const } : {}), ...base }
   if (message.retry == null || message.time?.completed != null) return undefined
   const retry = record(message.retry)
   const next = millis(retry.at)
@@ -163,6 +176,16 @@ function statusRow(sessionID: string, message: Record<string, any>, at: number |
   }
 }
 
+/** (R-04) Whether the message's step was aborted because one of its tool calls' permission was denied. */
+function declinedTool(message: Record<string, any>): boolean {
+  if (!Array.isArray(message.content) || record(message.error).type !== ABORTED) return false
+  return message.content.some((part: any) => {
+    if (part?.type !== "tool" || part.state?.status !== "error") return false
+    const error = record(part.state.error)
+    return error.type === ABORTED && error.message === DECLINED_TOOL
+  })
+}
+
 /** 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)
@@ -325,8 +348,12 @@ export function timelinePart(messages: readonly unknown[], messageID: string, pa
 }
 
 const DETAIL_MAX_BYTES = 750_000
+/**
+ * A tool call's detail for the console: embedded images (tool screenshots as data: URLs or base64 parts) become
+ * small placeholders, so they never count against the limit nor travel to the console; huge text still fails.
+ */
 export function boundedTimelinePart(messages: readonly unknown[], messageID: string, partID: string): unknown {
-  const detail = timelinePart(messages, messageID, partID)
+  const detail = redactEmbeddedMedia(timelinePart(messages, messageID, partID))
   if (JSON.stringify(detail).length > DETAIL_MAX_BYTES) throw new Error("Timeline part is too large to display")
   return detail
 }