@huynle/hub 0.7.3 → 0.8.0

package/src/central/workspaces/supervision.ts

@@ -0,0 +1,355 @@
+// Workspace supervision graph (HWA-05; contract docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md,
+// packages/protocol/src/hub-workspace.ts SupervisionLink, supervisionInputProblem, supervisionViolation).
+//
+// A supervision link says "member M is supervised by member S" inside one workspace. Each member has at most one
+// direct supervisor; the graph is acyclic and no member is more than `depth` links below a root (the contract's
+// supervisionDepth, master = depth 0). Links name members, and a member is one generation of a session in the
+// workspace, so a link always pins the supervisor's generation: a replacement (new generation, new member ID) only
+// inherits links through an explicit memberDeparted(…, {replacedBy}).
+//
+// Storage: StateStore collection `workspace-supervision`, ONE aggregate per workspace (key: workspace ID) holding
+// every link and the graph `revision` (0 before the first write, +1 per write). The StateStore has no cross-record
+// transactions, so the whole graph is one version-checked write (ifVersion): a cycle or depth check is always made
+// against the graph that is written over, and two concurrent opposing edges can never both land. Mutations name the
+// graph revision they read (`expectedRevision`, required by the HTTP route, optional for internal callers); a
+// mismatch is a 409 conflict with `currentRevision`. Without it, a lost race re-reads and re-checks, so the later
+// edge of an opposing pair is refused as a cycle. Each link also carries its own `revision` (1 on attach, +1 per
+// move or reorder); a detach removes it and a re-attach is a new link ID.
+//
+// Members: both ends must be current members of the workspace (unknown: not_found; departed: invalid), and the
+// workspace's master cannot be given a supervisor (it is the root). Every write reads the supervision aggregate
+// FIRST and the members second: any member a stored link names joined before that link was written, so it is in
+// the later member read unless it was pruned for having departed. Departure is terminal, so each write drops the
+// links whose ends are departed or no longer retained (`pruned`). Reads report such stale links truthfully
+// (`left` / `missing`) rather than hiding them; memberDeparted (HWA-06 calls it after leave / sessionEnded /
+// archive) detaches a departed member's links, or moves them to its replacement when the move stays acyclic and
+// within depth (otherwise detached and counted). Archived workspaces read but refuse changes.
+//
+// Authority: supervision grants nothing and is separate from native session ancestry. This module never reads or
+// writes parent/root session fields, grants, the directory or the registry: the own-tree permission/form ban and
+// the root-only prompt rule of the acting engine are untouched. Events (HWA-06) carry IDs, revisions and counts.
+//
+// Limits: links per workspace (429 rate_limited at the cap; a move is not a new link), depth (400 invalid with
+// extra.violation "depth"), cycles (400 invalid with extra.violation "cycle"), order a finite number within
+// ±ORDER_MAX (fractions allowed so a drag can land between two siblings without renumbering them).
+// Other builds: an aggregate with a newer `v` answers 422 unsupported and is left untouched; a malformed one is a
+// 500. Rollback: older hubs never read this collection, so it stays dormant.
+import { randomBytes } from "node:crypto"
+import {
+  CONTRACT_VERSION,
+  ID_PREFIXES,
+  type IdKind,
+  isContractID,
+  type SupervisionLink,
+  supervisionInputProblem,
+  supervisionViolation,
+  WORKSPACE_LIMITS,
+  type WorkspaceMember,
+} from "../../protocol"
+import { AgentError } from "../agent/errors"
+import type { Clock, StateStore } from "../backend/types"
+import type { MembershipStore } from "./members"
+import type { WorkspaceStore } from "./store"
+
+export const WORKSPACE_SUPERVISION = "workspace-supervision"
+/** Largest |order| a link may carry. */
+export const ORDER_MAX = 1e9
+/** Version-checked write attempts before a contended change gives up. */
+const ATTEMPTS = 16
+
+export interface SupervisionLimits {
+  /** Links per workspace (the contract's supervisionLinksPerWorkspace). */
+  readonly linksPerWorkspace: number
+  /** Links from the deepest member up to its root (the contract's supervisionDepth). */
+  readonly depth: number
+}
+
+export const SUPERVISION_LIMITS: SupervisionLimits = {
+  linksPerWorkspace: WORKSPACE_LIMITS.supervisionLinksPerWorkspace,
+  depth: WORKSPACE_LIMITS.supervisionDepth,
+}
+
+export interface SupervisionStoreDeps {
+  readonly state: StateStore
+  readonly workspaces: Pick<WorkspaceStore, "require">
+  readonly members: Pick<MembershipStore, "members">
+  readonly now?: Clock
+  readonly newID?: (kind: IdKind) => string
+  readonly limits?: Partial<SupervisionLimits>
+}
+
+/** A link end as the members read it: a current member, a departed one, or no longer retained. */
+export type LinkEnd = "current" | "left" | "missing"
+
+export interface SupervisionLinkView {
+  readonly link: SupervisionLink
+  readonly member: LinkEnd
+  readonly supervisor: LinkEnd
+}
+
+export interface SupervisionGraph {
+  readonly workspaceID: string
+  /** The graph revision a mutation names as expectedRevision (0: never written). */
+  readonly revision: number
+  /** In storage order (stable); the dashboard sorts siblings by `order`. */
+  readonly links: readonly SupervisionLinkView[]
+}
+
+export type SupervisionChange = "attached" | "moved" | "reordered" | "detached" | "unchanged"
+
+export interface SupervisionResult {
+  readonly workspaceID: string
+  /** The graph revision after the call. */
+  readonly revision: number
+  readonly change: SupervisionChange
+  /** The member's link after the call (absent when it has no supervisor). */
+  readonly link?: SupervisionLink
+  /** Stale links (departed or missing ends) dropped by this write. */
+  readonly pruned: number
+}
+
+export interface DepartureResult {
+  readonly workspaceID: string
+  readonly revision: number
+  /** Links naming the departed member that were removed. */
+  readonly detached: number
+  /** Links naming the departed member moved to its replacement. */
+  readonly transferred: number
+  /** Other stale links dropped by the same write. */
+  readonly pruned: number
+}
+
+interface SupervisionDoc {
+  readonly v: 1
+  readonly workspaceID: string
+  readonly revision: number
+  readonly links: readonly SupervisionLink[]
+}
+
+type Members = ReadonlyMap<string, WorkspaceMember>
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const isNum = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v)
+
+const conflict = (currentRevision: number) =>
+  new AgentError("conflict", `The supervision graph changed since you read it (revision ${currentRevision} now)`, {
+    hint: "Read it again and retry with its current revision",
+    extra: { currentRevision },
+  })
+
+/** The stored aggregate, or an empty graph; newer versions are unsupported, malformed ones internal. */
+function readDoc(raw: unknown, workspaceID: string): SupervisionDoc {
+  if (raw === undefined) return { v: 1, workspaceID, revision: 0, links: [] }
+  if (isObj(raw) && isNum(raw.v) && raw.v > CONTRACT_VERSION)
+    throw new AgentError("unsupported", `Workspace ${workspaceID} supervision was written by a newer hub`, {
+      hint: "Upgrade this hub",
+      extra: { feature: WORKSPACE_SUPERVISION },
+    })
+  if (!isObj(raw) || raw.v !== CONTRACT_VERSION || raw.workspaceID !== workspaceID || !Number.isSafeInteger(raw.revision) || !Array.isArray(raw.links))
+    throw new AgentError("internal", "Stored workspace supervision is malformed")
+  return raw as unknown as SupervisionDoc
+}
+
+const endOf = (members: Members, id: string): LinkEnd => {
+  const member = members.get(id)
+  return !member ? "missing" : member.leftAt === undefined ? "current" : "left"
+}
+
+const isLive = (members: Members, link: SupervisionLink) => endOf(members, link.memberID) === "current" && endOf(members, link.supervisorMemberID) === "current"
+
+const edges = (links: readonly SupervisionLink[]) => new Map(links.map((l) => [l.memberID, l.supervisorMemberID]))
+
+function violationError(violation: "cycle" | "depth", depth: number): AgentError {
+  return violation === "cycle"
+    ? new AgentError("invalid", "That supervisor is supervised by this member (directly or through others): it would make a cycle", {
+        hint: "Move the supervisor elsewhere first",
+        extra: { violation },
+      })
+    : new AgentError("invalid", `Supervision is at most ${depth} levels deep`, { hint: "Attach the member (or its subtree) higher up", extra: { violation, depth } })
+}
+
+/** A current member in the snapshot: not_found when unknown, invalid when departed. */
+function current(members: Members, workspaceID: string, memberID: string): WorkspaceMember {
+  const member = members.get(memberID)
+  if (!member) throw new AgentError("not_found", `No member ${memberID} in workspace ${workspaceID}`)
+  if (member.leftAt !== undefined) throw new AgentError("invalid", `Member ${memberID} left the workspace`, { hint: "Use a current member" })
+  return member
+}
+
+export class SupervisionStore {
+  readonly limits: SupervisionLimits
+  private readonly state: StateStore
+  private readonly newID: (kind: IdKind) => string
+
+  constructor(private readonly deps: SupervisionStoreDeps) {
+    this.state = deps.state
+    this.newID = deps.newID ?? ((kind) => `${ID_PREFIXES[kind]}_${randomBytes(12).toString("hex")}`)
+    this.limits = { ...SUPERVISION_LIMITS, ...deps.limits }
+  }
+
+  /** The workspace's links with each end's membership state, and the graph revision. */
+  async graph(userID: string, workspaceID: string): Promise<SupervisionGraph> {
+    await this.deps.workspaces.require(userID, workspaceID)
+    const doc = readDoc((await this.state.get(userID, WORKSPACE_SUPERVISION, workspaceID))?.value, workspaceID)
+    const members = await this.memberMap(userID, workspaceID)
+    return {
+      workspaceID,
+      revision: doc.revision,
+      links: doc.links.map((link) => ({ link, member: endOf(members, link.memberID), supervisor: endOf(members, link.supervisorMemberID) })),
+    }
+  }
+
+  /**
+   * PUT /workspaces/:id/supervision: `{memberID, supervisorMemberID | null, order?, expectedRevision}`. Attaches,
+   * moves, reorders or (null) detaches the member's one supervision link in a single version-checked write.
+   */
+  async set(userID: string, workspaceID: string, input: unknown): Promise<SupervisionResult> {
+    if (!isObj(input)) throw new AgentError("invalid", "body must be an object")
+    const expectedRevision = input.expectedRevision
+    const problem = supervisionInputProblem(expectedRevision === undefined ? { ...input, expectedRevision: 0 } : input)
+    if (problem) throw new AgentError("invalid", problem)
+    const memberID = input.memberID as string
+    const supervisorID = input.supervisorMemberID as string | null
+    const order = input.order
+    if (order !== undefined) {
+      if (supervisorID === null) throw new AgentError("invalid", "order applies to an attached member, not a detach")
+      if (!isNum(order) || Math.abs(order) > ORDER_MAX) throw new AgentError("invalid", `order must be a finite number within ±${ORDER_MAX}`)
+    }
+    const workspace = await this.deps.workspaces.require(userID, workspaceID)
+    if (workspace.state === "archived") throw new AgentError("invalid", `Workspace ${workspaceID} is archived`, { hint: "Restore it first" })
+
+    let result: Omit<SupervisionResult, "workspaceID" | "revision" | "pruned"> = { change: "unchanged" }
+    const written = await this.mutate(userID, workspaceID, (doc, members) => {
+      if (expectedRevision !== undefined && doc.revision !== expectedRevision) throw conflict(doc.revision)
+      const live = doc.links.filter((l) => isLive(members, l))
+      current(members, workspaceID, memberID)
+      if (supervisorID !== null) current(members, workspaceID, supervisorID)
+      const existing = live.find((l) => l.memberID === memberID)
+      result = { change: "unchanged", ...(existing ? { link: existing } : {}) }
+      let links = live
+      if (supervisorID === null) {
+        if (existing) {
+          links = live.filter((l) => l !== existing)
+          result = { change: "detached" }
+        }
+      } else if (existing && existing.supervisorMemberID === supervisorID) {
+        if (order !== undefined && order !== existing.order) {
+          const link = { ...existing, order: order as number, revision: existing.revision + 1 }
+          links = live.map((l) => (l === existing ? link : l))
+          result = { change: "reordered", link }
+        }
+      } else {
+        if (memberID === workspace.masterMemberID)
+          throw new AgentError("invalid", `Member ${memberID} is the master: the root of supervision has no supervisor`, { hint: "Replace the master first" })
+        const violation = supervisionViolation(edges(live), memberID, supervisorID, this.limits.depth)
+        if (violation) throw violationError(violation, this.limits.depth)
+        if (!existing && live.length >= this.limits.linksPerWorkspace)
+          throw new AgentError("rate_limited", `A workspace has at most ${this.limits.linksPerWorkspace} supervision links`, { hint: "Detach some first" })
+        const siblings = live.filter((l) => l.supervisorMemberID === supervisorID && l.memberID !== memberID).map((l) => l.order)
+        const at = (order as number | undefined) ?? (siblings.length ? Math.max(...siblings) + 1 : 0)
+        if (existing) {
+          const link = { ...existing, supervisorMemberID: supervisorID, order: at, revision: existing.revision + 1 }
+          links = live.map((l) => (l === existing ? link : l))
+          result = { change: "moved", link }
+        } else {
+          const link: SupervisionLink = { v: 1, id: this.newID("supervision"), workspaceID, supervisorMemberID: supervisorID, memberID, order: at, revision: 1 }
+          links = [...live, link]
+          result = { change: "attached", link }
+        }
+      }
+      return result.change === "unchanged" && live.length === doc.links.length ? undefined : links
+    })
+    return { workspaceID, ...result, revision: written.doc.revision, pruned: written.pruned }
+  }
+
+  /**
+   * A member departed (left, ended, archived or replaced): detaches its links, or with `replacedBy` (a current
+   * member, e.g. HWA-12's new master generation) moves them to the replacement where that stays acyclic, within
+   * depth and one supervisor per member; the rest are detached. Members it supervised without a transfer become
+   * roots. Refuses a current member (invalid): supervision follows membership, never the other way round.
+   */
+  async memberDeparted(userID: string, workspaceID: string, memberID: string, options: { readonly replacedBy?: string } = {}): Promise<DepartureResult> {
+    if (!isContractID("member", memberID)) throw new AgentError("invalid", "memberID must be a workspace member ID")
+    const { replacedBy } = options
+    if (replacedBy !== undefined && !isContractID("member", replacedBy)) throw new AgentError("invalid", "replacedBy must be a workspace member ID")
+    const workspace = await this.deps.workspaces.require(userID, workspaceID)
+    let detached = 0
+    let transferred = 0
+    const written = await this.mutate(userID, workspaceID, (doc, members) => {
+      if (members.get(memberID)?.leftAt === undefined && members.has(memberID))
+        throw new AgentError("invalid", `Member ${memberID} is still current`, { hint: "Supervision follows membership: remove the member first" })
+      if (replacedBy !== undefined) current(members, workspaceID, replacedBy)
+      detached = 0
+      transferred = 0
+      const affected = (l: SupervisionLink) => l.memberID === memberID || l.supervisorMemberID === memberID
+      let links = doc.links.filter((l) => !affected(l) && isLive(members, l))
+      for (const old of doc.links.filter(affected)) {
+        const moved = replacedBy === undefined ? undefined : this.transfer(old, memberID, replacedBy, links, members, workspace.masterMemberID)
+        if (moved) {
+          links = [...links, moved]
+          transferred++
+        } else detached++
+      }
+      return detached + transferred === 0 && links.length === doc.links.length ? undefined : links
+    })
+    return { workspaceID, revision: written.doc.revision, detached, transferred, pruned: written.pruned - detached - transferred }
+  }
+
+  /** Drops links whose ends departed or are no longer retained (each write does this too). */
+  async prune(userID: string, workspaceID: string): Promise<{ workspaceID: string; revision: number; pruned: number }> {
+    await this.deps.workspaces.require(userID, workspaceID)
+    const written = await this.mutate(userID, workspaceID, (doc, members) => {
+      const live = doc.links.filter((l) => isLive(members, l))
+      return live.length === doc.links.length ? undefined : live
+    })
+    return { workspaceID, revision: written.doc.revision, pruned: written.pruned }
+  }
+
+  // ---------- internals ----------
+
+  /** The old member's link rewritten to its replacement, or undefined when that is not allowed (then detached). */
+  private transfer(
+    old: SupervisionLink,
+    departed: string,
+    replacement: string,
+    links: readonly SupervisionLink[],
+    members: Members,
+    masterMemberID: string | undefined,
+  ): SupervisionLink | undefined {
+    const memberID = old.memberID === departed ? replacement : old.memberID
+    const supervisorMemberID = old.supervisorMemberID === departed ? replacement : old.supervisorMemberID
+    if (memberID === supervisorMemberID || memberID === masterMemberID) return undefined
+    if (endOf(members, memberID) !== "current" || endOf(members, supervisorMemberID) !== "current") return undefined
+    if (links.some((l) => l.memberID === memberID)) return undefined
+    if (supervisionViolation(edges(links), memberID, supervisorMemberID, this.limits.depth)) return undefined
+    return { ...old, memberID, supervisorMemberID, revision: old.revision + 1 }
+  }
+
+  /** The workspace's members (current and departed) by ID. */
+  private async memberMap(userID: string, workspaceID: string): Promise<Members> {
+    const views = await this.deps.members.members(userID, workspaceID, { includeLeft: true })
+    return new Map(views.map((v) => [v.member.id, v.member]))
+  }
+
+  /**
+   * One version-checked write of the aggregate: reads it, THEN the members (see the header), and writes the links
+   * `change` returns (undefined: nothing to write) at revision + 1. Retried when another writer got there first.
+   */
+  private async mutate(
+    userID: string,
+    workspaceID: string,
+    change: (doc: SupervisionDoc, members: Members) => readonly SupervisionLink[] | undefined,
+  ): Promise<{ doc: SupervisionDoc; pruned: number }> {
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const stored = await this.state.get(userID, WORKSPACE_SUPERVISION, workspaceID)
+      const doc = readDoc(stored?.value, workspaceID)
+      const members = await this.memberMap(userID, workspaceID)
+      const links = change(doc, members)
+      if (links === undefined) return { doc, pruned: 0 }
+      const next: SupervisionDoc = { v: 1, workspaceID, revision: doc.revision + 1, links }
+      const put = await this.state.put(userID, WORKSPACE_SUPERVISION, workspaceID, next, { ifVersion: stored?.version ?? 0 })
+      if (put.ok) return { doc: next, pruned: doc.links.filter((l) => !isLive(members, l)).length }
+    }
+    throw new Error(`state update of ${WORKSPACE_SUPERVISION}/${workspaceID} kept conflicting`)
+  }
+}

