@huynle/hub 0.8.0 → 0.8.2

package/src/central/registry.ts

@@ -11,7 +11,7 @@
 // another one and reaches it through SpokeHub.request (pod RPC). Events, alerts and speech stay with the pod that
 // holds the connection; remote state is never re-exported.
 import path from "node:path"
-import { HARNESS_OPENCODE, helloHarness, spokeFeatures, type EvidenceLevel, type ForwardedEvent, type Hello, type HerdrWorkspace, type ProcessKind, type SessionInfo, type SessionRevertInfo, type SpokeFeature, type SpokeMode, type TerminalInfo, type Terminals } from "../protocol"
+import { HARNESS_OPENCODE, helloHarness, spokeFeatures, type EvidenceLevel, type ForwardedEvent, type Hello, type HerdrWorkspace, type ProcessKind, type SessionInfo, type RevertCommitted, type SessionRevertInfo, type SpokeFeature, type SpokeMode, type TerminalInfo, type Terminals } from "../protocol"
 import { StatusBoard, errorTypeLabel, permissionRequest, providerFailureNeedsUser, providerRetryNeedsUser, type Blocker, type BlockerRecommendation, type PermissionRequest, type SessionStatus } from "../status"
 import { sanitizeLabel } from "./agent/envelope"
 import { DoneWatch } from "./done"
