@huynle/hub 0.7.4 → 0.8.1

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

@@ -0,0 +1,350 @@
+// CON-03 situation board routes on /api/agent (contract: docs/plans/2026-11-01-concierge-contracts.md, "Situation
+// board (CON-03)"):
+//
+//   GET /api/agent/concierge/board                         user; the Concierge → {board, rendered}
+//   GET /api/agent/concierge/decisions[?state&limit&cursor] user; the Concierge → {decisions, cursor?} (full records)
+//   GET /api/agent/concierge/decisions/:id                 user; the Concierge → {decision}
+//
+// Who: users (their own), and the user's CURRENT Concierge session through its act token (canActAsSession and
+// ConciergeIdentity.current, checked on every call). Every other credential (app tokens of any scope, shell tokens,
+// other sessions, a previous Concierge) gets 404 before anything is read: the routes do not reveal themselves. The
+// Decisions routes are the one new read of Decision text (question, options, recommendation): the Concierge needs it
+// to explain a Decision, and its user opted in by enabling it. The board itself never carries that text.
+//
+// One render reads: the watchlist config, ONE catalog snapshot (shared with the watchlist resolution), the user's
+// directory records, the activity tracker, ONE open-Decisions list (shared too), launch labels, then for the shown
+// sessions only (≤ CONCIERGE_BOARD_LIMITS.sessions) one batched directory lookup, the stored intents (many) and the
+// last results (many): never the whole intents collection, never a spoke, never a model. Online state comes from the
+// registry (this hub's catalog), so a session the directory evicted (it keeps at most 2000 records per user) is
+// still on the board while it is reported. The only write is the board's revision record (board.ts), and only when
+// the content changed. No journal event.
+import { LIST_LIMIT_MAX } from "../../protocol"
+import { CONCIERGE_BOARD_LIMITS, CONCIERGE_BOARD_PENDING_MAX, type ConciergeBoardMachine, type ConciergeBoardState, type ConciergeBoardView } from "../../../packages/protocol/src/concierge"
+import { type AgentActor, canActAsSession } from "../agent/actor"
+import { DECISION_STATES, type Decision, type Decisions, type DecisionState } from "../agent/decisions"
+import type { Directory } from "../agent/directory"
+import { AgentError } from "../agent/errors"
+import type { SessionIntents } from "../agent/intents"
+import type { ReadRegistry } from "../agent/read-routes"
+import type { AgentRoute } from "../agent/routes"
+import type { Clock, StateStore } from "../backend/types"
+import type { CatalogMachine, CatalogSession } from "../registry"
+import type { Store } from "../store"
+import type { ActivityTracker } from "./activity"
+import { BoardRevisions, buildBoard, type BoardContent, type BoardDecisionInput, type BoardInput, type BoardRoot } from "./board"
+import type { ResultTracker } from "./board-results"
+import { frame, renderBoard } from "./board-render"
+import { resolveWatchlist, rootsOf, type WatchFact } from "./watchlist"
+import { type ConciergeIdentity, NO_CONCIERGE, watchFacts, WatchlistStore } from "./watchlist-routes"
+
+/** Literal, not from AGENT_PREFIX (routes.ts imports this module). */
+const PREFIX = "/api/agent/concierge"
+const NO_STORE = { "cache-control": "no-store" }
+const DECISIONS_PAGE = 50
+
+export interface BoardRouteDeps {
+  readonly state: StateStore
+  readonly activity: Pick<ActivityTracker, "list">
+  readonly directory: Pick<Directory, "entries">
+  readonly store: Pick<Store, "agentData" | "viewPrefs" | "machines">
+  readonly registry: Pick<ReadRegistry, "catalog" | "sessionTenant">
+  readonly decisions?: Pick<Decisions, "list" | "get">
+  /** Launched sessions' labels (the latest launch wins), for label filters. */
+  readonly labels?: (userID: string) => Promise<ReadonlyMap<string, Readonly<Record<string, string>>>>
+  readonly intents?: Pick<SessionIntents, "many">
+  readonly results?: Pick<ResultTracker, "many">
+  readonly identity?: ConciergeIdentity
+  /** (CON-06) The Decision armed now by the current Concierge; a failure shows none armed. */
+  readonly armed?: (userID: string) => Promise<string | undefined>
+  /** (CON-10) The user's time zone (Concierge settings): the rendered board's time is local. */
+  readonly timeZone?: (userID: string) => Promise<string | undefined>
+  /**
+   * (CON-13) Whether the current Concierge's grant would approve this pending request once (`inGrant`, Acting.covers:
+   * the act verb's own check, without acting), and whether it may do so without the user (`auto`: not the tap risk
+   * tier, Acting.coverage). Absent, or no current Concierge: every permission reads inGrant=no, auto=no.
+   */
+  readonly coverage?: (userID: string, conciergeSessionID: string, sessionID: string, requestID: string) => Promise<{ readonly inGrant: boolean; readonly auto: boolean }>
+  readonly now?: Clock
+}
+
+const notFound = () => new AgentError("not_found", "Not found")
+const STATES: ReadonlySet<string> = new Set<ConciergeBoardState>(["idle", "working", "blocked", "error"])
+const RANK: Record<string, number> = { error: 4, blocked: 3, working: 2, idle: 1 }
+
+/** The live catalog session of each wanted ID this user owns (the most recently updated report wins), with its machine. */
+function liveSessions(catalog: readonly CatalogMachine[], wanted: ReadonlySet<string>, owns: (id: string) => boolean) {
+  const out = new Map<string, { session: CatalogSession; machine: string }>()
+  for (const machine of catalog) {
+    for (const process of machine.processes) {
+      for (const s of process.sessions) {
+        if (!wanted.has(s.id)) continue
+        const known = out.get(s.id)
+        if (known && known.session.updated >= s.updated) continue
+        if (!owns(s.id)) continue
+        out.set(s.id, { session: s, machine: machine.name })
+      }
+    }
+  }
+  return out
+}
+
+/** Builds one user's board. Read-only except for the revision record. */
+export async function conciergeBoard(deps: BoardRouteDeps, revisions: BoardRevisions, userID: string, hidden: readonly string[]): Promise<ConciergeBoardView> {
+  const now = (deps.now ?? Date.now)()
+  const catalog = deps.registry.catalog()
+  // One open-Decisions list for both the resolution and the board; a failure fails the board's section only.
+  const open: Promise<{ ok: true; list: Decision[] } | { ok: false }> = deps.decisions
+    ? deps.decisions.list(userID, { state: "open" }).then(
+        (list) => ({ ok: true as const, list }),
+        (cause: unknown) => (console.error(`[hub] concierge board: decisions failed: ${(cause as Error).message}`), { ok: false as const }),
+      )
+    : Promise.resolve({ ok: true as const, list: [] })
+  const [config, facts] = await Promise.all([
+    new WatchlistStore(deps.state).get(userID),
+    watchFacts({ ...deps, decisions: { list: async () => { const r = await open; return r.ok ? r.list : [] } } }, userID, hidden, catalog),
+  ])
+  const { entries, truncated } = resolveWatchlist(config, facts)
+
+  // Tree states of every watched root (for the counts), from the same facts.
+  const roots = rootsOf(facts.sessions)
+  const rootOf = (id: string) => roots.get(id) ?? id
+  const treeStates = new Map<string, ConciergeBoardState>()
+  for (const f of facts.sessions) {
+    const id = rootOf(f.sessionID)
+    const own = f.blockers > 0 ? "blocked" : f.state
+    if (own === undefined || !STATES.has(own)) continue
+    const known = treeStates.get(id)
+    if (known === undefined || (RANK[own] ?? 0) > (RANK[known] ?? 0)) treeStates.set(id, own as ConciergeBoardState)
+  }
+
+  // Facts of the shown roots: one directory lookup, the live catalog sessions, intents and results (many).
+  const shown = entries.slice(0, CONCIERGE_BOARD_LIMITS.sessions).map((e) => e.sessionID)
+  const wanted = new Set(shown)
+  const live = liveSessions(catalog, wanted, (id) => deps.registry.sessionTenant(id) === userID)
+  const records = deps.directory.entries(userID, shown)
+  const ownMachines = deps.store.machines().filter((m) => m.ownerID === userID && !m.revoked)
+  const machineName = new Map(ownMachines.map((m) => [m.id, m.name]))
+  const slugs = new Map(facts.sessions.filter((f) => f.projectSlug !== undefined).map((f) => [f.sessionID, f.projectSlug!]))
+  const coverage = await coverageOf(deps, userID, live)
+  const [intents, results, decisions, armed] = await Promise.all([
+    deps.intents ? deps.intents.many(userID, shown) : new Map(),
+    deps.results ? deps.results.many(userID, shown) : new Map(),
+    open,
+    deps.armed ? deps.armed(userID).catch((cause: unknown) => (console.error(`[hub] concierge board: armed failed: ${(cause as Error).message}`), undefined)) : undefined,
+  ])
+  const rootFacts = new Map<string, BoardRoot>()
+  for (const id of shown) {
+    const record = records.get(id)
+    const reported = live.get(id)
+    const common = {
+      sessionID: id,
+      ...(record?.name ? { name: `@${record.name}` } : {}),
+      ...((record?.project ?? slugs.get(id)) ? { project: record?.project ?? slugs.get(id)! } : {}),
+    }
+    if (reported) {
+      const s = reported.session
+      const blockers = s.blockers.map((b) => ({ kind: b.kind, id: b.id, ...(b.action !== undefined ? { action: b.action } : {}), ...(b.kind === "permission" ? { inGrant: coverage.get(b.id)?.inGrant === true, auto: coverage.get(b.id)?.auto === true } : {}) }))
+      rootFacts.set(id, { ...common, machine: reported.machine, state: STATES.has(s.state) ? (s.state as ConciergeBoardState) : "idle", online: true, title: s.title, blockers })
+      continue
+    }
+    const machine = record?.machineID !== undefined ? machineName.get(record.machineID) : undefined
+    const base = { ...common, ...(machine ? { machine } : {}), ...(record?.title ? { title: record.title } : {}) }
+    // Online per the (shared) directory but not in this hub's catalog: state as last known, blockers not reported.
+    if (record?.online) rootFacts.set(id, { ...base, state: record.state && STATES.has(record.state) ? (record.state as ConciergeBoardState) : "idle", online: true })
+    else rootFacts.set(id, { ...base, state: "offline", online: false, ...(record?.lastSeen !== undefined ? { lastSeen: record.lastSeen } : {}) })
+  }
+
+  const onlineMachines = new Set(catalog.filter((m) => m.processes.length > 0).map((m) => m.id))
+  const machines: ConciergeBoardMachine[] = ownMachines
+    .map((m) => ({ id: m.id, name: m.name, online: onlineMachines.has(m.id) }))
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : a.id < b.id ? -1 : 1))
+
+  const input: BoardInput = {
+    now,
+    entries,
+    truncated,
+    roots: rootFacts,
+    treeStates,
+    rootOf,
+    intents,
+    results,
+    decisions: !deps.decisions ? { status: "unsupported", feature: "decisions" } : decisions.ok ? (decisions.list as BoardDecisionInput[]) : { status: "failed" },
+    hidden,
+    machines,
+    ...(armed !== undefined ? { armed } : {}),
+  }
+  const content: BoardContent = buildBoard(input)
+  const board = { revision: await revisions.stamp(userID, content), ...content }
+  const timeZone = deps.timeZone ? await deps.timeZone(userID).catch(() => undefined) : undefined
+  const rendered = renderBoard(board, timeZone !== undefined ? { timeZone } : {})
+  const extra = [
+    ...(entries.length ? [] : [allSessionsLine(facts.sessions, rootOf, treeStates, hidden)]),
+    ...mutedLine(deps, userID, config.muted, config.mutedProjects.length, hidden),
+  ]
+  return { board, rendered: [rendered, ...extra].join("\n") }
+}
+
+/**
+ * (CON-13) inGrant of the shown sessions' pending permissions (at most CONCIERGE_BOARD_PENDING_MAX each), by request
+ * ID: the current Concierge's grant would approve it once. A failure reads as not covered.
+ */
+async function coverageOf(deps: BoardRouteDeps, userID: string, live: ReadonlyMap<string, { session: CatalogSession }>): Promise<Map<string, { inGrant: boolean; auto: boolean }>> {
+  const out = new Map<string, { inGrant: boolean; auto: boolean }>()
+  if (!deps.coverage || !deps.identity) return out
+  const conciergeID = await deps.identity.current(userID).then((c) => c.sessionID, () => undefined)
+  if (conciergeID === undefined) return out
+  const asks: Array<Promise<void>> = []
+  for (const { session } of live.values()) {
+    for (const b of session.blockers.filter((x) => x.kind === "permission").slice(0, CONCIERGE_BOARD_PENDING_MAX)) {
+      asks.push(deps.coverage(userID, conciergeID, b.sessionID ?? session.id, b.id).then((c) => void out.set(b.id, c), () => void out.set(b.id, { inGrant: false, auto: false })))
+    }
+  }
+  await Promise.all(asks)
+  return out
+}
+
+/** Muted sessions named on the line (the rest counted). */
+const MUTED_SHOWN = 20
+
+/**
+ * (CON-10) The user's muted sessions, so the Concierge says "muted" rather than that it cannot see them: the session
+ * ID and its framed @name (the directory's, this user's records only; never a title), at most MUTED_SHOWN, and the
+ * number of muted projects (never their paths). Never the Concierge's own sessions. No line when nothing is muted.
+ */
+function mutedLine(deps: BoardRouteDeps, userID: string, muted: readonly string[], projects: number, hidden: readonly string[]): string[] {
+  const own = new Set(hidden)
+  const records = deps.directory.entries(userID, muted.filter((id) => !own.has(id)))
+  const ids = muted.filter((id) => records.has(id))
+  if (!ids.length && !projects) return []
+  const all = ids.slice(0, MUTED_SHOWN).map((id) => {
+    const name = records.get(id)?.name
+    return name ? `${id} ${frame(`@${name}`, 80)}` : id
+  })
+  const head = "Muted by the user (not watched; say they are muted): "
+  const tail = (shown: number) => [
+    ...(ids.length > shown ? [`${shown ? " " : ""}(${ids.length - shown} more)`] : []),
+    ...(projects ? [`${shown || ids.length ? "; " : ""}${projects} muted project${projects === 1 ? "" : "s"}`] : []),
+    ".",
+  ].join("")
+  // Names go first when the line is too long: the count of the rest and the muted projects always stay.
+  let named = all
+  while (named.length && head.length + named.join(", ").length + tail(named.length).length > MUTED_LINE_MAX) named = named.slice(0, -1)
+  return [`${head}${named.join(", ")}${tail(named.length)}`]
+}
+
+/** The muted line's length (whole names only). */
+const MUTED_LINE_MAX = 1_000
+
+/**
+ * (CON-09a) Nothing watched: one line of counts over ALL the user's root sessions (not archived or deleted, never the
+ * Concierge's own), so "what is running?" has an answer. Counts only: no names, titles or IDs.
+ */
+function allSessionsLine(sessions: readonly WatchFact[], rootOf: (id: string) => string, treeStates: ReadonlyMap<string, ConciergeBoardState>, hidden: readonly string[]): string {
+  const own = new Set(hidden.map(rootOf))
+  const counts = new Map<string, number>()
+  let total = 0
+  for (const f of sessions) {
+    if (rootOf(f.sessionID) !== f.sessionID || own.has(f.sessionID) || f.archived || f.deleted) continue
+    total++
+    const state = treeStates.get(f.sessionID) ?? (f.state === "offline" || f.state === undefined ? "offline" : "idle")
+    counts.set(state, (counts.get(state) ?? 0) + 1)
+  }
+  if (total === 0) return "All your sessions: none; none watched."
+  if ((counts.get("idle") ?? 0) === total) return `All your sessions: ${total}, all idle; none watched.`
+  const parts = (["working", "blocked", "error", "offline"] as const).filter((k) => counts.get(k)).map((k) => `${counts.get(k)} ${k === "error" ? "in error" : k}`)
+  return `All your sessions: ${total} (${parts.join(", ")}); none watched.`
+}
+
+// ---- Decisions paging ----------------------------------------------------------------------------------------
+
+const encodeCursor = (d: Decision) => Buffer.from(JSON.stringify([d.at, d.id])).toString("base64url")
+
+function decodeCursor(raw: string): [number, string] {
+  try {
+    const value: unknown = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"))
+    if (Array.isArray(value) && value.length === 2 && Number.isSafeInteger(value[0]) && typeof value[1] === "string") return [value[0], value[1]]
+  } catch {}
+  throw new AgentError("invalid", "cursor is not one this route gave")
+}
+
+function pageQuery(url: URL): { state?: DecisionState; limit: number; after?: [number, string] } {
+  const state = url.searchParams.get("state")
+  if (state !== null && state !== "" && !DECISION_STATES.includes(state as DecisionState)) throw new AgentError("invalid", `state is one of ${DECISION_STATES.join(", ")}`)
+  const rawLimit = url.searchParams.get("limit")
+  const limit = rawLimit === null ? DECISIONS_PAGE : Number(rawLimit)
+  if (!Number.isInteger(limit) || limit < 1 || limit > LIST_LIMIT_MAX) throw new AgentError("invalid", `limit is 1–${LIST_LIMIT_MAX}`)
+  const cursor = url.searchParams.get("cursor")
+  return { ...(state ? { state: state as DecisionState } : {}), limit, ...(cursor !== null ? { after: decodeCursor(cursor) } : {}) }
+}
+
+/** Newest first (at desc, then id desc, as Decisions.list sorts): the items strictly after the cursor. */
+const isAfter = (d: Decision, [at, id]: [number, string]) => d.at < at || (d.at === at && d.id < id)
+
+// ---- Routes ----------------------------------------------------------------------------------------------
+
+export function boardRoutes(deps: BoardRouteDeps): AgentRoute[] {
+  const identity = deps.identity ?? NO_CONCIERGE
+  const revisions = new BoardRevisions(deps.state)
+
+  /** Users, and the user's current Concierge through its act token; anyone else is 404. */
+  const admit = async (actor: AgentActor, userID: string) => {
+    if (actor.kind === "app") throw notFound()
+    const current = await identity.current(userID)
+    if (actor.kind === "session" && !(canActAsSession(actor) && current.sessionID !== undefined && current.sessionID === actor.sessionID)) throw notFound()
+    return current
+  }
+
+  const routes: AgentRoute[] = [
+    {
+      method: "GET",
+      path: `${PREFIX}/board`,
+      allow: { session: true, app: true },
+      async handle({ actor, user }) {
+        const current = await admit(actor, user.id)
+        return Response.json(await conciergeBoard(deps, revisions, user.id, current.hiddenSessionIDs), { headers: NO_STORE })
+      },
+    },
+  ]
+  const { decisions } = deps
+  if (decisions) {
+    routes.push(
+      {
+        method: "GET",
+        path: `${PREFIX}/decisions`,
+        allow: { session: true, app: true },
+        async handle({ actor, user, url }) {
+          await admit(actor, user.id)
+          const query = pageQuery(url)
+          const all = await decisions.list(user.id, query.state ? { state: query.state } : {})
+          const after = query.after ? all.filter((d) => isAfter(d, query.after!)) : all
+          const page = after.slice(0, query.limit)
+          const more = after.length > page.length
+          return Response.json({ decisions: page.map(conciergeDecisionView), ...(more ? { cursor: encodeCursor(page.at(-1)!) } : {}) }, { headers: NO_STORE })
+        },
+      },
+      {
+        method: "GET",
+        path: `${PREFIX}/decisions/:id`,
+        allow: { session: true, app: true },
+        async handle({ actor, user, params }) {
+          await admit(actor, user.id)
+          const decision = await decisions.get(user.id, params.id!)
+          if (!decision) throw new AgentError("not_found", "No such decision")
+          return Response.json({ decision: conciergeDecisionView(decision) }, { headers: NO_STORE })
+        },
+      },
+    )
+  }
+  return routes
+}
+
+/**
+ * (FX-05, coordinator decision: Concierge prompt-injection surface) A Decision as these routes return it: exactly
+ * the record they returned before FX-05, without the structured request and reason the hub now stores on its action
+ * for the user's console (GET /api/decisions) only.
+ */
+export function conciergeDecisionView(decision: Decision): Decision {
+  if (!decision.action || (!("request" in decision.action) && !("reason" in decision.action))) return decision
+  const { request: _request, reason: _reason, ...action } = decision.action as typeof decision.action & { request?: unknown; reason?: unknown }
+  return { ...decision, action: action as Decision["action"] }
+}