package/src/index.ts

@@ -11,6 +11,9 @@ import { HubRpc, VoiceRpc } from "./rpc"
 import { jobFromInfo, type JobInfo } from "./protocol"
 import { checkServer, parseServerInput } from "./setup"
 import { defineVoiceAgent, orchestratorParts, STOP_TOOL, STOP_TOOL_DESCRIPTION } from "./spoke/conversation"
+import { defineConciergeAgent } from "./spoke/concierge-agent"
+
+import { CONCIERGE_AGENT, CONCIERGE_TOOLS } from "../packages/protocol/src/concierge.ts"
 import { envInjector, hubBinDir, ShellCorrelator, stripInheritedHubEnv } from "./spoke/env-inject"
 import { herdrRunner } from "./spoke/herdr"
 import { launchSource } from "./spoke/launch-source"
@@ -18,14 +21,19 @@ import { HubRpcError, hubMsg, hubWho } from "./spoke/hub-rpc"
 import { HUB_TOOL, HUB_TOOL_DESCRIPTION, HUB_TOOL_INPUT, runHubTool } from "./spoke/hub-tool"
 import { cliEntry, installLaunchers, linkUserBin, standaloneHubctl } from "./spoke/launchers"
 import { listServiceSessions } from "./spoke/listing"
-import { ensureLocalHub } from "./spoke/localhub"
+import { defaultStateDir, ensureLocalHub } from "./spoke/localhub"
+import path from "node:path"
 import { nodeConfigPath, readWorkspaceRoots } from "./spoke/node-roots"
 import { PromptReferences } from "./spoke/prompt-refs"
