@huynle/hub 0.8.0 → 0.8.2

package/packages/node/src/opencode-warm.ts

@@ -16,12 +16,12 @@
 // origin only. Logs on changes only.
 import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync, type Stats } from "node:fs"
 import path from "node:path"
-import { readFile } from "node:fs/promises"
 import { listServiceSessions, type ListingClient, type RawProject, type RawSession } from "../../../src/spoke/listing.ts"
 
 /** How often the daemon asks (a restarted server is warmed within this). */
 export const WARM_INTERVAL_MS = 30_000
-const WARM_TIMEOUT_MS = 10_000
+/** Per-request timeout (node.json opencode.timeoutSeconds overrides it): long enough for a busy machine's first project load. */
+export const WARM_TIMEOUT_MS = 30_000
 /** Project locations warmed per server and tick, besides its default location. */
 export const WARM_DIRECTORIES_MAX = 8
 /** Automatic project locations: sessions updated within this many days, from one page of this many. */
@@ -30,6 +30,8 @@ const SESSION_PAGE = 100
 /** Loopback hosts asked as they are (after URL normalization); localhost is rewritten to 127.0.0.1. */
 const LOOPBACK = new Set(["127.0.0.1", "[::1]"])
 const PASSWORD_FILE_MAX = 4096
+/** Largest service.json read (OpenCode's is a few hundred bytes). */
+const REGISTRATION_MAX = 64 * 1024
 
 /** A local OpenCode server (the service's registration, or a node.json server with its password). */
 export interface WarmEndpoint {
@@ -243,23 +245,40 @@ export class OpenCodeWarmer {
 
 /**
  * OpenCode's background service from its registration file (service.json: {url, pid, password?, id?, version?}),
- * without any request: undefined when the file is missing or malformed or its process is gone. The URL is passed on
- * as it is; OpenCodeWarmer.tick decides whether it may be asked.
+ * without any request: undefined when the file is missing or malformed, is not this user's own (a symbolic link, not
+ * owned by this uid, or writable by group or others), or its process is gone or another user's (EPERM). The URL is
+ * passed on as it is; OpenCodeWarmer.tick decides whether it may be asked.
  */
-export async function readServiceRegistration(file: string): Promise<WarmEndpoint | undefined> {
+export async function readServiceRegistration(file: string, options: { readonly uid?: number } = {}): Promise<WarmEndpoint | undefined> {
+  const uid = options.uid ?? (typeof process.getuid === "function" ? process.getuid() : undefined)
   let info: unknown
+  let fd: number | undefined
   try {
-    info = JSON.parse(await readFile(file, "utf8"))
+    const before = lstatSync(file)
+    if (!before.isFile()) return undefined
+    fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0))
+    const stat = fstatSync(fd)
+    if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino) return undefined
+    if ((stat.mode & 0o022) !== 0) return undefined
+    if (uid !== undefined && stat.uid !== uid) return undefined
+    if (stat.size > REGISTRATION_MAX) return undefined
+    // Read through the descriptor that was checked (no second open by path).
+    const buffer = Buffer.alloc(REGISTRATION_MAX + 1)
+    const length = readSync(fd, buffer, 0, buffer.length, 0)
+    if (length > REGISTRATION_MAX) return undefined
+    info = JSON.parse(buffer.subarray(0, length).toString("utf8"))
   } catch {
     return undefined
+  } finally {
+    if (fd !== undefined) closeSync(fd)
   }
   if (!info || typeof info !== "object") return undefined
   const { url, pid, password } = info as Record<string, unknown>
   if (typeof url !== "string" || url.length > 2048 || typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return undefined
   try {
     process.kill(pid, 0)
-  } catch (cause) {
-    if ((cause as NodeJS.ErrnoException).code !== "EPERM") return undefined
+  } catch {
+    return undefined // gone (ESRCH), or another user's process (EPERM): not this user's service
   }
   return typeof password === "string" ? { url, auth: { type: "basic", username: "opencode", password } } : { url }
 }

package/packages/node/src/run.ts

@@ -50,9 +50,10 @@ export const openCodeServiceFile = (env: Env, home: string): string =>
 function startOpenCodeWarmers(config: NodeConfig, service: () => Promise<WarmEndpoint | undefined>, log: (line: string) => void, signal: AbortSignal): void {
   const roots = () => config.workspaceRoots
   const directories = config.opencode?.directories
-  new OpenCodeWarmer({ discover: service, log, roots, ...(directories ? { directories } : {}) }).start(signal)
+  const timeout = config.opencode?.timeoutSeconds !== undefined ? { timeoutMs: config.opencode.timeoutSeconds * 1000 } : {}
+  new OpenCodeWarmer({ discover: service, log, roots, ...timeout, ...(directories ? { directories } : {}) }).start(signal)
   for (const server of config.opencode?.servers ?? []) {
-    new OpenCodeWarmer({ discover: serverEndpoint(server), log, name: "the OpenCode server", roots, ...(server.directories ? { directories: server.directories } : {}) }).start(signal)
+    new OpenCodeWarmer({ discover: serverEndpoint(server), log, name: "the OpenCode server", roots, ...timeout, ...(server.directories ? { directories: server.directories } : {}) }).start(signal)
   }
 }
 

package/packages/preset/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-preset",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "private": true,
   "description": "The preset spoke: drives a harness without a spoke of its own through a terminal pane (tmux), described by a data-only preset; official presets in presets/ (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-protocol",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "private": true,
   "description": "Hub ↔ spoke wire protocol (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/src/concierge.ts

@@ -98,7 +98,10 @@ export const CONCIERGE_LIMITS = {
 
 // ---- Session context (CON-04, spoke feature "sessionContext") ----
 
-/** The keys of the parts a session context carries, appended to the session's system prompt in this order. */
+/**
+ * The keys of the parts a session context carries. The spoke appends instructions then notes to the session's system
+ * prompt (stable between turns) and sends the board after the conversation (it changes: V-01, the prompt cache).
+ */
 export const SESSION_CONTEXT_KEYS = ["instructions", "board", "notes"] as const
 export type SessionContextKey = (typeof SESSION_CONTEXT_KEYS)[number]
 

package/packages/protocol/src/embedded-media.ts

@@ -0,0 +1,59 @@
+/**
+ * (M1) Embedded media in tool-call details. Harnesses keep tool screenshots inside the tool output: OpenCode 2.2.3 as
+ * `data:` URLs (`read` of a PNG, MCP image results), MCP and Claude Code as raw base64 image parts. A tool-call
+ * detail shows none of these bytes: each is replaced by a short placeholder naming its type and approximate size,
+ * e.g. "[image/png, 1.2 MB — not shown]", so the rest of the detail (input, text output) fits the detail limit and
+ * no image bytes travel to the console. Inline media display is a separate, later feature.
+ */
+
+/** A base64 `data:` URL: optional mime, optional parameters, then the payload. */
+const DATA_URL = /data:([\w.+-]+\/[\w.+-]+)?((?:;[\w.+-]+=[^;,\s"'<>]*)*);base64,([A-Za-z0-9+/_-]+={0,2})/gi
+const BASE64 = /^[A-Za-z0-9+/_-]+={0,2}$/
+const MIME_KEYS = ["mime", "mimeType", "media_type", "mediaType"] as const
+
+/** The approximate decoded size of `length` base64 characters, for people ("10 B", "900 KB", "1.2 MB"). */
+function sizeOf(base64: string): string {
+  const padding = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0
+  const bytes = Math.max(0, Math.floor((base64.length * 3) / 4) - padding)
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+/** The placeholder shown instead of embedded bytes. */
+export function mediaPlaceholder(mime: string | undefined, base64: string): string {
+  return `[${mime || "data"}, ${sizeOf(base64)} — not shown]`
+}
+
+function redactText(text: string): string {
+  if (!text.includes("base64,")) return text
+  return text.replace(DATA_URL, (_match, mime: string | undefined, _params: string, data: string) => mediaPlaceholder(mime?.toLowerCase(), data))
+}
+
+/** The mime of an object that carries raw base64 image bytes in `data`, else undefined. */
+function rawImageMime(object: Record<string, unknown>): string | undefined {
+  if (typeof object.data !== "string" || !BASE64.test(object.data)) return undefined
+  const mime = MIME_KEYS.map((key) => object[key]).find((value): value is string => typeof value === "string")
+  if (mime?.toLowerCase().startsWith("image/")) return mime.toLowerCase()
+  if (object.type === "image" || object.type === "base64") return mime || "image"
+  return undefined
+}
+
+/**
+ * A copy of `value` (JSON-like) with every embedded base64 payload replaced by a placeholder: `data:…;base64,…` URLs
+ * in any string, and raw base64 `data` of image parts. Everything else is kept as it is; `value` is not changed.
+ */
+export function redactEmbeddedMedia<T>(value: T): T {
+  return redact(value) as T
+}
+
+function redact(value: unknown): unknown {
+  if (typeof value === "string") return redactText(value)
+  if (Array.isArray(value)) return value.map(redact)
+  if (!value || typeof value !== "object") return value
+  const object = value as Record<string, unknown>
+  const mime = rawImageMime(object)
+  const out: Record<string, unknown> = {}
+  for (const [key, item] of Object.entries(object)) out[key] = key === "data" && mime ? mediaPlaceholder(mime, item as string) : redact(item)
+  return out
+}

package/packages/protocol/src/index.ts

@@ -31,6 +31,7 @@ export * from "./hub-workspace.ts"
 export * from "./concierge.ts"
 export * from "./profiles.ts"
 export * from "./artifacts.ts"
+export * from "./embedded-media.ts"
 export * from "./teams.ts"
 export * from "./graph.ts"
 export { HUB_URL_MAX_CHARS, isHubURL, MAX_FRAME, MAX_RETRY_AFTER_MS }
@@ -93,7 +94,8 @@ export interface AvailableModel {
  * A timeline page. Forward mode (`cursor`): oldest rows first, `cursor` for the next newer page. Newest-first
  * mode (`order: "desc"` or `before`): the newest rows (before `before`) in chronological order, `older` for the
  * page before them. Both cursors are opaque. Items are the spoke's rows (src/spoke/timeline.ts TimelineItem); newer
- * spokes add optional `pos` (ordering position), `callID`, `childSessionID`, `title` and `ordinal`.
+ * spokes add optional `pos` (ordering position), `callID`, `childSessionID`, `title`, `ordinal` and, on error rows,
+ * `declined` (a denied permission stopped the turn).
  */
 export interface TimelinePage {
   readonly items: readonly unknown[]
@@ -154,6 +156,14 @@ export interface SessionInfo {
    * Older hubs ignore it.
    */
   readonly revert?: SessionRevertInfo
+  /**
+   * The latest revert committed in this session as this process saw it (feature "revert"): the history from
+   * `messageID` on was removed. Hub message rows (agent messages the session sent or got) from `from` (the reverted
+   * message's time, when known) until `until` (when the revert was staged; later ones were held for after it) belonged
+   * to that history: the hub keeps the window and leaves them out. `at` (commit time) changes with every commit.
+   * Older hubs ignore it.
+   */
+  readonly revertCommitted?: RevertCommitted
   /**
    * (CON-04, feature "sessionContext") Sessions the hub gave a locked context (the Concierge): the agent the spoke
    * last saw the session run on, and the context revision it holds now (absent: none, e.g. after a restart). The hub
@@ -161,6 +171,11 @@ export interface SessionInfo {
    */
   readonly agent?: string
   readonly contextRevision?: number
+  /**
+   * (FX-07) The session is locked as a Concierge session on this spoke (sent from the first sessions frame after a
+   * restart, before `agent` or `contextRevision` are known). The hub treats it as a Concierge session.
+   */
+  readonly locked?: true
 }
 
 /** Most files a revert summary or preview lists (`filesTotal` counts them all). */
@@ -187,6 +202,21 @@ export interface SessionRevertInfo {
   /** Restored files (at most REVERT_FILES_MAX). */
   readonly files: readonly RevertFile[]
   readonly filesTotal: number
+  /** When this process saw it staged (epoch ms; optional, older spokes send none). */
+  readonly stagedAt?: number
+}
+
+/** A committed revert's removed window (SessionInfo.revertCommitted). */
+export interface RevertCommitted {
+  readonly messageID: string
+  readonly from?: number
+  readonly until: number
+  readonly at: number
+}
+
+/** A committed revert's window as a spoke reports it. */
+export function isRevertCommitted(v: unknown): v is RevertCommitted {
+  return isObj(v) && nonEmpty(v.messageID) && v.messageID.length <= 300 && (v.from === undefined || num(v.from)) && num(v.until) && num(v.at)
 }
 
 /** An attachment of a user message, by its position in the message's files (fetched through timelineFile). */
@@ -824,8 +854,29 @@ export interface Res {
   readonly ok: boolean
   readonly result?: unknown
   readonly error?: string
+  /**
+   * A refusal's kind, so the hub need not match `error` texts (optional and additive: older hubs ignore it, older
+   * spokes send none). See RES_ERROR_CODES; a peer may send codes the other does not know (they are ignored).
+   */
+  readonly code?: string
 }
 
+/**
+ * Refusal codes a spoke puts on `{ok: false}` answers: "busy" (the session runs, e.g. a revert while a turn is
+ * running; the hub answers 409 busy) and "not_found" (the session, or the message an op names, is not there; 404).
+ */
+export const RES_ERROR_CODES = ["busy", "not_found"] as const
+export type ResErrorCode = (typeof RES_ERROR_CODES)[number]
+/** Longest `code` a res frame carries. */
+export const RES_CODE_MAX = 40
+
+/** The spoke's refusal of a revert while the session runs (code "busy"). */
+export const REVERT_BUSY = "The session is working; wait for it to finish (or stop it) before reverting"
+/** The spoke's refusal of a restore or commit while the session runs (code "busy"). */
+export const REVERT_END_BUSY = "The session is working; wait for it to finish (or stop it) before restoring or committing the revert"
+/** A fork or revert naming a message that is not one of the session's user messages (code "not_found"). */
+export const NOT_A_USER_MESSAGE = "Not a user message of this session"
+
 export interface Bye {
   readonly t: "bye"
   readonly reason: string
@@ -910,8 +961,10 @@ function isSession(v: unknown): v is SessionInfo {
     (v.open === undefined || typeof v.open === "boolean") &&
     (v.terminal === undefined || isTerminal(v.terminal)) &&
     (v.revert === undefined || isSessionRevert(v.revert)) &&
+    (v.revertCommitted === undefined || isRevertCommitted(v.revertCommitted)) &&
     (v.agent === undefined || (nonEmpty(v.agent) && v.agent.length <= AGENT_NAME_MAX)) &&
-    (v.contextRevision === undefined || (Number.isSafeInteger(v.contextRevision) && (v.contextRevision as number) >= 0))
+    (v.contextRevision === undefined || (Number.isSafeInteger(v.contextRevision) && (v.contextRevision as number) >= 0)) &&
+    (v.locked === undefined || v.locked === true)
   )
 }
 
@@ -942,7 +995,8 @@ export function isSessionRevert(v: unknown): v is SessionRevertInfo {
     v.files.length <= REVERT_FILES_MAX &&
     v.files.every(isRevertFile) &&
     count(v.filesTotal) &&
-    (v.filesTotal as number) >= v.files.length
+    (v.filesTotal as number) >= v.files.length &&
+    (v.stagedAt === undefined || num(v.stagedAt))
   )
 }
 
@@ -1181,8 +1235,11 @@ export function parseSpokeMessage(raw: string | Buffer): SpokeMessage | undefine
         (m.launchID === undefined || (str(m.launchID) && ID.test(m.launchID)))
         ? (m as unknown as Hello)
         : undefined
-    case "sessions":
-      return Array.isArray(m.sessions) && m.sessions.every(isSession) ? (m as unknown as Sessions) : undefined
+    case "sessions": {
+      if (!Array.isArray(m.sessions)) return undefined
+      const sessions = m.sessions.map(lenientSession)
+      return sessions.every(isSession) ? ({ ...m, sessions } as unknown as Sessions) : undefined
+    }
     case "terminals":
       return m.herdr === undefined || isHerdrInfo(m.herdr) ? (m as unknown as Terminals) : undefined
     case "event":
@@ -1192,7 +1249,7 @@ export function parseSpokeMessage(raw: string | Buffer): SpokeMessage | undefine
     case "req":
       return nonEmpty(m.id) && isSpokeRequest(m.req) ? (m as unknown as Req<SpokeRequest>) : undefined
     case "res":
-      return isRes(m) ? (m as unknown as Res) : undefined
+      return isRes(m) ? lenientRes(m) : undefined
     case "bye":
       return isBye(m) ? (m as unknown as Bye) : undefined
     default:
@@ -1200,6 +1257,32 @@ export function parseSpokeMessage(raw: string | Buffer): SpokeMessage | undefine
   }
 }
 
+/** A res frame without an invalid `code` (over-long, empty or not a string): ignored, as for older peers. */
+function lenientRes(m: Record<string, unknown>): Res {
+  if (m.code === undefined || (nonEmpty(m.code) && m.code.length <= RES_CODE_MAX)) return m as unknown as Res
+  const { code: _dropped, ...rest } = m
+  return rest as unknown as Res
+}
+
+/**
+ * A reported session without malformed additive revert fields (`revertCommitted`, `revert.stagedAt`): they are
+ * dropped (older hubs ignore them too), never failing the whole sessions frame.
+ */
+function lenientSession(v: unknown): unknown {
+  if (!isObj(v)) return v
+  let out: Record<string, unknown> = v
+  if (out.revertCommitted !== undefined && !isRevertCommitted(out.revertCommitted)) {
+    const { revertCommitted: _dropped, ...rest } = out
+    out = rest
+  }
+  const revert = out.revert
+  if (isObj(revert) && revert.stagedAt !== undefined && !num(revert.stagedAt)) {
+    const { stagedAt: _dropped, ...rest } = revert
+    out = { ...out, revert: rest }
+  }
+  return out
+}
+
 /** Parses a frame received by the spoke. Returns undefined for anything invalid. */
 export function parseServerMessage(raw: string | Buffer): ServerMessage | undefined {
   const m = parse(raw)
@@ -1210,7 +1293,7 @@ export function parseServerMessage(raw: string | Buffer): ServerMessage | undefi
     case "req":
       return nonEmpty(m.id) && isServerRequest(m.req) ? (m as unknown as Req<ServerRequest>) : undefined
     case "res":
-      return isRes(m) ? (m as unknown as Res) : undefined
+      return isRes(m) ? lenientRes(m) : undefined
     case "bye":
       return isBye(m) ? (m as unknown as Bye) : undefined
     default:

package/packages/protocol/src/launch.ts

@@ -103,6 +103,14 @@ export interface LaunchArtifacts {
   readonly dirty?: boolean
 }
 
+/** Why a queued launch waits (FX-02): capacity (a fitting node is full), no_match (no node fits), active (the per-user cap). */
+export interface LaunchWaitingInfo {
+  readonly wait: "capacity" | "no_match" | "active"
+  readonly reason: string
+  /** ms epoch: since when it has waited for this kind of reason. */
+  readonly since: number
+}
+
 /** A launch as the API reports it. */
 export interface LaunchInfo {
   readonly id: string
@@ -118,6 +126,12 @@ export interface LaunchInfo {
   readonly name?: string
   readonly outcome?: LaunchOutcome
   readonly artifacts?: LaunchArtifacts
+  /** Only while queued: why it waits (`reason` is the same text). */
+  readonly waiting?: LaunchWaitingInfo
+  /** The launcher's label when it launched (an app token's label). */
+  readonly byLabel?: string
+  /** The app token that launched it was revoked: it still runs and counts toward the cap until stopped. */
+  readonly launcherRevoked?: boolean
 }
 
 // ---------- checks ----------

package/packages/protocol/src/wire.ts

@@ -17,6 +17,7 @@ export const featureList = (v: unknown): v is string[] => Array.isArray(v) && v.
 /** Control (C0, C1), format (bidi, zero-width, BOM) and line/paragraph separator characters. */
 export const UNSAFE_CHARS = /[\p{Cc}\p{Cf}\u2028\u2029]/u
 
+/** A res frame (an optional `code` is not checked here: an invalid one is dropped, never fatal; see parse). */
 export const isResFrame = (v: Record<string, unknown>): boolean => nonEmpty(v.id) && typeof v.ok === "boolean" && (v.error === undefined || str(v.error))
 /** Longest reconnect delay a bye's retryAfterMs may ask for (5 minutes). */
 export const MAX_RETRY_AFTER_MS = 300_000

package/packages/runtime-openshell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-openshell",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "private": true,
   "description": "The `openshell` runtime of `hub node`: launches in NVIDIA OpenShell sandboxes, driven through the openshell CLI (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/runtime-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-sdk",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "private": true,
   "description": "The Runtime interface `hub node` runtimes implement (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-sdk",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "private": true,
   "description": "Typed client for the hub's /api/agent (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/sdk/src/client.ts

@@ -320,6 +320,8 @@ export interface ActOptions extends CallOptions {
 export interface ApproveOptions extends ActOptions {
   /** Approve for good (OpenCode saves the rule); agents need a grant with allowAlways. */
   readonly always?: boolean
+  /** (R-03) The Concierge advises approving: only then does its escalation Decision recommend approve. */
+  readonly recommend?: boolean
 }
 
 export interface PromptOptions extends ActOptions {
@@ -688,7 +690,7 @@ export class HubClient {
 
   /** Approves a pending permission request in a session's tree. */
   approve(addr: string, requestID: string, options: ApproveOptions = {}): Promise<Approved> {
-    const body = { requestID, ...(options.always ? { always: true } : {}), ...whyField(options) }
+    const body = { requestID, ...(options.always ? { always: true } : {}), ...(options.recommend ? { recommend: true } : {}), ...whyField(options) }
     return this.call("POST", `${AGENT}/sessions/${segment(addr)}/approve`, { body, ...signalOf(options) })
   }
 

package/packages/sdk/src/errors.ts

@@ -21,6 +21,7 @@ export type ErrorCode =
   | "rate_limited"
   | "internal"
   | "offline"
+  | "busy"
   | (string & {})
 
 export interface Envelope {

package/packages/sdk/src/index.ts

@@ -11,5 +11,6 @@ export * from "./concierge.ts"
 export * from "./envelope.ts"
 export * from "./errors.ts"
 export * from "./sse.ts"
+export * from "./wake.ts"
 export * from "./webhook.ts"
 export type * from "./types.ts"

package/packages/sdk/src/types.ts

@@ -269,8 +269,11 @@ export type MessageKind = "msg" | "ask" | "reply" | "decline"
 /** `sent` for msg/reply/decline; asks are open until answered, declined or expired. */
 export type MessageState = "sent" | "open" | "answered" | "declined" | "expired"
 /** How a message reached its recipient session. */
-/** (CON-10) "dropped": it was pending for a session that ended for good (a retired Concierge session); never delivered. */
-export type MessageDelivery = "steer" | "turn" | "queued" | "retained" | "pending" | "dropped"
+/**
+ * (CON-10) "dropped": it was pending for a session that ended for good (a retired Concierge session); never delivered.
+ * "expired": it was pending for 24 h (its recipient stayed offline or busy); never delivered, and its sender was told.
+ */
+export type MessageDelivery = "steer" | "turn" | "queued" | "retained" | "pending" | "dropped" | "expired"
 
 /** A stored agent message. */
 export interface AgentMessage {
@@ -296,10 +299,21 @@ export interface AgentMessage {
   readonly answer?: { readonly id: string; readonly at: number }
 }
 
+/**
+ * Why a message to a session did not start a turn: the sender asked wake:false, the recipient is a subagent
+ * (never woken), the reply chain went past the hop cap (8 hops without a human turn), or the recipient's wake
+ * budget (30 per 10 minutes) is spent. The message is still delivered.
+ */
+export type WakeSkip = "wake_false" | "subagent" | "hop_cap" | "budget"
+
 /** POST /api/agent/msg and /ask: the stored message and how it was delivered (none: stored only). */
 export interface Sent {
   readonly message: AgentMessage
   readonly delivery?: MessageDelivery
+  /** Messages to a session: whether the hub sent it to wake the recipient (absent from hubs before 0.8.1). */
+  readonly woke?: boolean
+  /** When woke is false: why. */
+  readonly wakeSkipped?: WakeSkip
 }
 
 /** POST /api/agent/msg or /ask with all: one per session. */
@@ -577,6 +591,12 @@ export interface LaunchView {
   readonly updated: number
   /** Who launched it: `user`, `app:<token id>` or a session ID. */
   readonly by?: string
+  /** The launcher's label when it launched (an app token's label). */
+  readonly byLabel?: string
+  /** The app token that launched it was revoked: it still runs and counts toward the cap until stopped. */
+  readonly launcherRevoked?: boolean
+  /** Only while queued: why it waits (`reason` is the same text). */
+  readonly waiting?: { readonly wait: "capacity" | "no_match" | "active"; readonly reason: string; readonly since: number }
   readonly machineID?: string
   readonly directory?: string
   readonly sessionID?: string

package/packages/sdk/src/wake.ts

@@ -0,0 +1,20 @@
+// Why a message did not wake its recipient (Sent.woke / Sent.wakeSkipped, hub 0.8.1), in the words the CLI, `hub mcp`
+// and the OpenCode hub tool show: one place so every client says the same thing.
+import type { Sent, WakeSkip } from "./types.ts"
+
+/** One short reason per WakeSkip. */
+export const WAKE_SKIP_TEXT: Readonly<Record<WakeSkip, string>> = {
+  wake_false: "sent without a wake",
+  subagent: "subagents are never woken",
+  hop_cap: "hop limit reached (8 agent messages without a human turn)",
+  budget: "wake budget spent (30 per 10 minutes)",
+}
+
+/**
+ * ` — wake skipped: <reason>` when the hub did not wake the recipient and the message waits for a later turn; empty
+ * when it woke, went into a running turn (steer) or started one, or the hub did not say (hubs before 0.8.1).
+ */
+export function wakeSkipNote({ delivery, woke, wakeSkipped }: Pick<Sent, "delivery" | "woke" | "wakeSkipped">): string {
+  if (woke !== false || !wakeSkipped || delivery === "steer" || delivery === "turn") return ""
+  return ` — wake skipped: ${WAKE_SKIP_TEXT[wakeSkipped] ?? wakeSkipped}`
+}

package/packages/spoke-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-spoke-sdk",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "private": true,
   "description": "Harness-neutral spoke building blocks: hub connection, enrollment, tokens, idempotent deliver, prompt references, HarnessSpoke (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/spoke-sdk/src/connection.ts

@@ -11,6 +11,7 @@ import {
   type ServerRequest,
   type SpokeMessage,
   type SpokeRequest,
+  type ResErrorCode,
   type Welcome,
 } from "../../protocol/src/index.ts"
 
@@ -67,6 +68,17 @@ const defaultSocket = (url: string, headers: Record<string, string>): SocketLike
 
 const message = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause))
 
+/** An op's refusal with a protocol code (Res.code, RES_ERROR_CODES): the hub maps it without matching the text. */
+export class CodedError extends Error {
+  constructor(
+    message: string,
+    readonly code: ResErrorCode,
+  ) {
+    super(message)
+    this.name = "CodedError"
+  }
+}
+
 interface Pending {
   resolve: (value: unknown) => void
   reject: (error: Error) => void
@@ -245,7 +257,7 @@ export class SpokeConnection {
     try {
       reply = { t: "res", id, ok: true, result: await this.options.handle(req) }
     } catch (cause) {
-      reply = { t: "res", id, ok: false, error: message(cause) }
+      reply = { t: "res", id, ok: false, error: message(cause), ...(cause instanceof CodedError ? { code: cause.code } : {}) }
     }
     this.send(reply)
   }

package/src/central/agent/acting-routes.ts

@@ -1,6 +1,6 @@
 // The act verbs on /api/agent (design §5, §8; decision wvqeuis0): thin HTTP over the acting engine (acting.ts).
 //
-//   POST /api/agent/sessions/:addr/approve {requestID, always?, why?}
+//   POST /api/agent/sessions/:addr/approve {requestID, always?, why?, recommend?}   recommend: a Concierge advises it (R-03)
 //   POST /api/agent/sessions/:addr/deny    {requestID, why?}               why → the harness, with who denied it
 //   POST /api/agent/sessions/:addr/answer  {formID, answer | cancel: true, why?}
 //   POST /api/agent/sessions/:addr/prompt  {text, images? (users), delivery? "queue"|"steer", wake?, why?}
@@ -65,7 +65,8 @@ export function actingRoutes(acting: Acting): AgentRoute[] {
       async handle({ request, params, actor, user }) {
         const body = await bodyOf(request)
         const always = flag(body, "always")
-        return ok(await acting.approve({ actor, userID: user.id }, params.addr!, { requestID: id(body, "requestID"), ...(always ? { always } : {}), ...why(body) }))
+        const recommend = flag(body, "recommend")
+        return ok(await acting.approve({ actor, userID: user.id }, params.addr!, { requestID: id(body, "requestID"), ...(always ? { always } : {}), ...(recommend ? { recommend } : {}), ...why(body) }))
       },
     },
     {