@huynle/hub 0.7.4 → 0.8.1

package/src/central/concierge/schedule.ts

@@ -0,0 +1,113 @@
+// CON-05 schedule (contract: "Event-driven turns, digests, quiet hours (CON-05)"): wall-clock time in IANA zones for
+// the Concierge's quiet hours (their own `timeZone`) and digests (`settings.timeZone`). Pure; Intl only.
+//
+// - An invalid or unknown zone (settings validate zones, but the runtime's zone data can change) is UTC.
+// - A wall time in a spring-forward gap (02:30 on the night clocks jump 02:00 → 03:00) moves forward by the gap
+//   (03:30), as cron and Temporal's "compatible" do; one in a fall-back overlap is its first occurrence.
+// - A digest is due from its minute for DIGEST_GRACE_MS (the leader ticks every 30 s; a failover or an enable after
+//   the minute does not send it late), keyed `digest:<local date>:<entry index>`: the notifier's ledger sends each
+//   key once, so a fall-back day that repeats the minute still sends it once.
+import type { ConciergeDigest, ConciergeQuietHours } from "../../../packages/protocol/src/concierge"
+
+const MIN = 60_000
+const DAY = 86_400_000
+/** How long after its minute a digest may still go out. */
+export const DIGEST_GRACE_MS = 60 * MIN
+
+export interface LocalTime {
+  /** YYYY-MM-DD in the zone. */
+  readonly date: string
+  /** Minutes since local midnight (0–1439). */
+  readonly minutes: number
+  /** 0 = Sunday … 6 = Saturday. */
+  readonly weekday: number
+}
+
+export interface DueDigest {
+  readonly key: string
+  readonly index: number
+  /** The entry's HH:MM. */
+  readonly label: string
+  readonly occurredAt: number
+}
+
+const formats = new Map<string, Intl.DateTimeFormat>()
+const FORMATS_MAX = 200
+
+function format(zone: string): Intl.DateTimeFormat | undefined {
+  let f = formats.get(zone)
+  if (f) return f
+  try {
+    f = new Intl.DateTimeFormat("en-US", { timeZone: zone, year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hourCycle: "h23" })
+  } catch {
+    return undefined
+  }
+  if (formats.size >= FORMATS_MAX) formats.delete(formats.keys().next().value as string)
+  formats.set(zone, f)
+  return f
+}
+
+/** The zone, or UTC when it is not a zone this runtime knows. */
+export function zoneOrUTC(zone: string): string {
+  return typeof zone === "string" && zone.length > 0 && zone.length <= 64 && format(zone) ? zone : "UTC"
+}
+
+/** The wall-clock fields at `at` in `zone`, as a UTC timestamp of the same fields (minute resolution). */
+function wall(at: number, zone: string): number {
+  const parts: Record<string, number> = {}
+  for (const p of format(zone)!.formatToParts(at)) if (p.type !== "literal") parts[p.type] = Number(p.value)
+  return Date.UTC(parts.year!, parts.month! - 1, parts.day!, parts.hour! % 24, parts.minute!)
+}
+
+const pad = (n: number) => String(n).padStart(2, "0")
+const dateOf = (utcFields: number) => {
+  const d = new Date(utcFields)
+  return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`
+}
+
+export function localTime(at: number, zone: string): LocalTime {
+  const fields = wall(at, zoneOrUTC(zone))
+  const d = new Date(fields)
+  return { date: dateOf(fields), minutes: d.getUTCHours() * 60 + d.getUTCMinutes(), weekday: d.getUTCDay() }
+}
+
+const clockMinutes = (hhmm: string) => Number(hhmm.slice(0, 2)) * 60 + Number(hhmm.slice(3, 5))
+
+/** The instant of wall time `minutes` on local `date` (YYYY-MM-DD) in `zone` (gaps forward, overlaps first). */
+export function zonedInstant(date: string, minutes: number, zone: string): number {
+  const z = zoneOrUTC(zone)
+  const [y, m, d] = date.split("-").map(Number) as [number, number, number]
+  const target = Date.UTC(y, m - 1, d, 0, minutes)
+  const offset = (t: number) => wall(t, z) - Math.floor(t / MIN) * MIN
+  // The offsets a day either side: at most one transition lies between them.
+  const candidates = [...new Set([target - offset(target - DAY), target - offset(target + DAY)])]
+  const valid = candidates.filter((t) => wall(t, z) === target)
+  return valid.length ? Math.min(...valid) : Math.max(...candidates)
+}
+
+/** The digests due at `at` (from their minute, for `graceMs`), oldest local date first per entry. */
+export function dueDigests(digests: readonly ConciergeDigest[], zone: string, at: number, graceMs: number = DIGEST_GRACE_MS): DueDigest[] {
+  const z = zoneOrUTC(zone)
+  const dates = [...new Set([localTime(at - graceMs, z).date, localTime(at, z).date])]
+  const out: DueDigest[] = []
+  digests.forEach((digest, index) => {
+    for (const date of dates) {
+      const [y, m, d] = date.split("-").map(Number) as [number, number, number]
+      const weekday = new Date(Date.UTC(y, m - 1, d)).getUTCDay() as 0 | 1 | 2 | 3 | 4 | 5 | 6
+      if (digest.days && !digest.days.includes(weekday)) continue
+      const occurredAt = zonedInstant(date, clockMinutes(digest.at), z)
+      if (occurredAt <= at && at < occurredAt + graceMs) out.push({ key: `digest:${date}:${index}`, index, label: digest.at, occurredAt })
+    }
+  })
+  return out
+}
+
+/** Whether `at` falls in the quiet hours (start inclusive, end exclusive; across midnight when start > end). */
+export function inQuietHours(quiet: ConciergeQuietHours | undefined, at: number): boolean {
+  if (!quiet) return false
+  const start = clockMinutes(quiet.start)
+  const end = clockMinutes(quiet.end)
+  if (start === end) return false
+  const { minutes } = localTime(at, quiet.timeZone)
+  return start < end ? minutes >= start && minutes < end : minutes >= start || minutes < end
+}

package/src/central/concierge/service.ts

@@ -0,0 +1,243 @@
+// CON-04 the Concierge service (contract "Concierge service: settings, launch, supervise, hide, context"): what the
+// Settings routes do, on top of the settings and notes records, the supervisor (state record, launch, relaunch,
+// disable) and the grant. Users only (routes.ts); every operation is keyed by the user (the tenant).
+//
+// - Machine eligibility (eligibilityOf, pure): one of the user's machines with a hub node (host runtime with OpenCode,
+//   workspace roots, not draining) and a connected OpenCode service spoke announcing `launch` and `sessionContext`.
+//   Each "no" has a reason Settings shows. An offline machine is not eligible now but may be enabled: the state is
+//   waiting_machine until it is back.
+// - Enable: entitlements.check (403 with its reason), machineID and directory required (400), the machine must be
+//   the user's (404 otherwise, like anything of another user), an online machine must qualify and the directory be
+//   under its node's workspace roots (422 unsupported {feature: "conciergeMachine", reason}). Then the grant (when
+//   settings.grant: Grants.create/update, holder @@concierge), the settings (enabled, version-checked), and the
+//   supervisor starts it. A grant created for a refused enable is revoked again.
+// - A settings change that picks a machine that is not the user's (unknown or another user's, alike): 404 (CON-09b).
+// - A settings change while enabled: a new or removed grant applies at once (update restarts its expiry: Renew);
+//   another machine, directory or model restarts the Concierge.
+// - Disable: settings first (enabled false, version-checked), then the supervisor's idempotent steps.
+import type { ConciergeSettings, ConciergeStatus } from "../../../packages/protocol/src/concierge"
+import type { NodeRuntimeInfo } from "../../protocol"
+import { AgentError } from "../agent/errors"
+import type { Grants } from "../agent/grants"
+import type { ConciergeEntitlements } from "./entitlements"
+import type { ConciergeNotes, NotesStore } from "./notes"
+import { grantInput, parseSettingsPatch, type SettingsStore, validTimeZone } from "./settings"
+import type { Eligibility, Supervisor } from "./supervisor"
+
+/** What the hub knows about one of the user's machines (http.ts gathers it from the store, nodes and registry). */
+export interface MachineFacts {
+  readonly id: string
+  readonly name: string
+  /** A process of the machine is connected (spoke or node). */
+  readonly online: boolean
+  readonly node?: { readonly runtimes: readonly NodeRuntimeInfo[]; readonly workspaceRoots: readonly string[]; readonly draining: boolean }
+  /** The machine's OpenCode service spoke and what it announces. */
+  readonly service?: { readonly launch: boolean; readonly sessionContext: boolean }
+}
+
+export interface MachineView extends Eligibility {
+  readonly id: string
+  readonly name: string
+  /** The node's workspace roots (the directory picker's start points). */
+  readonly roots: readonly string[]
+}
+
+/** Whether a machine can host the Concierge now, and why not. */
+export function eligibilityOf(facts: Omit<MachineFacts, "id" | "name">): Eligibility {
+  const no = (reason: string): Eligibility => ({ eligible: false, online: facts.online, reason })
+  if (!facts.node && !facts.online) return no("Offline")
+  if (!facts.node) return no("No hub node runs on it: start `hub node` there with a workspace root")
+  if (facts.node.draining) return no("Its hub node is draining")
+  if (!facts.node.runtimes.some((r) => r.kind === "host" && r.harnesses?.includes("opencode"))) return no("Its hub node has no host runtime with OpenCode")
+  if (!facts.node.workspaceRoots.length) return no("Its hub node has no workspace roots")
+  if (!facts.service) return no("No OpenCode service runs on it (the hub plugin's background service)")
+  if (!facts.service.launch) return no("Its OpenCode plugin cannot launch sessions: update the hub plugin")
+  if (!facts.service.sessionContext) return no("Its OpenCode plugin is too old for the Concierge: update the hub plugin")
+  return { eligible: true, online: true }
+}
+
+const underRoot = (dir: string, root: string) => {
+  const base = root.replace(/\/+$/, "")
+  return dir === base || dir.startsWith(`${base}/`)
+}
+
+export interface ConciergeView {
+  readonly settings: ConciergeSettings
+  readonly status: ConciergeStatus
+  readonly machines: readonly MachineView[]
+}
+
+export interface ServiceDeps {
+  readonly settings: SettingsStore
+  readonly notes: NotesStore
+  readonly supervisor: Supervisor
+  readonly grants: Pick<Grants, "create" | "update" | "revoke">
+  /** The user's machines (not revoked) with their facts. */
+  readonly machines: (userID: string) => readonly MachineFacts[]
+  readonly entitlements: ConciergeEntitlements
+  /** The admin audit: {actor: owner, action: concierge.*} only. */
+  readonly audit: (userID: string, action: string) => Promise<void>
+  /**
+   * Makes buffered state writes durable (StateStore.flush; a write-through store has none). Awaited before every
+   * security-relevant answer (settings, enable, disable, restart): a 200 is never lost to a crash.
+   */
+  readonly flush?: () => Promise<void>
+}
+
+const ignorable = (cause: unknown) => cause instanceof AgentError && (cause.code === "gone" || cause.code === "not_found")
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+function revisionOf(body: unknown, allowed: readonly string[] = []): number {
+  if (!isObject(body)) throw new AgentError("invalid", "The body is {expectedRevision}")
+  for (const key of Object.keys(body)) if (key !== "expectedRevision" && !allowed.includes(key)) throw new AgentError("invalid", `Unknown field ${key.slice(0, 40)}`)
+  if (!Number.isSafeInteger(body.expectedRevision)) throw new AgentError("invalid", "expectedRevision is required")
+  return body.expectedRevision as number
+}
+
+const checkRevision = (settings: ConciergeSettings, expected: number) => {
+  if (settings.revision !== expected) throw new AgentError("conflict", "The Concierge settings changed meanwhile", { extra: { currentRevision: settings.revision } })
+}
+
+export class ConciergeService {
+  constructor(private readonly deps: ServiceDeps) {}
+
+  get supervisor(): Supervisor {
+    return this.deps.supervisor
+  }
+
+  /** The user's machines with their eligibility. */
+  machineViews(userID: string): MachineView[] {
+    return this.deps.machines(userID).map((m) => ({ id: m.id, name: m.name, ...eligibilityOf(m), roots: m.node ? [...m.node.workspaceRoots] : [] }))
+  }
+
+  /** The supervisor's eligibility port. */
+  eligibility(userID: string, machineID: string): Eligibility {
+    const facts = this.deps.machines(userID).find((m) => m.id === machineID)
+    return facts ? eligibilityOf(facts) : { eligible: false, online: false, reason: "Not one of your machines" }
+  }
+
+  async view(userID: string): Promise<ConciergeView> {
+    const [settings, status] = await Promise.all([this.deps.settings.get(userID), this.deps.supervisor.status(userID)])
+    return { settings, status, machines: this.machineViews(userID) }
+  }
+
+  /** Refuses a machine or directory that cannot host the Concierge (an offline machine is fine). */
+  private checkPlacement(userID: string, settings: ConciergeSettings): void {
+    if (settings.machineID === undefined || settings.directory === undefined) throw new AgentError("invalid", "Pick a machine and a directory (a git repo on it) first")
+    const facts = this.deps.machines(userID).find((m) => m.id === settings.machineID)
+    if (!facts) throw new AgentError("not_found", "No such machine")
+    const unsupported = (reason: string) => new AgentError("unsupported", `This machine cannot host the Concierge: ${reason}`, { extra: { feature: "conciergeMachine", reason } })
+    const verdict = eligibilityOf(facts)
+    if (!verdict.eligible && verdict.online) throw unsupported(verdict.reason ?? "not eligible")
+    if (facts.node && !facts.node.workspaceRoots.some((root) => underRoot(settings.directory!, root))) throw unsupported("The directory is not under the machine's workspace roots")
+  }
+
+  /** Creates, renews or revokes the @@concierge grant for the settings; the grant ID (undefined: none). */
+  private async applyGrant(userID: string, settings: ConciergeSettings): Promise<string | undefined> {
+    if (!settings.grant) {
+      if (settings.grantID !== undefined) await this.deps.grants.revoke(userID, settings.grantID).catch((cause) => (ignorable(cause) ? undefined : Promise.reject(cause)))
+      return undefined
+    }
+    if (settings.grantID !== undefined) {
+      try {
+        await this.deps.grants.update(userID, settings.grantID, grantInput(settings.grant), { managed: true })
+        return settings.grantID
+      } catch (cause) {
+        if (!ignorable(cause)) throw cause
+      }
+    }
+    return (await this.deps.grants.create(userID, grantInput(settings.grant), { managed: true })).id
+  }
+
+  private async withGrantID(userID: string, expected: number, grantID: string | undefined, change: (s: ConciergeSettings) => ConciergeSettings): Promise<ConciergeSettings> {
+    return this.deps.settings.update(userID, (current) => {
+      checkRevision(current, expected)
+      const next = change(current)
+      const { grantID: _old, ...rest } = next
+      return grantID !== undefined ? { ...rest, grantID } : rest
+    })
+  }
+
+  async updateSettings(userID: string, body: unknown): Promise<{ settings: ConciergeSettings; status: ConciergeStatus }> {
+    const current = await this.deps.settings.get(userID)
+    const next = parseSettingsPatch(body, current)
+    // CON-09b: a machine that is not the user's is refused when it is saved, not only at enable. An unknown ID and
+    // another user's answer alike (no oracle). A machine saved earlier and removed since is only checked at enable.
+    if (next.machineID !== undefined && next.machineID !== current.machineID && !this.deps.machines(userID).some((m) => m.id === next.machineID)) {
+      throw new AgentError("not_found", "That machine is not one of yours: pick one of your machines")
+    }
+    const placementChanged = next.machineID !== current.machineID || next.directory !== current.directory || next.model !== current.model
+    if (current.enabled && placementChanged) this.checkPlacement(userID, next)
+    const grantTouched = isObject(body) && "grant" in body
+    const grantID = current.enabled && grantTouched ? await this.applyGrant(userID, next) : current.grantID
+    const settings = await this.withGrantID(userID, current.revision, grantID, () => next)
+    await this.deps.audit(userID, "concierge.settings")
+    const status = current.enabled && placementChanged ? await this.deps.supervisor.restart(userID) : await this.deps.supervisor.status(userID)
+    await this.durable()
+    return { settings, status }
+  }
+
+  async enable(userID: string, body: unknown): Promise<{ settings: ConciergeSettings; status: ConciergeStatus }> {
+    const expected = revisionOf(body, ["timeZone"])
+    const timeZone = (body as { timeZone?: unknown }).timeZone
+    if (timeZone !== undefined && !validTimeZone(timeZone)) throw new AgentError("invalid", "timeZone is an IANA time zone")
+    const entitled = await this.deps.entitlements.check(userID)
+    if (!entitled.ok) throw new AgentError("forbidden", entitled.reason)
+    const current = await this.deps.settings.get(userID)
+    checkRevision(current, expected)
+    this.checkPlacement(userID, current)
+    const grantID = await this.applyGrant(userID, current)
+    let settings: ConciergeSettings
+    try {
+      settings = await this.withGrantID(userID, expected, grantID, (s) => ({ ...s, enabled: true, ...(typeof timeZone === "string" && s.updatedAt === undefined ? { timeZone } : {}) }))
+    } catch (cause) {
+      if (grantID !== undefined && grantID !== current.grantID) await this.deps.grants.revoke(userID, grantID).catch(() => undefined)
+      throw cause
+    }
+    await this.deps.audit(userID, "concierge.enable")
+    const status = await this.deps.supervisor.enable(userID)
+    await this.durable()
+    return { settings, status }
+  }
+
+  async disable(userID: string, body: unknown): Promise<{ settings: ConciergeSettings; status: ConciergeStatus }> {
+    const expected = revisionOf(body)
+    const current = await this.deps.settings.get(userID)
+    checkRevision(current, expected)
+    if (current.enabled) await this.withGrantID(userID, expected, current.grantID, (s) => ({ ...s, enabled: false }))
+    const status = await this.deps.supervisor.disable(userID)
+    await this.durable()
+    return { settings: await this.deps.settings.get(userID), status }
+  }
+
+  async restart(userID: string): Promise<{ status: ConciergeStatus }> {
+    const settings = await this.deps.settings.get(userID)
+    if (!settings.enabled) throw new AgentError("conflict", "The Concierge is disabled: enable it first")
+    const entitled = await this.deps.entitlements.check(userID)
+    if (!entitled.ok) throw new AgentError("forbidden", entitled.reason)
+    // A suspended Concierge lost its grant: the user's Restart grants it again (the standing setting).
+    if (settings.grant && settings.grantID === undefined) {
+      const grantID = await this.applyGrant(userID, settings)
+      if (grantID !== undefined) await this.deps.settings.update(userID, (s) => ({ ...s, grantID }))
+    }
+    const status = await this.deps.supervisor.restart(userID)
+    await this.durable()
+    return { status }
+  }
+
+  /** Flushes the state store (see ServiceDeps.flush). */
+  private async durable(): Promise<void> {
+    await this.deps.flush?.()
+  }
+
+  notes(userID: string): Promise<ConciergeNotes> {
+    return this.deps.notes.get(userID)
+  }
+
+  async setNotes(userID: string, body: unknown): Promise<ConciergeNotes> {
+    const expected = revisionOf(body, ["text"])
+    const text = (body as { text?: unknown }).text
+    if (typeof text !== "string") throw new AgentError("invalid", "text is required (a string, at most 32 KiB)")
+    return this.deps.notes.put(userID, text, expected)
+  }
+}

package/src/central/concierge/session-routes.ts

@@ -0,0 +1,125 @@
+// CON-04 the routes a Concierge session may call (round-3 verify): its session tokens (act AND shell, the current
+// session and every previous one) reach ONLY the routes listed here; every other /api/agent route answers 403
+// forbidden {policy: "concierge"} before its handler runs. The check is central (agentApi's gate), so a route added
+// later is refused until it is listed here (fail closed).
+//
+// What the list keeps: reads (who, status, sessions, its inbox and messages), messages to @me and replies/declines
+// to asks addressed to it (the outbound rule narrows msg/ask/reply/decline further, inbound.ts), the grant-gated act
+// verbs, its own notes, its board and Decision reads, and the watchlist verbs. Nothing that puts its text in front
+// of another session (intake, artifacts, workspaces, side chats, profiles, names, intents, webhooks, teams…).
+// CON-06's own routes are added through the tiers slot (ConciergeTiers.routes), which are Concierge routes by design.
+import type { AgentActor } from "../agent/actor"
+import { AgentError } from "../agent/errors"
+import type { AgentRoute } from "../agent/routes"
+import type { ConciergeIdentity } from "./watchlist-routes"
+
+const A = "/api/agent"
+const C = `${A}/concierge`
+
+export const CONCIERGE_SESSION_ROUTES: readonly { readonly method: string; readonly path: string }[] = [
+  { method: "GET", path: `${A}/whoami` },
+  { method: "GET", path: `${A}/who` },
+  { method: "GET", path: `${A}/status` },
+  { method: "GET", path: `${A}/sessions` },
+  { method: "GET", path: `${A}/sessions/:addr` },
+  { method: "POST", path: `${A}/msg` },
+  { method: "POST", path: `${A}/ask` },
+  { method: "POST", path: `${A}/reply` },
+  { method: "POST", path: `${A}/decline` },
+  { method: "GET", path: `${A}/inbox` },
+  { method: "GET", path: `${A}/messages/:id` },
+  ...["approve", "deny", "answer", "prompt", "stop"].map((verb) => ({ method: "POST", path: `${A}/sessions/:addr/${verb}` })),
+  { method: "GET", path: `${C}/notes` },
+  { method: "PUT", path: `${C}/notes` },
+  { method: "GET", path: `${C}/board` },
+  { method: "GET", path: `${C}/decisions` },
+  { method: "GET", path: `${C}/decisions/:id` },
+  { method: "GET", path: `${C}/watchlist` },
+  ...["watch", "unwatch", "mute", "unmute"].map((verb) => ({ method: "POST", path: `${C}/watchlist/${verb}` })),
+  // CON-06 (tiers.ts): proposals and arming. Proposals put no Concierge text in front of another session: free text
+  // (prompt, form answers) runs only after the user's tap.
+  { method: "POST", path: `${C}/proposals` },
+  { method: "GET", path: `${C}/arm` },
+  { method: "POST", path: `${C}/arm` },
+  // CON-13 (tiers.ts): a pending form's schema (fields, options), so its answers fit the form.
+  { method: "GET", path: `${C}/sessions/:addr/forms/:form` },
+]
+
+const key = (method: string, path: string) => `${method} ${path}`
+
+/**
+ * (FX-07) How long a Concierge identity check waits for the state store (the route gate, the acting guard, the inbound
+ * and outbound rules, team staffing): past it the check fails closed with `busy` (503).
+ */
+export const IDENTITY_TIMEOUT_MS = 5_000
+
+/** (FX-07) The refusal while the hub's state does not answer: neutral (no Concierge wording), retried by clients. */
+export const stateBusy = () => new AgentError("busy", "Hub state is busy, try again", { extra: { retryAfter: Math.ceil(IDENTITY_TIMEOUT_MS / 1000) } })
+
+/** `read`, or a `busy` rejection once `ms` passed (the timer never outlives the answer; a late answer is ignored). */
+function within<T>(read: Promise<T>, ms: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const late = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(stateBusy()), ms)
+  })
+  read.catch(() => {}) // a late rejection is not unhandled
+  return Promise.race([read, late]).finally(() => clearTimeout(timer))
+}
+
+const TIMED = Symbol("concierge.timedIdentity")
+
+/**
+ * (FX-07) The identity with a time limit on each read: past it, the read rejects `busy`. A user whose read timed out
+ * is answered `busy` at once for the next `ms` (no new store read: a stuck store is not asked again per check, so
+ * the checks of one request share one wait and reads do not pile up). Wrapping a timed identity returns it as is.
+ */
+export function timedIdentity(identity: ConciergeIdentity, ms: number = IDENTITY_TIMEOUT_MS, now: () => number = Date.now): ConciergeIdentity {
+  if ((identity as { [TIMED]?: true })[TIMED]) return identity
+  const stuckUntil = new Map<string, number>()
+  const timed = {
+    [TIMED]: true as const,
+    async current(userID: string) {
+      const until = stuckUntil.get(userID)
+      if (until !== undefined) {
+        if (now() < until) throw stateBusy()
+        stuckUntil.delete(userID)
+      }
+      try {
+        return await within(identity.current(userID), ms)
+      } catch (cause) {
+        if (cause instanceof AgentError && cause.code === "busy") stuckUntil.set(userID, now() + ms)
+        throw cause
+      }
+    },
+  }
+  return timed
+}
+
+/**
+ * The gate agentApi runs for every session actor before the route's own checks: a Concierge session (current or
+ * previous) may call only the allow-list and `extra` (the tiers slot's routes). (FX-07) An identity read that fails or
+ * has not answered within `timeoutMs` refuses every other route with a neutral 503 `busy` (fail closed, without
+ * telling an ordinary session it is the Concierge); the allow-list still passes.
+ */
+export function conciergeSessionGate(
+  identity: ConciergeIdentity,
+  extra: () => readonly AgentRoute[] = () => [],
+  options: { readonly timeoutMs?: number } = {},
+): (actor: AgentActor, route: Pick<AgentRoute, "method" | "path">) => Promise<void> {
+  const allowed = new Set(CONCIERGE_SESSION_ROUTES.map((r) => key(r.method, r.path)))
+  const timed = timedIdentity(identity, options.timeoutMs ?? IDENTITY_TIMEOUT_MS)
+  return async (actor, route) => {
+    if (actor.kind !== "session") return
+    const listed = () => allowed.has(key(route.method, route.path)) || extra().some((r) => r.method === route.method && r.path === route.path)
+    let concierge: boolean
+    try {
+      const current = await timed.current(actor.userID)
+      concierge = current.sessionID === actor.sessionID || current.hiddenSessionIDs.includes(actor.sessionID)
+    } catch {
+      if (listed()) return
+      throw stateBusy()
+    }
+    if (!concierge || listed()) return
+    throw new AgentError("forbidden", "The Concierge cannot use this route", { extra: { policy: "concierge" } })
+  }
+}