@huynle/hub 0.7.3 → 0.8.0

package/src/central/teams/validation.ts

@@ -0,0 +1,256 @@
+// Team definition bodies (HWA-33): the frozen contract check (teamInputProblem, packages/protocol/src/teams.ts)
+// plus the additive fields this store keeps next to it, normalization, the content digest and the revision diff.
+//
+// A TeamSpec is the publishable content of a team: everything a published revision freezes. The store adds the
+// record fields around it (id, state, revision, version, paused, timestamps). Additive (contract questions in the
+// HWA-33 handoff), all optional, none of them grants authority:
+// - team `projects`: project names the team works on (filters).
+// - role `responsibilities` (short lines), `profile` (desired profile ref {profileID, version?}), `prefs`
+//   (harness / model / machineID placement preferences for staffing), `minMembers` / `maxMembers`.
+// Stricter than the contract (never looser): unknown fields are refused, a role description is bounded text, an
+// edge's kinds are unique, and one ordered role pair is covered by at most one edge (a two-way edge covers both).
+import { createHash } from "node:crypto"
+import {
+  DESCRIPTION_MAX,
+  isContractID,
+  isLabel,
+  isSlug,
+  isText,
+  TEAM_LIMITS,
+  type TeamEdge,
+  type TeamMessageKind,
+  type TeamMode,
+  type TeamRole,
+  teamInputProblem,
+} from "../../protocol"
+import { canonicalBody } from "../agent/idempotency"
+import { AgentError } from "../agent/errors"
+
+export const TEAM_STORE_LIMITS = {
+  ...TEAM_LIMITS,
+  responsibilitiesPerRole: 16,
+  responsibilityMax: 200,
+  projectsPerTeam: 16,
+  /** Published revisions kept per team (older ones nobody pins are dropped). */
+  versionsRetained: 50,
+  /** Ended staffing records kept per team (oldest dropped first). */
+  endedSeatsRetained: 200,
+} as const
+
+/** Machine IDs as the hub mints them (same shape the workspace bindings accept). */
+const MACHINE_ID = /^[A-Za-z0-9_.:-]{1,128}$/
+const MODEL_MAX = 200
+
+/** Staffing preferences of a role (advisory: staffing still runs under the caller's grants). */
+export interface TeamRolePrefs {
+  readonly harness?: string
+  readonly model?: string
+  readonly machineID?: string
+}
+
+/** A contract TeamRole plus the additive fields. */
+export interface TeamRoleSpec extends TeamRole {
+  readonly responsibilities?: readonly string[]
+  readonly profile?: { readonly profileID: string; readonly version?: number }
+  readonly prefs?: TeamRolePrefs
+  readonly minMembers?: number
+  readonly maxMembers?: number
+}
+
+/** The publishable content of a team. */
+export interface TeamSpec {
+  readonly name: string
+  readonly title: string
+  readonly description?: string
+  readonly mode: TeamMode
+  readonly roles: readonly TeamRoleSpec[]
+  readonly entryRole: string
+  readonly edges: readonly TeamEdge[]
+  readonly tags?: readonly string[]
+  readonly metadata?: Readonly<Record<string, string>>
+  readonly projects?: readonly string[]
+}
+
+export interface TeamDiff {
+  /** Changed scalar fields, in a fixed order: title, description, mode, entryRole. */
+  readonly fields: readonly string[]
+  readonly roles: { readonly added: readonly string[]; readonly removed: readonly string[]; readonly changed: readonly string[] }
+  /** Edge keys `from>to` as drawn. */
+  readonly edges: { readonly added: readonly string[]; readonly removed: readonly string[]; readonly changed: readonly string[] }
+  readonly tags: { readonly added: readonly string[]; readonly removed: readonly string[] }
+  readonly metadata: { readonly added: readonly string[]; readonly removed: readonly string[]; readonly changed: readonly string[] }
+  readonly projects: { readonly added: readonly string[]; readonly removed: readonly string[] }
+}
+
+export const SPEC_FIELDS: ReadonlySet<string> = new Set(["name", "title", "description", "mode", "roles", "entryRole", "edges", "tags", "metadata", "projects"])
+const ROLE_FIELDS = new Set(["name", "label", "description", "externalContact", "responsibilities", "profile", "prefs", "minMembers", "maxMembers"])
+const EDGE_FIELDS = new Set(["from", "to", "kinds", "direction"])
+const PROFILE_FIELDS = new Set(["profileID", "version"])
+const PREFS_FIELDS = new Set(["harness", "model", "machineID"])
+const REQUIRED = new Set(["title", "mode", "roles", "entryRole"])
+const SCALARS = ["title", "description", "mode", "entryRole"] as const
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const fail = (message: string): never => {
+  throw new AgentError("invalid", message)
+}
+const printable = (key: string) => (/^[A-Za-z0-9_-]{1,40}$/.test(key) ? key : "(unprintable)")
+
+function onlyFields(v: Record<string, unknown>, allowed: ReadonlySet<string>, where: string): void {
+  for (const key of Object.keys(v)) if (!allowed.has(key)) fail(`${where}unknown field ${printable(key)}`)
+}
+
+function roleProblem(role: Record<string, unknown>): string | undefined {
+  const name = role.name as string
+  if (role.description !== undefined && !isText(role.description, DESCRIPTION_MAX)) return `role ${name} description must be at most ${DESCRIPTION_MAX} characters`
+  const r = role.responsibilities
+  if (r !== undefined) {
+    const limit = TEAM_STORE_LIMITS.responsibilitiesPerRole
+    if (!Array.isArray(r) || r.length > limit || !r.every((line) => isLabel(line, TEAM_STORE_LIMITS.responsibilityMax)))
+      return `role ${name} responsibilities must be at most ${limit} lines of 1–${TEAM_STORE_LIMITS.responsibilityMax} characters`
+  }
+  const p = role.profile
+  if (p !== undefined) {
+    if (!isObj(p)) return `role ${name} profile must be {profileID, version?}`
+    onlyFields(p, PROFILE_FIELDS, `role ${name} profile: `)
+    if (!isContractID("profile", p.profileID)) return `role ${name} profile.profileID must be a profile ID`
+    if (p.version !== undefined && !(Number.isSafeInteger(p.version) && (p.version as number) >= 1)) return `role ${name} profile.version must be a version number`
+  }
+  const prefs = role.prefs
+  if (prefs !== undefined) {
+    if (!isObj(prefs)) return `role ${name} prefs must be an object`
+    onlyFields(prefs, PREFS_FIELDS, `role ${name} prefs: `)
+    if (prefs.harness !== undefined && !isSlug(prefs.harness)) return `role ${name} prefs.harness must be a harness name`
+    if (prefs.model !== undefined && !isLabel(prefs.model, MODEL_MAX)) return `role ${name} prefs.model must be 1–${MODEL_MAX} characters`
+    if (prefs.machineID !== undefined && !(typeof prefs.machineID === "string" && MACHINE_ID.test(prefs.machineID))) return `role ${name} prefs.machineID must be a machine ID`
+  }
+  const cap = TEAM_LIMITS.sessionsPerRole
+  const { minMembers: min, maxMembers: max } = role
+  if (min !== undefined && !(Number.isSafeInteger(min) && (min as number) >= 0 && (min as number) <= cap)) return `role ${name} minMembers must be 0–${cap}`
+  if (max !== undefined && !(Number.isSafeInteger(max) && (max as number) >= 1 && (max as number) <= cap)) return `role ${name} maxMembers must be 1–${cap}`
+  if (min !== undefined && max !== undefined && (min as number) > (max as number)) return `role ${name} minMembers must not exceed maxMembers`
+  return undefined
+}
+
+function normalizedRole(r: Record<string, unknown>): TeamRoleSpec {
+  const profile = r.profile as Record<string, unknown> | undefined
+  const prefs = r.prefs as Record<string, unknown> | undefined
+  return {
+    name: r.name as string,
+    ...(r.label !== undefined ? { label: r.label as string } : {}),
+    ...(r.description !== undefined ? { description: r.description as string } : {}),
+    ...(r.externalContact !== undefined ? { externalContact: r.externalContact as boolean } : {}),
+    ...(r.responsibilities !== undefined ? { responsibilities: [...(r.responsibilities as string[])] } : {}),
+    ...(profile !== undefined ? { profile: { profileID: profile.profileID as string, ...(profile.version !== undefined ? { version: profile.version as number } : {}) } } : {}),
+    ...(prefs !== undefined
+      ? {
+          prefs: {
+            ...(prefs.harness !== undefined ? { harness: prefs.harness as string } : {}),
+            ...(prefs.model !== undefined ? { model: prefs.model as string } : {}),
+            ...(prefs.machineID !== undefined ? { machineID: prefs.machineID as string } : {}),
+          },
+        }
+      : {}),
+    ...(r.minMembers !== undefined ? { minMembers: r.minMembers as number } : {}),
+    ...(r.maxMembers !== undefined ? { maxMembers: r.maxMembers as number } : {}),
+  }
+}
+
+/** A validated, normalized team spec; throws AgentError invalid. */
+export function teamSpecOf(input: unknown): TeamSpec {
+  if (!isObj(input)) return fail("body must be an object")
+  onlyFields(input, SPEC_FIELDS, "")
+  if (Array.isArray(input.roles)) for (const role of input.roles) if (isObj(role)) onlyFields(role, ROLE_FIELDS, `role ${printable(String(role.name))}: `)
+  if (Array.isArray(input.edges)) for (const edge of input.edges) if (isObj(edge)) onlyFields(edge, EDGE_FIELDS, "edge: ")
+  const problem = teamInputProblem(input)
+  if (problem) fail(problem)
+  const roles = input.roles as Record<string, unknown>[]
+  for (const role of roles) {
+    const p = roleProblem(role)
+    if (p) fail(p)
+  }
+  const projects = input.projects
+  if (projects !== undefined) {
+    const limit = TEAM_STORE_LIMITS.projectsPerTeam
+    if (!Array.isArray(projects) || projects.length > limit || !projects.every((p) => isLabel(p)) || new Set(projects).size !== projects.length)
+      fail(`projects must be at most ${limit} unique project names`)
+  }
+  const covered = new Set<string>()
+  const edges: TeamEdge[] = []
+  for (const e of (input.edges ?? []) as Record<string, unknown>[]) {
+    const kinds = e.kinds as TeamMessageKind[]
+    if (new Set(kinds).size !== kinds.length) fail(`edge ${e.from as string} → ${e.to as string} lists a kind twice`)
+    const pairs = e.direction === "two-way" ? [[e.from, e.to], [e.to, e.from]] : [[e.from, e.to]]
+    for (const [from, to] of pairs) {
+      const key = `${from as string} → ${to as string}`
+      if (covered.has(key)) fail(`There are two edges for ${key}; one edge per role pair (two-way covers both directions)`)
+      covered.add(key)
+    }
+    edges.push({ from: e.from as string, to: e.to as string, kinds: [...kinds].sort(), direction: e.direction as TeamEdge["direction"] })
+  }
+  return {
+    name: input.name as string,
+    title: input.title as string,
+    ...(input.description !== undefined ? { description: input.description as string } : {}),
+    mode: input.mode as TeamMode,
+    roles: roles.map(normalizedRole),
+    entryRole: input.entryRole as string,
+    edges,
+    ...(input.tags !== undefined ? { tags: [...(input.tags as string[])] } : {}),
+    ...(input.metadata !== undefined ? { metadata: { ...(input.metadata as Record<string, string>) } } : {}),
+    ...(projects !== undefined ? { projects: [...(projects as string[])] } : {}),
+  }
+}
+
+/**
+ * The spec after a patch: fields replace the base's (roles and edges wholesale), null clears an optional one, the
+ * name never changes (it is the `#team` address), and the result is validated as a whole.
+ */
+export function teamPatchOf(base: TeamSpec, patch: unknown): TeamSpec {
+  if (!isObj(patch)) return fail("body must be an object")
+  onlyFields(patch, SPEC_FIELDS, "")
+  const keys = Object.keys(patch)
+  if (keys.length === 0) fail("Nothing to change")
+  if (patch.name !== undefined && patch.name !== base.name) fail("A team's name cannot change (it is the #team address); create a new team")
+  const next: Record<string, unknown> = { ...base }
+  for (const key of keys) {
+    const value = patch[key]
+    if (value === null) {
+      if (REQUIRED.has(key) || key === "name") fail(`${key} cannot be cleared`)
+      if (key === "edges") next.edges = []
+      else delete next[key]
+    } else if (value !== undefined) next[key] = value
+  }
+  return teamSpecOf(next)
+}
+
+/** sha256 of the spec's canonical JSON (key order never matters). */
+export const specDigest = (spec: TeamSpec): string => createHash("sha256").update(canonicalBody(spec)).digest("hex")
+
+const same = (a: unknown, b: unknown) => canonicalBody(a) === canonicalBody(b)
+
+function setDiff(from: readonly string[] = [], to: readonly string[] = []) {
+  return { added: to.filter((x) => !from.includes(x)), removed: from.filter((x) => !to.includes(x)) }
+}
+
+function keyedDiff<T>(from: ReadonlyMap<string, T>, to: ReadonlyMap<string, T>) {
+  return {
+    added: [...to.keys()].filter((k) => !from.has(k)),
+    removed: [...from.keys()].filter((k) => !to.has(k)),
+    changed: [...to.keys()].filter((k) => from.has(k) && !same(from.get(k), to.get(k))),
+  }
+}
+
+/** What changed from one spec to another (names and keys only, never descriptions). */
+export function diffTeamSpecs(from: TeamSpec, to: TeamSpec): TeamDiff {
+  const edgeMap = (s: TeamSpec) => new Map(s.edges.map((e) => [`${e.from}>${e.to}`, e] as const))
+  const metaMap = (s: TeamSpec) => new Map(Object.entries(s.metadata ?? {}))
+  return {
+    fields: SCALARS.filter((f) => !same(from[f], to[f])),
+    roles: keyedDiff(new Map(from.roles.map((r) => [r.name, r] as const)), new Map(to.roles.map((r) => [r.name, r] as const))),
+    edges: keyedDiff(edgeMap(from), edgeMap(to)),
+    tags: setDiff(from.tags, to.tags),
+    metadata: keyedDiff(metaMap(from), metaMap(to)),
+    projects: setDiff(from.projects, to.projects),
+  }
+}

