@huynle/hub 0.7.4 → 0.8.1

package/src/central/concierge/supervisor.ts

@@ -0,0 +1,767 @@
+// CON-04 Concierge supervisor (contract "Supervise / relaunch", "State record", "Disable"): one hub-launched,
+// hub-owned OpenCode session per user, on the machine the user picked in Settings → Concierge.
+//
+// State record: collection `concierge`, key `state`, per user: the public ConciergeStatus plus launchSeq (the launch
+// key counter), pendingSeq (a launch being accepted), attempts (relaunch times, last hour), backoffIndex,
+// runningSince, fresh (the next launch follows an enable or a Restart, not a failure) and lastLaunchID. Every write
+// is a compare-and-set on the record's version (StatusStore.cas): a deposed leader, a second pod or a racing route
+// handler loses the race instead of launching twice, and the launch key (concierge:<user hash>:<seq>) is written
+// BEFORE LaunchEngine.accept, so a retried accept of the same seq is idempotent.
+//
+// One pass (reconcile, serialized per user in this process; never rejects):
+//   settings disabled → finish a disable whose record is not disabled yet (a crash between the settings and record
+//     writes, or one left stopping; failed waits for the user), release stray @@concierge holders, stop live launches
+//   failed → nothing (Restart, or disable + enable)
+//   a launch recorded → follow it: running → claim @@concierge (managed, exclusive; other holders released first),
+//     hide the session, push its context; ended for any reason → backoff (CONCIERGE_LIMITS.relaunchBackoffMs, reset
+//     after healthyAfterMs running) or failed past relaunchesPerHour; queued/provisioning → keep waiting
+//   a launch being accepted → accept the same key again (idempotent)
+//   backoff not due → nothing
+//   otherwise → entitlements.check, the machine's eligibility (ineligible → waiting_machine with its reason), then
+//     a new launch: in process, `by: "app:concierge"`, no prompt, no name, no roles (the user's standing setting is
+//     the authority; audited as concierge.launch / concierge.relaunch)
+// Live Concierge launches (label hub/system=concierge) other than the recorded one are stopped (orphans of a lost
+// race or a restart), and every live one while the Concierge is disabled. Each relaunch is a new session; the old
+// ID stays in hiddenSessionIDs (at most 20, oldest dropped). (CON-09a) A host session outlives its stopped launch on
+// the machine's OpenCode, so every previous session (Restart, a relaunch, and each other hidden one when a new one is
+// adopted) is retired: its context replaced by a locked, powerless one (no board, notes or tools).
+import { createHash } from "node:crypto"
+import { CONCIERGE_AGENT, CONCIERGE_LIMITS, CONCIERGE_PARTY, CONCIERGE_ROLE, type ConciergeSettings, type ConciergeStatus } from "../../../packages/protocol/src/concierge"
+import type { Clock, StateStore, Timers } from "../backend/types"
+import type { Directory } from "../agent/directory"
+import { AgentError } from "../agent/errors"
+import type { Grants } from "../agent/grants"
+import type { LaunchEngine } from "../agent/launch-engine"
+import type { Launch } from "../agent/launch-store"
+import type { ConciergeEntitlements } from "./entitlements"
+import { CONCIERGE_COLLECTION } from "./notes"
+import type { SettingsStore } from "./settings"
+
+const KEY = "state"
+const HOUR_MS = 3_600_000
+export const SUPERVISOR_TICK_MS = 5_000
+/** Why a Concierge found on another agent is suspended (Settings shows it). */
+export const CONCIERGE_TAMPERED = "The Concierge's agent was changed outside the hub"
+/** The label every Concierge launch carries (never interpreted by the hub elsewhere). */
+export const CONCIERGE_LABEL = { "hub/system": "concierge" } as const
+
+export interface ConciergeRecord extends ConciergeStatus {
+  readonly launchSeq: number
+  readonly pendingSeq?: number
+  readonly attempts: readonly number[]
+  readonly backoffIndex: number
+  readonly runningSince?: number
+  readonly fresh?: boolean
+  readonly lastLaunchID?: string
+  readonly settingsRevision?: number
+  /**
+   * Every Concierge session this user ever had (at most PAST_SESSIONS_MAX, oldest dropped), beyond the 20 the status
+   * shows as hidden: a past Concierge session never becomes an ordinary session (identity, guards, gate).
+   */
+  readonly pastSessionIDs?: readonly string[]
+}
+
+export const PAST_SESSIONS_MAX = 500
+
+const DEFAULT_RECORD: ConciergeRecord = { state: "disabled", hiddenSessionIDs: [], generation: 0, since: 0, launchSeq: 0, attempts: [], backoffIndex: 0 }
+
+/** The public status of a record (no internals, no undefined fields). */
+export function statusOf(r: ConciergeRecord): ConciergeStatus {
+  return {
+    state: r.state,
+    ...(r.reason !== undefined ? { reason: r.reason.slice(0, 200) } : {}),
+    ...(r.sessionID !== undefined ? { sessionID: r.sessionID } : {}),
+    hiddenSessionIDs: [...r.hiddenSessionIDs],
+    ...(r.launchID !== undefined ? { launchID: r.launchID } : {}),
+    ...(r.machineID !== undefined ? { machineID: r.machineID } : {}),
+    generation: r.generation,
+    since: r.since,
+    ...(r.nextAttemptAt !== undefined ? { nextAttemptAt: r.nextAttemptAt } : {}),
+  }
+}
+
+/** Drops undefined fields (records are stored as JSON). */
+const clean = <T extends object>(value: T): T => Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined)) as T
+
+export interface RecordSnapshot {
+  readonly record: ConciergeRecord
+  readonly version: number
+}
+
+/** The per-user state record, written only by compare-and-set. */
+export class StatusStore {
+  constructor(
+    private readonly state: StateStore,
+    private readonly now: Clock = Date.now,
+  ) {}
+
+  async read(userID: string): Promise<RecordSnapshot> {
+    const stored = await this.state.get<ConciergeRecord>(userID, CONCIERGE_COLLECTION, KEY)
+    return { record: stored?.value ?? DEFAULT_RECORD, version: stored?.version ?? 0 }
+  }
+
+  async get(userID: string): Promise<ConciergeRecord> {
+    return (await this.read(userID)).record
+  }
+
+  /** Writes `next` when the record is still at `snap`'s version; the past sessions only ever grow (bounded). */
+  async cas(userID: string, snap: RecordSnapshot, next: ConciergeRecord): Promise<boolean> {
+    const past = [...new Set([...(snap.record.pastSessionIDs ?? []), ...snap.record.hiddenSessionIDs, ...next.hiddenSessionIDs, ...(next.pastSessionIDs ?? []), ...(next.sessionID !== undefined ? [next.sessionID] : [])])].slice(-PAST_SESSIONS_MAX)
+    return (await this.state.put(userID, CONCIERGE_COLLECTION, KEY, clean({ ...next, pastSessionIDs: past }), { ifVersion: snap.version })).ok
+  }
+
+  /** Read-modify-write, retried on a lost race. */
+  async update(userID: string, change: (current: ConciergeRecord) => ConciergeRecord): Promise<ConciergeRecord> {
+    for (let attempt = 0; attempt < 16; attempt++) {
+      const snap = await this.read(userID)
+      const next = clean(change(snap.record))
+      if (await this.cas(userID, snap, next)) return next
+    }
+    throw new AgentError("conflict", "The Concierge state kept changing; retry")
+  }
+
+  /** The clock (records' `since`). */
+  time(): number {
+    return this.now()
+  }
+}
+
+export interface IdentityOptions {
+  /**
+   * (FX-07) The user's sessions a machine reports locked now (its spoke holds them as Concierge sessions: they carry
+   * an agent or a context revision). The state record keeps only PAST_SESSIONS_MAX past sessions; an older one its
+   * machine still reports is still a Concierge session (and one no machine reports cannot use its tokens).
+   */
+  readonly reported?: (userID: string) => Iterable<string>
+}
+
+/**
+ * The Concierge-only authority read from the state record: the current session and every hidden one (plus, FX-07,
+ * those a machine reports locked). A failing report adds nothing; the record's own sessions always count.
+ */
+export function recordIdentity(store: StatusStore, options: IdentityOptions = {}): { current(userID: string): Promise<{ sessionID?: string; hiddenSessionIDs: readonly string[] }> } {
+  return {
+    current: async (userID) => {
+      const r = await store.get(userID)
+      const all = new Set([...(r.pastSessionIDs ?? []), ...r.hiddenSessionIDs])
+      try {
+        if (options.reported) for (const id of options.reported(userID)) all.add(id)
+      } catch (cause) {
+        console.error(`[hub] concierge locked-session report failed: ${(cause as Error).message}`)
+      }
+      return { ...(r.sessionID !== undefined ? { sessionID: r.sessionID } : {}), hiddenSessionIDs: [...all] }
+    },
+  }
+}
+
+/** A Concierge launch key: one per launch attempt of the user. */
+export function conciergeLaunchKey(userID: string, seq: number): string {
+  return `concierge:${createHash("sha256").update(userID).digest("hex").slice(0, 16)}:${seq}`
+}
+
+/** The launch spec of attempt `seq` (contract "Launch"). */
+export function conciergeLaunchSpec(userID: string, settings: ConciergeSettings, seq: number): Record<string, unknown> {
+  return {
+    key: conciergeLaunchKey(userID, seq),
+    roles: [],
+    harness: "opencode",
+    agent: CONCIERGE_AGENT,
+    ...(settings.model !== undefined ? { model: settings.model } : {}),
+    workspace: { repo: settings.directory, mode: "checkout" },
+    runtime: { kind: "host" },
+    placement: { machine: settings.machineID, mode: "require" },
+    labels: { ...CONCIERGE_LABEL },
+    end: { when: "never", cleanup: "keep" },
+  }
+}
+
+/** A queued launch's waiting reason as the Concierge's status: "Waiting: …" (kept when it already says Waiting). */
+const waitingText = (reason: string): string => (reason.startsWith("Waiting") ? reason : `Waiting: ${reason}`)
+
+/** Whether a launch is a Concierge launch (its label). */
+export const isConciergeLaunch = (launch: Pick<Launch, "spec">): boolean => launch.spec.labels?.["hub/system"] === "concierge"
+
+export const addHidden = (hidden: readonly string[], sessionID: string): string[] =>
+  hidden.includes(sessionID) ? [...hidden] : [...hidden, sessionID].slice(-CONCIERGE_LIMITS.hiddenHistory)
+
+export interface Eligibility {
+  readonly eligible: boolean
+  readonly online: boolean
+  readonly reason?: string
+}
+
+export interface SupervisorDeps {
+  readonly state: StateStore
+  readonly settings: SettingsStore
+  readonly launches: Pick<LaunchEngine, "accept" | "view" | "stop"> & Partial<Pick<LaunchEngine, "list">>
+  /** (CON-09a) `unname`: Concierge sessions hold no @name (none derived from their titles). */
+  readonly directory: Pick<Directory, "resolve" | "claimRole" | "releaseRole"> & Partial<Pick<Directory, "unname">>
+  readonly grants: Pick<Grants, "revoke">
+  /** Whether the user's machine can host the Concierge now (a node, a launch- and sessionContext-capable spoke). */
+  readonly eligibility: (userID: string, machineID: string) => Eligibility
+  readonly entitlements: ConciergeEntitlements
+  /** The session context (context.ts): pushed once running, cleared on disable. Never rejects in production. */
+  readonly context: {
+    push(userID: string, sessionID: string): Promise<void>
+    clear(userID: string, sessionID: string): Promise<void>
+    /**
+     * (CON-09a) A previous Concierge session: locked (the concierge agent kept) and powerless (no board, notes or
+     * tools), so a session left running on its machine can do nothing. Never rejects in production.
+     */
+    retire?(userID: string, sessionID: string): Promise<void>
+  }
+  /** Every change of the public status (console SSE, journal). */
+  readonly onStatus?: (userID: string, status: ConciergeStatus) => void
+  /** A session became the Concierge: detach it from workspaces and teams (it is hub-owned). Never rejects in production. */
+  readonly onAdopted?: (userID: string, sessionID: string) => Promise<void>
+  /** The Concierge was suspended (an alert for the user). */
+  readonly onSuspended?: (userID: string, sessionID: string) => void
+  /** The admin audit: concierge.launch | relaunch | restart | disable | suspended. */
+  readonly audit?: (userID: string, action: string) => Promise<void>
+  readonly users: () => Promise<Iterable<string>>
+  readonly now?: Clock
+  readonly timers?: Timers
+  readonly tickMs?: number
+}
+
+const defaultTimers: Timers = {
+  set: (fn, ms) => {
+    const handle = setTimeout(fn, ms)
+    ;(handle as { unref?: () => void }).unref?.()
+    return handle
+  },
+  clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+}
+
+const errorText = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause)).slice(0, 160)
+const ignorable = (cause: unknown) => cause instanceof AgentError && (cause.code === "gone" || cause.code === "not_found")
+
+export class Supervisor {
+  readonly store: StatusStore
+  private readonly now: Clock
+  private readonly timers: Timers
+  private readonly chains = new Map<string, Promise<void>>()
+  private running = false
+  private timer: unknown
+
+  constructor(private readonly deps: SupervisorDeps) {
+    this.now = deps.now ?? Date.now
+    this.timers = deps.timers ?? defaultTimers
+    this.store = new StatusStore(deps.state, this.now)
+  }
+
+  // ---- identity and status ----
+
+  /** The user's current Concierge session (state record) and every hidden one: the Concierge-only authority. */
+  current(userID: string): Promise<{ sessionID?: string; hiddenSessionIDs: readonly string[] }> {
+    return recordIdentity(this.store).current(userID)
+  }
+
+  async status(userID: string): Promise<ConciergeStatus> {
+    return statusOf(await this.store.get(userID))
+  }
+
+  // ---- leader loop ----
+
+  /** Leader elected: a pass over every user now, then every tickMs. */
+  start(): void {
+    if (this.running) return
+    this.running = true
+    void this.tick()
+  }
+
+  /** Deposed (or shutting down): no more passes from this process. */
+  stop(): void {
+    this.running = false
+    if (this.timer !== undefined) this.timers.clear(this.timer)
+    this.timer = undefined
+  }
+
+  get leading(): boolean {
+    return this.running
+  }
+
+  /** Something about the user changed (a launch, a node, a spoke): a pass now when this process supervises. */
+  kick(userID: string): void {
+    if (this.running) void this.reconcile(userID)
+  }
+
+  private async tick(): Promise<void> {
+    try {
+      for (const userID of await this.deps.users()) {
+        if (!this.running) break
+        await this.reconcile(userID)
+      }
+    } catch (cause) {
+      console.error(`[hub] concierge supervisor pass failed: ${errorText(cause)}`)
+    } finally {
+      if (this.running) this.timer = this.timers.set(() => void (this.running ? this.tick() : undefined), this.deps.tickMs ?? SUPERVISOR_TICK_MS)
+    }
+  }
+
+  /** One pass for the user (serialized per user in this process). Never rejects. */
+  reconcile(userID: string): Promise<void> {
+    const previous = this.chains.get(userID) ?? Promise.resolve()
+    const run = previous.then(() => this.pass(userID)).catch((cause) => console.error(`[hub] concierge pass failed: ${errorText(cause)}`))
+    this.chains.set(userID, run)
+    void run.finally(() => {
+      if (this.chains.get(userID) === run) this.chains.delete(userID)
+    })
+    return run
+  }
+
+  // ---- writes ----
+
+  private async write(userID: string, snap: RecordSnapshot, next: ConciergeRecord): Promise<boolean> {
+    const ok = await this.store.cas(userID, snap, next)
+    if (ok) this.changed(userID, snap.record, next)
+    return ok
+  }
+
+  private changed(userID: string, before: ConciergeRecord, after: ConciergeRecord): void {
+    const status = statusOf(after)
+    if (JSON.stringify(statusOf(before)) === JSON.stringify(status)) return
+    try {
+      this.deps.onStatus?.(userID, status)
+    } catch (cause) {
+      console.error(`[hub] concierge status listener failed: ${errorText(cause)}`)
+    }
+  }
+
+  private async audit(userID: string, action: string): Promise<void> {
+    await this.deps.audit?.(userID, action).catch((cause) => console.error(`[hub] concierge audit failed: ${errorText(cause)}`))
+  }
+
+  /** A change through update() with the status listener. */
+  private async mutate(userID: string, change: (r: ConciergeRecord) => ConciergeRecord): Promise<ConciergeRecord> {
+    let before = DEFAULT_RECORD
+    const after = await this.store.update(userID, (r) => ((before = r), change(r)))
+    this.changed(userID, before, after)
+    return after
+  }
+
+  // ---- the pass ----
+
+  private async pass(userID: string): Promise<void> {
+    const settings = await this.deps.settings.get(userID)
+    const snap = await this.store.read(userID)
+    const r = snap.record
+    if (!settings.enabled) {
+      // Disabled settings with a record that never got there (a crash between the two writes, or a disable left
+      // stopping): finish the disable. failed stays failed (the user retries).
+      if (r.state !== "disabled" && r.state !== "failed") await this.disable(userID)
+      else await this.releaseHolders(userID)
+      // A launch accepted while disabling (a racing or deposed pass) is stopped.
+      await this.reap(userID)
+      return
+    }
+    if (r.state === "failed") return
+    if (r.state === "disabled" || r.state === "stopping") {
+      // Enabled, but the record never left disabled (a crash between the two writes): start fresh.
+      await this.write(userID, snap, { ...r, state: "starting", reason: "Starting", since: this.now(), fresh: true })
+      return this.pass(userID)
+    }
+    if (r.launchID !== undefined) await this.follow(userID, settings, snap)
+    else if (r.pendingSeq !== undefined) await this.accept(userID, settings, r.pendingSeq)
+    else if (!(r.state === "backoff" && (r.nextAttemptAt ?? 0) > this.now())) await this.begin(userID, settings, snap)
+    await this.reap(userID)
+  }
+
+  /** A new launch attempt (see the header). */
+  private async begin(userID: string, settings: ConciergeSettings, snap: RecordSnapshot): Promise<void> {
+    const r = snap.record
+    const t = this.now()
+    const since = (state: string) => (r.state === state ? r.since : t)
+    const entitled = await this.deps.entitlements.check(userID)
+    if (!entitled.ok) {
+      await this.write(userID, snap, { ...r, state: "failed", reason: entitled.reason, since: t, nextAttemptAt: undefined })
+      return
+    }
+    if (settings.machineID === undefined || settings.directory === undefined) {
+      await this.write(userID, snap, { ...r, state: "failed", reason: "Pick a machine and a directory in Settings → Concierge", since: t, nextAttemptAt: undefined })
+      return
+    }
+    const machine = this.deps.eligibility(userID, settings.machineID)
+    if (!machine.eligible) {
+      const reason = machine.reason ?? "Waiting for the machine"
+      if (r.state !== "waiting_machine" || r.reason !== reason || r.machineID !== settings.machineID) {
+        await this.write(userID, snap, { ...r, state: "waiting_machine", reason, machineID: settings.machineID, since: since("waiting_machine"), nextAttemptAt: undefined })
+      }
+      return
+    }
+    const relaunch = r.fresh !== true
+    const recent = r.attempts.filter((at) => t - at < HOUR_MS)
+    if (relaunch && recent.length >= CONCIERGE_LIMITS.relaunchesPerHour) return this.fail(userID, snap, recent.length)
+    const seq = r.launchSeq + 1
+    const next: ConciergeRecord = {
+      ...r,
+      state: "starting",
+      reason: "Starting",
+      since: since("starting"),
+      machineID: settings.machineID,
+      launchSeq: seq,
+      pendingSeq: seq,
+      attempts: relaunch ? [...recent, t] : recent,
+      fresh: undefined,
+      nextAttemptAt: undefined,
+      settingsRevision: settings.revision,
+    }
+    if (!(await this.write(userID, snap, next))) return
+    await this.audit(userID, relaunch ? "concierge.relaunch" : "concierge.launch")
+    await this.accept(userID, settings, seq)
+  }
+
+  /** Accepts launch attempt `seq` (idempotent per key) and records its ID. */
+  private async accept(userID: string, settings: ConciergeSettings, seq: number): Promise<void> {
+    let launch: Launch
+    try {
+      const accepted = await this.deps.launches.accept(userID, conciergeLaunchSpec(userID, settings, seq), { by: CONCIERGE_PARTY })
+      launch = accepted.launch
+      if (accepted.created) this.deps.entitlements.record(userID, { kind: "launch", n: 1 })
+    } catch (cause) {
+      const snap = await this.store.read(userID)
+      if (snap.record.pendingSeq !== seq) return
+      await this.write(userID, snap, this.backoff(snap.record, `The launch was refused: ${errorText(cause)}`))
+      return
+    }
+    const snap = await this.store.read(userID)
+    if (snap.record.pendingSeq !== seq || snap.record.launchID !== undefined) return
+    if (!(await this.write(userID, snap, { ...snap.record, launchID: launch.id, pendingSeq: undefined }))) return
+    await this.follow(userID, settings, await this.store.read(userID))
+  }
+
+  /** The recorded launch: running → adopt it; ended → back off; else wait (starting says why it waits, FX-02). */
+  private async follow(userID: string, settings: ConciergeSettings, snap: RecordSnapshot): Promise<void> {
+    const launch = await this.deps.launches.view(userID, snap.record.launchID!)
+    if (!launch || launch.state === "ended") return this.ended(userID, snap, launch)
+    if (launch.state === "running" && launch.sessionID !== undefined) return this.adopt(userID, snap, launch.sessionID, launch.machineID)
+    if (snap.record.state === "starting") {
+      const reason = launch.state === "queued" && launch.waiting ? waitingText(launch.waiting.reason) : "Starting"
+      if (snap.record.reason !== reason) {
+        if (!(await this.write(userID, snap, { ...snap.record, reason }))) return
+        snap = await this.store.read(userID)
+      }
+    }
+    const r = snap.record
+    if (launch.sessionID !== undefined && !r.hiddenSessionIDs.includes(launch.sessionID)) {
+      // Hidden from the console's lists as soon as the session exists, and never auto-named from its title.
+      if (await this.write(userID, snap, { ...r, hiddenSessionIDs: addHidden(r.hiddenSessionIDs, launch.sessionID) })) await this.unname(userID, [launch.sessionID])
+    }
+    void settings
+  }
+
+  private async holds(userID: string, sessionID: string): Promise<boolean> {
+    try {
+      return this.deps.directory.resolve(userID, `@@${CONCIERGE_ROLE}`).sessions.some((s) => s.sessionID === sessionID)
+    } catch {
+      return false
+    }
+  }
+
+  /** Releases @@concierge from every holder but `keep` (idempotent). */
+  private async releaseHolders(userID: string, keep?: string): Promise<void> {
+    let holders: string[]
+    try {
+      holders = this.deps.directory.resolve(userID, `@@${CONCIERGE_ROLE}`).sessions.map((s) => s.sessionID)
+    } catch {
+      return
+    }
+    for (const id of holders) {
+      if (id === keep) continue
+      await this.deps.directory.releaseRole(userID, id, CONCIERGE_ROLE, undefined, { managed: true }).catch((cause) => {
+        if (!ignorable(cause)) throw cause
+      })
+    }
+  }
+
+  /** Drops (and stops deriving) the @names of Concierge sessions. */
+  private async unname(userID: string, sessionIDs: readonly string[]): Promise<void> {
+    await this.deps.directory.unname?.(userID, sessionIDs).catch((cause) => console.error(`[hub] concierge unname failed: ${errorText(cause)}`))
+  }
+
+  /** Retires previous Concierge sessions (see SupervisorDeps.context.retire). */
+  private async retire(userID: string, sessionIDs: readonly (string | undefined)[]): Promise<void> {
+    for (const id of new Set(sessionIDs)) {
+      if (id === undefined) continue
+      await this.deps.context.retire?.(userID, id).catch((cause) => console.error(`[hub] concierge retire failed: ${errorText(cause)}`))
+    }
+  }
+
+  private async release(userID: string, sessionID: string | undefined): Promise<void> {
+    if (sessionID === undefined) return
+    await this.deps.directory.releaseRole(userID, sessionID, CONCIERGE_ROLE, undefined, { managed: true }).catch((cause) => {
+      if (!ignorable(cause)) console.error(`[hub] concierge role release failed: ${errorText(cause)}`)
+    })
+  }
+
+  /** The launch runs: the session becomes the current Concierge (role, hidden, context). */
+  private async adopt(userID: string, snap: RecordSnapshot, sessionID: string, machineID: string | undefined): Promise<void> {
+    const r = snap.record
+    if (r.state === "running" && r.sessionID === sessionID) {
+      if (await this.holds(userID, sessionID)) return
+      // The role dropped (offline past ROLE_OFFLINE_MS): claim it again (a new generation).
+    }
+    let generation: number
+    try {
+      await this.releaseHolders(userID, sessionID)
+      generation = (await this.deps.directory.claimRole(userID, sessionID, CONCIERGE_ROLE, { byUser: true, exclusive: true, managed: true })).generation
+    } catch (cause) {
+      const reason = `Waiting for the session: ${errorText(cause)}`
+      if (r.reason !== reason) await this.write(userID, snap, { ...r, reason })
+      return
+    }
+    const t = this.now()
+    const same = r.state === "running" && r.sessionID === sessionID
+    const next: ConciergeRecord = {
+      ...r,
+      state: "running",
+      reason: undefined,
+      sessionID,
+      ...(machineID !== undefined ? { machineID } : {}),
+      generation,
+      since: same ? r.since : t,
+      runningSince: same ? r.runningSince : t,
+      hiddenSessionIDs: addHidden(r.hiddenSessionIDs, sessionID),
+    }
+    if (!(await this.write(userID, snap, next))) return
+    if (same) return
+    // The current and every past Concierge session: no @name (an auto name derived from a title, e.g. @greeting).
+    await this.unname(userID, [...new Set([...(r.pastSessionIDs ?? []), ...next.hiddenSessionIDs])])
+    await this.deps.onAdopted?.(userID, sessionID).catch((cause) => console.error(`[hub] concierge detach failed: ${errorText(cause)}`))
+    await this.deps.context.push(userID, sessionID).catch((cause) => console.error(`[hub] concierge context push failed: ${errorText(cause)}`))
+    // Every earlier Concierge session a spoke may still run (a lost race, a restart, a relaunch) is retired.
+    await this.retire(userID, next.hiddenSessionIDs.filter((id) => id !== sessionID))
+  }
+
+  /** The backoff record after a failed or ended launch. */
+  private backoff(r: ConciergeRecord, reason: string): ConciergeRecord {
+    const t = this.now()
+    const healthy = r.runningSince !== undefined && t - r.runningSince >= CONCIERGE_LIMITS.healthyAfterMs
+    const index = healthy ? 0 : r.backoffIndex
+    const delays = CONCIERGE_LIMITS.relaunchBackoffMs
+    const delay = delays[Math.min(index, delays.length - 1)]!
+    return {
+      ...r,
+      state: "backoff",
+      reason,
+      since: t,
+      launchID: undefined,
+      pendingSeq: undefined,
+      lastLaunchID: r.launchID ?? r.lastLaunchID,
+      sessionID: undefined,
+      runningSince: undefined,
+      nextAttemptAt: t + delay,
+      backoffIndex: index + 1,
+    }
+  }
+
+  private async fail(userID: string, snap: RecordSnapshot, relaunches: number): Promise<void> {
+    const r = snap.record
+    await this.write(userID, snap, {
+      ...r,
+      state: "failed",
+      reason: `Relaunched ${relaunches} times in the last hour: Restart it in Settings → Concierge`,
+      since: this.now(),
+      launchID: undefined,
+      pendingSeq: undefined,
+      lastLaunchID: r.launchID ?? r.lastLaunchID,
+      sessionID: undefined,
+      runningSince: undefined,
+      nextAttemptAt: undefined,
+    })
+  }
+
+  /** The launch ended for any reason but a service stop (those clear launchID first): relaunch with backoff. */
+  private async ended(userID: string, snap: RecordSnapshot, launch: Launch | undefined): Promise<void> {
+    const r = snap.record
+    const t = this.now()
+    const recent = r.attempts.filter((at) => t - at < HOUR_MS)
+    const ok = recent.length >= CONCIERGE_LIMITS.relaunchesPerHour ? (await this.fail(userID, snap, recent.length), true) : await this.write(userID, snap, this.backoff(r, `The Concierge session ended (${launch?.outcome ?? "gone"}); relaunching`))
+    if (ok) {
+      await this.release(userID, r.sessionID)
+      await this.retire(userID, [r.sessionID])
+    }
+  }
+
+  /** Stops live Concierge launches other than the recorded one (orphans). */
+  private async reap(userID: string): Promise<void> {
+    if (!this.deps.launches.list) return
+    const r = await this.store.get(userID)
+    const live = await this.deps.launches.list(userID, { states: ["queued", "placing", "provisioning", "running"] })
+    const disabled = r.state === "disabled" || r.state === "failed"
+    for (const launch of live) {
+      if (!isConciergeLaunch(launch)) continue
+      if (!disabled && launch.id === r.launchID) continue
+      if (!disabled && r.pendingSeq !== undefined && launch.spec.key === conciergeLaunchKey(userID, r.pendingSeq)) continue
+      await this.deps.launches.stop(userID, launch.id, "Not the current Concierge").catch((cause) => {
+        if (!ignorable(cause)) console.error(`[hub] concierge orphan stop failed: ${errorText(cause)}`)
+      })
+    }
+  }
+
+  // ---- user operations (the service calls them) ----
+
+  /**
+   * Disable, after the settings say disabled: stopping, then revoke the grant, stop the launch(es), release
+   * @@concierge, clear the context; then disabled. Each step is idempotent; a failed one leaves failed with a
+   * reason (retry by disabling again). Notes and watchlist are kept.
+   */
+  async disable(userID: string): Promise<ConciergeStatus> {
+    const before = await this.store.get(userID)
+    if (before.state === "disabled") {
+      await this.releaseHolders(userID).catch(() => undefined)
+      return statusOf(before)
+    }
+    const stopping = await this.mutate(userID, (r) => ({ ...r, state: "stopping", reason: "Stopping", since: this.now(), nextAttemptAt: undefined }))
+    const problems: string[] = []
+    const step = async (fn: () => Promise<unknown>) => {
+      try {
+        await fn()
+      } catch (cause) {
+        if (!ignorable(cause)) problems.push(errorText(cause))
+      }
+    }
+    await step(async () => {
+      const settings = await this.deps.settings.get(userID)
+      if (settings.grantID === undefined) return
+      await this.deps.grants.revoke(userID, settings.grantID).catch((cause) => {
+        if (!ignorable(cause)) throw cause
+      })
+      await this.deps.settings.update(userID, (s) => {
+        const { grantID: _gone, ...rest } = s
+        return rest
+      })
+    })
+    await step(async () => {
+      if (stopping.launchID !== undefined) await this.deps.launches.stop(userID, stopping.launchID, "The Concierge was disabled").catch((cause) => {
+        if (!ignorable(cause)) throw cause
+      })
+      if (!this.deps.launches.list) return
+      for (const launch of await this.deps.launches.list(userID, { states: ["queued", "placing", "provisioning", "running"] })) {
+        if (!isConciergeLaunch(launch)) continue
+        await this.deps.launches.stop(userID, launch.id, "The Concierge was disabled").catch((cause) => {
+          if (!ignorable(cause)) throw cause
+        })
+      }
+    })
+    await step(() => this.releaseHolders(userID))
+    if (stopping.sessionID !== undefined) await this.deps.context.clear(userID, stopping.sessionID).catch(() => undefined)
+    const t = this.now()
+    const done = await this.mutate(userID, (r) =>
+      problems.length
+        ? { ...r, state: "failed", reason: `Disable did not finish: ${problems[0]}; disable again`, since: t }
+        : {
+            ...r,
+            state: "disabled",
+            reason: undefined,
+            since: t,
+            sessionID: undefined,
+            launchID: undefined,
+            pendingSeq: undefined,
+            lastLaunchID: r.launchID ?? r.lastLaunchID,
+            nextAttemptAt: undefined,
+            runningSince: undefined,
+            attempts: [],
+            backoffIndex: 0,
+            fresh: undefined,
+            hiddenSessionIDs: r.sessionID !== undefined ? addHidden(r.hiddenSessionIDs, r.sessionID) : r.hiddenSessionIDs,
+          },
+    )
+    if (!problems.length) await this.audit(userID, "concierge.disable")
+    return statusOf(done)
+  }
+
+  /** Enable (the settings already say enabled): a fresh start. */
+  async enable(userID: string): Promise<ConciergeStatus> {
+    const next = await this.mutate(userID, (r) =>
+      r.state === "disabled" || r.state === "failed" || r.state === "stopping"
+        ? { ...r, state: "starting", reason: "Starting", since: this.now(), fresh: true, attempts: [], backoffIndex: 0, nextAttemptAt: undefined, launchID: undefined, pendingSeq: undefined, sessionID: undefined }
+        : r,
+    )
+    this.kick(userID)
+    return statusOf(next)
+  }
+
+  /**
+   * Suspends the Concierge at once (the spoke reports its session on another agent, or anything else that means the
+   * hub no longer controls it): the grant is revoked, the session loses @@concierge and the Concierge-only authority
+   * (it moves to the hidden history), its launch is stopped, and the state is failed with `reason`. Nothing relaunches
+   * it: only the user's Restart (or disable + enable). Idempotent for the same session.
+   */
+  async suspend(userID: string, sessionID: string, reason: string): Promise<ConciergeStatus> {
+    const before = await this.store.get(userID)
+    if (before.sessionID !== sessionID) return statusOf(before)
+    const t = this.now()
+    const after = await this.mutate(userID, (r) =>
+      r.sessionID !== sessionID
+        ? r
+        : {
+            ...r,
+            state: "failed",
+            reason,
+            since: t,
+            sessionID: undefined,
+            launchID: undefined,
+            pendingSeq: undefined,
+            lastLaunchID: r.launchID ?? r.lastLaunchID,
+            runningSince: undefined,
+            nextAttemptAt: undefined,
+            hiddenSessionIDs: addHidden(r.hiddenSessionIDs, sessionID),
+          },
+    )
+    const settings = await this.deps.settings.get(userID)
+    if (settings.grantID !== undefined) {
+      await this.deps.grants.revoke(userID, settings.grantID).catch((cause) => {
+        if (!ignorable(cause)) console.error(`[hub] concierge suspend: grant revoke failed: ${errorText(cause)}`)
+      })
+      await this.deps.settings.update(userID, (s) => {
+        const { grantID: _gone, ...rest } = s
+        return rest
+      })
+    }
+    await this.releaseHolders(userID).catch(() => undefined)
+    if (before.launchID !== undefined) await this.deps.launches.stop(userID, before.launchID, reason).catch(() => undefined)
+    await this.deps.context.clear(userID, sessionID).catch(() => undefined)
+    await this.audit(userID, "concierge.suspended")
+    try {
+      this.deps.onSuspended?.(userID, sessionID)
+    } catch (cause) {
+      console.error(`[hub] concierge suspend listener failed: ${errorText(cause)}`)
+    }
+    return statusOf(after)
+  }
+
+  /** Restart: ends the current launch and launches again at once (no backoff, no relaunch count). */
+  async restart(userID: string): Promise<ConciergeStatus> {
+    let old: ConciergeRecord = DEFAULT_RECORD
+    const next = await this.mutate(userID, (r) => {
+      old = r
+      return {
+        ...r,
+        state: "starting",
+        reason: "Restarting",
+        since: this.now(),
+        launchID: undefined,
+        pendingSeq: undefined,
+        lastLaunchID: r.launchID ?? r.lastLaunchID,
+        sessionID: undefined,
+        runningSince: undefined,
+        nextAttemptAt: undefined,
+        backoffIndex: 0,
+        attempts: [],
+        fresh: true,
+        hiddenSessionIDs: r.sessionID !== undefined ? addHidden(r.hiddenSessionIDs, r.sessionID) : r.hiddenSessionIDs,
+      }
+    })
+    if (old.launchID !== undefined) {
+      await this.deps.launches.stop(userID, old.launchID, "The Concierge restarted").catch((cause) => {
+        if (!ignorable(cause)) console.error(`[hub] concierge restart stop failed: ${errorText(cause)}`)
+      })
+    }
+    await this.release(userID, old.sessionID)
+    await this.retire(userID, [old.sessionID])
+    await this.audit(userID, "concierge.restart")
+    this.kick(userID)
+    return statusOf(next)
+  }
+}