@@ -224,6 +224,8 @@ export interface SessionView extends BrowserFields {
   readonly terminal?: TerminalInfo
   /** A staged revert (feature "revert"), as the most recent report says. */
   readonly revert?: SessionRevertInfo
+  /** The latest committed revert's removed window (feature "revert"), as the most recent report says. */
+  readonly revertCommitted?: RevertCommitted
   /** (CON-04) A locked (Concierge) session: the agent and the context revision the most recent report says. */
   readonly agent?: string
   readonly contextRevision?: number
@@ -253,6 +255,8 @@ export interface CatalogProcess {
   readonly connected: number
   readonly lastSeen: number
   readonly sessions: CatalogSession[]
+  /** (FX-07) Connected, but its first sessions frame has not come yet: an empty `sessions` says nothing then. */
+  readonly sessionsPending?: true
 }
 
 /** A machine's terminal context: its Herdr workspaces (latest terminals frame of the machine). */
@@ -279,6 +283,8 @@ interface Conn {
   sessions: Map<string, SessionInfo>
   /** The last sessions frame as JSON, to skip unchanged snapshots. */
   sessionsKey: string
+  /** (FX-07) No sessions frame yet. */
+  sessionsPending?: true
   /** sessionID → activity sequence number of the last event this process sent for it. */
   activity: Map<string, number>
   /**
@@ -304,6 +310,8 @@ export interface SliceConn {
   readonly launchID?: string
   /** The machine's terminal context, when this connection sent the latest one. */
   readonly terminals?: MachineTerminals
+  /** (FX-07) No sessions frame yet (absent from older pods: reported). */
+  readonly sessionsPending?: true
 }
 
 /** A root session's status tree (live: run starts and recommendations included) and activity feed. */
@@ -547,6 +555,12 @@ export class Registry {
     return conn && this.tenant(conn)
   }
 
+  /** The committed revert windows the connection reports for its own tenant's sessions (feature "revert"). */
+  revertCommits(connID: string): Array<{ sessionID: string; committed: RevertCommitted }> {
+    const conn = this.conn(connID)
+    return conn ? this.visible(conn).flatMap((s) => (s.revertCommitted ? [{ sessionID: s.id, committed: s.revertCommitted }] : [])) : []
+  }
+
   /** IDs of the sessions the connection reports for its own tenant (subagents included); empty when unknown. */
   reportedSessions(connID: string): string[] {
     const conn = this.conn(connID)
@@ -598,6 +612,7 @@ export class Registry {
       lastSeen: t,
       sessions: new Map(),
       sessionsKey: "[]",
+      sessionsPending: true,
       activity: new Map(),
     })
     this.changed(this.tenant(this.conns.get(connID)!))
@@ -640,7 +655,9 @@ export class Registry {
     conn.lastSeen = this.now()
     // Spokes re-send their snapshot periodically; only changes reach the phones.
     const key = JSON.stringify(sessions)
-    if (key !== conn.sessionsKey) {
+    const first = conn.sessionsPending === true
+    delete conn.sessionsPending
+    if (key !== conn.sessionsKey || first) {
       conn.sessionsKey = key
       conn.sessions = new Map(sessions.map((s) => [s.id, s]))
       this.syncBoards()
@@ -1165,6 +1182,15 @@ export class Registry {
   }
 
   /** Something in the session's tree is working or waiting for the user (typed input steers then). */
+  /**
+   * Whether a process reports a staged revert for the session (feature "revert"): anything admitted into it would
+   * commit the revert (OpenCode's next prompt does), so hub deliveries and act prompts wait or are refused.
+   */
+  revertStaged(sessionID: string): boolean {
+    for (const conn of this.all()) if (this.reports(conn, sessionID)?.revert) return true
+    return false
+  }
+
   running(sessionID: string): boolean {
     const state = this.browserFields(sessionID).state
     return state === "working" || state === "blocked"
@@ -1232,6 +1258,7 @@ export class Registry {
         features: [...conn.features].sort(),
         connected: conn.connected,
         lastSeen: conn.lastSeen,
+        ...(conn.sessionsPending ? { sessionsPending: true as const } : {}),
         sessions: this.visible(conn).map((s) => {
           const fields = this.browserFields(s.id)
           return {
@@ -1249,6 +1276,19 @@ export class Registry {
     return [...machines.values()]
   }
 
+  /**
+   * (FX-07) The tenant's sessions a spoke reports locked now (the Concierge's: `locked`, from the first frame after a
+   * restart, and `agent` / `contextRevision`, sent only for locked sessions), on this pod's connections and other pods'.
+   */
+  lockedSessions(tenant: string): string[] {
+    const out = new Set<string>()
+    for (const conn of this.all()) {
+      if (this.tenant(conn) !== tenant) continue
+      for (const s of conn.sessions.values()) if (s.locked === true || s.agent !== undefined || s.contextRevision !== undefined) out.add(s.id)
+    }
+    return [...out]
+  }
+
   /** The session as reported by any process plus its live status; undefined when nobody reports it. */
   session(sessionID: string): SessionView | undefined {
     let info: SessionInfo | undefined
@@ -1273,6 +1313,7 @@ export class Registry {
       updated: info.updated,
       ...(terminal ? { open: true, terminal } : {}),
       ...(info.revert ? { revert: info.revert } : {}),
+      ...(info.revertCommitted ? { revertCommitted: info.revertCommitted } : {}),
       ...(info.agent !== undefined ? { agent: info.agent } : {}),
       ...(info.contextRevision !== undefined ? { contextRevision: info.contextRevision } : {}),
       ...fields,
@@ -1722,10 +1763,12 @@ export class Registry {
   recommend(requestID: string, recommendation: BlockerRecommendation): boolean {
     const origin = this.permissions.get(requestID)
     if (!origin) return false
-    const why = recommendation.why === undefined ? "" : sanitizeLabel(recommendation.why, RECOMMENDATION_WHY_MAX)
+    // (R-03) Without recommends it only links the Decision: no why either.
+    const recommends = recommendation.recommends === "approve"
+    const why = !recommends || recommendation.why === undefined ? "" : sanitizeLabel(recommendation.why, RECOMMENDATION_WHY_MAX)
     origin.recommendation = {
       by: sanitizeLabel(recommendation.by, RECOMMENDATION_BY_MAX) || "An agent",
-      recommends: "approve",
+      ...(recommends ? { recommends: "approve" as const } : {}),
       ...(why ? { why } : {}),
       ...(recommendation.decisionID && DECISION_ID.test(recommendation.decisionID) ? { decisionID: recommendation.decisionID } : {}),
     }
@@ -1893,6 +1936,7 @@ export class Registry {
           activity: [...conn.activity],
           ...(conn.launchID !== undefined ? { launchID: conn.launchID } : {}),
           ...(terminals?.connID === conn.id ? { terminals: terminals.terminals } : {}),
+          ...(conn.sessionsPending ? { sessionsPending: true as const } : {}),
         }
       })
     const boards: SliceBoard[] = [...this.boards]
@@ -1966,6 +2010,7 @@ export class Registry {
             sessionsKey: "",
             activity: new Map(c.activity ?? []),
             ...(c.launchID !== undefined ? { launchID: c.launchID } : {}),
+            ...(c.sessionsPending === true ? { sessionsPending: true as const } : {}),
             remote: { pod, tenant },
           })
           if (c.terminals) terminals.set(c.machine.id, c.terminals)

package/src/central/revert-windows.ts

@@ -0,0 +1,66 @@
+// Committed revert windows (feature "revert", docs/session-view.md → Fork and revert). A committed revert removed a
+// session's history from the reverted message on; hub message rows (agent messages the session sent or got) from
+// the reverted message's time until the revert was staged belonged to that history (later ones were held for after
+// it, decision 3q94ez94). The spoke reports the latest window (SessionInfo.revertCommitted); the hub keeps every
+// window per (user, session) in the StateStore, so GET /api/sessions/:id/messages leaves those rows out for good
+// (also after the spoke restarts or another process reports the session).
+import type { RevertCommitted } from "../protocol"
+import type { StateStore } from "./backend/types"
+
+const COLLECTION = "revertWindows"
+/** Windows kept per session (the oldest go first). */
+export const REVERT_WINDOWS_MAX = 50
+
+export interface RevertWindow {
+  readonly from: number
+  readonly until: number
+  /** Commit time (identifies the commit). */
+  readonly at: number
+}
+
+interface Stored {
+  readonly windows: readonly RevertWindow[]
+}
+
+/** Whether a row at `at` falls into one of the windows. */
+export function inRevertWindow(at: unknown, windows: readonly RevertWindow[]): boolean {
+  return typeof at === "number" && windows.some((w) => at >= w.from && at < w.until)
+}
+
+export class RevertWindows {
+  /** Windows known stored (by user, session and the whole window): the frames that repeat them read nothing. */
+  private readonly stored = new Set<string>()
+
+  constructor(private readonly state: StateStore) {}
+
+  /**
+   * A reported window (each sessions frame repeats it): kept unless known stored. Only a stored (or already present)
+   * window is remembered, so one reported first without its start (nothing to store), or whose write failed, is taken
+   * again from the next frame. Errors are the caller's.
+   */
+  async observe(userID: string, sessionID: string, committed: RevertCommitted): Promise<void> {
+    if (committed.from === undefined || committed.until <= committed.from) return
+    const key = JSON.stringify([userID, sessionID, committed.from, committed.until, committed.at])
+    if (this.stored.has(key)) return
+    if (await this.record(userID, sessionID, committed)) this.stored.add(key)
+  }
+
+  async list(userID: string, sessionID: string): Promise<readonly RevertWindow[]> {
+    return (await this.state.get<Stored>(userID, COLLECTION, sessionID))?.value.windows ?? []
+  }
+
+  /**
+   * Keeps a reported window (one without a start removes no rows: skipped). True when it is stored now (new, or
+   * already there); false when skipped or the write lost a race (version check).
+   */
+  async record(userID: string, sessionID: string, committed: RevertCommitted): Promise<boolean> {
+    if (committed.from === undefined || committed.until <= committed.from) return false
+    const window: RevertWindow = { from: committed.from, until: committed.until, at: committed.at }
+    const current = await this.state.get<Stored>(userID, COLLECTION, sessionID)
+    const windows = current?.value.windows ?? []
+    if (windows.some((w) => w.at === window.at && w.from === window.from && w.until === window.until)) return true
+    const next = [...windows, window].slice(-REVERT_WINDOWS_MAX)
+    const result = await this.state.put<Stored>(userID, COLLECTION, sessionID, { windows: next }, current ? { ifVersion: current.version } : {})
+    return result.ok
+  }
+}

package/src/central/spoke-ws.ts

@@ -61,9 +61,12 @@ export interface Notifier {
 
 /** The spoke answered with an error, or disconnected before answering. */
 export class SpokeError extends Error {
-  constructor(message: string) {
+  /** The refusal's protocol code (Res.code, e.g. "busy", "not_found"), when the spoke sent one. */
+  readonly code?: string
+  constructor(message: string, code?: string) {
     super(message)
     this.name = "SpokeError"
+    if (code !== undefined) this.code = code
   }
 }
 
@@ -669,7 +672,7 @@ export class SpokeHub {
   }
 
   /** Resolves or rejects the pending request a `res` frame answers. */
-  private settle(connID: string, message: { readonly id: string; readonly ok: boolean; readonly result?: unknown; readonly error?: string }): void {
+  private settle(connID: string, message: { readonly id: string; readonly ok: boolean; readonly result?: unknown; readonly error?: string; readonly code?: string }): void {
     const pending = this.pending.get(message.id)
     if (!pending || pending.connID !== connID) return
     this.pending.delete(message.id)
@@ -683,7 +686,7 @@ export class SpokeHub {
       return pending.resolve(message.result)
     }
     if (message.ok) pending.resolve(message.result)
-    else pending.reject(new SpokeError(message.error || `OpenCode ${pending.op} request failed`))
+    else pending.reject(new SpokeError(message.error || `OpenCode ${pending.op} request failed`, message.code))
   }
 
   private async answer(ws: Socket, frame: Req<SpokeRequest>): Promise<void> {

package/src/central/teams/intake.ts

@@ -25,6 +25,9 @@
 // progress is reported explicitly through setStatus (POST /teams/:id/intake/:intakeID/status, MCP
 // team_intake_update, the OpenCode hub tool's intake_update verb), which the submitter reads (GET, `team.intake`
 // events). The text says so, with the exact verb and IDs (reportingLines).
+// Hops (0.8.1): a session's submission continues its hop chain — the submitter's depth + 1 at submit time (hopOf)
+// is kept on the row (never shown) and delivered as SendOptions.chainHop, so intake is not a way to restart a chain
+// at hop 1; the user's and apps' submissions start their own.
 //
 // Status (explicit, never inferred from idleness/presence/departure; HWA-04/06): intake `queued` → `routed` →
 // `done` | `failed` | `cancelled` (queued may be cancelled). While routed, `progress` mirrors the assignment:
@@ -143,6 +146,8 @@ export interface StoredIntake extends TeamIntake {
 
 interface IntakeRow extends StoredIntake {
   readonly claim?: { readonly owner: string; readonly at: number }
+  /** A session submitter's depth + 1 at submit time: the delivery continues its hop chain (never shown). */
+  readonly hop?: number
 }
 
 interface IntakeKey {
@@ -159,8 +164,14 @@ interface IntakeDoc {
   readonly keys: Readonly<Record<string, IntakeKey>>
 }
 
-/** Delivers one task text to a session (production: Delivery.send as intakeActor). */
-export type IntakeDeliver = (userID: string, sessionID: string, text: string) => Promise<{ readonly messageID: string }>
+/**
+ * Delivers one task text to a session (production: Delivery.send as intakeActor); `hop`: the chain it continues (a
+ * submitting session's depth + 1; production passes it as SendOptions.chainHop).
+ */
+export type IntakeDeliver = (userID: string, sessionID: string, text: string, options?: { readonly hop?: number }) => Promise<{ readonly messageID: string }>
+
+/** The hop a message from the session would carry now (production: Delivery.hops.next). */
+export type IntakeHopOf = (userID: string, sessionID: string) => Promise<number>
 
 export interface TeamIntakeDeps {
   readonly state: StateStore
@@ -170,6 +181,8 @@ export interface TeamIntakeDeps {
   readonly members: Pick<MembershipStore, "members" | "assign" | "assignment" | "setStatus" | "reassign">
   readonly presence: SessionPresenceLookup
   readonly deliver: IntakeDeliver
+  /** A session submitter's hop chain (absent: deliveries start their own chain). */
+  readonly hopOf?: IntakeHopOf
   readonly events?: Pick<AgentEvents, "append">
   readonly report?: (cause: unknown) => void
   readonly now?: Clock
@@ -239,9 +252,9 @@ const sameSource = (row: StoredIntake, actor: AgentActor): boolean =>
   (actor.kind === "session" && row.source.kind === "session" && row.source.sessionID === actor.sessionID) ||
   (actor.kind === "user" && row.source.kind === "user")
 
-/** The stored row as reads show it (no routing claim). */
+/** The stored row as reads show it (no routing claim, no hop). */
 function view(row: IntakeRow): StoredIntake {
-  const { claim: _claim, ...rest } = row
+  const { claim: _claim, hop: _hop, ...rest } = row
   return rest
 }
 
@@ -308,6 +321,7 @@ export class TeamIntakeService {
     const digest = digestOf(body)
     const slot = key === undefined ? undefined : `${partyOf(actor)}|${key}`
     const id = this.newID("intake")
+    const hop = actor.kind === "session" && this.deps.hopOf ? await this.deps.hopOf(userID, actor.sessionID) : undefined
     if (body.brief !== undefined) await this.state.put(userID, TEAM_INTAKE_BRIEFS, id, { v: 1, teamID, brief: body.brief })
     let result: { row: IntakeRow; created: boolean } | undefined
     try {
@@ -331,7 +345,7 @@ export class TeamIntakeService {
         if (doc.items.filter((i) => !CLOSED.has(i.status)).length >= this.limits.openPerTeam)
           throw new AgentError("rate_limited", `A team holds at most ${this.limits.openPerTeam} open submissions`, { hint: "Close or cancel some first", extra: { limit: this.limits.openPerTeam } })
         const { brief: _brief, ...fields } = body
-        const row: IntakeRow = { v: 1, id, teamID, ...fields, source: sourceOf(actor), status: "queued", revision: 1, createdAt: at, updatedAt: at }
+        const row: IntakeRow = { v: 1, id, teamID, ...fields, source: sourceOf(actor), status: "queued", revision: 1, createdAt: at, updatedAt: at, ...(hop === undefined ? {} : { hop }) }
         result = { row, created: true }
         const nextKeys = slot === undefined ? keys : { ...keys, [slot]: { intakeID: id, digest, at } }
         return { ...doc, items: this.retained([...doc.items, row]), keys: this.boundedKeys(nextKeys) }
@@ -540,7 +554,7 @@ export class TeamIntakeService {
         await this.mutate(userID, team.id, intakeID, (row) => ({ ...row, assignmentID: assignment.id, workspaceID: target.workspaceID }), false)
       const brief = (await this.state.get<{ brief?: unknown }>(userID, TEAM_INTAKE_BRIEFS, intakeID))?.value?.brief
       const text = this.text(team, claimed, assignment.id, target, typeof brief === "string" ? brief : undefined)
-      const sent = await this.deps.deliver(userID, target.sessionID, text)
+      const sent = await this.deps.deliver(userID, target.sessionID, text, claimed.hop === undefined ? {} : { hop: claimed.hop })
       let cancelled = false
       let routed: IntakeRow | undefined
       await this.writeDoc(userID, team.id, (doc) => {

package/src/central/teams/staffing.ts

@@ -219,8 +219,15 @@ export interface TeamStaffingDeps {
   readonly report?: (cause: unknown) => void
   readonly now?: Clock
   readonly newID?: (kind: IdKind) => string
+  /**
+   * (FX-07) Whether the session is one of the user's Concierge sessions (current or past). Such a session is never
+   * staffed (attach, replace, a team launch), for anyone: the hub manages it. The routes guard this too.
+   */
+  readonly protects?: (userID: string, sessionID: string) => Promise<boolean>
 }
 
+const conciergeRefusal = () => new AgentError("forbidden", "This does not apply to the Concierge: the hub manages it", { extra: { policy: "concierge" } })
+
 interface Need {
   readonly verb: "launch" | "roles"
   readonly directory: string
@@ -540,7 +547,7 @@ export class TeamStaffingService {
   /** The launch body: the caller's, with the role's placement/harness/model/profile defaults and team labels. */
   private async launchSpec(userID: string, team: Team, role: TeamRoleSpec, base: unknown, requestID: string): Promise<Record<string, unknown>> {
     if (!isObj(base)) throw new AgentError("invalid", "launch must be a launch body (workspace, prompt, …)")
-    if (base.key !== undefined) throw new AgentError("invalid", "launch.key is set by staffing", { hint: "Send an Idempotency-Key header instead" })
+    if (base.key !== undefined) throw new AgentError("invalid", "launch.key is set by staffing", { hint: "Send idempotencyKey (the Idempotency-Key header) instead" })
     const labels = isObj(base.labels) ? base.labels : base.labels === undefined ? {} : undefined
     if (!labels) throw new AgentError("invalid", "launch.labels must be an object")
     if (TEAM_LAUNCH_LABEL in labels || TEAM_REQUEST_LABEL in labels) throw new AgentError("invalid", `launch.labels ${TEAM_LAUNCH_LABEL} and ${TEAM_REQUEST_LABEL} are set by staffing`)
@@ -560,7 +567,7 @@ export class TeamStaffingService {
       ...(agentProfile !== undefined ? { agentProfile } : {}),
       labels: { ...labels, [TEAM_LAUNCH_LABEL]: team.id, [TEAM_REQUEST_LABEL]: requestID },
     }
-    validateLaunchSpec(spec)
+    validateLaunchSpec(spec, { staffing: true })
     return spec
   }
 
@@ -604,6 +611,7 @@ export class TeamStaffingService {
     let staffing: TeamSeatRecord
     let created: boolean
     try {
+      await this.notConcierge(userID, sessionID)
       const team = await this.deps.teams.require(userID, request.teamID)
       if (request.replaces) {
         staffable(team)
@@ -800,9 +808,23 @@ export class TeamStaffingService {
     if (typeof sessionID !== "string" || sessionID.length === 0 || sessionID.length > 200) throw new AgentError("invalid", "sessionID must be a session ID")
     const presence = await this.deps.presence(userID, sessionID)
     if (presence === "unknown" || presence === "deleted") throw new AgentError("not_found", `No session ${sessionID}`)
+    await this.notConcierge(userID, sessionID)
     return sessionID
   }
 
+  /**
+   * (FX-07) Refuses a Concierge session. A failed identity read refuses too (fail closed): a timed-out one with its own
+   * `busy` (503), any other as the Concierge refusal.
+   */
+  private async notConcierge(userID: string, sessionID: string): Promise<void> {
+    if (!this.deps.protects) return
+    const concierge = await this.deps.protects(userID, sessionID).catch((cause: unknown) => {
+      if (cause instanceof AgentError && cause.code === "busy") throw cause
+      return true
+    })
+    if (concierge) throw conciergeRefusal()
+  }
+
   /** The session's project for a grant check; offline when no spoke reports it (as role writes answer). */
   private directoryOf(userID: string, sessionID: string): string {
     const directory = this.deps.sessionDirectory(userID, sessionID)

package/src/central/workspaces/sidechats-routes.ts

@@ -223,7 +223,7 @@ export function sideChatRoutes(deps: SideChatRoutesDeps): AgentRoute[] {
       snapshot: full ? snapshot : summary,
       status,
       ...(launch
-        ? { launch: { id: launch.id, state: launch.state, ...(launch.outcome ? { outcome: launch.outcome } : {}), ...(context.actor.kind === "user" || launch.by === launchedBy(context.actor) ? { reason: launch.reason } : {}) } }
+        ? { launch: { id: launch.id, state: launch.state, ...(launch.outcome ? { outcome: launch.outcome } : {}), ...(context.actor.kind === "user" ? { reason: launch.reason } : launch.by === launchedBy(context.actor) ? { reason: (launch.state === "queued" ? launch.waiting?.shared : undefined) ?? launch.reason } : {}) } }
         : {}),
       ...(updatedAt !== undefined ? { sourceUpdatedAt: updatedAt, stale: updatedAt > snapshot.takenAt } : {}),
     }

package/src/index.ts

@@ -14,25 +14,31 @@ import { defineVoiceAgent, orchestratorParts, STOP_TOOL, STOP_TOOL_DESCRIPTION }
 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 { defaultHubBinDir, envInjector, hubBinDir, ShellCorrelator, stripInheritedHubEnv } from "./spoke/env-inject"
 import { herdrRunner } from "./spoke/herdr"
 import { launchSource } from "./spoke/launch-source"
 import { HubRpcError, hubMsg, hubWho } from "./spoke/hub-rpc"
 import { HUB_TOOL, HUB_TOOL_DESCRIPTION, HUB_TOOL_INPUT, runHubTool } from "./spoke/hub-tool"
 import { cliEntry, installLaunchers, linkUserBin, standaloneHubctl } from "./spoke/launchers"
 import { listServiceSessions } from "./spoke/listing"
-import { defaultStateDir, ensureLocalHub } from "./spoke/localhub"
+import { conciergeLockFiles, ensureLocalHub } from "./spoke/localhub"
+import { hintStateDirOnce, resolveHubStateDir } from "./migrate"
 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 { listedNames, namesReader, replyPermission, serverNames, vcsReader, type PermissionLocation, type VcsReader } from "./spoke/locations"
 import { foregroundEndpoint, formOutcome } from "./spoke/own-server"
 import { joinProcess, type Membership } from "./spoke/singleton"
+import { applySessionContext, sortTools } from "./spoke/session-context"
 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")
+/** Written in the state dir; also read from the other default places, so a lock from before an upgrade still holds. */
+const conciergeLocks = () => {
+  const { file, read } = conciergeLockFiles()
+  return { conciergeLockFile: file, conciergeLockReadFiles: read }
+}
 
 type Context = Parameters<Parameters<typeof Plugin.define>[0]["setup"]>[0]
 
@@ -67,7 +73,7 @@ function pluginVersion(): string {
  * 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(kind: "service" | "standalone", scope: () => string[], options?: { days: number; max: number; include: readonly string[] }) {
+async function listRecent(kind: "service" | "standalone", scope: () => string[], options?: { days: number; max: number; include: readonly string[]; signal?: AbortSignal }) {
   if (kind === "service") {
     const { Service } = await import("@opencode/client/service")
     const { OpenCode } = await import("@opencode/client")
@@ -165,13 +171,42 @@ function unwrap<T>(value: unknown, isBare: (v: any) => boolean): T {
 /** This instance's location-scoped permission API (OpenCode keeps pending permissions per location). */
 function permissionLocation(ctx: Context): PermissionLocation {
   const permission = ctx.permission as any
+  const vcs = (ctx as any).vcs
+  const skill = (ctx as any).skill
+  const command = (ctx as any).command
   return {
     directory: ctx.location.directory,
     get: (input) => permission.get(input),
     reply: (input) => permission.reply(input),
+    // OpenCode's plugin vcs, skill and command lists answer for this instance's location only (whatever location is passed).
+    ...(vcs?.diff && vcs?.get ? { vcs: vcsOf(vcs, ctx.location.directory) } : {}),
+    ...(skill?.list && command?.list ? { names: () => localNamesOf(skill, command, ctx.location.directory) } : {}),
+  }
+}
+
+/** A plugin instance's own location's skill and command names (its lists answer only for that location). */
+async function localNamesOf(skill: any, command: any, directory: string) {
+  const [skills, commands] = await Promise.all([skill.list({ location: { directory } }), command.list({ location: { directory } })])
+  return { skills: listedNames(skills), commands: listedNames(commands) }
+}
+
+/** A vcs API's working-copy changes and current branch of a directory (plugin API or own-server client). */
+function vcsOf(vcs: any, directory: string) {
+  return {
+    diff: async () => unwrap<ReadonlyArray<unknown>>(await vcs.diff({ mode: "working", location: { directory } }), Array.isArray),
+    branch: async () => {
+      const info = unwrap<{ branch?: { current?: string } }>(await vcs.get({ location: { directory } }), (v) => "branch" in v)
+      return typeof info?.branch?.current === "string" ? info.branch.current : undefined
+    },
   }
 }
 
+/** The own server's vcs API (it honours the location), when the server can be reached. */
+function serverVcs(client: { vcs?: unknown } | undefined): VcsReader | undefined {
+  if (!client?.vcs) return undefined
+  return { diff: (directory) => vcsOf(client.vcs, directory).diff(), branch: (directory) => vcsOf(client.vcs, directory).branch() }
+}
+
 /** `locations`: the permission APIs of every plugin instance in this process (one per location). */
 function hostFrom(ctx: Context, locations: () => PermissionLocation[], kind: "service" | "standalone"): SpokeHost {
   const session = ctx.session as any
@@ -180,7 +215,11 @@ function hostFrom(ctx: Context, locations: () => PermissionLocation[], kind: "se
   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] : []))
+  const vcsRead = vcsReader(locations, async () => (canList(kind) ? serverVcs(await ownClient(kind).catch(() => undefined)) : undefined))
+  const namesRead = namesReader(locations, async () => {
+    const client = canList(kind) ? await ownClient(kind).catch(() => undefined) : undefined
+    return client?.skill && client?.command ? serverNames(client) : undefined
+  })
   return {
     directory: ctx.location.directory,
     opencodeVersion: ctx.app?.version ?? "unknown",
@@ -212,7 +251,7 @@ 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
     },
-    ...(canList(kind) ? { listRecent: (options?: { days: number; max: number; include: readonly string[] }) => listRecent(kind, () => locations().map((l) => l.directory), options) } : {}),
+    ...(canList(kind) ? { listRecent: (options?: { days: number; max: number; include: readonly string[]; signal?: AbortSignal }) => 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)
@@ -227,24 +266,12 @@ function hostFrom(ctx: Context, locations: () => PermissionLocation[], kind: "se
       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) }
-          },
-        }
-      : {}),
+    // Read in the session's own directory (src/spoke/locations.ts); unknown (undefined): the profile's skills and
+    // commands are not offered, never checked against another folder's names.
+    ...((skill?.list && command?.list) || canList(kind) ? { localNames: (directory: string) => namesRead(directory) } : {}),
     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
-      ? {
-          vcsBranch: async (directory: string) => {
-            const info = unwrap<{ branch?: { current?: string } }>(await vcs.get({ location: { directory } }), (v) => "branch" in v)
-            return typeof info?.branch?.current === "string" ? info.branch.current : undefined
-          },
-        }
-      : {}),
+    // A directory's branch and changes: its own plugin instance, else the own server (src/spoke/locations.ts).
+    ...(vcs?.diff || canList(kind) ? { vcsDiff: (directory: string) => vcsRead.diff(directory), vcsBranch: (directory: string) => vcsRead.branch(directory) } : {}),
   }
 }
 
@@ -254,6 +281,8 @@ function hostFrom(ctx: Context, locations: () => PermissionLocation[], kind: "se
  */
 async function registerShellEnv(ctx: Context, identity: (sessionID: string) => { token: string; url?: string } | undefined) {
   const binDir = hubBinDir()
+  // XDG_STATE_HOME set while the existing ~/.local/state/hub is kept: one line saying so, with the mv to switch.
+  hintStateDirOnce(resolveHubStateDir(process.env, homedir()))
   try {
     mkdirSync(binDir, { recursive: true, mode: 0o700 })
     // The `hub`/`hubctl` launchers run the CLI with this runtime (OpenCode's binary as bun; src/spoke/launchers.ts).
@@ -262,7 +291,7 @@ async function registerShellEnv(ctx: Context, identity: (sessionID: string) => {
     if (entry) {
       installLaunchers({ binDir, execPath: process.execPath, bun, entry, standalone: standaloneHubctl(homedir()) })
       // `hub` in the user's own terminals too (~/.local/bin/hub, never over anything of theirs).
-      const { hint } = linkUserBin({ home: homedir(), binDir, path: process.env.PATH })
+      const { hint } = linkUserBin({ home: homedir(), binDir, path: process.env.PATH, defaultBinDir: defaultHubBinDir() })
       if (hint) console.error(`[hub] ${hint}`)
     } else console.error("[hub] no built hub CLI (packages/cli/dist/hub-cli.js): `hub` is not installed")
   } catch (cause) {
@@ -297,13 +326,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), conciergeLockFile: conciergeLockFile() })
+          return new Spoke(host, { ...common, configFile: source.file, launch: source.launch, workspaceRoots: () => readWorkspaceRoots(nodeConfig), ...conciergeLocks() })
         }
         return new Spoke(host, {
           ...common,
           configFile: prepareConfigPath(),
           // Concierge session locks survive a restart before the hub reconnects (src/spoke/session-context.ts).
-          conciergeLockFile: conciergeLockFile(),
+          ...conciergeLocks(),
           // 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
@@ -343,12 +372,16 @@ export default definePlugin({
           // 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 })
+          // (CON-04) The hub's session context: its stable parts after the profile's, its board after the conversation
+          // (V-01: the prompt cache survives a board change), its denied tools removed, the kept tools in name order.
+          if (spoke) applySessionContext(event as any, spoke.contexts.systemParts(event.sessionID), spoke.contexts.tailParts(event.sessionID))
           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]
+          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]
+            sortTools(event.tools as Record<string, unknown>)
+          }
         }),
       ),
       // The voice agent stops one worker ("cancel the deploy one") without stopping itself or the others.