package/src/central/concierge/board.ts

@@ -0,0 +1,249 @@
+// CON-03 situation board (contract: docs/plans/2026-11-01-concierge-contracts.md, "Situation board (CON-03)"): the
+// pure builder over the watchlist and the hub's own facts, and the per-user revision record. Modelled on
+// workspaces/board.ts: the same section envelope (ok | omitted | unsupported | failed) and truthfulness rules
+// (blockers `{reported: false}` when this hub's catalog does not report the session now, never "none").
+//
+// What a session item carries: IDs, the @name, project and machine labels, the tree state, when it began, blocker
+// count and kinds, open Decision IDs, the stored intent (else the non-placeholder title), the last result and the
+// watch reasons. What it never carries: prompts, message bodies, blocker summaries, Decision questions, options,
+// recommendations or answers, launch reasons, notes, intent writers. Every string from a session (intent, title,
+// machine and party labels) is untrusted: sanitised (boardText: control, ANSI, bidi, zero-width, tag and filler
+// characters go), one line and cut here; the renderer frames it in «…».
+//
+// Decisions shown: open ones about a watched tree (about or the asker, rolled up to the root), sessionless ones (an
+// app's or the user's, about nothing) and the Concierge's own (asked by a hidden session). One only about sessions
+// the watchlist leaves out (muted, unwatched) is not shown: the narrower reading of the contract (CON-03
+// clarification). Newest first, CONCIERGE_BOARD_LIMITS.decisions; per session at most decisionsPerSession IDs.
+//
+// Revision: monotonic per user, stored in StateStore collection `concierge-board` key `revision` as {revision,
+// digest} (a SHA-256 of the content without `at`), version-checked, so it changes only when the content changes and
+// concurrent renders of one change bump it once. Nothing else is written.
+import { createHash } from "node:crypto"
+import {
+  CONCIERGE_BOARD_LIMITS,
+  CONCIERGE_BOARD_PENDING_MAX,
+  INTENT_MAX,
+  type ConciergeBoard,
+  type ConciergeBoardBlocker,
+  type ConciergeBoardDecision,
+  type ConciergeBoardMachine,
+  type ConciergeBoardSection,
+  type ConciergeBoardSession,
+  type ConciergeBoardState,
+  type ConciergeResultOutcome,
+  type SessionIntent,
+  type WatchlistEntry,
+} from "../../../packages/protocol/src/concierge"
+import type { Decision } from "../agent/decisions"
+import { partyLabel } from "../agent/envelope"
+import { isPlaceholderTitle } from "../agent/names"
+import { updateVersioned } from "../agent/versioned"
+import type { StateStore } from "../backend/types"
+import { boardText } from "./board-render"
+
+export const BOARD_COLLECTION = "concierge-board"
+const REVISION_KEY = "revision"
+/** Party labels on the board (sanitised, one line). */
+const FROM_MAX = 80
+/** Machine, project and name labels. */
+const LABEL_CHARS = 80
+
+/** What the hub knows about a shown root session now (directory and catalog; never a spoke). */
+export interface BoardRoot {
+  readonly sessionID: string
+  /** "@name". */
+  readonly name?: string
+  readonly project?: string
+  readonly machine?: string
+  /** The tree state (the catalog rolls blocked/error/working up to the root); offline when no spoke reports it. */
+  readonly state: ConciergeBoardState
+  readonly online: boolean
+  /** The directory's lastSeen (offline sessions). */
+  readonly lastSeen?: number
+  readonly title?: string
+  /** Open blockers in the tree when this hub's catalog reports it; absent: not reported. Summaries are never read. */
+  readonly blockers?: readonly { readonly kind: string; readonly id?: string; readonly action?: string; readonly inGrant?: boolean; readonly auto?: boolean }[]
+}
+
+/** The Decision fields the board reads (never question, options, recommendation or answer). */
+export type BoardDecisionInput = Pick<Decision, "id" | "from" | "about" | "urgency" | "tier" | "at" | "deadline" | "state">
+
+export interface LastResult {
+  readonly at: number
+  readonly outcome: ConciergeResultOutcome
+}
+
+export interface BoardInput {
+  readonly now: number
+  /** The resolved watchlist (≤ 200, priority order). */
+  readonly entries: readonly WatchlistEntry[]
+  readonly truncated: boolean
+  /** Facts of the shown roots (the first CONCIERGE_BOARD_LIMITS.sessions entries). */
+  readonly roots: ReadonlyMap<string, BoardRoot>
+  /** Tree state of every watched root (for the counts). */
+  readonly treeStates: ReadonlyMap<string, ConciergeBoardState>
+  /** The root of a session (subagents roll up). */
+  readonly rootOf: (sessionID: string) => string
+  /** Stored intents of the shown roots. */
+  readonly intents: ReadonlyMap<string, SessionIntent>
+  /** Last results of the shown roots. */
+  readonly results: ReadonlyMap<string, LastResult>
+  /** The user's open Decisions, or why there are none to show. */
+  readonly decisions: readonly BoardDecisionInput[] | { readonly status: "unsupported"; readonly feature: string } | { readonly status: "failed" }
+  /** The Concierge's own sessions (current and previous). */
+  readonly hidden: readonly string[]
+  readonly machines: readonly ConciergeBoardMachine[]
+  /** The Decision armed now (CON-06): its board item carries `armed: true`. */
+  readonly armed?: string
+}
+
+export type BoardContent = Omit<ConciergeBoard, "revision">
+
+/** Sanitised, one line, at most `max` characters (code points); undefined when nothing is left. */
+function label(text: string | undefined, max: number): string | undefined {
+  if (text === undefined) return undefined
+  return boardText(text, max) || undefined
+}
+
+/** Blocker kinds are hub enums (permission, form, …); anything else is shown as "other", never as free text. */
+const BLOCKER_KIND = /^[a-z][a-z_]{0,31}$/
+
+/** (CON-13) Blocker IDs the board names (spoke IDs: per_…, frm_…, que_…). */
+const BLOCKER_ID = /^[A-Za-z0-9_-]{1,64}$/
+/** Permission actions are tool or permission names (edit, shell, external_directory, an MCP tool…). */
+const ACTION = /^[A-Za-z][A-Za-z0-9_.:-]{0,39}$/
+
+/** (CON-13) The pending permissions (with the hub's inGrant) and forms the Concierge may act on, by ID. */
+function pendingOf(blockers: NonNullable<BoardRoot["blockers"]>): ConciergeBoardBlocker[] {
+  const out: ConciergeBoardBlocker[] = []
+  for (const b of blockers) {
+    if (out.length >= CONCIERGE_BOARD_PENDING_MAX) break
+    if (b.id === undefined || !BLOCKER_ID.test(b.id)) continue
+    if (b.kind === "permission") out.push({ kind: "permission", id: b.id, action: b.action !== undefined && ACTION.test(b.action) ? b.action : "other", inGrant: b.inGrant === true, auto: b.inGrant === true && b.auto === true })
+    else if (b.kind === "form") out.push({ kind: "form", id: b.id })
+  }
+  return out
+}
+
+const COUNTED: ReadonlySet<ConciergeBoardState> = new Set(["working", "blocked", "error"])
+
+function sessionItem(entry: WatchlistEntry, input: BoardInput, decisions: readonly string[]): ConciergeBoardSession {
+  const r = input.roots.get(entry.sessionID)
+  const state: ConciergeBoardState = r?.state ?? "offline"
+  const result = input.results.get(entry.sessionID)
+  const since = state === "offline" ? r?.lastSeen : state === "idle" ? result?.at : entry.lastActiveAt
+  const stored = input.intents.get(entry.sessionID)
+  const intentText = stored ? label(stored.text, INTENT_MAX) : undefined
+  const title = intentText === undefined && r && !isPlaceholderTitle(r.title) ? label(r.title, CONCIERGE_BOARD_LIMITS.titleChars) : undefined
+  const blockers = r?.blockers
+  const name = label(r?.name, LABEL_CHARS)
+  const project = label(r?.project, LABEL_CHARS)
+  const machine = label(r?.machine, LABEL_CHARS)
+  return {
+    sessionID: entry.sessionID,
+    ...(name ? { name } : {}),
+    ...(project ? { project } : {}),
+    ...(machine ? { machine } : {}),
+    state,
+    ...(since !== undefined ? { since } : {}),
+    blockers: blockers ? { reported: true, count: blockers.length, kinds: [...new Set(blockers.map((b) => (BLOCKER_KIND.test(b.kind) ? b.kind : "other")))].sort(), ...pendingField(blockers) } : { reported: false },
+    decisions,
+    ...(intentText !== undefined && stored ? { intent: { text: intentText, source: stored.source } } : {}),
+    ...(title !== undefined ? { title } : {}),
+    ...(result ? { lastResult: { at: result.at, outcome: result.outcome } } : {}),
+    reasons: [...entry.reasons],
+  }
+}
+
+const pendingField = (blockers: NonNullable<BoardRoot["blockers"]>) => {
+  const pending = pendingOf(blockers)
+  return pending.length ? { pending } : {}
+}
+
+/** Builds the board's content (everything but the revision). Pure. */
+export function buildBoard(input: BoardInput): BoardContent {
+  const limits = CONCIERGE_BOARD_LIMITS
+  const watched = new Set(input.entries.map((e) => e.sessionID))
+  const hidden = new Set(input.hidden)
+
+  // ---------- Decisions ----------
+  const perRoot = new Map<string, string[]>()
+  let decisions: ConciergeBoardSection<ConciergeBoardDecision>
+  let openDecisions = 0
+  if (!Array.isArray(input.decisions)) decisions = input.decisions as ConciergeBoardSection<ConciergeBoardDecision>
+  else {
+    const open = (input.decisions as readonly BoardDecisionInput[]).filter((d) => d.state === "open").sort((a, b) => b.at - a.at || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    const shown: ConciergeBoardDecision[] = []
+    for (const d of open) {
+      const asker = d.from.kind === "session" ? d.from.sessionID : undefined
+      const concerned = [...new Set([...(asker !== undefined ? [asker] : []), ...d.about])]
+      const roots = [...new Set(concerned.map(input.rootOf))].filter((id) => watched.has(id))
+      const own = asker !== undefined && hidden.has(asker)
+      if (roots.length === 0 && concerned.length > 0 && !own) continue
+      openDecisions++
+      for (const id of roots) {
+        const list = perRoot.get(id) ?? []
+        if (list.length < limits.decisionsPerSession) list.push(d.id)
+        perRoot.set(id, list)
+      }
+      if (shown.length >= limits.decisions) continue
+      shown.push({
+        id: d.id,
+        from: own ? "@@concierge" : (label(partyLabel(d.from), FROM_MAX) ?? "unknown"),
+        about: d.about.slice(0, limits.decisionsPerSession),
+        urgency: d.urgency,
+        tier: d.tier,
+        at: d.at,
+        ...(d.deadline !== undefined ? { deadline: d.deadline } : {}),
+        ...(input.armed === d.id ? { armed: true as const } : {}),
+      })
+    }
+    decisions = { status: "ok", items: shown, truncated: openDecisions > shown.length }
+  }
+
+  // ---------- sessions ----------
+  const items = input.entries.slice(0, limits.sessions).map((entry) => sessionItem(entry, input, perRoot.get(entry.sessionID) ?? []))
+  const counts = { watched: input.entries.length, working: 0, blocked: 0, error: 0, openDecisions }
+  for (const entry of input.entries) {
+    const state = input.treeStates.get(entry.sessionID) ?? input.roots.get(entry.sessionID)?.state
+    if (state !== undefined && COUNTED.has(state)) counts[state as "working" | "blocked" | "error"]++
+  }
+
+  // ---------- machines ----------
+  const machines = input.machines.slice(0, limits.machines).map((m) => ({ id: m.id, name: label(m.name, LABEL_CHARS) ?? m.id, online: m.online }))
+
+  return {
+    at: input.now,
+    sessions: { status: "ok", items, truncated: input.truncated || input.entries.length > items.length },
+    decisions,
+    machines: { status: "ok", items: machines, truncated: input.machines.length > machines.length },
+    counts,
+  }
+}
+
+interface RevisionRecord {
+  readonly revision: number
+  readonly digest: string
+}
+
+/** The board content's digest: everything but `at`. */
+const digestOf = (board: BoardContent) => {
+  const { at: _at, ...content } = board
+  return createHash("sha256").update(JSON.stringify(content)).digest("base64url")
+}
+
+/** The per-user board revision: bumped (version-checked) only when the content's digest changes. */
+export class BoardRevisions {
+  constructor(private readonly state: StateStore) {}
+
+  async stamp(userID: string, board: BoardContent): Promise<number> {
+    const digest = digestOf(board)
+    let kept = 0
+    const written = await updateVersioned<RevisionRecord>(this.state, userID, BOARD_COLLECTION, REVISION_KEY, (current) => {
+      kept = current?.revision ?? 0
+      if (current?.digest === digest) return undefined
+      return { revision: kept + 1, digest }
+    })
+    return written?.revision ?? kept
+  }
+}