+import { PROFILE_TOOL, PROFILE_TOOL_DESCRIPTION, PROFILE_TOOL_INPUT } from "./spoke/profile-apply"
 import { replyPermission, type PermissionLocation } from "./spoke/locations"
 import { foregroundEndpoint, formOutcome } from "./spoke/own-server"
 import { joinProcess, type Membership } from "./spoke/singleton"
 import { detectKind, Spoke, SpokeError, type FormAction, type SpokeHost } from "./spoke/spoke"
 
+/** Where the spoke keeps the IDs of Concierge sessions (always restricted to the Concierge's tools). */
+const conciergeLockFile = () => path.join(defaultStateDir(), "concierge-sessions.json")
+
 type Context = Parameters<Parameters<typeof Plugin.define>[0]["setup"]>[0]
 
 /** Plugin.define without importing it (it returns its argument). */
@@ -54,18 +62,28 @@ function pluginVersion(): string {
 }
 
 /**
- * The most recent root sessions of the local OpenCode service with their workspace (used by the
- * service's own spoke for the phone's session browser): the history window plus `include`.
+ * The most recent root sessions with their workspace (the spoke's session listing): the history window plus
+ * `include`. The background service lists every session of its server; a foreground `opencode serve` lists, from
+ * its own server, only the sessions of the locations it loaded (`scope`), so idle sessions of a loaded project are
+ * online without having run in this process, and nothing of other projects is claimed.
  */
