@huynle/hub 0.6.0 → 0.7.1

package/src/central/agent/directory-routes.ts

@@ -0,0 +1,185 @@
+// The directory on /api/agent (design §2.2) and its wiring to the hub: the Registry is the SessionSource
+// (sessions reported now, per tenant), the console's Archive (viewPrefs.hiddenSessions) the archive source,
+// and every catalog change syncs the affected users (records, lastSeen, derived names).
+//
+// Routes (user actors always; session tokens may read, and write for their OWN session only):
+//   GET  /api/agent/who?project=&role=
+//   POST /api/agent/name           {name, session?}
+//   POST /api/agent/roles/claim    {role, exclusive?, project?, session?}
+//   POST /api/agent/roles/release  {role, project?, session?}
+// `session` is an address (ses_…, ID prefix, @name, …) resolved for the caller; a session token defaults to
+// its own session, a user must name one.
+import path from "node:path"
+import type { CatalogMachine, RegistryMessage } from "../registry"
+import type { Store } from "../store"
+import { Directory, type ReportedSession, type SessionSource } from "./directory"
+import { AgentError } from "./errors"
+import { slugify } from "./names"
+import { AGENT_PREFIX, type AgentContext, type AgentRoute } from "./routes"
+
+/** What the directory reads from the Registry. */
+export interface DirectoryRegistry {
+  catalog(): CatalogMachine[]
+  sessionTenant(sessionID: string): string | undefined
+  subscribe(listener: (message: RegistryMessage, tenant?: string) => void): () => void
+}
+
+type CatalogSession = CatalogMachine["processes"][number]["sessions"][number]
+
+/** The `.project` scope of a session: its project name (else folder name), as a slug. */
+function projectOf(s: Pick<CatalogSession, "projectName" | "project" | "directory">): string | undefined {
+  const name = s.projectName || path.basename(s.project || s.directory || "")
+  return name ? (slugify(name) ?? name.toLowerCase()) : undefined
+}
+
+/** Sessions the Registry reports for a user (subagents from the status trees too), and their Archive. */
+export function registrySource(registry: Pick<DirectoryRegistry, "catalog" | "sessionTenant">, store: Pick<Store, "viewPrefs">): SessionSource {
+  return {
+    reported(userID) {
+      const out = new Map<string, ReportedSession>()
+      for (const machine of registry.catalog()) {
+        for (const process of machine.processes) {
+          for (const s of process.sessions) {
+            if (out.has(s.id) || registry.sessionTenant(s.id) !== userID) continue
+            const project = projectOf(s)
+            const scope = project ? { project } : {}
+            out.set(s.id, { sessionID: s.id, title: s.title, machineID: s.machineID, ...(s.parentID ? { parentID: s.parentID } : {}), ...scope, state: s.state })
+            for (const child of s.status) {
+              if (child.id === s.id || out.has(child.id)) continue
+              out.set(child.id, { sessionID: child.id, title: child.title, machineID: s.machineID, parentID: child.parentID ?? s.id, ...scope, state: child.state })
+            }
+          }
+        }
+      }
+      return [...out.values()]
+    },
+    archived: (userID) => new Set(store.viewPrefs(userID).hiddenSessions),
+  }
+}
+
+/** The hub's directory: fed by the Registry, synced for the affected users on every catalog change. */
+export function hubDirectory(options: { registry: DirectoryRegistry; store: Pick<Store, "viewPrefs" | "updateAgentData" | "agentData" | "user">; now?: () => number }): Directory {
+  const { registry, store } = options
+  const directory = new Directory({ store, source: registrySource(registry, store), ...(options.now ? { now: options.now } : {}) })
+  /** Users with reported sessions at the last catalog change (they need a sync when theirs go away). */
+  let online = new Set<string>()
+  registry.subscribe((message) => {
+    if (message.type !== "catalog") return
+    const now = new Set<string>()
+    for (const machine of registry.catalog()) {
+      for (const process of machine.processes) {
+        for (const s of process.sessions) {
+          const tenant = registry.sessionTenant(s.id)
+          if (tenant !== undefined) now.add(tenant)
+        }
+      }
+    }
+    for (const userID of new Set([...online, ...now])) {
+      directory.sync(userID).catch((cause: unknown) => {
+        if (!(cause instanceof AgentError)) console.error("[hub] directory sync failed:", cause)
+      })
+    }
+    online = now
+  })
+  return directory
+}
+
+// ---------- routes ----------
+
+type Body = Record<string, unknown>
+
+async function readBody(request: Request): Promise<Body> {
+  const body = await request.json()
+  if (typeof body !== "object" || body === null || Array.isArray(body)) throw new AgentError("invalid", "Expected a JSON object")
+  return body as Body
+}
+
+function text(body: Body, field: string, required: true): string
+function text(body: Body, field: string, required?: false): string | undefined
+function text(body: Body, field: string, required = false): string | undefined {
+  const value = body[field]
+  if (value === undefined && !required) return undefined
+  if (typeof value !== "string" || !value || value.length > 300) throw new AgentError("invalid", `${field} must be a string`)
+  return value
+}
+
+function flag(body: Body, field: string): boolean | undefined {
+  const value = body[field]
+  if (value !== undefined && typeof value !== "boolean") throw new AgentError("invalid", `${field} must be true or false`)
+  return value
+}
+
+/**
+ * The session a write targets: a session token acts on its own session only (forbidden otherwise); a user
+ * names any of their sessions by address.
+ */
+function target(directory: Directory, { actor, user }: AgentContext, addr: string | undefined): string {
+  if (actor.kind === "session") {
+    if (addr === undefined) return actor.sessionID
+    const sessionID = directory.resolveOne(user.id, addr).sessionID
+    if (sessionID !== actor.sessionID) throw new AgentError("forbidden", "A session token can only act for its own session")
+    return sessionID
+  }
+  if (addr === undefined) throw new AgentError("invalid", "session is required (ses_…, @name)")
+  return directory.resolveOne(user.id, addr).sessionID
+}
+
+const NO_STORE = { "cache-control": "no-store" }
+const ok = (body: unknown) => Response.json(body, { headers: NO_STORE })
+
+export function directoryRoutes(directory: Directory): AgentRoute[] {
+  return [
+    {
+      method: "GET",
+      path: `${AGENT_PREFIX}/who`,
+      // Reading the directory: sessions, and app tokens holding sessions:read; writes stay users and sessions.
+      allow: { session: true, scope: "sessions:read" },
+      handle: ({ url, user }) => {
+        const project = url.searchParams.get("project") || undefined
+        const role = url.searchParams.get("role") || undefined
+        return ok({ sessions: directory.who(user.id, { ...(project ? { project } : {}), ...(role ? { role } : {}) }) })
+      },
+    },
+    {
+      method: "POST",
+      path: `${AGENT_PREFIX}/name`,
+      allow: { session: true },
+      handle: async (context) => {
+        const body = await readBody(context.request)
+        const name = text(body, "name", true)
+        const sessionID = target(directory, context, text(body, "session"))
+        return ok(await directory.setName(context.user.id, sessionID, name))
+      },
+    },
+    {
+      method: "POST",
+      path: `${AGENT_PREFIX}/roles/claim`,
+      allow: { session: true },
+      handle: async (context) => {
+        const body = await readBody(context.request)
+        const role = text(body, "role", true)
+        const exclusive = flag(body, "exclusive")
+        const project = text(body, "project")
+        const sessionID = target(directory, context, text(body, "session"))
+        const claim = await directory.claimRole(context.user.id, sessionID, role, {
+          ...(exclusive !== undefined ? { exclusive } : {}),
+          ...(project !== undefined ? { project } : {}),
+          byUser: context.actor.kind === "user",
+        })
+        return ok({ sessionID, ...claim })
+      },
+    },
+    {
+      method: "POST",
+      path: `${AGENT_PREFIX}/roles/release`,
+      allow: { session: true },
+      handle: async (context) => {
+        const body = await readBody(context.request)
+        const role = text(body, "role", true)
+        const project = text(body, "project")
+        const sessionID = target(directory, context, text(body, "session"))
+        return ok({ sessionID, ...(await directory.releaseRole(context.user.id, sessionID, role, project)), released: true })
+      },
+    },
+  ]
+}

