@huynle/hub 0.7.4 → 0.8.1

package/src/spoke/listing.ts

@@ -1,4 +1,5 @@
-// The background service's session listing for the phone's session browser: the most recent root
+// The session listing for the phone's session browser (the background service: every session; a foreground
+// `opencode serve`: those of the locations it loaded, see ListingOptions.scope): the most recent root
 // sessions (no subagent children, nothing archived) within the history window, plus sessions that must
 // always be listed (open in a terminal, running, ...), each with the workspace it belongs to.
 import path from "node:path"
@@ -21,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 {
@@ -51,16 +57,33 @@ export interface ListingOptions {
   readonly now?: number
   /** Session IDs listed even outside the window or over `max` (fetched one by one when missing). */
   readonly include?: readonly string[]
+  /**
+   * Directories of the locations this process has loaded (a foreground `opencode serve`): only sessions of their
+   * 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. */
 export const INCLUDE_FETCH_MAX = 50
 const DAY_MS = 86_400_000
 
+/**
+ * OpenCode's global project (directories outside any repository with commits). Its canonical directory is "/" in
+ * older versions and, in 2.2.x, a real directory (the first such directory registered): never a workspace root.
+ */
+export const GLOBAL_PROJECT_ID = "global"
+
+/** A project that is a real workspace root (not the global project). */
+const isRealProject = (project: RawProject | undefined): project is RawProject =>
+  project !== undefined && project.id !== GLOBAL_PROJECT_ID && !!project.canonical && project.canonical !== "/"
+
 /** Workspace root and name of a session: its project, else its directory minus its subpath. */
 export function workspaceOf(session: RawSession, projects: ReadonlyMap<string, RawProject>): { project: string; projectName: string } {
   const known = session.projectID ? projects.get(session.projectID) : undefined
-  if (known && known.canonical && known.canonical !== "/") {
+  if (isRealProject(known)) {
     return { project: known.canonical, projectName: known.name || path.basename(known.canonical) }
   }
   const directory = session.location.directory
@@ -69,16 +92,46 @@ export function workspaceOf(session: RawSession, projects: ReadonlyMap<string, R
   return { project: root, projectName: path.basename(root) || root }
 }
 
+const trimSlash = (dir: string) => dir.replace(/\/+$/, "") || "/"
+/** `dir` is `root` or inside it. */
+const within = (dir: string, root: string) => {
+  const r = trimSlash(root)
+  return dir === r || dir.startsWith(r === "/" ? "/" : `${r}/`)
+}
+
+/**
+ * Whether a session belongs to a loaded location: its directory is under one, or its project (a real one, not the
+ * global project) is the project of one (the project whose root holds the location, the deepest one).
+ */
+export function inScope(session: RawSession, scope: readonly string[], projects: ReadonlyMap<string, RawProject>): boolean {
+  const directory = trimSlash(session.location.directory)
+  const dirs = scope.map(trimSlash)
+  if (dirs.some((dir) => within(directory, dir))) return true
+  const own = session.projectID ? projects.get(session.projectID) : undefined
+  if (!isRealProject(own)) return false
+  const roots = [...projects.values()].filter(isRealProject).map((p) => p.canonical)
+  return dirs.some((dir) => {
+    const holder = roots.filter((root) => within(dir, root)).sort((a, b) => b.length - a.length)[0]
+    return holder !== undefined && trimSlash(holder) === trimSlash(own.canonical)
+  })
+}
+
 export async function listServiceSessions(client: ListingClient, options: ListingOptions = {}): Promise<ListedSession[]> {
   const max = options.max ?? 500
+  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
   }
+  const scope = options.scope
+  const wanted = (s: RawSession) => scope === undefined || inScope(s, scope, projects)
   const cutoff = options.days !== undefined ? (options.now ?? Date.now()) - options.days * DAY_MS : -Infinity
   const listed = (s: RawSession): ListedSession => ({ id: s.id, title: s.title ?? "", directory: s.location.directory, updated: s.time.updated, ...workspaceOf(s, projects) })
   const out: ListedSession[] = []
@@ -86,14 +139,15 @@ 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) {
         ended = true
         break
       }
-      out.push(listed(s))
+      if (wanted(s)) out.push(listed(s))
     }
     cursor = result.cursor.next ?? undefined
     if (!cursor || result.data.length === 0) break
@@ -101,8 +155,9 @@ 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)))
-    for (const s of fetched) if (s && s.id && !s.parentID && !s.time?.archived && s.location?.directory) out.push(listed(s))
+    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
 }

