@huynle/hub 0.8.0 → 0.8.1

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
@@ -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,30 @@ 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 { replyPermission, vcsReader, type PermissionLocation, type VcsReader } 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")
+/** 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 +72,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 +170,33 @@ 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
   return {
     directory: ctx.location.directory,
     get: (input) => permission.get(input),
     reply: (input) => permission.reply(input),
+    // OpenCode's plugin vcs answers for this instance's location only (whatever location is passed).
+    ...(vcs?.diff && vcs?.get ? { vcs: vcsOf(vcs, ctx.location.directory) } : {}),
+  }
+}
+
+/** 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,6 +205,7 @@ 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 vcsRead = vcsReader(locations, async () => (canList(kind) ? serverVcs(await ownClient(kind).catch(() => undefined)) : undefined))
   const names = (value: unknown) => (unwrap<ReadonlyArray<{ name?: unknown }>>(value, Array.isArray) ?? []).flatMap((item) => (typeof item?.name === "string" ? [item.name] : []))
   return {
     directory: ctx.location.directory,
@@ -212,7 +238,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)
@@ -236,15 +262,8 @@ function hostFrom(ctx: Context, locations: () => PermissionLocation[], kind: "se
         }
       : {}),
     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 +273,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 +283,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 +318,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

package/src/migrate.ts

@@ -16,7 +16,7 @@ import {
   symlinkSync,
 } from "node:fs"
 import path from "node:path"
-import type { Env } from "./env"
+import { hubEnv, type Env } from "./env"
 
 export const APP_DIR = "hub"
 /** Legacy directory names under ~/.config and ~/.local/state, most recent first. */
