@huynle/hub 0.7.3 → 0.8.0

package/src/central/agent/interaction-graph.ts

@@ -0,0 +1,865 @@
+// The interaction graph projection behind the Watchtower (HWA-31; contract packages/protocol/src/graph.ts,
+// decision 5e4l4u8v). A bounded, authorized, deterministic snapshot of who talks to whom through the hub:
+//
+// - Nodes: the hub, the user (@me), the user's machines (online or quiet), every session of the directory that is
+//   not archived or deleted (quiet and offline ones too), apps that appear in traffic, teams. Sessions carry the
+//   registry's machine, harness and state, the native parentID (subsession clusters), and — as separate overlays —
+//   workspace supervision (supervisorID) and team seats (teamIDs; `seats` adds the role, HWA-38). Teams carry
+//   their role names and entry role. Labels are only @names, session IDs, machine names and team titles: never
+//   titles, prompts or message text.
+// - Edges: messages aggregated per (kind, from, to) inside the window, with counts, first/last time, ask states,
+//   delivery modes and role-addressed counts; asks to @me carrying a Decision are `decision`; replies and declines
+//   are `reply` (declines counted). `launch` edges go from the launcher to the session. `policy` edges are the
+//   permitted paths of restricted teams between seated sessions (traffic along them counted) plus `denied` counts
+//   from the team.denied audit (denial-only edges have `permitted: false`).
+// - Visibility: the user sees everything. Sessions and apps (sessions:read + messages:read) see every session
+//   node, as GET /sessions does, but only traffic they sent or received (as GET /messages/:id); apps see teams
+//   with teams:read and supervision with workspaces:read; denials are the user's audit only. Launch edges,
+//   `launchID` and free-form launch `labels` follow the launch read rule (launch-routes.ts): the user all, apps
+//   with sessions:launch and sessions through their act token only launches they started, others none. Archived and deleted
+//   sessions are hidden with their traffic (`hidden.messages`). Another tenant's IDs simply do not exist here.
+// - Limits: GRAPH_LIMITS. Over `limit` nodes or GRAPH_LIMITS.edges edges the busiest are kept (`capped`).
+// - Retention: the message store's caps evict silently; `retention.truncated` says traffic inside the window may
+//   be missing (Messages.retention().evictedAt), `oldestAt` is the oldest retained interaction the viewer sees.
+// - Detail: edgeDetail/nodeDetail page message summaries (IDs, kinds, states, times; never text), newest first,
+//   with an opaque cursor. Text is read only through GET /api/agent/messages/:id. Unknown, foreign, hidden and
+//   other-party edges/nodes all answer the same not_found.
+// - Live updates: no new writer. Canonical journal events (message.changed, session.*, role.*, machine.changed,
+//   launch.changed, team.*, workspace.*) are the invalidation hints; graphInvalidation maps one to a compact
+//   `graph.invalidated` hint (IDs only). A journal `reset` means: take a new snapshot.
+import { GRAPH_LIMITS, type GraphEdge, type GraphNode, type GraphNodeKind, type GraphSnapshot, type TeamEdge } from "../../protocol"
+import type { AgentSession } from "../agent-data"
+import { type AgentActor, canActAsSession } from "./actor"
+import type { Decisions } from "./decisions"
+import type { Directory } from "./directory"
+import type { AgentEvent } from "./events"
+import { type Party, partyKey, sanitizeLabel } from "./envelope"
+import { AgentError } from "./errors"
+import type { Delivery, Message, Messages } from "./messages"
+import type { ReadRegistry } from "./read-routes"
+
+export type GraphEdgeKind = GraphEdge["kind"]
+export type GraphStatus = NonNullable<GraphNode["status"]>
+
+export const GRAPH_EDGE_KINDS: readonly GraphEdgeKind[] = ["msg", "ask", "reply", "decision", "launch", "policy"]
+export const GRAPH_STATUSES: readonly GraphStatus[] = ["idle", "working", "blocked", "error", "offline", "ended"]
+/** Message summaries per detail page. */
+export const GRAPH_DETAIL_PAGE = { default: 50, max: 200 } as const
+/** The fixed party HWA-11's supervisor digests come from (coordinatorActor). */
+export const COORDINATOR_PARTY = "app:workspace-coordinator"
+/** The fixed party of the Concierge service (CONCIERGE_PARTY, CON-04). */
+const CONCIERGE_APP_PARTY = "app:concierge"
+/** Characters of a filter value. */
+const FILTER_MAX = 200
+/** Native ancestry deeper than this is not followed (cycles in bad data). */
+const DEPTH_MAX = 32
+
+// ---- Sources ------------------------------------------------------------------------------------------------
+
+export interface GraphLaunch {
+  readonly id: string
+  /** `app:<token id>`, `ses_…` or `user` (Launch.by). */
+  readonly by?: string
+  readonly sessionID?: string
+  readonly state: string
+  readonly created: number
+  readonly spec: { readonly labels?: Readonly<Record<string, string>>; readonly harness?: string }
+}
+
+export interface GraphTeam {
+  readonly id: string
+  readonly name: string
+  readonly title: string
+  readonly state: string
+  readonly mode: "open" | "restricted"
+  readonly roles: readonly { readonly name: string }[]
+  /** The intake role (HWA-38 highlights it in team clusters). */
+  readonly entryRole?: string
+  readonly edges: readonly TeamEdge[]
+  readonly tags?: readonly string[]
+  readonly projects?: readonly string[]
+  readonly metadata?: Readonly<Record<string, string>>
+  readonly paused?: boolean
+}
+
+export interface GraphSeat {
+  readonly teamID: string
+  readonly role: string
+  readonly sessionID: string
+}
+
+/** A current workspace membership, with the member's supervisor's session (supervision overlay). */
+export interface GraphMembership {
+  readonly workspaceID: string
+  readonly sessionID: string
+  readonly supervisorSessionID?: string
+}
+
+/** A team policy refusal (the user's audit, `team.denied`): IDs only. */
+export interface GraphDenial {
+  readonly at: number
+  readonly senderID: string
+  readonly recipientID?: string
+}
+
+/** Everything the projection reads; each optional source adds its overlay. */
+export interface GraphSources {
+  readonly now: () => number
+  /** The user's machines (not revoked). */
+  machines(userID: string): readonly { readonly id: string; readonly name: string }[]
+  readonly registry: Pick<ReadRegistry, "catalog" | "sessionTenant">
+  /** The directory's session records (archived and deleted included: they are hidden here). */
+  sessions(userID: string): readonly AgentSession[]
+  readonly directory: Pick<Directory, "who">
+  readonly messages: Pick<Messages, "all" | "retention">
+  readonly decisions?: Pick<Decisions, "list">
+  launches?(userID: string): Promise<readonly GraphLaunch[]>
+  teams?(userID: string): Promise<{ readonly teams: readonly GraphTeam[]; readonly seats: readonly GraphSeat[] }>
+  supervision?(userID: string): Promise<readonly GraphMembership[]>
+  denials?(userID: string): Promise<readonly GraphDenial[]>
+}
+
+// ---- Views (additive to the frozen GraphNode/GraphEdge) -----------------------------------------------------
+
+export interface GraphNodeView extends GraphNode {
+  /** Apps (kind user) and the workspace coordinator (kind hub) are app parties. */
+  readonly party?: "app"
+  readonly online?: boolean
+  /** Machines: harness kinds of their connected processes. */
+  readonly harnesses?: readonly string[]
+  /** Sessions: role labels (`role` or `role.project`). */
+  readonly roles?: readonly string[]
+  readonly lastSeen?: number
+  /** Sessions: native depth (0 for a root) and root. */
+  readonly depth?: number
+  readonly rootID?: string
+  readonly workspaceIDs?: readonly string[]
+  /** Sessions a launch started: the latest launch and its labels (sanitized). */
+  readonly launchID?: string
+  readonly labels?: Readonly<Record<string, string>>
+  /** Teams. */
+  readonly name?: string
+  readonly projects?: readonly string[]
+  readonly mode?: "open" | "restricted"
+  readonly paused?: boolean
+  readonly metadata?: Readonly<Record<string, string>>
+  /** Teams (HWA-38): the entry role; `roles` carries a team's role names in definition order. */
+  readonly entryRole?: string
+  /** Sessions (HWA-38): the (team, role) seats they hold, sorted; only with team visibility, like `teamIDs`. */
+  readonly seats?: readonly { readonly teamID: string; readonly role: string }[]
+}
+
+export type AskState = "open" | "answered" | "declined" | "expired"
+
+export interface GraphEdgeView extends GraphEdge {
+  readonly firstAt?: number
+  /** Asks and Decisions: how many are in each state now. */
+  readonly states?: Partial<Record<AskState, number>>
+  /** How messages reached the recipient (absent: not recorded, e.g. stored only). */
+  readonly delivery?: Partial<Record<Delivery, number>>
+  /** Reply edges: how many were declines. */
+  readonly declined?: number
+  /** Messages sent to a role address (`@@role…`). */
+  readonly roleAddressed?: number
+  readonly maxHop?: number
+  /** Policy edges: a permitted team path (true) or only refused attempts (false). */
+  readonly permitted?: boolean
+  readonly kinds?: readonly string[]
+}
+
+export interface GraphSnapshotView extends GraphSnapshot {
+  readonly nodes: readonly GraphNodeView[]
+  readonly edges: readonly GraphEdgeView[]
+  /** Traffic left out because an endpoint is archived or deleted. */
+  readonly hidden: { readonly messages: number }
+}
+
+export interface MessageSummary {
+  readonly id: string
+  readonly kind: Message["kind"]
+  readonly state: Message["state"]
+  readonly from: string
+  readonly to: string
+  /** The address as the sender wrote it (sanitized): `@name`, `@@role`, `ses_…`, `@me`. */
+  readonly address: string
+  readonly at: number
+  readonly hop: number
+  readonly generation?: number
+  readonly replyTo?: string
+  readonly answer?: { readonly id: string; readonly at: number }
+  readonly expiresAt?: number
+  readonly delivery?: Delivery
+  readonly deliveredAt?: number
+  readonly decisionID?: string
+}
+
+// ---- Viewer and query -----------------------------------------------------------------------------------------
+
+export interface GraphViewer {
+  readonly kind: AgentActor["kind"]
+  /** Non-user viewers: their party key; they see only traffic they are a party of. */
+  readonly party?: string
+  /**
+   * Launch reads mirror launch-routes.ts (LAUNCH allow + launchedBy): users read every launch; apps with
+   * sessions:launch and sessions through their act token read only launches they started (`launcher`); others
+   * read none. Launch edges, `launchID` and the free-form `labels` follow it.
+   */
+  readonly launches: boolean
+  /** Non-user viewers: launches they started (Launch.by). */
+  readonly launcher?: string
+  readonly teams: boolean
+  readonly supervision: boolean
+  readonly denials: boolean
+}
+
+/** What the actor may see; an app also needs messages:read (the route checks sessions:read). */
+export function viewerOf(actor: AgentActor): GraphViewer {
+  switch (actor.kind) {
+    case "user":
+      return { kind: "user", launches: true, teams: true, supervision: true, denials: true }
+    case "session":
+      return { kind: "session", party: partyKey({ kind: "session", sessionID: actor.sessionID }), launches: canActAsSession(actor), launcher: actor.sessionID, teams: false, supervision: false, denials: false }
+    case "app": {
+      if (!actor.scopes.includes("messages:read")) throw new AgentError("forbidden", "Reading the interaction graph needs sessions:read and messages:read", { hint: "Create an app token with both scopes" })
+      const party = partyKey({ kind: "app", tokenID: actor.tokenID })
+      return { kind: "app", party, launches: actor.scopes.includes("sessions:launch"), launcher: party, teams: actor.scopes.includes("teams:read"), supervision: actor.scopes.includes("workspaces:read"), denials: false }
+    }
+  }
+}
+
+export interface GraphQuery {
+  readonly since: number
+  readonly until: number
+  readonly limit: number
+  readonly machine?: string
+  readonly harness?: string
+  readonly team?: string
+  readonly tag?: string
+  readonly project?: string
+  /** A session ID: it and its native descendants. */
+  readonly session?: string
+  readonly workspace?: string
+  readonly kinds?: ReadonlySet<GraphEdgeKind>
+  readonly states?: ReadonlySet<GraphStatus>
+}
+
+const invalid = (message: string) => new AgentError("invalid", message)
+
+function intParam(params: URLSearchParams, name: string): number | undefined {
+  const raw = params.get(name)
+  if (raw === null || raw === "") return undefined
+  if (!/^\d{1,15}$/.test(raw)) throw invalid(`${name} must be a whole number${name === "limit" ? "" : " of milliseconds since the epoch"}`)
+  return Number(raw)
+}
+
+function textParam(params: URLSearchParams, name: string): string | undefined {
+  const raw = params.get(name)?.trim()
+  if (!raw) return undefined
+  if (raw.length > FILTER_MAX) throw invalid(`${name} is longer than ${FILTER_MAX} characters`)
+  return raw
+}
+
+function listParam<T extends string>(params: URLSearchParams, name: string, allowed: readonly T[]): ReadonlySet<T> | undefined {
+  const raw = params.get(name)
+  if (raw === null || raw === "") return undefined
+  const values = raw.split(",").filter(Boolean)
+  if (values.some((v) => !allowed.includes(v as T))) throw invalid(`${name} is a comma list of ${allowed.join(", ")}`)
+  return new Set(values as T[])
+}
+
+/** since/until (ms; default the last 24 h; at most 7 days). */
+function windowOf(params: URLSearchParams, now: number): { since: number; until: number } {
+  const until = intParam(params, "until") ?? now
+  const since = intParam(params, "since") ?? until - GRAPH_LIMITS.defaultWindowMs
+  if (since > until) throw invalid("since must not be after until")
+  if (until - since > GRAPH_LIMITS.windowMs) throw invalid(`The window is at most ${GRAPH_LIMITS.windowMs / 86_400_000} days`)
+  return { since, until }
+}
+
+/** GET /api/agent/graph's query: window, limit and filters (invalid on anything malformed). */
+export function parseGraphQuery(params: URLSearchParams, now: number): GraphQuery {
+  const limit = intParam(params, "limit") ?? GRAPH_LIMITS.nodes
+  if (limit < 1 || limit > GRAPH_LIMITS.nodes) throw invalid(`limit must be 1–${GRAPH_LIMITS.nodes}`)
+  const out: Record<string, unknown> = { ...windowOf(params, now), limit }
+  for (const name of ["machine", "harness", "team", "tag", "project", "session", "workspace"] as const) {
+    const value = textParam(params, name)
+    if (value !== undefined) out[name] = value
+  }
+  const kinds = listParam(params, "kind", GRAPH_EDGE_KINDS)
+  const states = listParam(params, "state", GRAPH_STATUSES)
+  if (kinds) out.kinds = kinds
+  if (states) out.states = states
+  return out as unknown as GraphQuery
+}
+
+// ---- Projection -------------------------------------------------------------------------------------------------
+
+interface EdgeAcc {
+  readonly id: string
+  readonly kind: GraphEdgeKind
+  readonly from: string
+  readonly to: string
+  readonly teamID?: string
+  count: number
+  lastAt: number
+  firstAt?: number
+  denied: number
+  declined: number
+  roleAddressed: number
+  maxHop: number
+  permitted?: boolean
+  kinds?: Set<string>
+  readonly states: Partial<Record<AskState, number>>
+  readonly delivery: Partial<Record<Delivery, number>>
+  readonly messages: Message[]
+}
+
+interface Projection {
+  readonly nodes: Map<string, GraphNodeView>
+  readonly edges: Map<string, EdgeAcc>
+  /** Visible traffic in the window, oldest first. */
+  readonly messages: Message[]
+  readonly decisionOf: ReadonlyMap<string, string>
+  readonly hidden: number
+  readonly retention: GraphSnapshot["retention"]
+}
+
+const RANK: Record<GraphNodeKind, number> = { hub: 0, user: 1, machine: 2, team: 3, session: 5 }
+const rankOf = (node: GraphNodeView) => (node.id === "hub" ? 0 : node.id === "@me" ? 1 : node.party === "app" ? 4 : RANK[node.kind])
+const byID = (a: { id: string }, b: { id: string }) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
+const machineNode = (id: string) => `machine:${id}`
+
+/** A party's node ID: the session ID, `@me`, or `app:<token id>`. */
+export function partyNode(party: Party): string {
+  return party.kind === "session" ? party.sessionID : party.kind === "user" ? "@me" : partyKey(party)
+}
+
+function edgeKindOf(message: Message, decisionOf: ReadonlyMap<string, string>): GraphEdgeKind {
+  if (message.kind === "ask") return decisionOf.has(message.id) ? "decision" : "ask"
+  return message.kind === "msg" ? "msg" : "reply"
+}
+
+const edgeID = (kind: GraphEdgeKind, from: string, to: string, teamID?: string) => (kind === "policy" ? `policy|${from}|${to}|${teamID ?? ""}` : `${kind}|${from}|${to}`)
+
+function newEdge(kind: GraphEdgeKind, from: string, to: string, teamID?: string): EdgeAcc {
+  return { id: edgeID(kind, from, to, teamID), kind, from, to, ...(teamID !== undefined ? { teamID } : {}), count: 0, lastAt: 0, denied: 0, declined: 0, roleAddressed: 0, maxHop: 0, states: {}, delivery: {}, messages: [] }
+}
+
+function bump<K extends string>(record: Partial<Record<K, number>>, key: K): void {
+  record[key] = (record[key] ?? 0) + 1
+}
+
+function cleanLabels(labels: Readonly<Record<string, string>> | undefined): Record<string, string> | undefined {
+  if (!labels) return undefined
+  const out: Record<string, string> = {}
+  for (const [key, value] of Object.entries(labels)) {
+    const k = sanitizeLabel(String(key))
+    const v = sanitizeLabel(String(value))
+    if (k) out[k] = v
+  }
+  return Object.keys(out).length ? out : undefined
+}
+
+interface Live {
+  readonly harness: string
+  readonly machineID: string
+  readonly state: string
+  readonly parentID?: string
+}
+
+/** The user's live sessions (roots and subsessions) from the registry, tenant-checked: harness, machine, state. */
+function liveSessions(sources: GraphSources, userID: string): { sessions: Map<string, Live>; machines: Map<string, Set<string>> } {
+  const sessions = new Map<string, Live>()
+  const machines = new Map<string, Set<string>>()
+  for (const machine of sources.registry.catalog()) {
+    const harnesses = machines.get(machine.id) ?? new Set<string>()
+    machines.set(machine.id, harnesses)
+    for (const process of machine.processes) {
+      // A process reporting only another tenant's sessions says nothing about this user's machine.
+      if (!process.sessions.length || process.sessions.some((s) => sources.registry.sessionTenant(s.id) === userID)) harnesses.add(process.harness)
+      for (const session of process.sessions) {
+        if (sources.registry.sessionTenant(session.id) !== userID) continue
+        const tree = session.status?.length ? session.status : [{ id: session.id, state: session.state, ...(session.parentID ? { parentID: session.parentID } : {}) }]
+        for (const entry of tree) {
+          if (sessions.has(entry.id)) continue
+          sessions.set(entry.id, { harness: process.harness, machineID: machine.id, state: entry.state, ...(entry.parentID ? { parentID: entry.parentID } : {}) })
+        }
+      }
+    }
+  }
+  return { sessions, machines }
+}
+
+const STATUS: ReadonlySet<string> = new Set(GRAPH_STATUSES)
+
+/** A recorded harness kind, if it is one (records are free-form JSON). */
+const knownHarness = (value: unknown): string | undefined => (typeof value === "string" && /^[a-z0-9][a-z0-9._-]{0,63}$/.test(value) ? value : undefined)
+
+async function project(sources: GraphSources, userID: string, viewer: GraphViewer, since: number, until: number): Promise<Projection> {
+  const nodes = new Map<string, GraphNodeView>()
+  const put = (node: GraphNodeView) => nodes.set(node.id, node)
+  put({ id: "hub", kind: "hub", label: "Hub" })
+  put({ id: "@me", kind: "user", label: "@me" })
+
+  // Machines and sessions.
+  const live = liveSessions(sources, userID)
+  for (const m of sources.machines(userID)) {
+    const harnesses = live.machines.get(m.id)
+    put({ id: machineNode(m.id), kind: "machine", label: sanitizeLabel(m.name) || m.id, machineID: m.id, online: harnesses !== undefined, ...(harnesses?.size ? { harnesses: [...harnesses].sort() } : {}) })
+  }
+  const records = new Map<string, AgentSession>()
+  const hiddenSessions = new Set<string>()
+  for (const record of sources.sessions(userID) ?? []) {
+    if (!record?.sessionID) continue
+    if (record.archivedAt !== undefined || record.deletedAt !== undefined) hiddenSessions.add(record.sessionID)
+    else records.set(record.sessionID, record)
+  }
+  for (const [id, l] of live.sessions) if (!records.has(id) && !hiddenSessions.has(id)) records.set(id, { sessionID: id, machineID: l.machineID, ...(l.parentID ? { parentID: l.parentID } : {}) })
+  const entries = new Map(sources.directory.who(userID).map((e) => [e.sessionID, e]))
+  const parentOf = (id: string) => records.get(id)?.parentID ?? live.sessions.get(id)?.parentID
+  for (const [id, record] of records) {
+    const entry = entries.get(id)
+    const l = live.sessions.get(id)
+    let depth = 0
+    let root = id
+    for (let up = parentOf(id); up !== undefined && depth < DEPTH_MAX && records.has(up); up = parentOf(up)) {
+      depth++
+      root = up
+    }
+    const parentID = parentOf(id)
+    const machineID = l?.machineID ?? record.machineID
+    const state = l ? (STATUS.has(l.state) ? (l.state as GraphStatus) : "idle") : "offline"
+    const roles = (entry?.roles ?? []).map((r) => (r.project !== undefined ? `${r.role}.${r.project}` : r.role))
+    const harness = l?.harness ?? knownHarness(record.harness)
+    put({
+      id,
+      kind: "session",
+      label: entry?.name ? `@${entry.name}` : id,
+      ...(machineID ? { machineID } : {}),
+      ...(harness ? { harness } : {}),
+      ...(parentID ? { parentID } : {}),
+      status: state,
+      ...(record.project ? { project: record.project } : {}),
+      online: l !== undefined || entry?.online === true,
+      ...(record.lastSeen !== undefined ? { lastSeen: record.lastSeen } : {}),
+      depth,
+      ...(depth > 0 ? { rootID: root } : {}),
+      ...(roles.length ? { roles } : {}),
+    })
+  }
+  const isSession = (id: string) => nodes.get(id)?.kind === "session"
+  const update = (id: string, patch: Partial<GraphNodeView>) => {
+    const node = nodes.get(id)
+    if (node) nodes.set(id, { ...node, ...patch })
+  }
+
+  // Overlays: supervision, teams, launches.
+  const edges = new Map<string, EdgeAcc>()
+  const edgeFor = (kind: GraphEdgeKind, from: string, to: string, teamID?: string) => {
+    const id = edgeID(kind, from, to, teamID)
+    let acc = edges.get(id)
+    if (!acc) edges.set(id, (acc = newEdge(kind, from, to, teamID)))
+    return acc
+  }
+  if (viewer.supervision && sources.supervision) {
+    const workspaces = new Map<string, Set<string>>()
+    const supervisors = new Map<string, string>()
+    for (const m of await sources.supervision(userID)) {
+      if (!isSession(m.sessionID)) continue
+      ;(workspaces.get(m.sessionID) ?? workspaces.set(m.sessionID, new Set()).get(m.sessionID)!).add(m.workspaceID)
+      if (m.supervisorSessionID !== undefined && isSession(m.supervisorSessionID) && !supervisors.has(m.sessionID)) supervisors.set(m.sessionID, m.supervisorSessionID)
+    }
+    for (const [id, set] of workspaces) update(id, { workspaceIDs: [...set].sort(), ...(supervisors.has(id) ? { supervisorID: supervisors.get(id)! } : {}) })
+  }
+  let teamData: Awaited<ReturnType<NonNullable<GraphSources["teams"]>>> | undefined
+  if (viewer.teams && sources.teams) {
+    teamData = await sources.teams(userID)
+    const seatsOf = new Map<string, Set<string>>()
+    for (const team of teamData.teams) {
+      if (team.state !== "active") continue
+      put({
+        id: team.id,
+        kind: "team",
+        label: sanitizeLabel(team.title) || team.name,
+        name: team.name,
+        mode: team.mode,
+        ...(team.roles.length ? { roles: team.roles.map((r) => r.name) } : {}),
+        ...(team.entryRole ? { entryRole: team.entryRole } : {}),
+        ...(team.tags?.length ? { tags: [...team.tags] } : {}),
+        ...(team.projects?.length ? { project: team.projects[0]!, projects: [...team.projects] } : {}),
+        ...(team.paused ? { paused: true } : {}),
+        ...(team.metadata && Object.keys(team.metadata).length ? { metadata: cleanLabels(team.metadata)! } : {}),
+      })
+    }
+    const rolesOf = new Map<string, Map<string, { teamID: string; role: string }>>()
+    for (const seat of teamData.seats) {
+      if (!isSession(seat.sessionID) || nodes.get(seat.teamID)?.kind !== "team") continue
+      ;(seatsOf.get(seat.sessionID) ?? seatsOf.set(seat.sessionID, new Set()).get(seat.sessionID)!).add(seat.teamID)
+      ;(rolesOf.get(seat.sessionID) ?? rolesOf.set(seat.sessionID, new Map()).get(seat.sessionID)!).set(`${seat.teamID}\u0000${seat.role}`, { teamID: seat.teamID, role: seat.role })
+    }
+    const bySeat = (a: { teamID: string; role: string }, b: { teamID: string; role: string }) => (a.teamID < b.teamID ? -1 : a.teamID > b.teamID ? 1 : a.role < b.role ? -1 : a.role > b.role ? 1 : 0)
+    for (const [id, set] of seatsOf) update(id, { teamIDs: [...set].sort(), seats: [...rolesOf.get(id)!.values()].sort(bySeat) })
+  }
+  if (viewer.launches && sources.launches) {
+    // Only launches the viewer may read (all for the user, its own otherwise): the latest of them labels a session.
+    const launches = [...(await sources.launches(userID))]
+      .filter((launch) => viewer.launcher === undefined || launch.by === viewer.launcher)
+      .sort((a, b) => a.created - b.created || (a.id < b.id ? -1 : 1))
+    for (const launch of launches) {
+      if (launch.sessionID === undefined || !isSession(launch.sessionID)) continue
+      const labels = cleanLabels(launch.spec.labels)
+      const { labels: _previous, ...node } = nodes.get(launch.sessionID)!
+      const harness = node.harness ?? knownHarness(launch.spec.harness)
+      put({ ...node, launchID: launch.id, ...(labels ? { labels } : {}), ...(harness ? { harness } : {}) })
+      if (launch.by === undefined || launch.created < since || launch.created > until) continue
+      const from = launch.by === "user" ? "@me" : launch.by.startsWith("app:") ? launch.by : isSession(launch.by) ? launch.by : undefined
+      if (from === undefined) continue
+      if (from.startsWith("app:") && !nodes.has(from)) put(appNode(from))
+      const acc = edgeFor("launch", from, launch.sessionID)
+      acc.count++
+      acc.firstAt = Math.min(acc.firstAt ?? launch.created, launch.created)
+      acc.lastAt = Math.max(acc.lastAt, launch.created)
+    }
+  }
+
+  // A legacy offline session (recorded before the directory kept harnesses) on a machine whose processes for this
+  // user all run one harness: that harness. Never across tenants (liveSessions only counts this user's processes).
+  for (const node of nodes.values()) {
+    if (node.kind !== "session" || node.harness !== undefined || node.machineID === undefined) continue
+    const only = live.machines.get(node.machineID)
+    if (only?.size === 1) update(node.id, { harness: [...only][0]! })
+  }
+
+  // Messages.
+  const [all, retention, decisions] = await Promise.all([
+    sources.messages.all(userID),
+    sources.messages.retention(userID),
+    sources.decisions ? sources.decisions.list(userID) : Promise.resolve([]),
+  ])
+  const decisionOf = new Map(decisions.map((d) => [d.messageID, d.id]))
+  const visible = all.filter((m) => viewer.party === undefined || partyKey(m.from) === viewer.party || partyKey(m.recipient) === viewer.party)
+  const known = (party: Party) => party.kind !== "session" || isSession(party.sessionID)
+  const messages: Message[] = []
+  let hidden = 0
+  for (const m of visible) {
+    if (m.at < since || m.at > until) continue
+    if (!known(m.from) || !known(m.recipient)) {
+      hidden++
+      continue
+    }
+    messages.push(m)
+    for (const party of [m.from, m.recipient]) {
+      const id = partyNode(party)
+      if (party.kind === "app" && !nodes.has(id)) put(appNode(id, party.label))
+    }
+    const acc = edgeFor(edgeKindOf(m, decisionOf), partyNode(m.from), partyNode(m.recipient))
+    acc.count++
+    acc.firstAt = Math.min(acc.firstAt ?? m.at, m.at)
+    acc.lastAt = Math.max(acc.lastAt, m.at)
+    acc.maxHop = Math.max(acc.maxHop, m.hop)
+    if (m.to.startsWith("@@")) acc.roleAddressed++
+    if (m.kind === "ask") bump(acc.states, m.state as AskState)
+    if (m.kind === "decline") acc.declined++
+    if (m.delivery) bump(acc.delivery, m.delivery)
+    acc.messages.push(m)
+  }
+
+  // Team policy overlay: permitted paths of restricted teams between seated sessions, and refusals.
+  if (teamData) {
+    const seated = new Map<string, Map<string, string[]>>() // teamID → role → sessions
+    for (const seat of teamData.seats) {
+      if (!isSession(seat.sessionID)) continue
+      const roles = seated.get(seat.teamID) ?? seated.set(seat.teamID, new Map()).get(seat.teamID)!
+      ;(roles.get(seat.role) ?? roles.set(seat.role, []).get(seat.role)!).push(seat.sessionID)
+    }
+    for (const team of teamData.teams) {
+      if (team.state !== "active" || team.mode !== "restricted") continue
+      const roles = seated.get(team.id)
+      if (!roles) continue
+      for (const path of team.edges) {
+        const pairs: [string, string][] = []
+        for (const a of roles.get(path.from) ?? []) for (const b of roles.get(path.to) ?? []) if (a !== b) pairs.push([a, b], ...(path.direction === "two-way" ? [[b, a] as [string, string]] : []))
+        for (const [a, b] of pairs) {
+          if (edges.size >= GRAPH_LIMITS.edges * 2) break
+          const acc = edgeFor("policy", a, b, team.id)
+          acc.permitted = true
+          acc.kinds ??= new Set()
+          for (const kind of path.kinds) acc.kinds.add(kind)
+        }
+      }
+    }
+    for (const acc of edges.values()) {
+      if (acc.kind !== "policy") continue
+      for (const m of messages) {
+        if (m.from.kind !== "session" || m.recipient.kind !== "session" || m.from.sessionID !== acc.from || m.recipient.sessionID !== acc.to || !acc.kinds?.has(m.kind)) continue
+        acc.count++
+        acc.firstAt = Math.min(acc.firstAt ?? m.at, m.at)
+        acc.lastAt = Math.max(acc.lastAt, m.at)
+        acc.messages.push(m)
+      }
+    }
+  }
+  if (viewer.denials && sources.denials) {
+    // A refusal on a pair some team permits (another kind) counts on that path; others get a denial-only edge.
+    const permittedPair = new Map<string, EdgeAcc>()
+    for (const e of [...edges.values()].sort(byID)) if (e.kind === "policy" && e.permitted && !permittedPair.has(`${e.from}|${e.to}`)) permittedPair.set(`${e.from}|${e.to}`, e)
+    for (const d of await sources.denials(userID)) {
+      if (d.at < since || d.at > until || !isSession(d.senderID)) continue
+      const to = d.recipientID !== undefined && isSession(d.recipientID) ? d.recipientID : "hub"
+      const permitted = permittedPair.get(`${d.senderID}|${to}`)
+      const acc = permitted ?? edgeFor("policy", d.senderID, to)
+      if (!permitted) acc.permitted = false
+      acc.denied++
+      acc.lastAt = Math.max(acc.lastAt, d.at)
+      acc.firstAt = Math.min(acc.firstAt ?? d.at, d.at)
+    }
+  }
+
+  const evicted = retention.evictedAt !== undefined && retention.evictedAt >= since
+  const oldest = visible[0]?.at
+  return {
+    nodes,
+    edges,
+    messages,
+    decisionOf,
+    hidden,
+    retention: { truncated: evicted, ...(oldest !== undefined ? { oldestAt: oldest } : {}) },
+  }
+}
+
+function appNode(id: string, label?: string): GraphNodeView {
+  if (id === COORDINATOR_PARTY) return { id, kind: "hub", label: "workspace coordinator", party: "app" }
+  // (CON-09a) The Concierge service's party (its updates, digests and launches): the hub's, named for the Concierge.
+  if (id === CONCIERGE_APP_PARTY) return { id, kind: "hub", label: "@@concierge (hub)", party: "app" }
+  return { id, kind: "user", label: sanitizeLabel(label ?? "") || id, party: "app" }
+}
+
+function edgeView(acc: EdgeAcc): GraphEdgeView {
+  const nonEmpty = (record: Record<string, number | undefined>) => Object.keys(record).length > 0
+  return {
+    id: acc.id,
+    from: acc.from,
+    to: acc.to,
+    kind: acc.kind,
+    count: acc.count,
+    lastAt: acc.lastAt,
+    ...(acc.teamID ? { teamID: acc.teamID } : {}),
+    ...(acc.denied ? { denied: acc.denied } : {}),
+    ...(acc.firstAt !== undefined ? { firstAt: acc.firstAt } : {}),
+    ...(nonEmpty(acc.states) ? { states: { ...acc.states } } : {}),
+    ...(nonEmpty(acc.delivery) ? { delivery: { ...acc.delivery } } : {}),
+    ...(acc.declined ? { declined: acc.declined } : {}),
+    ...(acc.roleAddressed ? { roleAddressed: acc.roleAddressed } : {}),
+    ...(acc.maxHop ? { maxHop: acc.maxHop } : {}),
+    ...(acc.permitted !== undefined ? { permitted: acc.permitted } : {}),
+    ...(acc.kinds?.size ? { kinds: [...acc.kinds].sort() } : {}),
+  }
+}
+
+// ---- Filters and limits ---------------------------------------------------------------------------------------
+
+function sessionFilter(projection: Projection, sources: GraphSources, userID: string, q: GraphQuery): ((node: GraphNodeView) => boolean) | undefined {
+  const narrowing = q.machine ?? q.harness ?? q.team ?? q.tag ?? q.project ?? q.session ?? q.workspace ?? q.states
+  if (narrowing === undefined) return undefined
+  const machineIDs = q.machine !== undefined ? new Set(sources.machines(userID).filter((m) => m.id === q.machine || m.name === q.machine).map((m) => m.id)) : undefined
+  const teams = teamsMatching(projection, q)
+  const project = q.project?.toLowerCase()
+  const inTree = (node: GraphNodeView) => {
+    for (let id: string | undefined = node.id, depth = 0; id !== undefined && depth <= DEPTH_MAX; id = projection.nodes.get(id)?.parentID, depth++) if (id === q.session) return true
+    return false
+  }
+  return (node) =>
+    (!machineIDs || (node.machineID !== undefined && machineIDs.has(node.machineID))) &&
+    (q.harness === undefined || node.harness === q.harness) &&
+    (project === undefined || node.project?.toLowerCase() === project) &&
+    (q.session === undefined || inTree(node)) &&
+    (q.workspace === undefined || (node.workspaceIDs ?? []).includes(q.workspace)) &&
+    (!teams || (node.teamIDs ?? []).some((id) => teams.has(id))) &&
+    (!q.states || (node.status !== undefined && q.states.has(node.status)))
+}
+
+/** Team nodes the team/tag filters select (undefined: no team filter). */
+function teamsMatching(projection: Projection, q: GraphQuery): Set<string> | undefined {
+  if (q.team === undefined && q.tag === undefined) return undefined
+  const out = new Set<string>()
+  for (const node of projection.nodes.values()) {
+    if (node.kind !== "team") continue
+    if (q.team !== undefined && node.id !== q.team && node.name !== q.team) continue
+    if (q.tag !== undefined && !(node.tags ?? []).includes(q.tag)) continue
+    out.add(node.id)
+  }
+  return out
+}
+
+function snapshot(projection: Projection, sources: GraphSources, userID: string, q: GraphQuery): GraphSnapshotView {
+  const keepSession = sessionFilter(projection, sources, userID, q)
+  const teams = teamsMatching(projection, q)
+  const machineIDs = q.machine !== undefined ? new Set(sources.machines(userID).filter((m) => m.id === q.machine || m.name === q.machine).map((m) => m.id)) : undefined
+  const sessions = new Set<string>()
+  for (const node of projection.nodes.values()) if (node.kind === "session" && (!keepSession || keepSession(node))) sessions.add(node.id)
+  const hostMachines = new Set([...sessions].map((id) => projection.nodes.get(id)!.machineID))
+  const seatedTeams = new Set([...sessions].flatMap((id) => projection.nodes.get(id)!.teamIDs ?? []))
+  const keep = (node: GraphNodeView): boolean => {
+    if (node.party === "app" || node.id === "hub" || node.id === "@me") return true
+    switch (node.kind) {
+      case "session":
+        return sessions.has(node.id)
+      case "machine":
+        if (machineIDs) return machineIDs.has(node.machineID!)
+        return !keepSession || hostMachines.has(node.machineID)
+      case "team":
+        if (teams) return teams.has(node.id)
+        return !keepSession || seatedTeams.has(node.id)
+      default:
+        return true
+    }
+  }
+  const kept = new Map([...projection.nodes].filter(([, node]) => keep(node)))
+  let edges = [...projection.edges.values()].filter((e) => kept.has(e.from) && kept.has(e.to) && (!q.kinds || q.kinds.has(e.kind)))
+  // App parties appear only with traffic.
+  const touched = new Set(edges.flatMap((e) => [e.from, e.to]))
+  for (const [id, node] of kept) if (node.party === "app" && !touched.has(id)) kept.delete(id)
+
+  // Limits: the hub and @me first, then the busiest nodes.
+  const activity = new Map<string, number>()
+  for (const e of edges) for (const id of [e.from, e.to]) activity.set(id, (activity.get(id) ?? 0) + e.count + e.denied)
+  let capped = false
+  let nodes = [...kept.values()]
+  if (nodes.length > q.limit) {
+    capped = true
+    nodes = nodes
+      .sort((a, b) => Math.min(rankOf(a), 2) - Math.min(rankOf(b), 2) || (activity.get(b.id) ?? 0) - (activity.get(a.id) ?? 0) || rankOf(a) - rankOf(b) || byID(a, b))
+      .slice(0, q.limit)
+    const ids = new Set(nodes.map((node) => node.id))
+    edges = edges.filter((e) => ids.has(e.from) && ids.has(e.to))
+  }
+  if (edges.length > GRAPH_LIMITS.edges) {
+    capped = true
+    edges = edges.sort((a, b) => b.lastAt - a.lastAt || byID(a, b)).slice(0, GRAPH_LIMITS.edges)
+  }
+  return {
+    v: 1,
+    at: sources.now(),
+    window: { since: q.since, until: q.until },
+    nodes: nodes.sort((a, b) => rankOf(a) - rankOf(b) || byID(a, b)),
+    edges: edges.sort(byID).map(edgeView),
+    retention: projection.retention,
+    capped,
+    hidden: { messages: projection.hidden },
+  }
+}
+
+/** The graph snapshot for `viewer` (see the file comment). */
+export async function buildGraph(sources: GraphSources, userID: string, viewer: GraphViewer, q: GraphQuery): Promise<GraphSnapshotView> {
+  return snapshot(await project(sources, userID, viewer, q.since, q.until), sources, userID, q)
+}
+
+// ---- Detail -------------------------------------------------------------------------------------------------------
+
+export interface DetailPage {
+  readonly messages: MessageSummary[]
+  /** For the next (older) page; absent on the last one. */
+  readonly cursor?: string
+}
+
+function summary(m: Message, decisionOf: ReadonlyMap<string, string>): MessageSummary {
+  const decisionID = decisionOf.get(m.id)
+  return {
+    id: m.id,
+    kind: m.kind,
+    state: m.state,
+    from: partyNode(m.from),
+    to: partyNode(m.recipient),
+    address: sanitizeLabel(m.to),
+    at: m.at,
+    hop: m.hop,
+    ...(m.generation !== undefined ? { generation: m.generation } : {}),
+    ...(m.replyTo !== undefined ? { replyTo: m.replyTo } : {}),
+    ...(m.answer ? { answer: { id: m.answer.id, at: m.answer.at } } : {}),
+    ...(m.expiresAt !== undefined ? { expiresAt: m.expiresAt } : {}),
+    ...(m.delivery ? { delivery: m.delivery } : {}),
+    ...(m.deliveredAt !== undefined ? { deliveredAt: m.deliveredAt } : {}),
+    ...(decisionID ? { decisionID } : {}),
+  }
+}
+
+const encodeCursor = (m: Message) => Buffer.from(JSON.stringify([m.at, m.id])).toString("base64url")
+
+function decodeCursor(raw: string): [number, string] {
+  try {
+    const value = JSON.parse(Buffer.from(raw, "base64url").toString("utf8")) as unknown
+    if (Array.isArray(value) && value.length === 2 && Number.isSafeInteger(value[0]) && typeof value[1] === "string") return [value[0], value[1]]
+  } catch {
+    // falls through
+  }
+  throw new AgentError("invalid", "cursor is not one this list gave", { hint: "Start again without a cursor" })
+}
+
+/** Newest first, a page at a time. */
+function page(list: readonly Message[], params: URLSearchParams, decisionOf: ReadonlyMap<string, string>): DetailPage {
+  const limit = intParam(params, "limit") ?? GRAPH_DETAIL_PAGE.default
+  if (limit < 1 || limit > GRAPH_DETAIL_PAGE.max) throw invalid(`limit must be 1–${GRAPH_DETAIL_PAGE.max}`)
+  const raw = params.get("cursor")
+  const after = raw ? decodeCursor(raw) : undefined
+  const sorted = [...new Map(list.map((m) => [m.id, m])).values()]
+    .sort((a, b) => b.at - a.at || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0))
+    .filter((m) => !after || m.at < after[0] || (m.at === after[0] && m.id < after[1]))
+  const items = sorted.slice(0, limit)
+  return { messages: items.map((m) => summary(m, decisionOf)), ...(sorted.length > limit ? { cursor: encodeCursor(items.at(-1)!) } : {}) }
+}
+
+/** GET /graph/edges/:id: the edge and its messages (window from since/until). */
+export async function edgeDetail(sources: GraphSources, userID: string, viewer: GraphViewer, id: string, params: URLSearchParams, now: number): Promise<DetailPage & { edge: GraphEdgeView }> {
+  const { since, until } = windowOf(params, now)
+  const projection = await project(sources, userID, viewer, since, until)
+  const acc = projection.edges.get(id)
+  if (!acc) throw new AgentError("not_found", "No such edge")
+  return { edge: edgeView(acc), ...page(acc.messages, params, projection.decisionOf) }
+}
+
+/** GET /graph/nodes/:id: the node and the messages it sent or received (window from since/until). */
+export async function nodeDetail(sources: GraphSources, userID: string, viewer: GraphViewer, id: string, params: URLSearchParams, now: number): Promise<DetailPage & { node: GraphNodeView }> {
+  const { since, until } = windowOf(params, now)
+  const projection = await project(sources, userID, viewer, since, until)
+  const node = projection.nodes.get(id)
+  if (!node) throw new AgentError("not_found", "No such node")
+  const mine = projection.messages.filter((m) => partyNode(m.from) === id || partyNode(m.recipient) === id)
+  return { node, ...page(mine, params, projection.decisionOf) }
+}
+
+// ---- Live updates --------------------------------------------------------------------------------------------------
+
+/** Journal event types that change the graph (besides the `team.` and `workspace.` families). */
+export const GRAPH_INVALIDATING_EVENTS: ReadonlySet<string> = new Set([
+  "message.changed",
+  "session.added",
+  "session.removed",
+  "session.changed",
+  "session.archived",
+  "session.named",
+  "role.claimed",
+  "role.released",
+  "machine.changed",
+  "launch.changed",
+])
+
+export interface GraphInvalidation {
+  readonly type: "graph.invalidated"
+  readonly at: number
+  /** The journal event type that caused it (`reset`: the reader lost its place). */
+  readonly cause: string
+  /** Node IDs it touches (may be empty). */
+  readonly nodes: readonly string[]
+  readonly messageID?: string
+  /** Take a new snapshot instead of patching. */
+  readonly resnapshot?: true
+}
+
+/** The compact `graph.invalidated` hint of a journal event (IDs only), or undefined when it does not change the graph. */
+export function graphInvalidation(event: Pick<AgentEvent, "at" | "type" | "subject"> & Partial<Pick<AgentEvent, "id" | "data">>): GraphInvalidation | undefined {
+  if (event.type === "reset") return { type: "graph.invalidated", at: event.at, cause: "reset", nodes: [], resnapshot: true }
+  if (!GRAPH_INVALIDATING_EVENTS.has(event.type) && !event.type.startsWith("team.") && !event.type.startsWith("workspace.")) return undefined
+  const { senderID, sessionID, teamID, machineID, messageID } = event.subject
+  const nodes = [senderID, sessionID, teamID, machineID !== undefined ? machineNode(machineID) : undefined].filter((id): id is string => typeof id === "string" && id.length > 0)
+  return { type: "graph.invalidated", at: event.at, cause: event.type, nodes: [...new Set(nodes)].sort(), ...(messageID ? { messageID } : {}) }
+}