package/src/spoke/localhub.ts

@@ -10,7 +10,9 @@ import path from "node:path"
 import { fileURLToPath } from "node:url"
 import { hubEnv } from "../env"
 import { isLoopbackURL } from "../loopback"
-import { APP_DIR, legacyPaths, migrateFirst, stateBase } from "../migrate"
+import { migrateStateDir, resolveHubStateDir, stateLegacyPaths } from "../migrate"
+
+const CONCIERGE_LOCK = "concierge-sessions.json"
 
 export interface ChildLike {
   readonly pid?: number
@@ -23,7 +25,7 @@ export type SpawnLike = (command: string, args: readonly string[], options: obje
 
 export interface LocalHubOptions {
   /**
-   * Where hub.pid and hub.log live (default $HUB_STATE_DIR or ~/.local/state/hub, migrated from
+   * Where hub.pid and hub.log live (default $HUB_STATE_DIR, else $XDG_STATE_HOME/hub or ~/.local/state/hub, migrated from
    * ~/.local/state/opencode-hub or opencode-voice first so the hub does not find a fresh, empty state directory).
    */
   readonly stateDir?: string
@@ -86,7 +88,15 @@ export function hubScript(root: string = repoRoot()): string {
 }
 
 export function defaultStateDir(env: Readonly<Record<string, string | undefined>> = process.env, home: string = homedir()): string {
-  return hubEnv(env).HUB_STATE_DIR || path.join(stateBase(home), APP_DIR)
+  return resolveHubStateDir(env, home).dir
+}
+
+/** The Concierge lock file (written in the state dir) and the other default places' lock files (read too: fail closed). */
+export function conciergeLockFiles(env: Readonly<Record<string, string | undefined>> = process.env, home: string = homedir()): { file: string; read: string[] } {
+  const { candidates, source } = resolveHubStateDir(env, home)
+  const [dir, ...others] = candidates
+  // An explicit HUB_STATE_DIR is an isolated instance (a preview or a test): it never reads the user's default dirs.
+  return { file: path.join(dir!, CONCIERGE_LOCK), read: source === "env" ? [] : others.map((d) => path.join(d, CONCIERGE_LOCK)) }
 }
 
 /** The runtime for this process: probes the real executable, PATH and home directory. */
@@ -152,7 +162,7 @@ export async function ensureLocalHub(server: string, options: LocalHubOptions =
   if (!(options.webBuilt ?? hasWebBuild)(root)) return { status: "failed", error: WEB_NOT_BUILT }
 
   if (options.stateDir === undefined && !hubEnv(env).HUB_STATE_DIR) {
-    migrateFirst(legacyPaths(stateBase(home)), stateDir, { skip: ["hub.pid"], ...(options.log ? { log: options.log } : {}) })
+    migrateStateDir(stateLegacyPaths(env, home), stateDir, { skip: ["hub.pid"], ...(options.log ? { log: options.log } : {}) })
   }
   mkdirSync(stateDir, { recursive: true, mode: 0o700 })
 

package/src/spoke/locations.ts

@@ -10,6 +10,7 @@ export interface PermissionLocation {
   get(input: { sessionID: string; requestID: string }): Promise<unknown>
   /** `message`: a reject's reason (OpenCode's reply message). */
   reply(input: { sessionID: string; requestID: string; decision: PermissionDecision; message?: string }): Promise<unknown>
+  vcs?: { diff(): Promise<ReadonlyArray<unknown>>; branch(): Promise<string | undefined> }
 }
 
 /**
@@ -33,3 +34,42 @@ export async function replyPermission(
   }
   return "gone"
 }
+
+/** A directory's branch and working-copy changes (undefined: nothing could read them). */
+export interface VcsReader {
+  diff(directory: string): Promise<ReadonlyArray<unknown> | undefined>
+  branch(directory: string): Promise<string | undefined>
+}
+
+/**
+ * Reads a directory's VCS state through the plugin instance whose location is that directory, else the own
+ * server's API (which honours the location), else not at all. OpenCode's plugin vcs API answers for the
+ * instance's own location whatever location is passed, so the first instance (the background service's is
+ * its $HOME) would report another directory's branch and changes. A read that takes longer than `timeoutMs` (a hung
+ * server) answers undefined, so the session summary goes on without branch and changes.
+ */
+/** How long a branch or changes read may take before the summary goes on without it (a hung server). */
+export const VCS_READ_TIMEOUT_MS = 5_000
+
+/** The value, or undefined once `ms` passed (the read is left to finish on its own). */
+function within<T>(read: Promise<T | undefined>, ms: number): Promise<T | undefined> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const late = new Promise<undefined>((resolve) => {
+    timer = setTimeout(() => resolve(undefined), ms)
+  })
+  return Promise.race([read.catch(() => undefined), late]).finally(() => clearTimeout(timer))
+}
+
+export function vcsReader(locations: () => readonly PermissionLocation[], server: () => Promise<VcsReader | undefined>, timeoutMs: number = VCS_READ_TIMEOUT_MS): VcsReader {
+  const local = (directory: string) => locations().find((l) => l.directory === directory && l.vcs)?.vcs
+  return {
+    diff: async (directory) => {
+      const vcs = local(directory)
+      return within(vcs ? vcs.diff() : server().then((reader) => reader?.diff(directory)), timeoutMs)
+    },
+    branch: async (directory) => {
+      const vcs = local(directory)
+      return within(vcs ? vcs.branch() : server().then((reader) => reader?.branch(directory)), timeoutMs)
+    },
+  }
+}

package/src/spoke/profile-apply.ts

@@ -0,0 +1,298 @@
+// The OpenCode profile application adapter (HWA-16; contract packages/protocol/src/profiles.ts, SDK rules in
+// packages/spoke-sdk/src/profile-apply.ts). A hub profile becomes a session-scoped layer held in this process's
+// memory only; nothing is written to disk and no OpenCode configuration (global or project) is touched:
+//
+// - Instructions: the plugin's `context` hook appends them to the session's system prompt after OpenCode's own
+//   parts (which carry AGENTS.md and the user's config), framed by profileInstructionsBlock: local instructions win.
+// - Skills and commands: listed in that system part and served by the `hub_profile` tool (registered once per
+//   process like the `hub` tool; the context hook hides it from sessions without a profile, and it answers only
+//   the calling session's layer). OpenCode's skill/command registries are location-wide, so they are not used.
+//   Same-named local skills/commands win (partial). Commands that reference `{{secret:NAME}}` are skipped: a
+//   rendered command becomes a persisted prompt or tool result in OpenCode, and resolved secrets must never be
+//   written (renderAtInvocation false). The model preference is ignored (the user's model is never switched).
+// - Next-turn boundary: an idle session's layer is replaced at once (its next turn reads it). For a busy session
+//   the new layer is staged, the running turn keeps the previous one, and the answer waits for the turn to end
+//   (Spoke.observe calls settle; a poll backs it up). The answer echoes exactly the version that became
+//   effective. A wait past boundaryWaitMs fails: the hub, which times out first, keeps the pin pending and sends it
+//   again on the spoke's next sessions frame, which is answered from the then-effective layer. A newer version
+//   staged before the boundary supersedes the older one, which is answered `rejected`.
+// - Rollback: a failed or unsupported apply leaves the effective layer as it was; re-pinning an older version
+//   replaces the layer with it. There is no remove op in v1 (an empty version clears the layer).
+// - Bounded: at most maxSessions layers (oldest dropped; the hub re-sends after a reconnect), notes bounded by the
+//   SDK. Lost on process restart: the new connection's sessions frame makes the hub send the pin again.
+import { isObj } from "../../packages/protocol/src/wire.ts"
+import { type ProfileApplyRequest, type ProfileApplyResult, type ProfileCommand, type ProfileSkill, profileTemplateParts } from "../../packages/protocol/src/index.ts"
+import { boundedNotes, planProfileApplication, profileApplyResult, profileDigest, type ProfileLocalNames, renderProfileCommand } from "../../packages/spoke-sdk/src/profile-apply.ts"
+
+export const PROFILE_TOOL = "hub_profile"
+
+export const PROFILE_TOOL_DESCRIPTION =
+  "Use this session's hub agent profile: {skill: name} returns a profile skill's instructions; " +
+  "{command: name, params: {name: value}} returns a profile command's text with its parameters filled in, to follow as the user's request. " +
+  "Only the skills and commands listed in the hub profile section of your instructions exist."
+
+export const PROFILE_TOOL_INPUT = {
+  type: "object",
+  properties: {
+    skill: { type: "string", description: "A profile skill's name." },
+    command: { type: "string", description: "A profile command's name." },
+    params: { type: "object", additionalProperties: { type: "string" }, description: "The command's parameters (each {{name}} in it; `arguments` for free text)." },
+  },
+  additionalProperties: false,
+} as const
+
+export interface OpenCodeProfilesOptions {
+  /** The session has a turn running (OpenCode busy, or a hub turn in progress). */
+  readonly isBusy: (sessionID: string) => boolean
+  /** The session's local skill and command names; absent: skills and commands are not applied. */
+  readonly localNames?: (sessionID: string) => Promise<ProfileLocalNames>
+  /** The hub_profile tool is available in this OpenCode. */
+  readonly tool: () => boolean
+  /** How long a busy session's answer waits for the boundary (default 120 s). */
+  readonly boundaryWaitMs?: number
+  /** How often a waiting answer checks the session (default 1 s). */
+  readonly pollMs?: number
+  /** Sessions with a layer kept (default 1000). */
+  readonly maxSessions?: number
+}
+
+export interface ProfileEffectiveLayer {
+  readonly profileID: string
+  readonly version: number
+  readonly digest: string
+  readonly status: ProfileApplyResult["status"]
+}
+
+interface Layer {
+  readonly result: ProfileApplyResult
+  readonly instructions?: string
+  readonly skills: readonly ProfileSkill[]
+  readonly commands: readonly ProfileCommand[]
+}
+
+interface Waiter {
+  readonly resolve: (result: ProfileApplyResult) => void
+  readonly reject: (cause: Error) => void
+}
+
+interface Staged {
+  readonly layer: Layer
+  readonly waiters: Set<Waiter>
+  poll?: ReturnType<typeof setInterval>
+}
+
+/** A final answer, or one waiting for the boundary (its waiter is registered before staging returns). */
+type Step = { readonly result: ProfileApplyResult } | { readonly pending: Promise<ProfileApplyResult> }
+
+const sameVersion = (a: ProfileApplyResult, req: ProfileApplyRequest) => a.profileID === req.profileID && a.version === req.version && a.digest === req.digest
+
+export class OpenCodeProfiles {
+  private readonly layers = new Map<string, Layer>()
+  private readonly staged = new Map<string, Staged>()
+  private readonly locks = new Map<string, Promise<void>>()
+
+  constructor(private readonly options: OpenCodeProfilesOptions) {}
+
+  /** The profileApply op: answers once the version is effective in the session (see the header). */
+  async handle(req: ProfileApplyRequest): Promise<ProfileApplyResult> {
+    if (profileDigest(req.content) !== req.digest) return profileApplyResult(req, "rejected", ["digest does not match the content; nothing applied"])
+    const step = await this.serialize(req.sessionID, () => this.stage(req))
+    return "pending" in step ? step.pending : step.result
+  }
+
+  /** A turn boundary may have passed: makes a staged layer effective when the session is not busy. */
+  settle(sessionID: string): void {
+    const staged = this.staged.get(sessionID)
+    if (!staged || this.options.isBusy(sessionID)) return
+    this.dropStaged(sessionID, staged)
+    this.setLayer(sessionID, staged.layer)
+    for (const waiter of staged.waiters) waiter.resolve(staged.layer.result)
+  }
+
+  /** The version the session runs now, if any. */
+  effective(sessionID: string): ProfileEffectiveLayer | undefined {
+    const layer = this.layers.get(sessionID)
+    if (!layer) return undefined
+    const { profileID, version, digest, status } = layer.result
+    return { profileID, version, digest, status }
+  }
+
+  /** System prompt parts for the session's next model request (after local instructions). */
+  systemParts(sessionID: string): string[] {
+    const layer = this.layers.get(sessionID)
+    if (!layer) return []
+    const parts: string[] = []
+    if (layer.instructions !== undefined) parts.push(layer.instructions)
+    if (layer.skills.length || layer.commands.length) parts.push(bindingsText(layer))
+    return parts
+  }
+
+  /** Whether the session's model sees the hub_profile tool. */
+  toolVisible(sessionID: string): boolean {
+    const layer = this.layers.get(sessionID)
+    return layer !== undefined && (layer.skills.length > 0 || layer.commands.length > 0)
+  }
+
+  /** The hub_profile tool for the calling session: a skill's body or a command's rendered text, or why not. */
+  runTool(sessionID: string, input: unknown): string {
+    const value = isObj(input) ? input : {}
+    const skill = typeof value.skill === "string" ? value.skill : undefined
+    const command = typeof value.command === "string" ? value.command : undefined
+    if (skill === undefined && command === undefined) return "Give a skill or command name of this session's hub profile."
+    const layer = this.layers.get(sessionID)
+    if (!layer) return "This session has no hub profile."
+    if (skill !== undefined) {
+      const found = layer.skills.find((s) => s.name === skill)
+      return found ? `Skill ${found.name} (hub profile ${layer.result.profileID} v${layer.result.version}):\n\n${found.body}` : `This session has no hub profile skill named ${skill}.`
+    }
+    const found = layer.commands.find((c) => c.name === command)
+    if (!found) return `This session has no hub profile command named ${command}.`
+    const params = isObj(value.params) ? value.params : {}
+    if (!Object.values(params).every((v) => typeof v === "string")) return `Command ${found.name}: every parameter must be text.`
+    try {
+      // Commands with secret references are never in a layer, so no secret is ever resolved here.
+      return renderProfileCommand(found.template, params as Record<string, string>, () => undefined)
+    } catch (cause) {
+      return `Command ${found.name} could not be run: ${cause instanceof Error ? cause.message : String(cause)}`
+    }
+  }
+
+  /** The session ended: drops its layer and fails an answer still waiting for its boundary. */
+  forget(sessionID: string): void {
+    this.layers.delete(sessionID)
+    const staged = this.staged.get(sessionID)
+    if (!staged) return
+    this.dropStaged(sessionID, staged)
+    for (const waiter of staged.waiters) waiter.reject(new Error("the session ended before the profile took effect"))
+  }
+
+  // ---------- internals ----------
+
+  private async stage(req: ProfileApplyRequest): Promise<Step> {
+    const { sessionID } = req
+    const staged = this.staged.get(sessionID)
+    if (staged && sameVersion(staged.layer.result, req)) return { pending: this.wait(sessionID, staged) }
+    const current = this.layers.get(sessionID)
+    if (current && sameVersion(current.result, req)) {
+      this.supersede(sessionID, req)
+      return { result: current.result }
+    }
+    let local: ProfileLocalNames | undefined
+    if (this.options.localNames) {
+      try {
+        local = await this.options.localNames(sessionID)
+      } catch {
+        return { result: profileApplyResult(req, "rejected", ["could not read the session's local skills and commands (they take precedence); nothing applied"]) }
+      }
+    }
+    const bindings = this.options.tool() && local !== undefined
+    const plan = planProfileApplication(req, {
+      capabilities: { instructions: true, skills: bindings, commands: bindings, model: false, live: true, renderAtInvocation: false },
+      ...(local ? { local } : {}),
+    })
+    const result = profileApplyResult(req, plan.status, plan.notes)
+    if (plan.status === "unsupported") return { result }
+    const layer: Layer = { result, ...(plan.instructions !== undefined ? { instructions: plan.instructions } : {}), skills: plan.skills, commands: plan.commands }
+    this.supersede(sessionID, req)
+    if (!this.options.isBusy(sessionID)) {
+      this.setLayer(sessionID, layer)
+      return { result }
+    }
+    const next: Staged = { layer, waiters: new Set() }
+    this.staged.set(sessionID, next)
+    return { pending: this.wait(sessionID, next) }
+  }
+
+  /** Waits for the staged layer's boundary, at most boundaryWaitMs. */
+  private wait(sessionID: string, staged: Staged): Promise<ProfileApplyResult> {
+    const pending = new Promise<ProfileApplyResult>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        staged.waiters.delete(waiter)
+        if (!staged.waiters.size) this.stopPoll(staged)
+        const { profileID, version } = staged.layer.result
+        reject(new Error(`the session is still busy; profile ${profileID} v${version} is staged and takes effect at its next turn boundary`))
+      }, this.options.boundaryWaitMs ?? 120_000)
+      unref(timer)
+      const waiter: Waiter = {
+        resolve: (result) => (clearTimeout(timer), resolve(result)),
+        reject: (cause) => (clearTimeout(timer), reject(cause)),
+      }
+      staged.waiters.add(waiter)
+      if (!staged.poll) {
+        staged.poll = setInterval(() => this.settle(sessionID), this.options.pollMs ?? 1000)
+        unref(staged.poll)
+      }
+    })
+    pending.catch(() => {}) // handled by handle(); the waiter may fail before it is awaited
+    return pending
+  }
+
+  /** A staged layer for another version is answered rejected: `req` replaces it before it took effect. */
+  private supersede(sessionID: string, req: ProfileApplyRequest): void {
+    const staged = this.staged.get(sessionID)
+    if (!staged) return
+    this.dropStaged(sessionID, staged)
+    const { profileID, version, digest } = staged.layer.result
+    const note = `superseded by profile ${req.profileID} v${req.version} before it took effect at the next turn boundary`
+    const result: ProfileApplyResult = { sessionID, profileID, version, digest, status: "rejected", notes: boundedNotes([note]) }
+    for (const waiter of staged.waiters) waiter.resolve(result)
+  }
+
+  private dropStaged(sessionID: string, staged: Staged): void {
+    if (this.staged.get(sessionID) === staged) this.staged.delete(sessionID)
+    this.stopPoll(staged)
+  }
+
+  private stopPoll(staged: Staged): void {
+    if (staged.poll) clearInterval(staged.poll)
+    staged.poll = undefined
+  }
+
+  private setLayer(sessionID: string, layer: Layer): void {
+    this.layers.delete(sessionID)
+    this.layers.set(sessionID, layer)
+    while (this.layers.size > (this.options.maxSessions ?? 1000)) this.layers.delete(this.layers.keys().next().value!)
+  }
+
+  /** Runs one session's staging steps one at a time (waiting for a boundary is outside). */
+  private serialize<T>(sessionID: string, run: () => Promise<T>): Promise<T> {
+    const previous = this.locks.get(sessionID) ?? Promise.resolve()
+    const next = previous.then(run)
+    const tail = next.then(
+      () => undefined,
+      () => undefined,
+    )
+    this.locks.set(sessionID, tail)
+    void tail.then(() => {
+      if (this.locks.get(sessionID) === tail) this.locks.delete(sessionID)
+    })
+    return next
+  }
+}
+
+/** The system part that lists the session's profile skills and commands (names, descriptions, parameters). */
+function bindingsText(layer: Layer): string {
+  const { profileID, version } = layer.result
+  const lines = [
+    `Hub profile ${profileID} v${version} adds skills and commands to this session only, through the ${PROFILE_TOOL} tool. Local skills and commands of the same name take precedence and are not listed.`,
+  ]
+  if (layer.skills.length) {
+    lines.push("", `Profile skills (load one with ${PROFILE_TOOL} {"skill": name} before following it):`)
+    for (const skill of layer.skills) lines.push(`- ${skill.name}: ${oneLine(skill.description)}`)
+  }
+  if (layer.commands.length) {
+    lines.push("", `Profile commands (when the user asks for /name or the command by name, call ${PROFILE_TOOL} {"command": name, "params": {...}} and follow the text it returns):`)
+    for (const command of layer.commands) {
+      const parts = profileTemplateParts(command.template)
+      const params = typeof parts === "string" ? [] : [...new Set(parts.flatMap((p) => ("param" in p ? [p.param] : [])))]
+      lines.push(`- ${command.name}${params.length ? ` (params: ${params.join(", ")})` : ""}: ${oneLine(command.description)}`)
+    }
+  }
+  return lines.join("\n")
+}
+
+const oneLine = (text: string) => text.replace(/\s+/g, " ").trim()
+
+function unref(timer: ReturnType<typeof setTimeout>): void {
+  ;(timer as { unref?: () => void }).unref?.()
+}