@@ -24,8 +24,81 @@ export const LEGACY_APP_DIRS: readonly string[] = Object.freeze(["opencode-hub",
 
 /** $XDG_CONFIG_HOME or ~/.config. */
 export const configBase = (env: Env, home: string): string => env.XDG_CONFIG_HOME || path.join(home, ".config")
-/** ~/.local/state. */
-export const stateBase = (home: string): string => path.join(home, ".local", "state")
+/** $XDG_STATE_HOME when it is an absolute path (the XDG spec: a relative one is invalid and ignored), else undefined. */
+export const xdgStateHome = (env: Env): string | undefined => (env.XDG_STATE_HOME && path.isAbsolute(env.XDG_STATE_HOME) ? env.XDG_STATE_HOME : undefined)
+
+/** $XDG_STATE_HOME or ~/.local/state. The hub's own state dir is resolveHubStateDir (sticky), not this. */
+export const stateBase = (env: Env, home: string): string => xdgStateHome(env) ?? path.join(home, ".local", "state")
+
+export interface HubStateDir {
+  readonly dir: string
+  /** env: HUB_STATE_DIR; xdg: an existing $XDG_STATE_HOME/hub; legacy: an existing ~/.local/state/hub kept although
+   *  XDG_STATE_HOME is set; fresh: a new $XDG_STATE_HOME/hub; default: ~/.local/state/hub without XDG_STATE_HOME. */
+  readonly source: "env" | "xdg" | "legacy" | "fresh" | "default"
+  /** legacy only: one line for the log at startup (XDG_STATE_HOME is set, the existing dir is used, how to switch). */
+  readonly hint?: string
+  /** `dir`, then the other default places (~/.local/state/hub, $XDG_STATE_HOME/hub) it is not: the Concierge lock is read from all. */
+  readonly candidates: readonly string[]
+}
+
+/**
+ * What the hub writes in its state dir (the hub server's state.json, token-keys.json, agent/ and blobs/; the plugin's
+ * launchers bin/ and Concierge lock; the local hub's hub.log / hub.pid; the Claude Code and Codex spokes' dirs). A
+ * dir holding none of them (empty, or only `hubctl setup`'s bootstrap/) does not count as an existing state dir.
+ */
+export const HUB_STATE_MARKERS: readonly string[] = Object.freeze(["state.json", "token-keys.json", "agent", "blobs", "concierge-sessions.json", "bin", "hub.log", "hub.pid", "claude-code", "codex"])
+
+/** Whether `dir` holds hub state (any of HUB_STATE_MARKERS). */
+export const holdsHubState = (dir: string, exists: (p: string) => boolean = existsSync): boolean => HUB_STATE_MARKERS.some((marker) => exists(path.join(dir, marker)))
+
+const shellQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+
+/**
+ * The hub state dir, "sticky" (FX-08): $HUB_STATE_DIR; else $XDG_STATE_HOME/hub when XDG_STATE_HOME is set and that
+ * dir holds hub state (HUB_STATE_MARKERS; `exists` is asked about each marker); else an existing ~/.local/state/hub (kept, never copied or moved; with a hint when XDG_STATE_HOME is
+ * set); else $XDG_STATE_HOME/hub when it is set (fresh installs); else ~/.local/state/hub. Every part of hub (plugin,
+ * local hub, hub server, the Claude Code and Codex spokes) uses this, so a shell and a service unit agree unless one
+ * sets HUB_STATE_DIR.
+ */
+export function resolveHubStateDir(env: Env, home: string, exists: (p: string) => boolean = existsSync): HubStateDir {
+  const legacy = path.join(home, ".local", "state", APP_DIR)
+  const xdg = xdgStateHome(env)
+  const xdgHub = xdg ? path.join(xdg, APP_DIR) : undefined
+  const defaults = [legacy, ...(xdgHub && xdgHub !== legacy ? [xdgHub] : [])]
+  const result = (dir: string, source: HubStateDir["source"], hint?: string): HubStateDir => ({
+    dir,
+    source,
+    ...(hint ? { hint } : {}),
+    candidates: [dir, ...defaults.filter((d) => d !== dir)],
+  })
+  const explicit = hubEnv(env).HUB_STATE_DIR
+  if (explicit) return result(explicit, "env")
+  const holdsState = (dir: string) => holdsHubState(dir, exists)
+  if (xdgHub && holdsState(xdgHub)) return result(xdgHub, "xdg")
+  if (holdsState(legacy)) {
+    const hint =
+      xdgHub && xdgHub !== legacy
+        ? `XDG_STATE_HOME is set, but the existing ${legacy} is used as the hub state dir; to switch, stop the hub and OpenCode, then: mv ${shellQuote(legacy)} ${shellQuote(xdgHub)}`
+        : undefined
+    return result(legacy, "legacy", hint)
+  }
+  return xdgHub ? result(xdgHub, "fresh") : result(legacy, "default")
+}
+
+let hinted = false
+/** Logs the resolver's hint once per process (at startup). */
+export function hintStateDirOnce(resolved: HubStateDir, log: (line: string) => void = console.warn): void {
+  if (!resolved.hint || hinted) return
+  hinted = true
+  log(`[hub] ${resolved.hint}`)
+}
+
+/** The legacy (opencode-hub, opencode-voice) state dirs, most recent first: under $XDG_STATE_HOME, then ~/.local/state. */
+export function stateLegacyPaths(env: Env, home: string): string[] {
+  const xdg = xdgStateHome(env)
+  const bases = [...(xdg ? [xdg] : []), path.join(home, ".local", "state")]
+  return [...new Set(bases.flatMap((base) => legacyPaths(base)))]
+}
 
 export type MigrationResult = "migrated" | "none" | "failed"
 
@@ -103,3 +176,36 @@ export function migrateFirst(legacies: readonly string[], target: string, option
 
 /** The legacy copies of `<base>/<APP_DIR>/<...rest>`, most recent first. */
 export const legacyPaths = (base: string, ...rest: string[]): string[] => LEGACY_APP_DIRS.map((dir) => path.join(base, dir, ...rest))
+
+/**
+ * migrateFirst for the hub state dir: a target that holds no hub state (missing, empty, or only `hubctl setup`'s
+ * bootstrap/) counts as missing. The newest existing legacy dir is copied through a temporary sibling, then each of
+ * its top-level entries is renamed into the target unless the target already has one by that name (bootstrap/ is
+ * never overwritten). Never throws; the legacy copies are never touched.
+ */
+export function migrateStateDir(legacies: readonly string[], target: string, options: MigrateOptions = {}): MigrationResult {
+  if (!exists(target)) return migrateFirst(legacies, target, options)
+  if (holdsHubState(target, exists)) return "none"
+  const legacy = legacies.find(exists)
+  if (legacy === undefined) return "none"
+  const tmp = `${target}.migrating-${process.pid}-${Date.now()}`
+  let moved = 0
+  try {
+    const present = new Set(readdirSync(target))
+    copyEntry(legacy, tmp, [...(options.skip ?? []), ...present])
+    for (const name of readdirSync(tmp)) {
+      if (exists(path.join(target, name))) continue
+      renameSync(path.join(tmp, name), path.join(target, name))
+      moved++
+    }
+    rmSync(tmp, { recursive: true, force: true })
+  } catch (cause) {
+    rmSync(tmp, { recursive: true, force: true })
+    ;(options.log ?? ((m: string) => console.warn(`[hub] warning: ${m}`)))(`could not migrate ${legacy} to ${target}: ${cause instanceof Error ? cause.message : cause}`)
+    return "failed"
+  }
+  // Everything was there already (an earlier migration of a legacy dir without hub-state markers): nothing to say.
+  if (moved === 0) return "none"
+  ;(options.log ?? ((m: string) => console.log(`[hub] ${m}`)))(`migrated ${legacy} to ${target} (the project is now Hub; the old copy is kept)`)
+  return "migrated"
+}

package/src/spoke/env-inject.ts

@@ -14,6 +14,7 @@
 // they get only the stripped env and PATH, no token.
 import { homedir } from "node:os"
 import path from "node:path"
+import { hubEnv } from "../env"
 import { defaultStateDir } from "./localhub"
 
 type Env = Record<string, string | undefined>
@@ -124,11 +125,17 @@ export function applyHubEnv(env: Env, identity: Identity | undefined, binDir: st
   env.PATH = [binDir, ...rest].join(path.delimiter)
 }
 
-/** Where the `hub`/`hubctl` launchers live: bin under the hub state dir ($HUB_STATE_DIR or ~/.local/state/hub). */
+/** Where the `hub`/`hubctl` launchers live: bin under the hub state dir ($HUB_STATE_DIR, else $XDG_STATE_HOME/hub, else ~/.local/state/hub). */
 export function hubBinDir(env: Env = process.env, home: string = homedir()): string {
   return path.join(defaultStateDir(env, home), "bin")
 }
 
+/** Where ~/.local/bin/hub may point: the default (resolved) hub bin dir; none with HUB_STATE_DIR (a custom state). */
+export function defaultHubBinDir(env: Env = process.env, home: string = homedir()): string | undefined {
+  if (hubEnv(env).HUB_STATE_DIR) return undefined
+  return path.join(defaultStateDir(env, home), "bin")
+}
+
 /** The hook handlers: tool execute.before/after and shell create.before. They never throw. */
 export function envInjector(options: { correlator: ShellCorrelator; binDir: string; identity: (sessionID: string) => Identity | undefined }) {
   const { correlator, binDir, identity } = options

package/src/spoke/hub-tool.ts

@@ -25,6 +25,7 @@ import {
   type SentAll,
   type TeamIntake,
   type TeamIntakeStatusInput,
+  wakeSkipNote,
 } from "../../packages/sdk/src/index.ts"
 import { ME_LINE, reachText, whoSections } from "./who-teams"
 
@@ -41,9 +42,11 @@ export const HUB_TOOL_SELF_VERBS = ["name", "role_claim", "role_release"] as con
 
 /**
  * (CON-04) The Concierge's verbs (the `conciergeVerbs` section; CON-06 adds concierge_arm and concierge_propose). They
- * use the act token: the hub admits only the user's CURRENT Concierge session through it and answers 404 to every
- * other session. Listed in the Concierge's instructions only, never in the tool description. (CON-11) concierge_find
- * looks the user's sessions up by @name or title words (GET /api/agent/sessions?q=), framed as untrusted.
+ * use the act token. The /api/agent/concierge/* routes admit only the user's CURRENT Concierge session and answer 404
+ * to every other session. Listed in the Concierge's instructions only, never in the tool description. (CON-11)
+ * concierge_find looks the user's sessions up by @name or title words through GET /api/agent/sessions?q=, an ordinary
+ * read that any session (and the user) may make: it is a Concierge verb only for its framed, untrusted output. (FX-07)
+ * Text without a letter or digit is answered here without a request (the hub would match nothing).
  */
 export const HUB_TOOL_CONCIERGE_VERBS = ["concierge_board", "concierge_decisions", "concierge_decision", "concierge_notes", "concierge_notes_set", "concierge_watch", "concierge_unwatch", "concierge_mute", "concierge_unmute", "concierge_arm", "concierge_propose", "concierge_find", "concierge_form"] as const
 export type HubToolConciergeVerb = (typeof HUB_TOOL_CONCIERGE_VERBS)[number]
@@ -468,8 +471,8 @@ async function ask(client: HubClient, input: Input, send: { urgent?: boolean; wa
     while (asked.message.state === "open" && left > 0 && !bound.signal.aborted) {
       const step = Math.min(left, WAIT_POLL_MAX_S)
       left -= step
-      const delivery: Asked["delivery"] = asked.delivery
-      asked = { ...(delivery ? { delivery } : {}), ...(await client.message(asked.message.id, { wait: step, signal: bound.signal })) }
+      const sentAs: Sent = asked
+      asked = { ...deliveryMetadata(sentAs), ...(await client.message(asked.message.id, { wait: step, signal: bound.signal })) }
     }
     return askResult(asked)
   } catch (cause) {
@@ -486,22 +489,31 @@ async function ask(client: HubClient, input: Input, send: { urgent?: boolean; wa
 
 function askResult(asked: Asked): HubToolResult {
   const { message, answer } = asked
-  const metadata = { verb: "ask", id: message.id, state: message.state, ...(asked.delivery ? { delivery: asked.delivery } : {}) }
+  const metadata = { verb: "ask", id: message.id, state: message.state, ...deliveryMetadata(asked) }
   if (answer) return { content: `${message.state === "declined" ? "Declined" : "Answered"}: ${message.id}. ${NOT_FROM_USER}\n${envelope(answer)}`, metadata }
   if (message.state === "expired") return { content: `The ask ${message.id} expired without an answer.`, metadata }
-  return { content: `Asked ${message.id} (${asked.delivery ?? "stored"}); still open. The answer arrives as a hub message, or see hub inbox.`, metadata }
+  return { content: `Asked ${message.id} (${deliveryNote(asked)}); still open. The answer arrives as a hub message, or see hub inbox.`, metadata }
 }
 
 function sent(verb: string, result: Sent): HubToolResult {
   const { message } = result
   return {
-    content: `${verb === "decline" ? "Declined" : verb === "reply" ? "Replied" : "Sent"} ${message.id} to ${partyText(message)} (${result.delivery ?? "stored"}).`,
-    metadata: { verb, id: message.id, ...(result.delivery ? { delivery: result.delivery } : {}) },
+    content: `${verb === "decline" ? "Declined" : verb === "reply" ? "Replied" : "Sent"} ${message.id} to ${partyText(message)} (${deliveryNote(result)}).`,
+    metadata: { verb, id: message.id, ...deliveryMetadata(result) },
   }
 }
 
+/** `queued`, `turn`… and, when the hub did not wake the recipient, why (`queued — wake skipped: hop limit reached …`). */
+const deliveryNote = (result: Sent): string => `${result.delivery ?? "stored"}${wakeSkipNote(result)}`
+
+const deliveryMetadata = ({ delivery, woke, wakeSkipped }: Sent) => ({
+  ...(delivery ? { delivery } : {}),
+  ...(woke === undefined ? {} : { woke }),
+  ...(wakeSkipped ? { wakeSkipped } : {}),
+})
+
 function sentAll(verb: string, result: SentAll): HubToolResult {
-  const lines = result.sent.map((s) => `${s.message.id} → ${partyText(s.message)} (${s.delivery ?? "stored"})`)
+  const lines = result.sent.map((s) => `${s.message.id} → ${partyText(s.message)} (${deliveryNote(s)})`)
   return { content: `Sent to ${result.sent.length} session(s):\n${lines.join("\n")}`, metadata: { verb, ids: result.sent.map((s) => s.message.id) } }
 }
 
@@ -690,6 +702,8 @@ async function conciergeVerb(client: HubClient, verb: HubToolConciergeVerb, inpu
     }
     case "concierge_find": {
       const text = str(input, "text", verb)
+      // (FX-07) The hub matches words of letters and digits: text without any names no session (never all of them).
+      if (!/[\p{L}\p{N}]/u.test(text)) return { content: `No session matches ${framed(text, 200)}: give the @name or title words (letters or digits).`, metadata: { verb, sessions: 0 } }
       const { sessions } = await client.sessions({ q: text, ...signal })
       const roots = sessions.filter((x) => !x.parentID)
       const lines = roots.slice(0, FIND_MAX).map(foundLine)

package/src/spoke/launchers.ts

@@ -131,10 +131,12 @@ function onPath(name: string, searchPath: string, skip: string): string | undefi
  * terminal will not find it (~/.local/bin not on `path`, or another `hub` comes first). Small synchronous calls,
  * nothing when converged (the plugin runs this at start).
  */
-export function linkUserBin(options: { readonly home: string; readonly binDir: string; readonly path: string | undefined }): { linked: string[]; hint?: string } {
-  // Only the default hub bin dir (~/.local/state/hub/bin): a custom HUB_STATE_DIR (tests, containers, a throwaway
-  // state) must never leave ~/.local/bin pointing into it.
-  if (path.resolve(options.binDir) !== path.join(options.home, ".local", "state", "hub", "bin")) return { linked: [] }
+export function linkUserBin(options: { readonly home: string; readonly binDir: string; readonly path: string | undefined; readonly defaultBinDir?: string | undefined }): { linked: string[]; hint?: string } {
+  // Only the default hub bin dir (env-inject.ts defaultHubBinDir: the resolved state dir's bin, default
+  // ~/.local/state/hub/bin): a custom HUB_STATE_DIR (tests, containers, a throwaway state) must never leave
+  // ~/.local/bin pointing into it.
+  const allowed = options.defaultBinDir ?? path.join(options.home, ".local", "state", "hub", "bin")
+  if (path.resolve(options.binDir) !== path.resolve(allowed)) return { linked: [] }
   const userBin = userBinDir(options.home)
   const linkPath = path.join(userBin, "hub")
   const target = path.join(options.binDir, "hub")

package/src/spoke/listing.ts

@@ -22,14 +22,19 @@ export interface RawProject {
   readonly name?: string
 }
 
+/** Per-request options (the OpenCode client's RequestOptions): the listing's cancellation. */
+export interface ListingRequest {
+  readonly signal?: AbortSignal
+}
+
 /** The parts of the OpenCode client the listing uses. */
 export interface ListingClient {
   readonly session: {
-    list(input: { limit?: number; parentID?: null; cursor?: string }): Promise<{ data: readonly RawSession[]; cursor: { next?: string | null } }>
+    list(input: { limit?: number; parentID?: null; cursor?: string }, request?: ListingRequest): Promise<{ data: readonly RawSession[]; cursor: { next?: string | null } }>
     /** One session by ID (for always-included sessions outside the window). */
-    get?(input: { sessionID: string }): Promise<RawSession>
+    get?(input: { sessionID: string }, request?: ListingRequest): Promise<RawSession>
   }
-  readonly project: { list(): Promise<readonly RawProject[]> }
+  readonly project: { list(request?: ListingRequest): Promise<readonly RawProject[]> }
 }
 
 export interface ListedSession {
@@ -57,6 +62,8 @@ export interface ListingOptions {
    * projects, or in a directory under one of them, are listed. Absent: every session (the background service).
    */
   readonly scope?: readonly string[]
+  /** Cancels the listing: passed to every request, and no request starts once it aborted (the listing rejects). */
+  readonly signal?: AbortSignal
 }
 
 /** Most always-included sessions fetched one by one per listing. */
@@ -114,9 +121,12 @@ export async function listServiceSessions(client: ListingClient, options: Listin
   if (options.scope?.length === 0) return []
   const pageSize = options.pageSize ?? 100
   const maxPages = options.maxPages ?? 20
+  const { signal } = options
+  const request: ListingRequest = signal ? { signal } : {}
+  signal?.throwIfAborted()
   const projects = new Map<string, RawProject>()
   try {
-    for (const project of await client.project.list()) projects.set(project.id, project)
+    for (const project of await client.project.list(request)) projects.set(project.id, project)
   } catch {
     // workspaces fall back to directories
   }
@@ -129,7 +139,8 @@ export async function listServiceSessions(client: ListingClient, options: Listin
   // Sessions come newest first: the first one older than the window ends the listing.
   let ended = false
   for (let page = 0; page < maxPages && out.length < max && !ended; page++) {
-    const result = await client.session.list({ limit: pageSize, parentID: null, ...(cursor ? { cursor } : {}) })
+    signal?.throwIfAborted()
+    const result = await client.session.list({ limit: pageSize, parentID: null, ...(cursor ? { cursor } : {}) }, request)
     for (const s of result.data) {
       if (s.parentID || s.time.archived || out.length >= max) continue
       if (s.time.updated < cutoff) {
@@ -144,7 +155,8 @@ export async function listServiceSessions(client: ListingClient, options: Listin
   const have = new Set(out.map((s) => s.id))
   const missing = [...new Set(options.include ?? [])].filter((id) => !have.has(id)).slice(0, INCLUDE_FETCH_MAX)
   if (missing.length && client.session.get) {
-    const fetched = await Promise.all(missing.map((sessionID) => client.session.get!({ sessionID }).catch(() => undefined)))
+    signal?.throwIfAborted()
+    const fetched = await Promise.all(missing.map((sessionID) => client.session.get!({ sessionID }, request).catch(() => undefined)))
     for (const s of fetched) if (s && s.id && !s.parentID && !s.time?.archived && s.location?.directory && wanted(s)) out.push(listed(s))
   }
   return out