package/src/central/workspaces/board.ts

@@ -0,0 +1,408 @@
+// The master situation board (HWA-10; contract: Workspaces `GET /workspaces/:id/board` in docs/plans/2026-10-30-
+// hub-workspaces-artifacts-contracts.md and its HWA-06 clarification):
+//
+//   GET /api/agent/workspaces/:id/board                                                      workspaces:read + sessions:read
+//
+// One read-only, bounded snapshot of a workspace for whoever coordinates it: the workspace, its current members
+// with presence, last-known session state and blocker references, supervision links, assignments with their
+// explicit status, open Decisions concerning members, and artifact references.
+//
+// Who: users (their own workspaces; another user's is not_found). App tokens with workspaces:read and
+// sessions:read (the board names sessions and shows presence). Session tokens are refused: membership grants
+// nothing, and a master session reading its board through its own token would be a new authority (an open
+// contract question, not implemented). Sections an app may not read are `{status: "omitted", reason: "scope"}`:
+// Decisions need messages:read and show only those the app asked (as GET /decisions does); artifacts need
+// artifacts:read and are listed through the artifact store's ACL as the user.
+//
+// What it never carries: prompts, message bodies, Decision questions/options/answers, blocker summaries,
+// assignment criteria or artifact titles. Those stay behind their existing detail routes (GET /sessions/:addr,
+// /decisions/:id, /workspaces/:id/assignments/:id, /artifacts/:id), each with its own authorization. Assignment
+// titles are shown: the same caller reads them on the assignment routes with the same scopes.
+//
+// Truthfulness: assignment status is exactly the stored, explicitly set status; idleness, presence or departure
+// never complete, start or cancel anything. A session the catalog does not report here (another pod, offline) has
+// `blockers: {reported: false}` rather than an empty list. Members and open assignments carry `stale` markers when
+// the hub cannot vouch for them now (offline, archived, deleted or unknown sessions; departed or missing assignees;
+// no update within staleAfterMs). Unwired sections are `{status: "unsupported", feature}`; a section whose source
+// fails is `{status: "failed"}` without failing the whole board.
+//
+// Bounds and fanout: every section is capped (BOARD_LIMITS) and says `truncated`; the session facts are one
+// batched lookup over the shown members from the hub's own directory and catalog — the board never calls a spoke.
+// No model or runtime runs here, nothing is written and no event is appended (the compact journal is unchanged).
+import { LIST_LIMIT_MAX, WORKSPACE_LIMITS, WORKSPACE_SCOPES, type Artifact, type Page } from "../../protocol"
+import type { AgentActor } from "../agent/actor"
+import type { Decision, Decisions } from "../agent/decisions"
+import type { Directory } from "../agent/directory"
+import { partyFromActor } from "../agent/envelope"
+import { AgentError } from "../agent/errors"
+import type { ReadRegistry } from "../agent/read-routes"
+import type { AgentRoute } from "../agent/routes"
+import type { ArtifactPrincipal } from "../artifacts/access"
+import type { AssignmentStatus, MembershipStore, SessionPresence, StoredAssignment } from "./members"
+import type { WorkspaceStore } from "./store"
+import type { SupervisionStore } from "./supervision"
+
+const PREFIX = "/api/agent/workspaces"
+const NO_STORE = { "cache-control": "no-store" }
+const [READ_SCOPE] = WORKSPACE_SCOPES
+
+export interface BoardLimits {
+  /** Current members shown (the session lookup covers only these). */
+  readonly members: number
+  /** Open (not done or cancelled) assignments shown, oldest first. */
+  readonly assignments: number
+  /** Most recently closed assignments shown. */
+  readonly closedAssignments: number
+  /** Supervision links shown. */
+  readonly links: number
+  /** Open Decisions shown, newest first. */
+  readonly decisions: number
+  /** Artifact references shown, most recently updated first. */
+  readonly artifacts: number
+  /** Blocker references per member. */
+  readonly blockersPerMember: number
+  /** An open assignment without an update for this long is marked `no_recent_update`. */
+  readonly assignmentStaleMs: number
+}
+
+export const BOARD_LIMITS: BoardLimits = {
+  members: WORKSPACE_LIMITS.membersPerWorkspace,
+  assignments: LIST_LIMIT_MAX,
+  closedAssignments: 20,
+  links: WORKSPACE_LIMITS.supervisionLinksPerWorkspace,
+  decisions: 50,
+  artifacts: 50,
+  blockersPerMember: 8,
+  assignmentStaleMs: 24 * 60 * 60_000,
+}
+
+/** A blocker reference from the catalog (`summary` may be present at the source; the board never copies it). */
+export interface BoardBlockerSource {
+  readonly kind: string
+  readonly id: string
+  readonly sessionID?: string
+  readonly summary?: string
+}
+
+/** What the hub knows about a member's session now, without asking a spoke. */
+export interface BoardSession {
+  /** idle / working / blocked / error from the catalog; "offline" when no spoke reports it; else last known. */
+  readonly state: string
+  readonly online: boolean
+  readonly lastSeen?: number
+  readonly machineID?: string
+  readonly name?: string
+  readonly busySince?: number
+  /** Present only when this hub's catalog reports the session now (absent: not reported, never "none"). */
+  readonly blockers?: readonly BoardBlockerSource[]
+}
+
+/** One batched lookup of the user's sessions; IDs it does not know are left out of the map. */
+export type BoardSessions = (userID: string, sessionIDs: readonly string[]) => Promise<ReadonlyMap<string, BoardSession>>
+
+export interface BoardDeps {
+  readonly workspaces: Pick<WorkspaceStore, "require">
+  readonly members: Pick<MembershipStore, "members" | "assignments">
+  readonly supervision: Pick<SupervisionStore, "graph">
+  /** Session facts (the hub's directory and catalog); without it members show presence only. */
+  readonly sessions?: BoardSessions
+  /** Decisions (ask @me); without it the section is unsupported. */
+  readonly decisions?: Pick<Decisions, "list">
+  /** The artifact store (its ACL applies); without it the section is unsupported. */
+  readonly artifacts?: { list(userID: string, principal: ArtifactPrincipal, options?: { limit?: number; workspaceID?: string }): Promise<Page<Artifact>> }
+  readonly limits?: Partial<BoardLimits>
+  readonly now?: () => number
+}
+
+type Section<T> =
+  | { readonly status: "ok"; readonly items: readonly T[]; readonly truncated: boolean }
+  | { readonly status: "omitted"; readonly reason: "scope"; readonly scope: string }
+  | { readonly status: "unsupported"; readonly feature: string }
+  | { readonly status: "failed" }
+
+export type AssignmentStale = "assignee_left" | "assignee_missing" | "assignee_offline" | "no_recent_update"
+
+export interface BoardMember {
+  readonly memberID: string
+  readonly sessionID: string
+  readonly role: string
+  readonly generation: number
+  readonly revision: number
+  readonly joinedAt: number
+  readonly master: boolean
+  readonly presence: SessionPresence
+  readonly session?: Omit<BoardSession, "blockers">
+  readonly blockers: { readonly reported: false } | { readonly reported: true; readonly count: number; readonly items: readonly { kind: string; id: string; sessionID?: string }[]; readonly truncated?: true }
+  /** Not-closed assignments by status. */
+  readonly assignments: { readonly open: number; readonly in_progress: number; readonly blocked: number }
+  /** Open Decisions concerning this member's session (absent when the Decisions section is not readable). */
+  readonly decisions?: number
+  /** Why the hub cannot vouch for this member's session now (absent: online). */
+  readonly stale?: Exclude<SessionPresence, "online">
+}
+
+export interface BoardAssignment {
+  readonly id: string
+  readonly memberID: string
+  readonly title: string
+  readonly status: AssignmentStatus
+  readonly ref?: string
+  readonly revision: number
+  readonly createdAt: number
+  readonly updatedAt: number
+  readonly closedAt?: number
+  readonly assignee: "current" | "left" | "missing"
+  readonly stale?: readonly AssignmentStale[]
+}
+
+export interface BoardDecision {
+  readonly id: string
+  readonly state: Decision["state"]
+  readonly urgency: Decision["urgency"]
+  readonly tier: Decision["tier"]
+  readonly at: number
+  readonly expiresAt: number
+  readonly deadline?: number
+  readonly escalatedAt?: number
+  /** Member sessions it concerns (the asker when a member, then `about`). */
+  readonly sessionIDs: readonly string[]
+  readonly memberIDs: readonly string[]
+  readonly stale?: "past_deadline"
+}
+
+export interface BoardArtifact {
+  readonly id: string
+  readonly kind: Artifact["kind"]
+  readonly visibility: Artifact["visibility"]
+  readonly state: Artifact["state"]
+  readonly revision: number
+  readonly latestRevisionID: string
+  readonly updatedAt: number
+}
+
+const CLOSED: ReadonlySet<AssignmentStatus> = new Set(["done", "cancelled"])
+const ASSIGNMENT_STATUS_LIST: readonly AssignmentStatus[] = ["open", "in_progress", "blocked", "done", "cancelled"]
+
+const hasScope = (actor: AgentActor, scope: string) => actor.kind !== "app" || actor.scopes.includes(scope)
+
+/** A section's source failed: say so instead of failing the board (unsupported stays truthful). */
+function failure<T>(feature: string, cause: unknown): Section<T> {
+  if (cause instanceof AgentError && cause.code === "unsupported") return { status: "unsupported", feature }
+  console.error(`[hub] workspace board: ${feature} failed: ${(cause as Error).message}`)
+  return { status: "failed" }
+}
+
+/** The production session facts: the user's directory and this hub's catalog, never a spoke. */
+export function registryBoardSessions(directory: Pick<Directory, "resolve">, registry: Pick<ReadRegistry, "session" | "sessionTenant">): BoardSessions {
+  return async (userID, sessionIDs) => {
+    const out = new Map<string, BoardSession>()
+    for (const sessionID of sessionIDs) {
+      let entry
+      try {
+        entry = directory.resolve(userID, sessionID).sessions.find((s) => s.sessionID === sessionID)
+      } catch (cause) {
+        if (cause instanceof AgentError) continue
+        throw cause
+      }
+      if (!entry) continue
+      const named = { ...(entry.name ? { name: `@${entry.name}` } : {}), ...(entry.machineID ? { machineID: entry.machineID } : {}) }
+      const live = registry.sessionTenant(sessionID) === userID ? registry.session(sessionID) : undefined
+      if (live) {
+        const since = live.status.find((s) => s.id === sessionID) as { since?: number } | undefined
+        out.set(sessionID, {
+          state: live.state,
+          online: true,
+          ...named,
+          ...(since?.since !== undefined ? { busySince: since.since } : {}),
+          blockers: live.blockers.map((b) => ({ kind: b.kind, id: b.id, ...(b.sessionID && b.sessionID !== sessionID ? { sessionID: b.sessionID } : {}) })),
+        })
+      } else if (!entry.online) {
+        out.set(sessionID, { state: "offline", online: false, ...named, ...(entry.lastSeen !== undefined ? { lastSeen: entry.lastSeen } : {}) })
+      } else {
+        // Online per the (shared) directory but not in this hub's catalog: state as last known, blockers unknown.
+        out.set(sessionID, { state: entry.state ?? "unknown", online: true, ...named })
+      }
+    }
+    return out
+  }
+}
+
+/** Every retained assignment (≤ open + closed caps, so at most a couple of pages). */
+async function allAssignments(members: BoardDeps["members"], userID: string, workspaceID: string) {
+  const out = []
+  let cursor: string | undefined
+  do {
+    const page = await members.assignments(userID, workspaceID, { limit: LIST_LIMIT_MAX, ...(cursor ? { cursor } : {}) })
+    out.push(...page.items)
+    cursor = page.cursor
+  } while (cursor)
+  return out
+}
+
+/** Builds the board for one caller. Read-only. */
+export async function workspaceBoard(deps: BoardDeps, userID: string, actor: AgentActor, workspaceID: string) {
+  const limits = { ...BOARD_LIMITS, ...deps.limits }
+  const now = (deps.now ?? Date.now)()
+  const workspace = await deps.workspaces.require(userID, workspaceID)
+  const [memberViews, assignmentViews, graph] = await Promise.all([
+    deps.members.members(userID, workspaceID),
+    allAssignments(deps.members, userID, workspaceID),
+    deps.supervision.graph(userID, workspaceID),
+  ])
+
+  // ---------- Decisions (open, concerning current members) ----------
+  const sessionToMember = new Map(memberViews.map((v) => [v.member.sessionID, v.member.id]))
+  let decisions: Section<BoardDecision>
+  const perSession = new Map<string, number>()
+  if (!deps.decisions) decisions = { status: "unsupported", feature: "decisions" }
+  else if (!hasScope(actor, "messages:read")) decisions = { status: "omitted", reason: "scope", scope: "messages:read" }
+  else {
+    try {
+      const open = await deps.decisions.list(userID, { state: "open", ...(actor.kind === "user" ? {} : { from: partyFromActor(actor) }) })
+      const relevant: BoardDecision[] = []
+      for (const d of open) {
+        const sessionIDs = [...new Set([...(d.from.kind === "session" ? [d.from.sessionID] : []), ...d.about])].filter((s) => sessionToMember.has(s))
+        if (sessionIDs.length === 0) continue
+        for (const s of sessionIDs) perSession.set(s, (perSession.get(s) ?? 0) + 1)
+        relevant.push({
+          id: d.id,
+          state: d.state,
+          urgency: d.urgency,
+          tier: d.tier,
+          at: d.at,
+          expiresAt: d.expiresAt,
+          ...(d.deadline !== undefined ? { deadline: d.deadline } : {}),
+          ...(d.escalatedAt !== undefined ? { escalatedAt: d.escalatedAt } : {}),
+          sessionIDs,
+          memberIDs: sessionIDs.map((s) => sessionToMember.get(s)!),
+          ...(d.deadline !== undefined && d.deadline < now ? { stale: "past_deadline" as const } : {}),
+        })
+      }
+      decisions = { status: "ok", items: relevant.slice(0, limits.decisions), truncated: relevant.length > limits.decisions }
+    } catch (cause) {
+      decisions = failure("decisions", cause)
+    }
+  }
+
+  // ---------- members ----------
+  const shown = memberViews.slice(0, limits.members)
+  const facts = deps.sessions && shown.length > 0 ? await deps.sessions(userID, shown.map((v) => v.member.sessionID)) : new Map<string, BoardSession>()
+  const workload = new Map<string, { open: number; in_progress: number; blocked: number }>()
+  for (const { assignment } of assignmentViews) {
+    if (CLOSED.has(assignment.status)) continue
+    const counts = workload.get(assignment.memberID) ?? { open: 0, in_progress: 0, blocked: 0 }
+    counts[assignment.status as "open" | "in_progress" | "blocked"]++
+    workload.set(assignment.memberID, counts)
+  }
+  const boardMembers = shown.map(({ member, presence }): BoardMember => {
+    const fact = facts.get(member.sessionID)
+    const { blockers, ...session } = fact ?? ({} as BoardSession)
+    const refs = blockers?.map((b) => ({ kind: b.kind, id: b.id, ...(b.sessionID ? { sessionID: b.sessionID } : {}) }))
+    return {
+      memberID: member.id,
+      sessionID: member.sessionID,
+      role: member.role,
+      generation: member.generation,
+      revision: member.revision,
+      joinedAt: member.joinedAt,
+      master: workspace.masterMemberID === member.id,
+      presence,
+      ...(fact ? { session } : {}),
+      blockers: refs
+        ? { reported: true, count: refs.length, items: refs.slice(0, limits.blockersPerMember), ...(refs.length > limits.blockersPerMember ? { truncated: true as const } : {}) }
+        : { reported: false },
+      assignments: workload.get(member.id) ?? { open: 0, in_progress: 0, blocked: 0 },
+      ...(decisions.status === "ok" ? { decisions: perSession.get(member.sessionID) ?? 0 } : {}),
+      ...(presence !== "online" ? { stale: presence } : {}),
+    }
+  })
+
+  // ---------- assignments ----------
+  const counts = Object.fromEntries(ASSIGNMENT_STATUS_LIST.map((s) => [s, 0])) as Record<AssignmentStatus, number>
+  for (const { assignment } of assignmentViews) counts[assignment.status]++
+  const open = assignmentViews.filter((v) => !CLOSED.has(v.assignment.status))
+  const closed = assignmentViews
+    .filter((v) => CLOSED.has(v.assignment.status))
+    .sort((a, b) => ((b.assignment as StoredAssignment).closedAt ?? 0) - ((a.assignment as StoredAssignment).closedAt ?? 0))
+  const assignmentItems = [...open.slice(0, limits.assignments), ...closed.slice(0, limits.closedAssignments)].map(({ assignment, member, presence }): BoardAssignment => {
+    const a = assignment as StoredAssignment
+    const stale: AssignmentStale[] = []
+    if (!CLOSED.has(a.status)) {
+      if (member === "left") stale.push("assignee_left")
+      else if (member === "missing") stale.push("assignee_missing")
+      else if (presence !== "online") stale.push("assignee_offline")
+      if (now - a.updatedAt > limits.assignmentStaleMs) stale.push("no_recent_update")
+    }
+    return {
+      id: a.id,
+      memberID: a.memberID,
+      title: a.title,
+      status: a.status,
+      ...(a.ref !== undefined ? { ref: a.ref } : {}),
+      revision: a.revision,
+      createdAt: a.createdAt,
+      updatedAt: a.updatedAt,
+      ...(a.closedAt !== undefined ? { closedAt: a.closedAt } : {}),
+      assignee: member,
+      ...(stale.length ? { stale } : {}),
+    }
+  })
+
+  // ---------- artifacts (references only, through the artifact ACL as the user) ----------
+  let artifacts: Section<BoardArtifact>
+  if (!deps.artifacts) artifacts = { status: "unsupported", feature: "artifacts" }
+  else if (!hasScope(actor, "artifacts:read")) artifacts = { status: "omitted", reason: "scope", scope: "artifacts:read" }
+  else {
+    try {
+      const page = await deps.artifacts.list(userID, { kind: "user" }, { workspaceID, limit: limits.artifacts })
+      artifacts = {
+        status: "ok",
+        items: page.items.slice(0, limits.artifacts).map((a) => ({ id: a.id, kind: a.kind, visibility: a.visibility, state: a.state, revision: a.revision, latestRevisionID: a.latestRevisionID, updatedAt: a.updatedAt })),
+        truncated: page.cursor !== undefined || page.items.length > limits.artifacts,
+      }
+    } catch (cause) {
+      artifacts = failure("artifacts", cause)
+    }
+  }
+
+  return {
+    v: 1 as const,
+    at: now,
+    staleAfterMs: limits.assignmentStaleMs,
+    workspace: {
+      id: workspace.id,
+      title: workspace.title,
+      state: workspace.state,
+      revision: workspace.revision,
+      ...(workspace.masterMemberID ? { masterMemberID: workspace.masterMemberID } : {}),
+      createdAt: workspace.createdAt,
+      updatedAt: workspace.updatedAt,
+    },
+    members: { items: boardMembers, total: memberViews.length, truncated: memberViews.length > shown.length },
+    supervision: {
+      revision: graph.revision,
+      links: graph.links.slice(0, limits.links).map(({ link, member, supervisor }) => ({ memberID: link.memberID, supervisorMemberID: link.supervisorMemberID, order: link.order, member, supervisor })),
+      truncated: graph.links.length > limits.links,
+    },
+    assignments: { items: assignmentItems, counts, truncated: open.length > limits.assignments || closed.length > limits.closedAssignments },
+    decisions,
+    artifacts,
+  }
+}
+
+export type WorkspaceBoard = Awaited<ReturnType<typeof workspaceBoard>>
+
+/** GET /workspaces/:id/board. */
+export function boardRoutes(deps: BoardDeps): AgentRoute[] {
+  return [
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/board`,
+      allow: { scope: READ_SCOPE },
+      async handle({ actor, user, params }) {
+        if (!hasScope(actor, "sessions:read")) throw new AgentError("forbidden", "The board also needs scope sessions:read")
+        return Response.json(await workspaceBoard(deps, user.id, actor, params.id!), { headers: NO_STORE })
+      },
+    },
+  ]
+}