@huynle/hub 0.7.4 → 0.8.1

package/src/central/registry.ts

@@ -11,7 +11,7 @@
 // another one and reaches it through SpokeHub.request (pod RPC). Events, alerts and speech stay with the pod that
 // holds the connection; remote state is never re-exported.
 import path from "node:path"
-import { HARNESS_OPENCODE, helloHarness, spokeFeatures, type EvidenceLevel, type ForwardedEvent, type Hello, type HerdrWorkspace, type ProcessKind, type SessionInfo, type SpokeFeature, type SpokeMode, type TerminalInfo, type Terminals } from "../protocol"
+import { HARNESS_OPENCODE, helloHarness, spokeFeatures, type EvidenceLevel, type ForwardedEvent, type Hello, type HerdrWorkspace, type ProcessKind, type SessionInfo, type SessionRevertInfo, type SpokeFeature, type SpokeMode, type TerminalInfo, type Terminals } from "../protocol"
 import { StatusBoard, errorTypeLabel, permissionRequest, providerFailureNeedsUser, providerRetryNeedsUser, type Blocker, type BlockerRecommendation, type PermissionRequest, type SessionStatus } from "../status"
 import { sanitizeLabel } from "./agent/envelope"
 import { DoneWatch } from "./done"
@@ -222,6 +222,11 @@ export interface SessionView extends BrowserFields {
   /** Open in a terminal (any reporting process says so); where. */
   readonly open?: boolean
   readonly terminal?: TerminalInfo
+  /** A staged revert (feature "revert"), as the most recent report says. */
+  readonly revert?: SessionRevertInfo
+  /** (CON-04) A locked (Concierge) session: the agent and the context revision the most recent report says. */
+  readonly agent?: string
+  readonly contextRevision?: number
   readonly busy: boolean
   readonly conversation: boolean
   /** Status tree of the root session that contains this session. */
@@ -248,6 +253,8 @@ export interface CatalogProcess {
   readonly connected: number
   readonly lastSeen: number
   readonly sessions: CatalogSession[]
+  /** (FX-07) Connected, but its first sessions frame has not come yet: an empty `sessions` says nothing then. */
+  readonly sessionsPending?: true
 }
 
 /** A machine's terminal context: its Herdr workspaces (latest terminals frame of the machine). */
@@ -274,6 +281,8 @@ interface Conn {
   sessions: Map<string, SessionInfo>
   /** The last sessions frame as JSON, to skip unchanged snapshots. */
   sessionsKey: string
+  /** (FX-07) No sessions frame yet. */
+  sessionsPending?: true
   /** sessionID → activity sequence number of the last event this process sent for it. */
   activity: Map<string, number>
   /**
@@ -299,6 +308,8 @@ export interface SliceConn {
   readonly launchID?: string
   /** The machine's terminal context, when this connection sent the latest one. */
   readonly terminals?: MachineTerminals
+  /** (FX-07) No sessions frame yet (absent from older pods: reported). */
+  readonly sessionsPending?: true
 }
 
 /** A root session's status tree (live: run starts and recommendations included) and activity feed. */
@@ -405,6 +416,7 @@ export class Registry {
   private readonly sessionsListeners = new Set<(connID: string) => void>()
   /** Called when the user's own prompt reached a session's inbox (typed or spoken in the harness). */
   private readonly humanTurnListeners = new Set<(sessionID: string, tenant?: string) => void>()
+  private readonly sessionDeletedListeners = new Set<(sessionID: string, tenant: string) => void>()
   /** Pending form ID → its session and every connection that forwarded it, first first (like permissions). */
   private readonly forms = new Map<string, { connIDs: string[]; sessionID: string }>()
   /** Form IDs already alerted (forms may be forwarded by several processes). */
@@ -450,7 +462,7 @@ export class Registry {
   private remoteBoards = new Map<string, SliceBoard>()
   private remotePermissions = new Map<string, { sessionID: string; tenant: string; connIDs: string[]; request?: PermissionRequest; recommendation?: BlockerRecommendation }>()
   private remoteForms = new Map<string, { sessionID: string; connIDs: string[] }>()
-  private remotePresence: Array<{ sessionID: string; at: number }> = []
+  private remotePresence: Array<{ deviceID?: string; sessionID: string; at: number }> = []
   private remoteBusy = new Set<string>()
   private remoteTerminals = new Map<string, MachineTerminals>()
 
@@ -573,6 +585,12 @@ export class Registry {
     return () => this.humanTurnListeners.delete(listener)
   }
 
+  /** Listens to sessions a spoke reports deleted (session.deleted, seen once by the pod holding the spoke). */
+  onSessionDeleted(listener: (sessionID: string, tenant: string) => void): () => void {
+    this.sessionDeletedListeners.add(listener)
+    return () => this.sessionDeletedListeners.delete(listener)
+  }
+
   connect(connID: string, machine: MachineRef, hello: Hello, options: ConnectOptions = {}): void {
     const t = this.now()
     this.conns.set(connID, {
@@ -586,6 +604,7 @@ export class Registry {
       lastSeen: t,
       sessions: new Map(),
       sessionsKey: "[]",
+      sessionsPending: true,
       activity: new Map(),
     })
     this.changed(this.tenant(this.conns.get(connID)!))
@@ -628,7 +647,9 @@ export class Registry {
     conn.lastSeen = this.now()
     // Spokes re-send their snapshot periodically; only changes reach the phones.
     const key = JSON.stringify(sessions)
-    if (key !== conn.sessionsKey) {
+    const first = conn.sessionsPending === true
+    delete conn.sessionsPending
+    if (key !== conn.sessionsKey || first) {
       conn.sessionsKey = key
       conn.sessions = new Map(sessions.map((s) => [s.id, s]))
       this.syncBoards()
@@ -736,6 +757,7 @@ export class Registry {
       for (const listener of [...this.humanTurnListeners]) listener(sessionID, tenant)
     }
     if (event.type === "session.deleted" && sessionID) this.setConversation(sessionID, false)
+    if (event.type === "session.deleted" && sessionID) for (const listener of [...this.sessionDeletedListeners]) listener(sessionID, tenant)
     if (closedPermission) this.permissionClosed(...closedPermission)
   }
 
@@ -1037,6 +1059,17 @@ export class Registry {
     return false
   }
 
+  /**
+   * (CON-06) True while this device reported this exact session visible within PRESENCE_WINDOW_MS (on any pod):
+   * the voice-confirm check (a paired device with the Concierge open).
+   */
+  present(deviceID: string, sessionID: string): boolean {
+    const t = this.now()
+    const local = this.presence.get(`${deviceID} ${sessionID}`)
+    if (local && t - local.at <= PRESENCE_WINDOW_MS) return true
+    return this.remotePresence.some((entry) => entry.deviceID === deviceID && entry.sessionID === sessionID && t - entry.at <= PRESENCE_WINDOW_MS)
+  }
+
   /** Whether any process exposes the session to voice; undefined when no process reports it. */
   exposed(sessionID: string): boolean | undefined {
     let reported = false
@@ -1208,6 +1241,7 @@ export class Registry {
         features: [...conn.features].sort(),
         connected: conn.connected,
         lastSeen: conn.lastSeen,
+        ...(conn.sessionsPending ? { sessionsPending: true as const } : {}),
         sessions: this.visible(conn).map((s) => {
           const fields = this.browserFields(s.id)
           return {
@@ -1225,6 +1259,19 @@ export class Registry {
     return [...machines.values()]
   }
 
+  /**
+   * (FX-07) The tenant's sessions a spoke reports locked now (the Concierge's: `locked`, from the first frame after a
+   * restart, and `agent` / `contextRevision`, sent only for locked sessions), on this pod's connections and other pods'.
+   */
+  lockedSessions(tenant: string): string[] {
+    const out = new Set<string>()
+    for (const conn of this.all()) {
+      if (this.tenant(conn) !== tenant) continue
+      for (const s of conn.sessions.values()) if (s.locked === true || s.agent !== undefined || s.contextRevision !== undefined) out.add(s.id)
+    }
+    return [...out]
+  }
+
   /** The session as reported by any process plus its live status; undefined when nobody reports it. */
   session(sessionID: string): SessionView | undefined {
     let info: SessionInfo | undefined
@@ -1248,6 +1295,9 @@ export class Registry {
       ...(info.projectName ? { projectName: info.projectName } : {}),
       updated: info.updated,
       ...(terminal ? { open: true, terminal } : {}),
+      ...(info.revert ? { revert: info.revert } : {}),
+      ...(info.agent !== undefined ? { agent: info.agent } : {}),
+      ...(info.contextRevision !== undefined ? { contextRevision: info.contextRevision } : {}),
       ...fields,
       busy: this.busy(sessionID),
       conversation: this.conversations.has(sessionID),
@@ -1568,7 +1618,8 @@ export class Registry {
    * Connection that should run a turn for the session:
    * 1. a process reporting it as owned, most recent activity first;
    * 2. else a service process that reports it;
-   * 3. else the service process of a machine that reports it;
+   * 3. else the (never launch-bound) service process of a machine that reports it, of the same harness as its
+   *    reporters (never a service of another harness: a Claude Code service cannot serve an OpenCode session);
    * 4. else any process that reports it, most recent activity first;
    * 5. else none.
    */
@@ -1587,8 +1638,17 @@ export class Registry {
     if (owned.length) return recent(owned)
     const services = reporters.filter((c) => c.hello.kind === "service")
     if (services.length) return recent(services)
+    // A machine's service runs one harness: only a service of the session's harness (its reporters') may run it.
     const machines = new Set(reporters.map((c) => c.machine.id))
-    return recent(all.filter((c) => c.hello.kind === "service" && machines.has(c.machine.id))) ?? recent(reporters)
+    const harnesses = new Set(reporters.map((c) => helloHarness(c.hello).harness))
+    const machineServices = all.filter(
+      (c) =>
+        c.hello.kind === "service" &&
+        c.launchID === undefined &&
+        machines.has(c.machine.id) &&
+        harnesses.has(helloHarness(c.hello).harness),
+    )
+    return recent(machineServices) ?? recent(reporters)
   }
 
   /**
@@ -1856,6 +1916,7 @@ export class Registry {
           activity: [...conn.activity],
           ...(conn.launchID !== undefined ? { launchID: conn.launchID } : {}),
           ...(terminals?.connID === conn.id ? { terminals: terminals.terminals } : {}),
+          ...(conn.sessionsPending ? { sessionsPending: true as const } : {}),
         }
       })
     const boards: SliceBoard[] = [...this.boards]
@@ -1910,7 +1971,7 @@ export class Registry {
     const boards = new Map<string, SliceBoard>()
     const permissions = new Map<string, { sessionID: string; tenant: string; connIDs: string[]; request?: PermissionRequest; recommendation?: BlockerRecommendation }>()
     const forms = new Map<string, { sessionID: string; connIDs: string[] }>()
-    const presence: Array<{ sessionID: string; at: number }> = []
+    const presence: Array<{ deviceID?: string; sessionID: string; at: number }> = []
     const busy = new Set<string>()
     const terminals = new Map<string, MachineTerminals>()
     for (const [pod, slices] of this.remoteSlices) {
@@ -1929,6 +1990,7 @@ export class Registry {
             sessionsKey: "",
             activity: new Map(c.activity ?? []),
             ...(c.launchID !== undefined ? { launchID: c.launchID } : {}),
+            ...(c.sessionsPending === true ? { sessionsPending: true as const } : {}),
             remote: { pod, tenant },
           })
           if (c.terminals) terminals.set(c.machine.id, c.terminals)
@@ -1944,7 +2006,7 @@ export class Registry {
           if (known) known.connIDs.push(...f.connIDs.filter((id) => !known.connIDs.includes(id)))
           else forms.set(f.formID, { sessionID: f.sessionID, connIDs: [...f.connIDs] })
         }
-        for (const entry of slice.presence ?? []) presence.push({ sessionID: entry.sessionID, at: entry.at })
+        for (const entry of slice.presence ?? []) presence.push({ ...(typeof entry.deviceID === "string" ? { deviceID: entry.deviceID } : {}), sessionID: entry.sessionID, at: entry.at })
         for (const sessionID of slice.busy ?? []) busy.add(sessionID)
       }
     }

package/src/central/store.ts

@@ -126,6 +126,8 @@ export interface PushPrefs {
    * (once per run), or a retry for a quota, free-tier or auth error. Replaces the root's "failed" for that failure.
    */
   providerError: boolean
+  /** (CON-04) The Concierge needs you: its questions, permissions, Decisions, messages and spoken replies (opens /concierge). */
+  concierge: boolean
 }
 
 export const PUSH_PREF_KEYS = [
@@ -147,6 +149,7 @@ export const PUSH_PREF_KEYS = [
   "decision",
   "message",
   "providerError",
+  "concierge",
 ] as const satisfies readonly (keyof PushPrefs)[]
 
 /** Defaults: anything that needs you, all done, failed, hand-offs and spoken replies; the finer kinds are opt-in. */
@@ -170,6 +173,7 @@ export const DEFAULT_PUSH_PREFS: Readonly<PushPrefs> = Object.freeze({
   decision: true,
   message: true,
   providerError: true,
+  concierge: true,
 })
 
 /** Default and allowed range of a device's activity update interval, in minutes. */

package/src/central/teams/collections.ts

@@ -0,0 +1,34 @@
+// Shared storage shapes of the team modules (HWA-33): the staffing aggregate is read by the definition store (a
+// publish must not drop a staffed role) and owned by seats.ts.
+import { CONTRACT_VERSION, type TeamStaffing } from "../../protocol"
+import { AgentError } from "../agent/errors"
+
+/** One aggregate per team (key: team ID): its staffing records, current and ended, and the staffing Idempotency-Keys. */
+export const TEAM_SEATS = "team-seats"
+
+export interface SeatKey {
+  readonly staffingID: string
+  readonly digest: string
+  readonly at: number
+}
+
+export interface SeatsDoc {
+  readonly v: 1
+  readonly teamID: string
+  readonly seats: readonly TeamStaffing[]
+  readonly keys: Readonly<Record<string, SeatKey>>
+}
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** The stored staffing aggregate (undefined when missing); newer versions are unsupported, malformed ones internal. */
+export function readSeatsDoc(raw: unknown, teamID: string): SeatsDoc | undefined {
+  if (raw === undefined) return undefined
+  if (isObj(raw) && typeof raw.v === "number" && raw.v > CONTRACT_VERSION)
+    throw new AgentError("unsupported", `The staffing of team ${teamID} was written by a newer hub`, { hint: "Upgrade this hub", extra: { feature: "team-staffing" } })
+  if (!isObj(raw) || raw.v !== CONTRACT_VERSION || raw.teamID !== teamID || !Array.isArray(raw.seats)) throw new AgentError("internal", `Stored staffing of team ${teamID} is malformed`)
+  return { v: 1, teamID, seats: raw.seats as TeamStaffing[], keys: isObj(raw.keys) ? (raw.keys as Record<string, SeatKey>) : {} }
+}
+
+/** Current seats (not ended). */
+export const currentSeats = (doc: SeatsDoc | undefined): TeamStaffing[] => (doc?.seats ?? []).filter((s) => s.until === undefined)

package/src/central/teams/discovery.ts

@@ -0,0 +1,346 @@
+// Team-aware discovery (HWA-40; contract docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md, Teams
+// "Discovery (HWA-40)"; decisions zltiwb4s 2026-10-28 addition, r3vv4eon (+correction), 5etngvgm, qxzrdc6c).
+//
+// Who sees whom, for who / status / sessions / show / log / watch (with or without ?session=) and events:
+// - A session caller holding a seat in at least one ACTIVE team (paused teams count; archived ones do not — the same
+//   rule teamDeliveryVerdict uses) is team-scoped: it sees itself, every current member of its teams (grouped by team,
+//   with each member's roles there) and, unless the owner turned `teamIsolation` on, sessions in no active team.
+//   Sessions seated only in teams the caller is not in are invisible; so are the caller's teammates' seats in teams
+//   the caller is not in (never listed). Under isolation, sessions in no team are hidden too.
+// - Sessions in no active team, the user (console/device) and app tokens keep today's owner-wide view (r3vv4eon),
+//   whatever teamIsolation says (the frozen contract: isolation hides non-team sessions FROM TEAM MEMBERS only).
+//   They may filter by team. Without any team the answers are exactly today's.
+// - An invisible session reads exactly like a foreign or unknown one: not_found "No session <addr>", and address
+//   resolution never counts it (no ambiguity, no candidate, no prefix match reveals it): Directory.resolve takes the
+//   visibility predicate for that.
+// - Every census reads the teams and seats fresh (no cache), so staffing, unstaffing, replacement generations,
+//   pause/archive and the isolation setting apply to the very next read.
+//
+// Directions: `reach` is what the caller may send to a member (`send`) and receive from it (`receive`), each kind
+// asked of teamDeliveryVerdict (never re-derived): per team with that team as the explicit context (the `#team`
+// address), and per entry without one (a plain address). Visibility is not authorization: delivery is still enforced
+// by the TeamPolicy (HWA-34) and acting by grants.
+//
+// Team role addresses (`@@role#team`, `@@role.project#team`) resolve here for reads (show, log, watch): the sessions
+// currently seated in that role of that active team, restricted to what the caller may see.
+//
+// Cost per census: one team list (paged, ≤ TEAM_LIMITS.teamsPerUser) and one current-seat read per active team, plus
+// the settings for team-scoped callers.
+import { parseTeamRoleAddress, teamDeliveryVerdict, type TeamMessageKind, type TeamSeat } from "../../protocol"
+import type { AgentActor } from "../agent/actor"
+import type { Directory, DirectoryEntry, Resolved } from "../agent/directory"
+import { AgentError } from "../agent/errors"
+import type { Registry } from "../registry"
+import type { TeamSeatStore } from "./seats"
+import type { Team, TeamStore } from "./store"
+
+const KINDS: readonly TeamMessageKind[] = ["msg", "ask"]
+/** Pages of the team list read per census (teamsPerUser is 100; a page holds the list's default limit). */
+const MAX_TEAM_PAGES = 20
+/** Most candidates listed in an ambiguous error (as the directory). */
+const CANDIDATES_MAX = 20
+
+/** What the caller may send to / receive from a session, from teamDeliveryVerdict. */
+export interface Reach {
+  readonly send: TeamMessageKind[]
+  readonly receive: TeamMessageKind[]
+  readonly direction: "two-way" | "outbound" | "inbound" | "none"
+  /** The caller can send nothing to it (a restricted path, or outside the caller's teams). */
+  readonly unreachable?: true
+}
+
+/** One team a listed session is seated in. */
+export interface TeamMembership {
+  readonly teamID: string
+  readonly team: string
+  readonly roles: string[]
+  /** Team-scoped callers only, never for themselves: with this team as the explicit context. */
+  readonly reach?: Reach
+}
+
+export interface TeamGroupMember {
+  readonly sessionID: string
+  readonly role: string
+  readonly generation: number
+}
+
+/** A team in a discovery answer, with its listed members. */
+export interface TeamGroup {
+  readonly teamID: string
+  readonly name: string
+  readonly title: string
+  readonly mode: "open" | "restricted"
+  readonly paused?: true
+  /** The caller's own roles there (team-scoped callers). */
+  readonly yourRoles?: string[]
+  readonly members: TeamGroupMember[]
+}
+
+/** A who entry: the directory entry plus additive team fields. */
+export type DiscoveryEntry = DirectoryEntry & {
+  readonly harness?: string
+  readonly teams?: TeamMembership[]
+  /** Team-scoped callers only, never for themselves: what a plain address (no #team) reaches. */
+  readonly reach?: Reach
+}
+
+export interface WhoAnswer {
+  readonly sessions: DiscoveryEntry[]
+  /** Present when any listed session is seated in a team (always for team-scoped callers). */
+  readonly teams?: TeamGroup[]
+  /** "team" when the caller sees its teams only; absent for the owner-wide view. */
+  readonly scope?: "team"
+}
+
+export interface WhoFilter {
+  readonly project?: string
+  readonly role?: string
+  /** A team name or ID. */
+  readonly team?: string
+}
+
+interface Seat extends TeamSeat {
+  readonly generation: number
+}
+
+/** One read of the user's active teams and current seats, and what the caller may see. */
+export interface Census {
+  readonly userID: string
+  /** Set when the caller is team-scoped. */
+  readonly callerID?: string
+  readonly callerTeams: ReadonlySet<string>
+  readonly isolation: boolean
+  readonly teams: ReadonlyMap<string, Team>
+  /** Current seats in active teams, per session. */
+  readonly seats: ReadonlyMap<string, readonly Seat[]>
+}
+
+export interface TeamDiscoveryDeps {
+  readonly teams: Pick<TeamStore, "list" | "settings">
+  readonly seats: Pick<TeamSeatStore, "list">
+  readonly directory: Pick<Directory, "who" | "resolve">
+  /** Harness per reported session of the user (who entries carry it when known). */
+  readonly harnesses?: (userID: string) => ReadonlyMap<string, string>
+}
+
+export const teamScoped = (census: Census): boolean => census.callerTeams.size > 0
+
+/** Whether the census's caller may see the session (always, for the owner-wide view). */
+export function visible(census: Census, sessionID: string): boolean {
+  if (!teamScoped(census) || sessionID === census.callerID) return true
+  const seats = census.seats.get(sessionID) ?? []
+  if (seats.some((s) => census.callerTeams.has(s.teamID))) return true
+  return !census.isolation && seats.length === 0
+}
+
+const missing = (addr: string) => new AgentError("not_found", `No session ${addr}`)
+
+/** Journal subject fields that name a session (an event naming any hidden one is hidden as a whole). */
+const SESSION_SUBJECT_FIELDS = ["sessionID", "rootID", "senderID", "recipientID", "sourceSessionID", "parentID"] as const
+
+/**
+ * The journal events a team-scoped caller may read (unfiltered GET /events and GET /watch, HWA-28): none naming a
+ * session it cannot see, nor a team it holds no seat in. Undefined for the owner-wide view (no filtering at all).
+ */
+export function eventVisibility(census: Census): ((subject: Readonly<Record<string, string>>) => boolean) | undefined {
+  if (!teamScoped(census)) return undefined
+  return (subject) => {
+    if (subject.teamID !== undefined && !census.callerTeams.has(subject.teamID)) return false
+    return SESSION_SUBJECT_FIELDS.every((field) => subject[field] === undefined || visible(census, subject[field]!))
+  }
+}
+
+export class TeamDiscovery {
+  constructor(private readonly deps: TeamDiscoveryDeps) {}
+
+  /** Reads the user's active teams, their current seats and the caller's scope. */
+  async census(userID: string, actor: AgentActor): Promise<Census> {
+    const teams = new Map<string, Team>()
+    let cursor: string | undefined
+    for (let page = 0; page < MAX_TEAM_PAGES; page++) {
+      const { items, cursor: next } = await this.deps.teams.list(userID, { state: "active", ...(cursor ? { cursor } : {}) })
+      for (const team of items) teams.set(team.id, team)
+      if (!next) break
+      cursor = next
+    }
+    const seats = new Map<string, Seat[]>()
+    for (const teamID of [...teams.keys()]) {
+      let current
+      try {
+        current = await this.deps.seats.list(userID, teamID, { current: true })
+      } catch {
+        teams.delete(teamID) // a seat aggregate this build cannot read takes no part (as in delivery)
+        continue
+      }
+      for (const s of current) seats.set(s.sessionID, [...(seats.get(s.sessionID) ?? []), { teamID, role: s.role, generation: s.generation }])
+    }
+    const callerID = actor.kind === "session" ? actor.sessionID : undefined
+    const callerTeams = new Set((callerID !== undefined ? (seats.get(callerID) ?? []) : []).map((s) => s.teamID))
+    let isolation = false
+    if (callerTeams.size) {
+      try {
+        isolation = (await this.deps.teams.settings(userID)).teamIsolation
+      } catch {
+        isolation = true // unreadable settings: show less, never more
+      }
+    }
+    return { userID, ...(callerTeams.size ? { callerID } : {}), callerTeams, isolation, teams, seats }
+  }
+
+  /**
+   * The sessions an address names for the caller (Directory.resolve plus `@@role#team`), never an invisible one.
+   * not_found when nothing visible matches; ambiguous lists visible candidates only.
+   */
+  resolve(census: Census, addr: string): Resolved {
+    const team = parseTeamRoleAddress(addr)
+    if (!team) return this.deps.directory.resolve(census.userID, addr, { visible: (id) => visible(census, id) })
+    const record = [...census.teams.values()].find((t) => t.name === team.team)
+    if (!record || (teamScoped(census) && !census.callerTeams.has(record.id))) throw missing(addr)
+    const sessions: DirectoryEntry[] = []
+    for (const [sessionID, seats] of census.seats) {
+      if (!seats.some((s) => s.teamID === record.id && s.role === team.role) || !visible(census, sessionID)) continue
+      const entry = this.entry(census.userID, sessionID)
+      if (entry && (team.project === undefined || entry.project === team.project)) sessions.push(entry)
+    }
+    if (!sessions.length) throw missing(addr)
+    return { address: { kind: "role", role: team.role, ...(team.project ? { project: team.project } : {}) }, sessions }
+  }
+
+  /** Exactly one visible session (a role with several visible holders is ambiguous). */
+  resolveOne(census: Census, addr: string): DirectoryEntry {
+    const { sessions } = this.resolve(census, addr)
+    if (sessions.length > 1) {
+      const candidates = sessions.slice(0, CANDIDATES_MAX).map((s) => ({ sessionID: s.sessionID, ...(s.name ? { name: s.name } : {}), ...(s.project ? { project: s.project } : {}) }))
+      throw new AgentError("ambiguous", `${addr} matches ${sessions.length} sessions`, { extra: { candidates } })
+    }
+    return sessions[0]!
+  }
+
+  /** GET /who: the caller's visible sessions, filtered, with team memberships, reach and groups. */
+  who(census: Census, filter: WhoFilter = {}): WhoAnswer {
+    const { userID } = census
+    const project = filter.project?.toLowerCase()
+    let role = filter.role?.replace(/^@@/, "")
+    let teamName = filter.team
+    if (role?.includes("#")) {
+      const parsed = parseTeamRoleAddress(`@@${role}`)
+      if (!parsed) throw new AgentError("invalid", "A role is 2–40 characters: a-z, 0-9 and -, optionally .project and #team")
+      if (teamName !== undefined && teamName !== parsed.team) throw new AgentError("invalid", "role names another team than team")
+      role = parsed.project ? `${parsed.role}.${parsed.project}` : parsed.role
+      teamName = parsed.team
+    }
+    const team = teamName !== undefined ? this.team(census, teamName) : undefined
+    const [roleName, inlineProject] = role?.split(".") ?? []
+    const roleProject = inlineProject?.toLowerCase() ?? project
+    // Global role holders (Directory.who validates the role) and the base list.
+    const globalHolders = role !== undefined ? new Set(this.deps.directory.who(userID, { ...(project ? { project } : {}), role }).map((e) => e.sessionID)) : undefined
+    const listed = new Map(this.deps.directory.who(userID, project ? { project } : {}).map((e) => [e.sessionID, e] as const))
+    // Seated members the directory does not list (offline, unnamed): every teammate, and a filtered team's members.
+    const extra = new Set(team ? [team.id] : [...census.callerTeams])
+    for (const [sessionID, seats] of census.seats) {
+      if (listed.has(sessionID) || !seats.some((s) => extra.has(s.teamID))) continue
+      const entry = this.entry(userID, sessionID)
+      if (entry && !entry.archived && (project === undefined || entry.project === project || entry.roles.some((r) => r.project === project))) listed.set(sessionID, entry)
+    }
+    const entries = [...listed.values()]
+      .filter((e) => visible(census, e.sessionID))
+      .filter((e) => !team || this.shown(census, e.sessionID).some((s) => s.teamID === team.id))
+      .filter((e) => {
+        if (role === undefined) return true
+        const seated = this.shown(census, e.sessionID).some((s) => s.role === roleName && (!team || s.teamID === team.id) && (roleProject === undefined || e.project === roleProject))
+        return seated || (!team && globalHolders!.has(e.sessionID))
+      })
+    const harnesses = this.deps.harnesses?.(userID)
+    const sessions = entries.map((e) => this.annotate(census, e, harnesses?.get(e.sessionID)))
+    const teams = this.groups(census, sessions.map((s) => s.sessionID), team?.id)
+    return { sessions, ...(teams.length ? { teams } : {}), ...(teamScoped(census) ? { scope: "team" as const } : {}) }
+  }
+
+  /** Team groups of the listed sessions (the caller's teams only, all of them, when team-scoped), by team name. */
+  groups(census: Census, sessionIDs: readonly string[], only?: string): TeamGroup[] {
+    const out = new Map<string, TeamGroupMember[]>()
+    if (teamScoped(census)) for (const teamID of census.callerTeams) if (only === undefined || only === teamID) out.set(teamID, [])
+    for (const id of sessionIDs) {
+      for (const s of this.shown(census, id)) {
+        if (only !== undefined && s.teamID !== only) continue
+        out.set(s.teamID, [...(out.get(s.teamID) ?? []), { sessionID: id, role: s.role, generation: s.generation }])
+      }
+    }
+    return [...out]
+      .map(([teamID, members]) => {
+        const team = census.teams.get(teamID)!
+        const yours = census.callerID !== undefined ? (census.seats.get(census.callerID) ?? []).filter((s) => s.teamID === teamID).map((s) => s.role) : []
+        return { teamID, name: team.name, title: team.title, mode: team.mode, ...(team.paused ? { paused: true as const } : {}), ...(yours.length ? { yourRoles: yours } : {}), members }
+      })
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+  }
+
+  /** The session's team memberships as the caller may see them (show), each with reach when team-scoped. */
+  memberships(census: Census, sessionID: string): TeamMembership[] {
+    const byTeam = new Map<string, string[]>()
+    for (const s of this.shown(census, sessionID)) byTeam.set(s.teamID, [...(byTeam.get(s.teamID) ?? []), s.role])
+    return [...byTeam].map(([teamID, roles]) => {
+      const reach = this.reachOf(census, sessionID, teamID)
+      return { teamID, team: census.teams.get(teamID)!.name, roles, ...(reach ? { reach } : {}) }
+    })
+  }
+
+  /** What a team-scoped caller may send to / receive from the session (undefined otherwise, and for itself). */
+  reachOf(census: Census, sessionID: string, teamID?: string): Reach | undefined {
+    const caller = census.callerID
+    if (!teamScoped(census) || caller === undefined || sessionID === caller) return undefined
+    const mine = census.seats.get(caller) ?? []
+    const theirs = census.seats.get(sessionID) ?? []
+    const allowed = (from: readonly Seat[], to: readonly Seat[], kind: TeamMessageKind) =>
+      teamDeliveryVerdict({ kind, toUser: false, replyToPermittedAsk: false, senderSeats: from, recipientSeats: to, ...(teamID !== undefined ? { teamID } : {}), teams: census.teams }).allow
+    const send = KINDS.filter((k) => allowed(mine, theirs, k))
+    const receive = KINDS.filter((k) => allowed(theirs, mine, k))
+    const direction = send.length && receive.length ? "two-way" : send.length ? "outbound" : receive.length ? "inbound" : "none"
+    return { send, receive, direction, ...(send.length ? {} : { unreachable: true as const }) }
+  }
+
+  // ---------- internals ----------
+
+  /** The seats of a session the caller may be told about: in its own teams when team-scoped, else all. */
+  private shown(census: Census, sessionID: string): readonly Seat[] {
+    const seats = census.seats.get(sessionID) ?? []
+    return teamScoped(census) ? seats.filter((s) => census.callerTeams.has(s.teamID)) : seats
+  }
+
+  private annotate(census: Census, entry: DirectoryEntry, harness: string | undefined): DiscoveryEntry {
+    const teams = this.memberships(census, entry.sessionID)
+    const reach = this.reachOf(census, entry.sessionID)
+    return { ...entry, ...(harness ? { harness } : {}), ...(teams.length ? { teams } : {}), ...(reach ? { reach } : {}) }
+  }
+
+  /** A team filter: by name or ID, among the caller's teams when team-scoped (else not_found, like a missing one). */
+  private team(census: Census, nameOrID: string): Team {
+    const team = census.teams.get(nameOrID) ?? [...census.teams.values()].find((t) => t.name === nameOrID)
+    if (!team || (teamScoped(census) && !census.callerTeams.has(team.id))) throw new AgentError("not_found", `No team ${nameOrID}`)
+    return team
+  }
+
+  private entry(userID: string, sessionID: string): DirectoryEntry | undefined {
+    try {
+      return this.deps.directory.resolve(userID, sessionID).sessions.find((e) => e.sessionID === sessionID)
+    } catch {
+      return undefined
+    }
+  }
+}
+
+/** The harness of each session the user's spokes report now (roots and their subagents), from the catalog. */
+export function catalogHarnesses(registry: Pick<Registry, "catalog" | "sessionTenant">): (userID: string) => ReadonlyMap<string, string> {
+  return (userID) => {
+    const out = new Map<string, string>()
+    for (const machine of registry.catalog()) {
+      for (const process of machine.processes) {
+        for (const s of process.sessions) {
+          if (registry.sessionTenant(s.id) !== userID) continue
+          for (const id of [s.id, ...s.status.map((e) => e.id)]) if (!out.has(id)) out.set(id, process.harness)
+        }
+      }
+    }
+    return out
+  }
+}