-async function listRecent(options?: { days: number; max: number; include: readonly string[] }) {
-  const { Service } = await import("@opencode/client/service")
-  const { OpenCode } = await import("@opencode/client")
-  const endpoint = await Service.discover()
-  if (!endpoint) return []
-  const client = OpenCode.make({ baseUrl: endpoint.url, headers: Service.headers(endpoint) ?? {} })
-  return listServiceSessions(client, options ?? {})
+async function listRecent(kind: "service" | "standalone", scope: () => string[], options?: { days: number; max: number; include: readonly string[] }) {
+  if (kind === "service") {
+    const { Service } = await import("@opencode/client/service")
+    const { OpenCode } = await import("@opencode/client")
+    const endpoint = await Service.discover()
+    if (!endpoint) return []
+    const client = OpenCode.make({ baseUrl: endpoint.url, headers: Service.headers(endpoint) ?? {} })
+    return listServiceSessions(client, options ?? {})
+  }
+  const client = await ownClient(kind)
+  if (!client) return []
+  return listServiceSessions(client, { ...(options ?? {}), scope: scope() })
 }
 
+/** This process can list sessions: the background service, or a foreground `opencode serve` that knows its password. */
+const canList = (kind: "service" | "standalone") => kind === "service" || foregroundEndpoint(process.argv, process.env) !== undefined
+
 /** A client for this process's own OpenCode server, when it can be reached (see src/spoke/own-server.ts). */
 async function ownClient(kind: "service" | "standalone") {
   const { OpenCode } = await import("@opencode/client")
@@ -78,6 +96,13 @@ async function ownClient(kind: "service" | "standalone") {
   return endpoint ? OpenCode.make({ baseUrl: endpoint.url, headers: { authorization: endpoint.authorization } }) : undefined
 }
 
+/** The own server's client, or an error saying it cannot be reached. */
+async function requireOwnClient(kind: "service" | "standalone") {
+  const client = await ownClient(kind).catch(() => undefined)
+  if (!client) throw new Error("This OpenCode process cannot reach its own server")
+  return client
+}
+
 /** Answers or cancels a form through the own server's API (the plugin API has no forms). */
 async function replyForm(kind: "service" | "standalone", action: FormAction): Promise<"replied" | "gone" | "unavailable"> {
   const client = await ownClient(kind).catch(() => undefined)
@@ -153,6 +178,9 @@ function hostFrom(ctx: Context, locations: () => PermissionLocation[], kind: "se
   const agent = ctx.agent as any
   const mcp = (ctx as any).mcp
   const vcs = (ctx as any).vcs
+  const skill = (ctx as any).skill
+  const command = (ctx as any).command
+  const names = (value: unknown) => (unwrap<ReadonlyArray<{ name?: unknown }>>(value, Array.isArray) ?? []).flatMap((item) => (typeof item?.name === "string" ? [item.name] : []))
   return {
     directory: ctx.location.directory,
     opencodeVersion: ctx.app?.version ?? "unknown",
@@ -184,11 +212,30 @@ function hostFrom(ctx: Context, locations: () => PermissionLocation[], kind: "se
       const list = unwrap<Array<{ id: string; mode?: string; hidden?: boolean }>>(await agent.list({}), Array.isArray)
       return list?.find((a) => a.mode !== "subagent" && !a.hidden)?.id
     },
-    listRecent,
+    ...(canList(kind) ? { listRecent: (options?: { days: number; max: number; include: readonly string[] }) => listRecent(kind, () => locations().map((l) => l.directory), options) } : {}),
     activity: (directories) => activity(kind, directories),
+    // Fork and revert: over the own server's API (the plugin API has neither); only where it can be reached.
+    ...(canList(kind)
+      ? {
+          forkSession: async ({ sessionID, before }: { sessionID: string; before: string }) => (await requireOwnClient(kind)).session.fork({ sessionID, before }),
+          revertStage: async (input: { sessionID: string; messageID: string; files: boolean }) => (await requireOwnClient(kind)).session.revert.stage(input),
+          revertClear: async (sessionID: string) => (await requireOwnClient(kind)).session.revert.clear({ sessionID }),
+          revertCommit: async (sessionID: string) => (await requireOwnClient(kind)).session.revert.commit({ sessionID }),
+        }
+      : {}),
     createSession: async ({ directory, title }) =>
       unwrap<{ id: string }>(await session.create({ location: { directory }, ...(title ? { title } : {}) }), (v) => typeof v.id === "string"),
     ...(mcp?.list ? { mcpList: async (directory: string) => unwrap<ReadonlyArray<unknown>>(await mcp.list({ location: { directory } }), Array.isArray) } : {}),
+    // Hub profiles (src/spoke/profile-apply.ts): local skills/commands win over a profile's; its own need the tool.
+    ...(skill?.list && command?.list
+      ? {
+          localNames: async (directory: string) => {
+            const [skills, commands] = await Promise.all([skill.list({ location: { directory } }), command.list({ location: { directory } })])
+            return { skills: names(skills), commands: names(commands) }
+          },
+        }
+      : {}),
+    profileTool: typeof (ctx as any).tool?.transform === "function",
     ...(vcs?.diff ? { vcsDiff: async (directory: string) => unwrap<ReadonlyArray<unknown>>(await vcs.diff({ mode: "working", location: { directory } }), Array.isArray) } : {}),
     ...(vcs?.get
       ? {
@@ -250,11 +297,13 @@ export default definePlugin({
         const common = { machineName: hostname(), kind, processID, pid: process.pid, pluginVersion: pluginVersion() }
         if (source.kind === "launch") {
           const nodeConfig = source.nodeConfig
-          return new Spoke(host, { ...common, configFile: source.file, launch: source.launch, workspaceRoots: () => readWorkspaceRoots(nodeConfig) })
+          return new Spoke(host, { ...common, configFile: source.file, launch: source.launch, workspaceRoots: () => readWorkspaceRoots(nodeConfig), conciergeLockFile: conciergeLockFile() })
         }
         return new Spoke(host, {
           ...common,
           configFile: prepareConfigPath(),
+          // Concierge session locks survive a restart before the hub reconnects (src/spoke/session-context.ts).
+          conciergeLockFile: conciergeLockFile(),
           // Loopback servers only, and only when autoStartLocalHub is on (see src/spoke/localhub.ts).
           localHub: (server) => ensureLocalHub(server),
           // One Herdr reader per machine: the background service's spoke (see src/spoke/herdr.ts). Launch creates
@@ -269,12 +318,21 @@ export default definePlugin({
     // 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 voice and concierge agents", () =>
+        ctx.agent.transform((editor) => {
+          defineVoiceAgent(editor as any)
+          defineConciergeAgent(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({
+          // (CON-04) A locked session (the Concierge) keeps its agent: no voice style, no orchestrator parts.
+          const locked = spoke?.contexts.locked(event.sessionID) ?? false
+          // The hub hears which agent a Concierge session runs on (it suspends one moved to another agent).
+          if (locked) spoke?.noteAgent(event.sessionID, event.agent)
+          if (!locked && spoke?.isVoiceTurn(event.sessionID)) event.system.push({ type: "text", text: VOICE_STYLE })
+          const parts = locked ? [] : orchestratorParts({
             agent: event.agent,
             conversation: spoke?.inConversation(event.sessionID) ?? false,
             subagent: spoke?.subagent() ?? DEFAULT_SUBAGENT,
@@ -282,6 +340,15 @@ export default definePlugin({
             taskBoard: spoke?.taskBoard(event.sessionID),
           })
           for (const text of parts) event.system.push({ type: "text", text })
+          // A hub profile: after OpenCode's own parts (local instructions win), for this session only.
+          for (const text of spoke?.profiles.systemParts(event.sessionID) ?? []) event.system.push({ type: "text", text })
+          if (event.tools && !spoke?.profiles.toolVisible(event.sessionID)) delete event.tools[PROFILE_TOOL]
+          // (CON-04) The hub's session context: its parts after the profile's, its denied tools removed.
+          for (const text of spoke?.contexts.systemParts(event.sessionID) ?? []) event.system.push({ type: "text", text })
+          if (event.tools) spoke?.contexts.filterTools(event.sessionID, event.tools as Record<string, unknown>)
+          // The concierge agent keeps exactly CONCIERGE_TOOLS even without a hub context (a spoke that restarted before
+          // the hub re-sent it): OpenCode 2.2.3 offers `skill` whatever the agent's rules say.
+          if (event.tools && event.agent === CONCIERGE_AGENT) for (const name of Object.keys(event.tools)) if (!(CONCIERGE_TOOLS as readonly string[]).includes(name)) delete event.tools[name]
         }),
       ),
       // The voice agent stops one worker ("cancel the deploy one") without stopping itself or the others.
@@ -321,6 +388,21 @@ export default definePlugin({
           }),
         ),
       ),
+      // A hub profile's skills and commands, for the calling session only (src/spoke/profile-apply.ts).
+      attempt("register the hub profile tool", () =>
+        (ctx as any).tool?.transform?.((editor: any) =>
+          editor.add({
+            name: PROFILE_TOOL,
+            description: PROFILE_TOOL_DESCRIPTION,
+            input: PROFILE_TOOL_INPUT,
+            options: { codemode: false },
+            execute: async (value: unknown, context: { sessionID: string }) => {
+              const spoke = membership.active()
+              return { content: spoke ? spoke.profiles.runTool(context.sessionID, value) : "The hub is not running in this OpenCode process; no hub profile is available." }
+            },
+          }),
+        ),
+      ),
       // @name / @@role in a prompt get context from the hub as an attached text file; the text is never changed
       // and the harness's own @ meanings win (src/spoke/prompt-refs.ts, design §2.4).
       attempt("register the prompt hook", () => {

package/src/spoke/concierge-agent.ts

@@ -0,0 +1,33 @@
+// CON-04 the OpenCode agent the Concierge session runs on (contract "Agent"): registered by the plugin like the voice
+// agent (conversation.ts defineVoiceAgent), mode primary, hidden. Its rules are an ALLOW-LIST: deny everything
+// ("*"), then allow exactly CONCIERGE_TOOLS (hub, read, glob, grep, question). OpenCode evaluates the last matching
+// rule, so nothing else (subagent/task, execute, webfetch/websearch, shell, edit/write/patch, todo, skill,
+// external_directory, MCP or plugin tools, future tools) is allowed, even with no hub context. The hub also strips
+// every tool off that list from each turn (sessionContext tools.allow): defence in depth. The default agent's rules
+// are not inherited. Its instructions come from the hub with every turn (sessionContext), not from here.
+import { CONCIERGE_AGENT, CONCIERGE_TOOLS } from "../../packages/protocol/src/concierge.ts"
+import type { AgentEditorLike } from "./conversation"
+
+export const CONCIERGE_AGENT_NAME = "Concierge"
+export const CONCIERGE_AGENT_DESCRIPTION = "Hub Concierge: watches your sessions and acts only inside your grant. Hub-managed; not for direct use."
+const CONCIERGE_SYSTEM = "You are the hub's Concierge. Your instructions, situation board and notes arrive from the hub with every turn."
+
+export const CONCIERGE_RULES: ReadonlyArray<{ readonly action: string; readonly resource: string; readonly effect: "allow" | "deny" }> = [
+  { action: "*", resource: "*", effect: "deny" },
+  ...CONCIERGE_TOOLS.map((action) => ({ action, resource: "*", effect: "allow" as const })),
+]
+
+/** Adds (or refreshes) the hub's "concierge" agent; a "concierge" agent the user defined is left alone. */
+export function defineConciergeAgent(editor: AgentEditorLike): void {
+  // The description marks the hub's own agent, which is refreshed; a user's own "concierge" agent is left alone.
+  const existing = editor.get(CONCIERGE_AGENT)
+  if (existing && existing.description !== CONCIERGE_AGENT_DESCRIPTION) return
+  editor.update(CONCIERGE_AGENT, (agent) => {
+    agent.name = CONCIERGE_AGENT_NAME
+    agent.description = CONCIERGE_AGENT_DESCRIPTION
+    agent.mode = "primary"
+    agent.hidden = true
+    agent.system = CONCIERGE_SYSTEM
+    agent.permissions = CONCIERGE_RULES.map((r) => ({ ...r }))
+  })
+}

package/src/spoke/deliver.ts

@@ -34,13 +34,17 @@ export interface RecipientState {
  * (quirk hzmcqwpj), a steered one joins them in one call. With a form open OpenCode holds the message until the
  * form is answered ("retained").
  *
- * `wake:false` and subagent sessions are admitted without starting a turn ("queued"). They default to steer: a
- * queued item gets its own model call when a turn ends (that would wake the session), while a steered one
- * without resume waits for the next turn and arrives before its prompt (or joins a turn already running).
+ * `wake:false` and subagent sessions are admitted without starting a turn ("queued"), always steered (also over
+ * the hub's "queue", RF-05): a queued item gets its own model call when a turn ends, resume or not (that would wake
+ * the session), while a steered one without resume waits for the next turn and arrives before its prompt. A
+ * steered one admitted into a running turn costs a model call when the turn would have ended, so routine ones are
+ * refused while the session is busy (deferredWhileBusy).
  */
 export function planDelivery(req: { readonly wake: boolean; readonly meta: DeliverMeta }, state: RecipientState): DeliveryPlan {
   const resume = req.wake && !state.subagent
-  const chosen = req.meta.delivery ?? (!resume || req.meta.kind === "ask" ? "steer" : "queue")
+  // Not waking: always steer. OpenCode gives a queued item its own model call once a turn ends (resume or not),
+  // so a hub-chosen "queue" would wake the session after all; a steered one waits for the next turn.
+  const chosen = !resume ? "steer" : (req.meta.delivery ?? (req.meta.kind === "ask" ? "steer" : "queue"))
   // Idle: no running turn to queue behind; steered, the wake shares its model call with what already waits.
   const delivery = resume && !state.busy && !state.formOpen ? "steer" : chosen
   return { delivery, resume, delivered: deliveredAs(delivery, resume, state) }
@@ -71,5 +75,19 @@ export function deliverMetadata(req: { readonly messageID: string; readonly meta
   return { source: PROMPT_SOURCE, messageID: req.messageID, kind, from, to, ...(replyTo !== undefined ? { replyTo } : {}), ...(grant !== undefined ? { grant } : {}) }
 }
 
+/** The refusal of a routine quiet message to a busy session (the hub keeps it pending and retries). */
+export const QUIET_WHILE_BUSY = "The session is busy: a message that does not wake it is admitted after the running turn"
+
+/**
+ * Whether a message waits for the running turn to end (refused while busy, RF-05): a routine `wake:false` msg (not
+ * urgent: the hub sends routine msgs with delivery "queue") to a top-level session. OpenCode adds anything admitted
+ * into a running turn with a model call of its own when the turn would have ended. Urgent messages, asks, replies,
+ * primers and anything for a subagent (never woken; it may not be idle before its parent needs the answer) go in at
+ * once and accept that call.
+ */
+export function deferredWhileBusy(req: { readonly wake: boolean; readonly meta: DeliverMeta }, subagent: boolean): boolean {
+  return !req.wake && !subagent && req.meta.kind === "msg" && req.meta.delivery !== "steer"
+}
+
 // The prompt envelope, InboxOrigins and DeliveryLedger live in the spoke SDK (harness-neutral).
 export { deliverText, DeliveryLedger, InboxOrigins, renderPromptEnvelope, type Admission } from "../../packages/spoke-sdk/src/delivery.ts"