package/src/central/agent/directory.ts

@@ -0,0 +1,473 @@
+// The agent directory (design §2, §7): who is who among one user's sessions. Persisted per user in
+// UserRecord.agent (agent-data.ts): session records, @names (with rename aliases) and @@role holders.
+//
+// Every rule is evaluated lazily against the clock when the directory is used (no timers):
+// - A session record is created when a spoke reports the session; lastSeen is saved at minute granularity
+//   while it stays online (LAST_SEEN_STEP_MS), and exactly when it stops being reported.
+// - Archive source: the console's Archive (viewPrefs.hiddenSessions). Spokes never report archived OpenCode
+//   sessions (the listing drops them), so SessionInfo.archived never reaches the hub. archivedAt is the first
+//   time the directory sees the session in that list; unarchiving clears it. deletedAt comes from markDeleted.
+// - Names: derived once (names.ts deriveName), from the first non-placeholder title, for root sessions only; a taken derived name
+//   gets a suffix, an explicit taken one fails (name_taken). A name is released NAME_RELEASE_MS after its
+//   session was archived or deleted; a rename keeps the old name as an alias for ALIAS_MS.
+// - Roles: see claimRole. A holder offline (not reported) for ROLE_OFFLINE_MS loses the role, except during
+//   the RECONNECT_WINDOW_MS after the hub started, while spokes reconnect.
+// - At most SESSION_LIMIT records per user: archived/deleted ones are dropped first, then the least recently
+//   seen, with their names and roles.
+// - Primer (design §2.3): a session record remembers when the identity primer reached it (primed); explicit
+//   names are announced to onNamed listeners (the delivery engine primes on them), derived names never are.
+//
+// Tenancy: everything is per user; another user's sessions, names and roles do not exist here (not_found),
+// and ambiguity candidates only ever list the caller's own sessions.
+// Reads (resolve, who, primed) are synchronous: they evaluate the rules on a copy of the stored data and save
+// nothing. Writes (sync, names, roles, primer and deletion marks) are async: they run inside one store update and
+// resolve once it is saved (their errors reject). Uniqueness holds across pods: on a shared (cluster) store an update
+// that lost a race with another pod's write runs again on the fresh data before it resolves.
+// Cluster mode: the SessionSource reports every pod's sessions (the Registry's cluster view), so a sync on one pod
+// never takes another pod's sessions for offline.
+import { roleKey, type AgentData, type AgentName, type AgentRole, type AgentSession } from "../agent-data"
+import type { Store } from "../store"
+import { AgentError } from "./errors"
+import { deriveName, isPlaceholderTitle, isReservedName, isReservedRole, parseAddress, validName, withSuffix, type Address } from "./names"
+
+const MINUTE = 60_000
+const HOUR = 60 * MINUTE
+const DAY = 24 * HOUR
+
+export const SESSION_LIMIT = 2000
+export const NAME_RELEASE_MS = 7 * DAY
+export const ALIAS_MS = 24 * HOUR
+export const ROLE_OFFLINE_MS = 30 * MINUTE
+export const RECONNECT_WINDOW_MS = 2 * MINUTE
+export const LAST_SEEN_STEP_MS = MINUTE
+/** Most candidates listed in an ambiguous error. */
+const CANDIDATES_MAX = 20
+
+/** A session a spoke of the user reports now. */
+export interface ReportedSession {
+  readonly sessionID: string
+  readonly title: string
+  readonly machineID?: string
+  readonly parentID?: string
+  /** Project name, lowercased (the `.project` scope). */
+  readonly project?: string
+  readonly state?: string
+}
+
+/** What the directory needs to know about the user's live sessions. */
+export interface SessionSource {
+  /** The user's sessions reported now (roots and subagents), only ones the user owns. */
+  reported(userID: string): readonly ReportedSession[]
+  /** IDs of the sessions the user archived. */
+  archived(userID: string): ReadonlySet<string>
+}
+
+export type DirectoryStore = Pick<Store, "updateAgentData" | "agentData" | "user">
+
+export interface DirectoryOptions {
+  readonly store: DirectoryStore
+  readonly source: SessionSource
+  readonly now?: () => number
+}
+
+export interface RoleView {
+  readonly role: string
+  readonly project?: string
+  readonly generation: number
+  readonly exclusive?: boolean
+}
+
+/** One session in directory answers. */
+export interface DirectoryEntry {
+  readonly sessionID: string
+  readonly name?: string
+  readonly aliases?: string[]
+  readonly machineID?: string
+  readonly parentID?: string
+  readonly project?: string
+  readonly title?: string
+  readonly state?: string
+  /** A spoke reports it now. */
+  readonly online: boolean
+  readonly lastSeen?: number
+  readonly archived?: boolean
+  readonly roles: RoleView[]
+}
+
+/** Hears an explicit name change (setName); derived names are never announced. */
+export type NamedListener = (userID: string, sessionID: string, name: string) => void
+
+export interface Resolved {
+  readonly address: Address
+  /** One session for an ID or @name; every live holder for a @@role. */
+  readonly sessions: DirectoryEntry[]
+}
+
+/** The working copy of one user's data inside an update. */
+interface Draft {
+  readonly data: AgentData
+  readonly sessions: AgentSession[]
+  readonly byID: Map<string, AgentSession>
+  readonly reported: Map<string, ReportedSession>
+  names: AgentName[]
+  roles: AgentRole[]
+}
+
+const ended = (s: AgentSession | undefined): number | undefined => {
+  const times = [s?.archivedAt, s?.deletedAt].filter((t): t is number => typeof t === "number")
+  return times.length ? Math.min(...times) : undefined
+}
+
+export class Directory {
+  private readonly store: DirectoryStore
+  private readonly source: SessionSource
+  private readonly now: () => number
+  private readonly startedAt: number
+  /** Per user: the sessions reported at the last update (to stamp lastSeen when they go away). */
+  private readonly online = new Map<string, Set<string>>()
+  private readonly named = new Set<NamedListener>()
+
+  constructor(options: DirectoryOptions) {
+    this.store = options.store
+    this.source = options.source
+    this.now = options.now ?? Date.now
+    this.startedAt = this.now()
+  }
+
+  /** Applies what the spokes report and the clock to the user's records (saves only on change). */
+  sync(userID: string): Promise<void> {
+    return this.update(userID, () => undefined)
+  }
+
+  /** Records that a session was deleted (its name is released NAME_RELEASE_MS later). */
+  markDeleted(userID: string, sessionID: string): Promise<void> {
+    return this.update(userID, (draft) => {
+      const record = draft.byID.get(sessionID)
+      if (record && record.deletedAt === undefined) record.deletedAt = this.now()
+    })
+  }
+
+  // ---------- primer ----------
+
+  /** Whether the identity primer reached the session (false for an unknown one). */
+  primed(userID: string, sessionID: string): boolean {
+    return this.read(userID, (draft) => draft.byID.get(sessionID)?.primed !== undefined)
+  }
+
+  /** Records that the identity primer reached the session (an unknown session is ignored). */
+  markPrimed(userID: string, sessionID: string): Promise<void> {
+    return this.update(userID, (draft) => {
+      const record = draft.byID.get(sessionID)
+      if (record && record.primed === undefined) record.primed = this.now()
+    })
+  }
+
+  /** Listens for explicit names (setName); returns the unsubscribe. */
+  onNamed(listener: NamedListener): () => void {
+    this.named.add(listener)
+    return () => void this.named.delete(listener)
+  }
+
+  // ---------- names ----------
+
+  /** Names a session (explicit: a taken name fails); the previous name stays an alias for ALIAS_MS. Tells onNamed listeners. */
+  async setName(userID: string, sessionID: string, requested: string): Promise<{ sessionID: string; name: string; alias?: string }> {
+    const result = await this.assignName(userID, sessionID, requested)
+    for (const listener of this.named) {
+      try {
+        listener(userID, sessionID, result.name)
+      } catch (cause) {
+        console.error("[hub] name listener failed:", cause)
+      }
+    }
+    return result
+  }
+
+  private async assignName(userID: string, sessionID: string, requested: string): Promise<{ sessionID: string; name: string; alias?: string }> {
+    const name = requested.replace(/^@/, "")
+    if (!validName(name)) throw new AgentError("invalid", "A name is 2–40 characters: a-z, 0-9 and -")
+    if (isReservedName(name)) throw new AgentError("invalid", "@me is reserved: it always means the user")
+    return this.update(userID, (draft) => {
+      const record = this.known(draft, sessionID)
+      const held = draft.names.find((n) => n.name === name)
+      if (held && held.sessionID !== sessionID) throw new AgentError("name_taken", `@${name} is taken`)
+      record.named = true
+      const current = draft.names.find((n) => n.sessionID === sessionID && n.expiresAt === undefined)
+      if (current?.name === name) return { sessionID, name }
+      const t = this.now()
+      if (held) draft.names = draft.names.filter((n) => n !== held)
+      if (current) current.expiresAt = t + ALIAS_MS
+      draft.names.push({ name, sessionID, created: t })
+      return { sessionID, name, ...(current ? { alias: current.name } : {}) }
+    })
+  }
+
+  // ---------- roles ----------
+
+  /**
+   * Claims `role` (or `role.project`) for a session. Each new holder gets the next holder generation of
+   * (role, project). An exclusive claim fails (name_taken) while another live holder exists, and nobody else
+   * can claim while an exclusive holder is live. Reserved roles (orchestrator…, concierge…) need `byUser`
+   * (grants with `roles` come in phase 3). Exclusivity and generations are per (role, project scope).
+   */
+  async claimRole(userID: string, sessionID: string, requested: string, options: { exclusive?: boolean; project?: string; byUser?: boolean } = {}): Promise<RoleView> {
+    const { role, project } = parseRole(requested, options.project)
+    if (isReservedRole(role) && !options.byUser) throw new AgentError("forbidden", `@@${role} is reserved: only the user can assign it`)
+    return this.update(userID, (draft) => {
+      this.known(draft, sessionID)
+      const same = draft.roles.filter((r) => r.role === role && r.project === project)
+      const mine = same.find((r) => r.sessionID === sessionID)
+      const others = same.filter((r) => r !== mine)
+      if (others.some((r) => r.exclusive) || (options.exclusive && others.length)) {
+        throw new AgentError("name_taken", `@@${scoped(role, project)} is held${others.some((r) => r.exclusive) ? " exclusively" : ""} by another session`)
+      }
+      if (mine) {
+        if (options.exclusive) mine.exclusive = true
+        return roleView(mine)
+      }
+      const key = roleKey(role, project)
+      const generations = { ...(draft.data.generations ?? {}) }
+      const generation = (generations[key] ?? 0) + 1
+      generations[key] = generation
+      draft.data.generations = generations
+      const claim: AgentRole = { role, sessionID, ...(project !== undefined ? { project } : {}), generation, ...(options.exclusive ? { exclusive: true } : {}), claimedAt: this.now() }
+      draft.roles.push(claim)
+      return roleView(claim)
+    })
+  }
+
+  /** Gives a role up; not_found when the session does not hold it. */
+  async releaseRole(userID: string, sessionID: string, requested: string, scope?: string): Promise<{ role: string; project?: string }> {
+    const { role, project } = parseRole(requested, scope)
+    return this.update(userID, (draft) => {
+      const held = draft.roles.find((r) => r.sessionID === sessionID && r.role === role && r.project === project)
+      if (!held) throw new AgentError("not_found", `Not holding @@${scoped(role, project)}`)
+      draft.roles = draft.roles.filter((r) => r !== held)
+      return project !== undefined ? { role, project } : { role }
+    })
+  }
+
+  // ---------- directory ----------
+
+  /** The user's named, role-holding or online sessions (not archived or deleted), by project and role. */
+  who(userID: string, filter: { project?: string; role?: string } = {}): DirectoryEntry[] {
+    const project = filter.project?.toLowerCase()
+    const role = filter.role !== undefined ? parseRole(filter.role, project) : undefined
+    return this.read(userID, (draft) =>
+      draft.sessions
+        .filter((s) => s.archivedAt === undefined && s.deletedAt === undefined)
+        .map((s) => this.entry(draft, s.sessionID))
+        .filter((e) => e.online || e.name !== undefined || e.roles.length > 0)
+        .filter((e) => project === undefined || e.project === project || e.roles.some((r) => r.project === project))
+        .filter((e) => !role || e.roles.some((r) => r.role === role.role && inScope(r.project, e.project, role.project))),
+    )
+  }
+
+  // ---------- resolution ----------
+
+  /**
+   * The sessions an address names, for this user only: `ses_…` (an ID or a unique ID prefix), `@name[.project]`
+   * or `@@role[.project]` (every live holder). Throws invalid (malformed), not_found or ambiguous {candidates}.
+   */
+  resolve(userID: string, addr: string): Resolved {
+    const address = parseAddress(addr)
+    if (!address) throw new AgentError("invalid", `Not an address: use ses_…, @name or @@role`)
+    return this.read(userID, (draft) => ({ address, sessions: this.lookup(draft, address, addr) }))
+  }
+
+  /** Exactly one session; several (a role with several holders) is ambiguous. */
+  resolveOne(userID: string, addr: string): DirectoryEntry {
+    const { sessions } = this.resolve(userID, addr)
+    if (sessions.length > 1) throw ambiguous(addr, sessions)
+    return sessions[0]!
+  }
+
+  private lookup(draft: Draft, address: Address, addr: string): DirectoryEntry[] {
+    const missing = () => new AgentError("not_found", `No session ${addr}`)
+    if (address.kind === "id") {
+      if (draft.byID.has(address.id)) return [this.entry(draft, address.id)]
+      const matches = draft.sessions.filter((s) => s.sessionID.startsWith(address.id)).map((s) => this.entry(draft, s.sessionID))
+      if (matches.length > 1) throw ambiguous(addr, matches)
+      if (!matches.length) throw missing()
+      return matches
+    }
+    if (address.kind === "name") {
+      const held = draft.names.find((n) => n.name === address.name)
+      const entry = held && this.entry(draft, held.sessionID)
+      if (!entry || (address.project !== undefined && entry.project !== address.project)) throw missing()
+      return [entry]
+    }
+    const holders = draft.roles.filter((r) => r.role === address.role && inScope(r.project, draft.byID.get(r.sessionID)?.project, address.project))
+    const ids = [...new Set(holders.map((r) => r.sessionID))]
+    if (!ids.length) throw missing()
+    return ids.map((id) => this.entry(draft, id))
+  }
+
+  // ---------- internals ----------
+
+  private known(draft: Draft, sessionID: string): AgentSession {
+    const record = draft.byID.get(sessionID)
+    if (!record) throw new AgentError("not_found", `No session ${sessionID}`)
+    return record
+  }
+
+  private entry(draft: Draft, sessionID: string): DirectoryEntry {
+    const record = draft.byID.get(sessionID)
+    const live = draft.reported.get(sessionID)
+    const own = draft.names.filter((n) => n.sessionID === sessionID)
+    const name = own.find((n) => n.expiresAt === undefined)?.name
+    const aliases = own.filter((n) => n.expiresAt !== undefined).map((n) => n.name)
+    const roles = draft.roles.filter((r) => r.sessionID === sessionID).map(roleView)
+    return {
+      sessionID,
+      ...(name ? { name } : {}),
+      ...(aliases.length ? { aliases } : {}),
+      ...(record?.machineID ? { machineID: record.machineID } : {}),
+      ...(record?.parentID ? { parentID: record.parentID } : {}),
+      ...(record?.project ? { project: record.project } : {}),
+      ...(record?.title ? { title: record.title } : {}),
+      ...(live?.state ? { state: live.state } : {}),
+      online: live !== undefined,
+      ...(record?.lastSeen !== undefined ? { lastSeen: record.lastSeen } : {}),
+      ...(record?.archivedAt !== undefined ? { archived: true } : {}),
+      roles,
+    }
+  }
+
+  /** Runs `look` on a refreshed copy of the user's data, saving nothing; not_found for an unknown user. */
+  private read<T>(userID: string, look: (draft: Draft) => T): T {
+    if (!this.store.user(userID)) throw new AgentError("not_found", "No such user")
+    const reported = new Map(this.source.reported(userID).map((s) => [s.sessionID, s]))
+    return look(this.refresh(userID, this.store.agentData(userID), reported, this.source.archived(userID)))
+  }
+
+  /**
+   * Runs `change` on the user's refreshed data in one store update and resolves once it is saved; not_found for an
+   * unknown user. On a shared store the change may run again (on fresh data, after another pod's write).
+   */
+  private async update<T>(userID: string, change: (draft: Draft) => T): Promise<T> {
+    const reported = new Map(this.source.reported(userID).map((s) => [s.sessionID, s]))
+    const archived = this.source.archived(userID)
+    let done = false
+    let result: T | undefined
+    await this.store.updateAgentData(userID, (data) => {
+      const draft = this.refresh(userID, data, reported, archived)
+      result = change(draft)
+      this.write(draft)
+      done = true
+    })
+    if (!done) throw new AgentError("not_found", "No such user")
+    this.online.set(userID, new Set(reported.keys()))
+    return result as T
+  }
+
+  private write(draft: Draft): void {
+    const { data } = draft
+    if (draft.sessions.length || data.sessions) data.sessions = draft.sessions
+    if (draft.names.length || data.names) data.names = draft.names
+    if (draft.roles.length || data.roles) data.roles = draft.roles
+  }
+
+  /** Records, archive marks, releases, derivations and the cap, as of now. */
+  private refresh(userID: string, data: AgentData, reported: Map<string, ReportedSession>, archived: ReadonlySet<string>): Draft {
+    const t = this.now()
+    const sessions = data.sessions ?? []
+    const byID = new Map(sessions.map((s) => [s.sessionID, s]))
+    for (const live of reported.values()) {
+      let record = byID.get(live.sessionID)
+      if (!record) {
+        record = { sessionID: live.sessionID, firstSeen: t }
+        sessions.push(record)
+        byID.set(live.sessionID, record)
+      }
+      for (const field of ["machineID", "parentID", "project", "title"] as const) {
+        const value = live[field]
+        if (value !== undefined && value !== "" && record[field] !== value) record[field] = value
+      }
+      if (record.lastSeen === undefined || t - record.lastSeen >= LAST_SEEN_STEP_MS) record.lastSeen = t
+      delete record.deletedAt
+    }
+    for (const id of this.online.get(userID) ?? []) {
+      const record = byID.get(id)
+      if (record && !reported.has(id)) record.lastSeen = t
+    }
+    for (const record of sessions) {
+      if (archived.has(record.sessionID)) record.archivedAt ??= t
+      else delete record.archivedAt
+    }
+
+    const draft: Draft = { data, sessions, byID, reported, names: data.names ?? [], roles: data.roles ?? [] }
+    draft.names = draft.names.filter((n) => !this.nameReleased(n, byID, t))
+    draft.roles = draft.roles.filter((r) => this.holding(draft, r.sessionID, t))
+    this.derive(draft, t)
+    this.cap(draft)
+    return draft
+  }
+
+  private nameReleased(name: AgentName, byID: Map<string, AgentSession>, t: number): boolean {
+    if (name.expiresAt !== undefined && t >= name.expiresAt) return true
+    const end = ended(byID.get(name.sessionID))
+    return end !== undefined && t - end >= NAME_RELEASE_MS
+  }
+
+  /** A holder keeps its roles while reported, or offline for less than ROLE_OFFLINE_MS, or (any) during the reconnect window; never once deleted. */
+  private holding(draft: Draft, sessionID: string, t: number): boolean {
+    const record = draft.byID.get(sessionID)
+    if (record?.deletedAt !== undefined) return false
+    if (draft.reported.has(sessionID) || t - this.startedAt < RECONNECT_WINDOW_MS) return true
+    return record?.lastSeen !== undefined && t - record.lastSeen < ROLE_OFFLINE_MS
+  }
+
+  /** Names root sessions once, from their first non-placeholder title. */
+  private derive(draft: Draft, t: number): void {
+    for (const live of draft.reported.values()) {
+      const record = draft.byID.get(live.sessionID)!
+      if (live.parentID || record.named || isPlaceholderTitle(live.title)) continue
+      record.named = true
+      const slug = deriveName(live.title)
+      if (!slug || draft.names.some((n) => n.sessionID === live.sessionID && n.expiresAt === undefined)) continue
+      const taken = new Set(draft.names.map((n) => n.name))
+      draft.names.push({ name: withSuffix(slug, (n) => taken.has(n) || isReservedName(n)), sessionID: live.sessionID, created: t })
+    }
+  }
+
+  /** Drops records beyond SESSION_LIMIT (never a reported one), with their names and roles. */
+  private cap(draft: Draft): void {
+    const excess = draft.sessions.length - SESSION_LIMIT
+    if (excess <= 0) return
+    const seen = (s: AgentSession) => s.lastSeen ?? s.firstSeen ?? 0
+    const victims = draft.sessions
+      .filter((s) => !draft.reported.has(s.sessionID))
+      .sort((a, b) => Number(ended(b) !== undefined) - Number(ended(a) !== undefined) || seen(a) - seen(b))
+      .slice(0, excess)
+    const gone = new Set(victims.map((s) => s.sessionID))
+    const kept = draft.sessions.filter((s) => !gone.has(s.sessionID))
+    draft.sessions.splice(0, draft.sessions.length, ...kept)
+    for (const id of gone) draft.byID.delete(id)
+    draft.names = draft.names.filter((n) => !gone.has(n.sessionID))
+    draft.roles = draft.roles.filter((r) => !gone.has(r.sessionID))
+  }
+}
+
+/** `role`, `@@role` or `role.project` (an explicit scope wins); invalid when malformed. */
+function parseRole(requested: string, scope?: string): { role: string; project?: string } {
+  const [role = "", inline, ...rest] = requested.replace(/^@@/, "").split(".")
+  const project = (scope ?? inline)?.toLowerCase()
+  if (!validName(role) || rest.length || (project !== undefined && !/^[^./\s]+$/.test(project))) {
+    throw new AgentError("invalid", "A role is 2–40 characters: a-z, 0-9 and -, optionally .project")
+  }
+  return project !== undefined ? { role, project } : { role }
+}
+
+const scoped = (role: string, project?: string) => (project !== undefined ? `${role}.${project}` : role)
+
+/** A claim scoped to `claimProject` (or unscoped, in a session of `sessionProject`) counts for `wanted`. */
+const inScope = (claimProject: string | undefined, sessionProject: string | undefined, wanted: string | undefined) =>
+  wanted === undefined || claimProject === wanted || (claimProject === undefined && sessionProject === wanted)
+
+const roleView = (r: AgentRole): RoleView => ({ role: r.role, ...(r.project !== undefined ? { project: r.project } : {}), generation: r.generation ?? 0, ...(r.exclusive ? { exclusive: true } : {}) })
+
+function ambiguous(addr: string, sessions: readonly DirectoryEntry[]): AgentError {
+  const candidates = sessions.slice(0, CANDIDATES_MAX).map((s) => ({ sessionID: s.sessionID, ...(s.name ? { name: s.name } : {}), ...(s.project ? { project: s.project } : {}) }))
+  return new AgentError("ambiguous", `${addr} matches ${sessions.length} sessions`, { extra: { candidates } })
+}