@huynle/hub 0.7.4 → 0.8.1

package/src/central/workspaces/coordinator.ts

@@ -0,0 +1,841 @@
+// Batched supervisor delivery (HWA-11; contract: Workspaces checkpoints and "Contract clarifications" HWA-06/HWA-10
+// in docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md). Supervisors (the workspace master, and any member
+// with supervised members) learn what changed under them through the EXISTING messaging/wake path: one hub message
+// per batch to the supervisor session. Nothing here reads anything through a session token, and no new grant exists.
+//
+// What a supervisor hears: compact journal events (canonical agent journal, events.ts) about the members it is
+// responsible for (checkpoints.ts supervisedMembers: the master every other current member, anyone else its
+// supervision subtree): session state and blockers of their sessions, their assignments' status, membership and
+// supervision changes, and master replacement. Lines carry IDs, enums and numbers only, rendered from the already
+// text-free events; never titles, criteria, message text or blocker summaries (the supervisor's session token can't
+// read the workspace routes, so a digest must not leak what they hold). Message, launch and artifact families are
+// never read.
+//
+// Self-trigger and digest loops: a supervisor never hears about its own session, its own membership or messages
+// (delivering a digest wakes the supervisor and produces message and session events; none come back to it). Since
+// supervision is acyclic, a chain of wake-ups only travels up the tree and dies out at the master; the hourly
+// budgets cap it in any case. The sender is a fixed non-user party (coordinatorActor) so digests never reset the
+// recipient's message hop chain the way a human turn would.
+//
+// Batching and waking (RP-07 #10: supervisors were woken for "no action" turns): three kinds of lines.
+// - Priority (a blocker opened, a session blocked or erroring, an assignment blocked, a member leaving, a master
+//   replaced): next pass, urgent (steered into a running turn), listed first, waking the supervisor.
+// - Wake-worthy (an assignment closed: done or cancelled): debounced by wakeDebounceMs (at most wakeMaxDelayMs),
+//   waking the supervisor, not steered; whatever routine lines are held go along.
+// - Routine (session state, assignment progress, membership/supervision/workspace changes, calm snapshots):
+//   debounced by debounceMs (at most maxDelayMs) and sent with wake:false: admitted for the supervisor's next turn,
+//   never starting one (an idle supervisor is not woken; the digest folds into its next real wake).
+// - Snapshots are routine unless urgent: a priority line was folded into them (dropped by an overflow, lost to a
+//   reset, or in an abandoned priority batch) or they show a member blocked, erroring or with open blockers. An
+//   urgent snapshot wakes and steers like a priority batch (priority budget while there is one).
+// - Repeated trouble (RF-05): a session blocked or erroring again for a reason the supervisor was woken about within
+//   blockFoldMs (same session; same blocker kind, or the same blocked/error state; recorded in the ledger's
+//   `alerts` when that batch was delivered with a wake the hub carried out, `woke`, or acknowledged) is a routine line, not a priority one: a member asking the
+//   user one permission after another wakes its supervisor once per window, not per prompt. Another kind, another
+//   member, or the window passed (measured from the last wake about it) wakes again; snapshots fold the same way.
+//   Resolutions (blocker.closed, the recovery) were routine already.
+// State lines (a session's state, an assignment's status) are collapsed per subject while held (only the latest
+// counts), except that a held priority line is never replaced: an error or block that already cleared still goes
+// out, followed by the recovery. A batch is cut only from what the supervisor does not know yet: a state equal to
+// the last one delivered to it (ledger `facts`, from deltas and the latest snapshot; bounded by FACTS_MAX) is
+// dropped unless a priority line about the same subject goes with it, and a batch with nothing left is skipped (no
+// message, no budget). Presence (session.added / session.removed, subject `p:<session>`, RF-08) is a state line too:
+// only the latest held presence of a session counts, and it is dropped when it equals the last delivered one
+// (snapshots record each member's): a removed → added flap (a spoke restart or reconnect) is not news, a session
+// really gone, or back after a reported removal, is (routine; a member leaving is workspace.member.left, priority,
+// never collapsed). Held lines are never compared with each other: a duplicate event must not hide a real change.
+// Blockers and other event lines are never deduplicated.
+// Budgets per supervisor and rolling hour: batchesPerHour routine batches and priorityPerHour priority ones (a
+// priority batch over its budget uses the routine one, then waits); a batch holds at most linesPerBatch lines (the
+// rest is counted). Held lines are kept up to bufferLines; beyond that they are dropped, counted, and the next batch
+// is a snapshot instead.
+//
+// Snapshots replace deltas when the delta can't be trusted: a new supervisor without a usable checkpoint, a cursor
+// the journal no longer covers (expired, trimmed, or the standalone hub restarted: the memory journal gets a new
+// epoch), a buffer overflow, or an abandoned batch. A snapshot lists the supervised members (session, role,
+// presence, state, blocker count) and their unresolved assignments (IDs and status), with the workspace and
+// supervision revisions.
+//
+// Delivery truthfulness (at-least-once, never exactly-once): every batch has an identity (dig_…) and a sequence
+// number and is stored in the supervisor's ledger BEFORE it is sent. A send is first claimed in the ledger
+// (version-checked, so two pods never both claim it); the outcome is recorded after. A claim found unrecorded after
+// claimGraceMs (the sender crashed or was deposed mid-send) is uncertain and resent with the SAME batch ID; so is a
+// send that failed in a way that may have stored the message. Refusals that store nothing (rate limited, recipient
+// unknown or unsupported) are retried too. The text says "attempt n" and asks the supervisor to skip a batch ID it
+// already handled. After maxAttempts the batch is abandoned and the next batch is a snapshot that says so. A
+// checkpoint naming the batch (POST /workspaces/:id/checkpoints {batchID}) resolves it: no more retries.
+//
+// Revocation: a supervisor that departs, loses its last supervised member, or whose workspace is archived has its
+// ledger deleted on the next pass, pending batch included: nothing more is sent to it.
+//
+// Leadership and parity: passes run on the `workspace-coordinator` leader (http.ts); `isLeader` is checked before
+// each user and each send, and every ledger write is version-checked, so a deposed leader cannot double-advance a
+// ledger. Ledgers live in the StateStore (collection `workspace-coordinator`, key `<workspaceID>.<memberID>`, the
+// file store standalone, Postgres in a cluster) and survive restarts, session and launch expiry. A per-user scan
+// marker (`workspace-coordinator-scan`) skips users whose journal did not move and who have nothing pending.
+// Rollback: older hubs never read these collections.
+import {
+  LIST_LIMIT_MAX,
+  type HubWorkspace,
+  type WorkspaceMember,
+} from "../../protocol"
+import type { AppActor } from "../agent/actor"
+import { AgentError } from "../agent/errors"
+import type { AgentEvents, EventRecord, EventsSince } from "../agent/events"
+import { updateVersioned } from "../agent/versioned"
+import { realTimers } from "../backend/memory-bus"
+import type { Clock, StateStore, Timers } from "../backend/types"
+import type { BoardSession, BoardSessions } from "./board"
+import { type CheckpointCursors, type CheckpointStore, checkpointKey, newBatchID, supervisedMembers } from "./checkpoints"
+import type { MembershipStore } from "./members"
+import type { WorkspaceStore } from "./store"
+import type { SupervisionStore } from "./supervision"
+
+export const WORKSPACE_COORDINATOR = "workspace-coordinator"
+export const WORKSPACE_COORDINATOR_SCAN = "workspace-coordinator-scan"
+const SCAN_KEY = "journal"
+/** How often the leader looks at the journal. */
+export const COORDINATOR_TICK_MS = 10_000
+/** The fixed sender of digests: an app party no real token can be (app token IDs are 16 hex digits). */
+export const COORDINATOR_TOKEN = "workspace-coordinator"
+const HOUR_MS = 60 * 60_000
+const LINE_MAX = 200
+const HISTORY_MAX = 20
+/** Last reported states kept per supervisor (for skipping digests that tell nothing new). */
+const FACTS_MAX = 400
+
+export interface CoordinatorLimits {
+  /** Quiet period before routine lines go out (queued, without a wake). */
+  readonly debounceMs: number
+  /** Routine lines go out at most this long after the first one. */
+  readonly maxDelayMs: number
+  /** Quiet period before wake-worthy, non-urgent lines (an assignment closed) go out, waking the supervisor. */
+  readonly wakeDebounceMs: number
+  /** Wake-worthy lines go out at most this long after the first one. */
+  readonly wakeMaxDelayMs: number
+  /** Routine batches (snapshots included) per supervisor per rolling hour. */
+  readonly batchesPerHour: number
+  /** Priority batches per supervisor per rolling hour (over it they use the routine budget). */
+  readonly priorityPerHour: number
+  /** Lines listed in one batch. */
+  readonly linesPerBatch: number
+  /** Lines held per supervisor while waiting; beyond it they are dropped and a snapshot follows. */
+  readonly bufferLines: number
+  /** Send attempts of one batch before it is abandoned. */
+  readonly maxAttempts: number
+  /** Waits before each retry (the last repeats). */
+  readonly retryMs: readonly number[]
+  /** A send not answered within this long is given up on as uncertain (must stay below claimGraceMs). */
+  readonly sendTimeoutMs: number
+  /** A claimed but unrecorded send is in flight elsewhere for this long; after it, uncertain. */
+  readonly claimGraceMs: number
+  /** Supervisors served per user per pass. */
+  readonly supervisorsPerUser: number
+  /**
+   * A member blocked again for a reason the supervisor was woken about this recently (same session, same blocker
+   * kind or blocked/error state) is reported routinely instead of waking it again (RF-05).
+   */
+  readonly blockFoldMs: number
+}
+
+export const COORDINATOR_LIMITS: CoordinatorLimits = {
+  debounceMs: 2 * 60_000,
+  maxDelayMs: 15 * 60_000,
+  wakeDebounceMs: 30_000,
+  wakeMaxDelayMs: 5 * 60_000,
+  batchesPerHour: 12,
+  priorityPerHour: 12,
+  linesPerBatch: 40,
+  bufferLines: 200,
+  maxAttempts: 6,
+  retryMs: [30_000, 2 * 60_000, 10 * 60_000, 30 * 60_000],
+  sendTimeoutMs: 60_000,
+  claimGraceMs: 2 * 60_000,
+  supervisorsPerUser: 400,
+  blockFoldMs: 15 * 60_000,
+}
+
+/** Hands one digest to the messaging path (production: Delivery.send as coordinatorActor). */
+export type DigestSend = (
+  userID: string,
+  sessionID: string,
+  text: string,
+  options: { readonly wake: boolean; readonly urgent: boolean },
+) => Promise<{ readonly messageID: string; readonly delivery?: string; readonly woke?: boolean }>
+
+/** Whether a sent digest woke its supervisor: the hub says so (`woke`), else only a turn or a steer counts. */
+const woke = (result: { readonly delivery?: string; readonly woke?: boolean }): boolean => result.woke ?? (result.delivery === "turn" || result.delivery === "steer")
+
+/** The party digests come from: never the user (a user message would reset hop chains and imply a human). */
+export const coordinatorActor = (userID: string): AppActor => ({ kind: "app", userID, tokenID: COORDINATOR_TOKEN, scopes: [], label: "workspace digest" })
+
+/** Refusals that store nothing: retrying cannot duplicate. Anything else may have stored the message. */
+const REFUSED: ReadonlySet<string> = new Set(["rate_limited", "not_found", "unsupported", "forbidden", "invalid", "gone"])
+
+export interface CoordinatorDeps {
+  readonly state: StateStore
+  readonly events: Pick<AgentEvents, "since" | "latest">
+  readonly cursors: Pick<CheckpointCursors, "encode">
+  readonly workspaces: Pick<WorkspaceStore, "list">
+  readonly members: Pick<MembershipStore, "members" | "assignments">
+  readonly supervision: Pick<SupervisionStore, "graph">
+  /** Where a new ledger resumes (the supervisor's latest checkpoint); without it new ledgers snapshot. */
+  readonly checkpoints?: Pick<CheckpointStore, "latest">
+  /** Session facts for snapshots (the board's lookup: directory and catalog, never a spoke). */
+  readonly sessions?: BoardSessions
+  readonly send: DigestSend
+  readonly users: () => Iterable<string> | Promise<Iterable<string>>
+  /** Leadership (cluster: the leader loop); checked before each user and each send. Default: always. */
+  readonly isLeader?: () => boolean
+  readonly owner?: string
+  readonly now?: Clock
+  readonly timers?: Timers
+  readonly tickMs?: number
+  readonly limits?: Partial<CoordinatorLimits>
+  readonly newBatchID?: () => string
+  readonly log?: (message: string) => void
+}
+
+interface Line {
+  /** Priority: goes out on the next pass, steered, waking the supervisor. */
+  readonly p: boolean
+  readonly text: string
+  /** Wakes the supervisor (an assignment closed), after the shorter wake debounce; not steered. */
+  readonly w?: true
+  /** A state line: the subject it is about (later lines replace it) and the state it reports. */
+  readonly k?: string
+  readonly f?: string
+  /** Further states a snapshot line reports (a member's presence next to its state): recorded like k/f. */
+  readonly x?: Facts
+  /** A priority line about trouble of a session: its reasons (`<session> blocker:<kind>`, `<session> state:<state>`). */
+  readonly b?: readonly string[]
+}
+
+/** Last reported state per subject (`s:<session>`, `p:<session>` presence, `a:<assignment>`). */
+type Facts = Readonly<Record<string, string>>
+
+export interface DigestBatch {
+  readonly id: string
+  readonly seq: number
+  readonly kind: "delta" | "snapshot"
+  /** Snapshots: why (and how many lines were dropped). */
+  readonly reason?: SnapshotReason
+  readonly dropped?: number
+  /** Which budget it uses (priority batches are urgent). */
+  readonly budget: "priority" | "routine"
+  /** Whether it starts a turn (absent in batches stored by older hubs: they woke). */
+  readonly wake?: boolean
+  /** The states it reports; a snapshot's replace the ledger's on delivery, a delta's are merged. */
+  readonly facts?: Facts
+  /** The trouble reasons it wakes the supervisor about (Line.b of its priority lines). */
+  readonly alerts?: readonly string[]
+  readonly lines: readonly string[]
+  readonly more: number
+  /** The journal position it covers up to (its cursor). */
+  readonly position: string
+  readonly cutAt: number
+  readonly state: "ready" | "sending" | "retry"
+  readonly attempts: number
+  readonly nextAt?: number
+  readonly claimedBy?: string
+  readonly claimedAt?: number
+  /** Why the last attempt did not land. */
+  readonly last?: "uncertain" | "refused"
+}
+
+export type SnapshotReason = "new" | "reset" | "overflow" | "abandoned"
+
+/** A snapshot owed instead of a delta; `urgent` when priority news was folded into it (it wakes and steers). */
+interface OwedSnapshot {
+  readonly reason: SnapshotReason
+  readonly dropped: number
+  readonly urgent?: true
+}
+
+const urgentIf = (urgent: boolean): { urgent?: true } => (urgent ? { urgent: true } : {})
+
+export interface DigestOutcome {
+  readonly batchID: string
+  readonly seq: number
+  readonly kind: DigestBatch["kind"]
+  readonly at: number
+  readonly attempts: number
+  readonly outcome: "delivered" | "acknowledged" | "abandoned"
+  readonly messageID?: string
+  readonly delivery?: string
+}
+
+/** A supervisor's durable delivery state. */
+export interface SupervisorLedger {
+  readonly v: 1
+  readonly workspaceID: string
+  readonly supervisorMemberID: string
+  readonly sessionID: string
+  readonly generation: number
+  /** Journal position scanned up to. */
+  readonly position: string
+  /** A snapshot is owed instead of a delta. */
+  readonly snapshot?: OwedSnapshot
+  readonly buffer: readonly Line[]
+  readonly firstAt?: number
+  readonly lastAt?: number
+  readonly batch?: DigestBatch
+  /** Sends in the last hour (budgets). */
+  readonly window: readonly { readonly at: number; readonly budget: DigestBatch["budget"] }[]
+  readonly history: readonly DigestOutcome[]
+  readonly seq: number
+  /** The states delivered so far (bounded): a digest that would only repeat them is skipped. */
+  readonly facts?: Facts
+  /** Trouble reasons the supervisor was woken about → when (bounded): repeats within blockFoldMs are folded. */
+  readonly alerts?: Readonly<Record<string, number>>
+}
+
+interface Context {
+  readonly userID: string
+  readonly workspace: HubWorkspace
+  readonly supervisor: WorkspaceMember
+  readonly master: boolean
+  readonly scope: ReadonlySet<string>
+  /** Supervised members' sessions → member IDs. */
+  readonly sessions: ReadonlyMap<string, string>
+  readonly current: readonly { member: WorkspaceMember; presence: string }[]
+  readonly supervisionRevision: number
+}
+
+type Since = (position: string) => Promise<EventsSince>
+
+const without = <T extends object, K extends keyof T>(value: T, ...keys: K[]): Omit<T, K> => {
+  const out = { ...value }
+  for (const key of keys) delete out[key]
+  return out
+}
+
+const OPEN: ReadonlySet<string> = new Set(["open", "in_progress", "blocked"])
+const SESSION_TYPES: ReadonlySet<string> = new Set(["session.changed", "blocker.opened", "blocker.closed", "session.added", "session.removed"])
+
+function render(p: boolean, type: string, ids: readonly (string | undefined)[], data: Readonly<Record<string, string | number | boolean>>, extra: Omit<Line, "p" | "text"> = {}): Line {
+  const kv = Object.entries(data).map(([k, v]) => `${k}=${String(v)}`)
+  const text = [p ? "!" : "-", type, ...ids.filter((id): id is string => !!id), ...kv].join(" ")
+  return { p, text: text.length > LINE_MAX ? `${text.slice(0, LINE_MAX - 1)}…` : text, ...extra }
+}
+
+/** Assignment statuses that close it: the supervisor is woken (its worker finished or gave up). */
+const CLOSED: ReadonlySet<unknown> = new Set(["done", "cancelled"])
+/** Session states that need the supervisor (priority lines, urgent snapshots). */
+const URGENT_STATES: ReadonlySet<unknown> = new Set(["blocked", "error"])
+const sessionFact = (state: unknown) => `state=${String(state)}`
+/** A session's presence (session.added: online, session.removed: offline), its own subject `p:<session>`. */
+const presenceFact = (online: boolean) => `presence=${online ? "online" : "offline"}`
+const PRESENCE: ReadonlySet<string> = new Set(["session.added", "session.removed"])
+const assignmentFact = (status: unknown, memberID: string | undefined) => `status=${String(status)} member=${memberID ?? "?"}`
+
+/** The line a journal record is for this supervisor, or undefined (not its business, or its own doing). */
+export function digestLine(record: Pick<EventRecord, "event" | "family">, ctx: Pick<Context, "workspace" | "supervisor" | "master" | "scope" | "sessions">): Line | undefined {
+  const { event, family } = record
+  const s = event.subject
+  const d = event.data
+  const me = ctx.supervisor
+  if (s.sessionID === me.sessionID || s.senderID === me.sessionID || s.memberID === me.id) return undefined
+  if (family === "session") {
+    if (!SESSION_TYPES.has(event.type) || !s.sessionID) return undefined
+    const memberID = ctx.sessions.get(s.sessionID)
+    if (!memberID) return undefined
+    const p = event.type === "blocker.opened" || (event.type === "session.changed" && URGENT_STATES.has(d.state))
+    const state =
+      event.type === "session.changed"
+        ? { k: `s:${s.sessionID}`, f: sessionFact(d.state) }
+        : PRESENCE.has(event.type)
+          ? { k: `p:${s.sessionID}`, f: presenceFact(event.type === "session.added") }
+          : {}
+    const reason = event.type === "blocker.opened" ? `blocker:${String(d.kind)}` : `state:${String(d.state)}`
+    return render(p, event.type, [s.sessionID, memberID], d, { ...state, ...(p ? { b: [`${s.sessionID} ${reason}`] } : {}) })
+  }
+  if (family !== "manage" || s.workspaceID !== ctx.workspace.id) return undefined
+  const inScope = s.memberID !== undefined && ctx.scope.has(s.memberID)
+  const ids = [s.memberID, s.sessionID, s.assignmentID, s.supervisorMemberID]
+  switch (event.type) {
+    case "workspace.assignment.changed":
+      if (!inScope || !s.assignmentID) return undefined
+      return render(d.status === "blocked", event.type, ids, d, { k: `a:${s.assignmentID}`, f: assignmentFact(d.status, s.memberID), ...(CLOSED.has(d.status) ? { w: true as const } : {}) })
+    case "workspace.member.left":
+      return inScope || ctx.master ? render(true, event.type, ids, d) : undefined
+    case "workspace.master.replaced":
+      return render(true, event.type, ids, d)
+    case "workspace.supervision.changed":
+      return inScope || s.supervisorMemberID === me.id || ctx.master ? render(false, event.type, ids, d) : undefined
+    case "workspace.member.joined":
+    case "workspace.updated":
+    case "workspace.sidechat.created":
+      return ctx.master || inScope ? render(false, event.type, ids, d) : undefined
+    default:
+      return undefined
+  }
+}
+
+/** The ledger's facts once `batch` reached the supervisor: a snapshot's replace them, a delta's are merged (bounded). */
+function reported(ledger: SupervisorLedger, batch: DigestBatch): Facts {
+  const base: Record<string, string> = batch.kind === "snapshot" ? {} : { ...ledger.facts }
+  for (const [key, fact] of Object.entries(batch.facts ?? {})) {
+    delete base[key] // re-inserted last: the oldest facts are dropped first
+    base[key] = fact
+  }
+  const keys = Object.keys(base)
+  for (const key of keys.slice(0, Math.max(0, keys.length - FACTS_MAX))) delete base[key]
+  return base
+}
+
+/** The ledger's alerts once `batch` woke the supervisor at `at`: expired ones dropped, the batch's added (bounded). */
+function withAlerts(ledger: SupervisorLedger, batch: DigestBatch, at: number, foldMs: number): Readonly<Record<string, number>> {
+  const out: Record<string, number> = {}
+  for (const [key, when] of Object.entries(ledger.alerts ?? {})) if (at - when < foldMs) out[key] = when
+  for (const key of batch.alerts ?? []) {
+    delete out[key] // re-inserted last: the oldest are dropped first
+    out[key] = at
+  }
+  const keys = Object.keys(out)
+  for (const key of keys.slice(0, Math.max(0, keys.length - FACTS_MAX))) delete out[key]
+  return out
+}
+
+export class SupervisorCoordinator {
+  readonly limits: CoordinatorLimits
+  private readonly deps: CoordinatorDeps
+  private readonly now: Clock
+  private readonly timers: Timers
+  private readonly owner: string
+  private readonly log: (message: string) => void
+  private readonly newBatchID: () => string
+  private running: Promise<void> | undefined
+  private timer: unknown
+  private started = false
+  private stopped = false
+
+  constructor(deps: CoordinatorDeps) {
+    this.deps = deps
+    this.limits = { ...COORDINATOR_LIMITS, ...deps.limits }
+    this.now = deps.now ?? Date.now
+    this.timers = deps.timers ?? realTimers
+    this.owner = deps.owner ?? `coordinator-${process.pid}`
+    this.log = deps.log ?? ((message) => console.error(message))
+    this.newBatchID = deps.newBatchID ?? newBatchID
+  }
+
+  /** Runs a pass every tickMs until stop() (the leader calls it when elected). */
+  start(): void {
+    this.stopped = false
+    if (this.started) return
+    this.started = true
+    this.schedule()
+  }
+
+  /** Stops scheduling and sending (deposed or shutting down); a pass in flight sends nothing more. */
+  stop(): void {
+    this.stopped = true
+    this.started = false
+    if (this.timer !== undefined) this.timers.clear(this.timer)
+    this.timer = undefined
+  }
+
+  /** One pass over every user (passes never overlap). */
+  tick(): Promise<void> {
+    this.running ??= this.pass().finally(() => {
+      this.running = undefined
+    })
+    return this.running
+  }
+
+  /** A supervisor's ledger (tests, HWA-12 recovery). */
+  async ledger(userID: string, workspaceID: string, supervisorMemberID: string): Promise<SupervisorLedger | undefined> {
+    return (await this.deps.state.get<SupervisorLedger>(userID, WORKSPACE_COORDINATOR, checkpointKey(workspaceID, supervisorMemberID)))?.value
+  }
+
+  /** A checkpoint named a batch: if it is still pending, it is resolved (no more retries). */
+  async acknowledged(userID: string, workspaceID: string, supervisorMemberID: string, batchID: string | undefined): Promise<void> {
+    if (!batchID) return
+    await updateVersioned<SupervisorLedger>(this.deps.state, userID, WORKSPACE_COORDINATOR, checkpointKey(workspaceID, supervisorMemberID), (ledger) => {
+      if (!ledger?.batch || ledger.batch.id !== batchID) return undefined
+      return { ...without(ledger, "batch"), facts: reported(ledger, ledger.batch), alerts: this.alerted(ledger, ledger.batch), history: this.outcome(ledger, ledger.batch, "acknowledged") }
+    })
+  }
+
+  // ---------- internals ----------
+
+  private alerted(ledger: SupervisorLedger, batch: DigestBatch, at = this.now()): Readonly<Record<string, number>> {
+    return withAlerts(ledger, batch, at, this.limits.blockFoldMs)
+  }
+
+  /** A priority line about trouble the supervisor was woken about within blockFoldMs: routine instead (RF-05). */
+  private fold(line: Line, ledger: SupervisorLedger, t: number): Line {
+    if (!line.p || !line.b?.length) return line
+    const alerts = ledger.alerts ?? {}
+    const known = line.b.every((key) => alerts[key] !== undefined && t - alerts[key]! < this.limits.blockFoldMs)
+    return known ? { ...without(line, "b"), p: false, text: line.text.replace(/^! /, "- ") } : line
+  }
+
+  private leading(): boolean {
+    return !this.stopped && (this.deps.isLeader?.() ?? true)
+  }
+
+  private schedule(): void {
+    this.timer = this.timers.set(() => {
+      this.timer = undefined
+      void this.tick().finally(() => {
+        if (this.started) this.schedule()
+      })
+    }, this.deps.tickMs ?? COORDINATOR_TICK_MS)
+  }
+
+  private async pass(): Promise<void> {
+    if (!this.leading()) return
+    let users: string[]
+    try {
+      users = [...(await this.deps.users())]
+    } catch (cause) {
+      this.log(`[hub] workspace coordinator: users failed: ${(cause as Error).message}`)
+      return
+    }
+    for (const userID of users) {
+      if (!this.leading()) return
+      try {
+        await this.user(userID)
+      } catch (cause) {
+        this.log(`[hub] workspace coordinator: pass failed: ${(cause as Error).message}`)
+      }
+    }
+  }
+
+  private async user(userID: string): Promise<void> {
+    const { state } = this.deps
+    const latest = await this.deps.events.latest(userID)
+    const ledgers = await state.list<SupervisorLedger>(userID, WORKSPACE_COORDINATOR)
+    const marker = (await state.get<{ position: string }>(userID, WORKSPACE_COORDINATOR_SCAN, SCAN_KEY))?.value
+    const busy = ledgers.some(({ value }) => value.batch !== undefined || value.buffer.length > 0 || value.snapshot !== undefined)
+    if (marker?.position === latest && !busy) return
+
+    const memo = new Map<string, Promise<EventsSince>>()
+    const since: Since = (position) => {
+      let result = memo.get(position)
+      if (!result) memo.set(position, (result = this.deps.events.since(userID, position)))
+      return result
+    }
+    const active: HubWorkspace[] = []
+    let cursor: string | undefined
+    do {
+      const page = await this.deps.workspaces.list(userID, { state: "active", limit: LIST_LIMIT_MAX, ...(cursor ? { cursor } : {}) })
+      active.push(...page.items)
+      cursor = page.cursor
+    } while (cursor)
+
+    const served = new Set<string>()
+    const examined = new Set<string>()
+    let count = 0
+    for (const workspace of active) {
+      if (count >= this.limits.supervisorsPerUser) {
+        this.log(`[hub] workspace coordinator: over ${this.limits.supervisorsPerUser} supervisors for one user; the rest wait`)
+        break
+      }
+      examined.add(workspace.id)
+      const views = await this.deps.members.members(userID, workspace.id)
+      const graph = await this.deps.supervision.graph(userID, workspace.id)
+      const links = graph.links.filter((l) => l.member === "current" && l.supervisor === "current").map((l) => l.link)
+      const current = views.map((v) => v.member)
+      const supervisors = new Set<string>([...(workspace.masterMemberID ? [workspace.masterMemberID] : []), ...links.map((l) => l.supervisorMemberID)])
+      for (const memberID of supervisors) {
+        const supervisor = current.find((m) => m.id === memberID)
+        const scope = supervisor && supervisedMembers(workspace, current, links, memberID)
+        if (!supervisor || !scope) continue
+        if (count++ >= this.limits.supervisorsPerUser) break
+        served.add(checkpointKey(workspace.id, memberID))
+        const sessions = new Map(current.filter((m) => scope.has(m.id)).map((m) => [m.sessionID, m.id]))
+        const ctx: Context = { userID, workspace, supervisor, master: workspace.masterMemberID === memberID, scope, sessions, current: views, supervisionRevision: graph.revision }
+        try {
+          await this.step(ctx, latest, since)
+        } catch (cause) {
+          this.log(`[hub] workspace coordinator: supervisor step failed: ${(cause as Error).message}`)
+        }
+        if (!this.leading()) return
+      }
+    }
+    // Revocation: ledgers of workspaces no longer active, or of members that no longer supervise.
+    const activeIDs = new Set(active.map((w) => w.id))
+    for (const { key, value } of ledgers) {
+      if (served.has(key)) continue
+      if (activeIDs.has(value.workspaceID) && !examined.has(value.workspaceID)) continue
+      await state.delete(userID, WORKSPACE_COORDINATOR, key)
+    }
+    await state.put(userID, WORKSPACE_COORDINATOR_SCAN, SCAN_KEY, { position: latest })
+  }
+
+  /** A new ledger: after the supervisor's checkpoint when it has one, else a snapshot from now. */
+  private async fresh(ctx: Context, latest: string): Promise<SupervisorLedger> {
+    const { supervisor, workspace } = ctx
+    const checkpoint = await this.deps.checkpoints?.latest(ctx.userID, workspace.id, supervisor.id)
+    const resume = checkpoint && checkpoint.generation === supervisor.generation && checkpoint.sessionID === supervisor.sessionID
+    return {
+      v: 1,
+      workspaceID: workspace.id,
+      supervisorMemberID: supervisor.id,
+      sessionID: supervisor.sessionID,
+      generation: supervisor.generation,
+      position: resume ? checkpoint.position : latest,
+      ...(resume ? {} : { snapshot: { reason: "new" as const, dropped: 0 } }),
+      buffer: [],
+      window: [],
+      history: [],
+      seq: 0,
+    }
+  }
+
+  private async step(ctx: Context, latest: string, since: Since): Promise<void> {
+    const { state } = this.deps
+    const key = checkpointKey(ctx.workspace.id, ctx.supervisor.id)
+    const stored = await state.get<SupervisorLedger>(ctx.userID, WORKSPACE_COORDINATOR, key)
+    const t = this.now()
+    let ledger = stored?.value
+    if (!ledger || ledger.sessionID !== ctx.supervisor.sessionID || ledger.generation !== ctx.supervisor.generation) ledger = await this.fresh(ctx, latest)
+    const pending = ledger.batch
+    // Someone may be sending it right now (another pod before failover, or a pass in flight).
+    if (pending?.state === "sending" && (pending.claimedAt ?? 0) + this.limits.claimGraceMs > t) return
+
+    let next = await this.scan(ledger, ctx, since)
+    next = { ...next, window: next.window.filter((w) => w.at > t - HOUR_MS) }
+    if (!next.batch) {
+      const budget = this.due(next, t)
+      if (budget) next = await this.cut(next, ctx, budget, t)
+    }
+    const batch = next.batch
+    const sendable = batch !== undefined && (batch.state === "ready" || batch.state === "sending" || (batch.state === "retry" && (batch.nextAt ?? 0) <= t))
+    let claimed: DigestBatch | undefined
+    if (sendable) {
+      claimed = {
+        ...batch,
+        state: "sending",
+        attempts: batch.attempts + 1,
+        claimedBy: this.owner,
+        claimedAt: t,
+        // A claim nobody recorded: the earlier send may or may not have landed.
+        ...(batch.state === "sending" ? { last: "uncertain" as const } : {}),
+      }
+      next = { ...next, batch: claimed }
+    }
+    if (!this.leading()) return
+    const put = await state.put(ctx.userID, WORKSPACE_COORDINATOR, key, next, { ifVersion: stored?.version ?? 0 })
+    if (!put.ok || !claimed) return
+    await this.attempt(ctx, key, next, claimed)
+  }
+
+  /** Reads the journal after the ledger's position into its buffer (or owes a snapshot). */
+  private async scan(ledger: SupervisorLedger, ctx: Context, since: Since): Promise<SupervisorLedger> {
+    const result = await since(ledger.position)
+    if ("reset" in result) {
+      const position = await this.deps.events.latest(ctx.userID)
+      const urgent = ledger.snapshot?.urgent === true || ledger.buffer.some((l) => l.p)
+      return { ...without(ledger, "firstAt", "lastAt"), position, buffer: [], snapshot: { reason: "reset", dropped: ledger.snapshot?.dropped ?? 0, ...urgentIf(urgent) } }
+    }
+    if (!result.records.length) return ledger
+    let { snapshot, firstAt, lastAt } = ledger
+    let buffer: Line[] = [...ledger.buffer]
+    const t = this.now()
+    for (const record of result.records) {
+      const raw = digestLine(record, ctx)
+      if (!raw) continue
+      const line = this.fold(raw, ledger, t)
+      if (snapshot) {
+        if (snapshot.reason === "overflow") snapshot = { ...snapshot, dropped: snapshot.dropped + 1 }
+        if (line.p) snapshot = { ...snapshot, urgent: true } // folded in: the snapshot wakes and steers
+        continue
+      }
+      // A state line replaces the routine one held for the same subject (only the latest state matters), never a
+      // held priority line: an error or a block that cleared meanwhile is still news, followed by the recovery.
+      // Presence (p:<session>) too: a removed → added flap leaves only the latest, which cut() drops when it equals
+      // what the supervisor was last told (RF-08), never by comparing with a held line (duplicates exist).
+      if (line.k !== undefined) buffer = buffer.filter((held) => held.k !== line.k || held.p)
+      if (buffer.length >= this.limits.bufferLines) {
+        snapshot = { reason: "overflow", dropped: 1, ...urgentIf(line.p || buffer.some((l) => l.p)) }
+        buffer = []
+        firstAt = lastAt = undefined
+        continue
+      }
+      buffer.push(line)
+      firstAt ??= record.event.at
+      lastAt = record.event.at
+    }
+    const position = result.records.at(-1)!.position
+    const base = without(ledger, "firstAt", "lastAt", "snapshot")
+    return { ...base, position, buffer, ...(snapshot ? { snapshot } : {}), ...(firstAt !== undefined && buffer.length ? { firstAt, lastAt: lastAt! } : {}) }
+  }
+
+  /** Whether a batch is due now, and the budget it may use; undefined when not due or over budget. */
+  private due(ledger: SupervisorLedger, t: number): DigestBatch["budget"] | undefined {
+    const routine = ledger.window.filter((w) => w.budget === "routine").length < this.limits.batchesPerHour
+    const priority = ledger.window.filter((w) => w.budget === "priority").length < this.limits.priorityPerHour
+    if (ledger.snapshot?.urgent) return priority ? "priority" : routine ? "routine" : undefined
+    if (ledger.snapshot) return routine ? "routine" : undefined
+    if (!ledger.buffer.length) return undefined
+    if (ledger.buffer.some((l) => l.p)) return priority ? "priority" : routine ? "routine" : undefined
+    const wake = ledger.buffer.some((l) => l.w)
+    const quiet = t - (ledger.lastAt ?? t) >= (wake ? this.limits.wakeDebounceMs : this.limits.debounceMs)
+    const late = t - (ledger.firstAt ?? t) >= (wake ? this.limits.wakeMaxDelayMs : this.limits.maxDelayMs)
+    return (quiet || late) && routine ? "routine" : undefined
+  }
+
+  /** Turns the buffer (or an owed snapshot) into the next batch. */
+  private async cut(ledger: SupervisorLedger, ctx: Context, budget: DigestBatch["budget"], t: number): Promise<SupervisorLedger> {
+    const base = { ...without(ledger, "firstAt", "lastAt", "snapshot"), buffer: [] as Line[] }
+    let listed: Line[]
+    let more = 0
+    let wake: boolean
+    if (ledger.snapshot) {
+      if (ctx.scope.size === 0) return base // nothing to tell yet
+      const all = (await this.snapshotLines(ctx)).map((l) => this.fold(l, ledger, t))
+      listed = all.slice(0, this.limits.linesPerBatch)
+      more = all.length - listed.length
+      // A snapshot is routine (queued) unless priority news was folded into it or it shows a member blocked,
+      // erroring or with open blockers: then it wakes and steers, using the priority budget while there is one.
+      wake = ledger.snapshot.urgent === true || all.some((l) => l.p)
+      if (wake && budget === "routine" && ledger.window.filter((w) => w.budget === "priority").length < this.limits.priorityPerHour) budget = "priority"
+    } else {
+      // Only what the supervisor does not know yet: a state line repeating the last delivered state is dropped,
+      // unless a priority line about the same subject goes out with it (then it reports the recovery).
+      const known = ledger.facts ?? {}
+      const urgentSubjects = new Set(ledger.buffer.flatMap((l) => (l.p && l.k !== undefined ? [l.k] : [])))
+      const news = ledger.buffer.filter((l) => l.p || l.k === undefined || urgentSubjects.has(l.k) || known[l.k] !== l.f)
+      if (!news.length) return base // nothing material: skipped, no budget used
+      const ordered = [...news.filter((l) => l.p), ...news.filter((l) => !l.p)]
+      listed = ordered.slice(0, this.limits.linesPerBatch)
+      more = ordered.length - listed.length
+      wake = listed.some((l) => l.p || l.w)
+    }
+    const lines = listed.map((l) => l.text)
+    const facts = Object.fromEntries(listed.flatMap((l) => [...(l.k !== undefined && l.f !== undefined ? [[l.k, l.f] as const] : []), ...Object.entries(l.x ?? {})]))
+    const alerts = [...new Set(listed.flatMap((l) => (l.p ? (l.b ?? []) : [])))]
+    const seq = ledger.seq + 1
+    const batch: DigestBatch = {
+      id: this.newBatchID(),
+      seq,
+      kind: ledger.snapshot ? "snapshot" : "delta",
+      ...(ledger.snapshot ? { reason: ledger.snapshot.reason, dropped: ledger.snapshot.dropped } : {}),
+      budget,
+      wake,
+      facts,
+      ...(alerts.length ? { alerts } : {}),
+      lines,
+      more,
+      position: ledger.position,
+      cutAt: t,
+      state: "ready",
+      attempts: 0,
+    }
+    return { ...base, seq, batch }
+  }
+
+  /** The snapshot, line by line; member states and open assignments are also the states it reports. */
+  private async snapshotLines(ctx: Context): Promise<Line[]> {
+    const supervised = ctx.current.filter((v) => ctx.scope.has(v.member.id))
+    const facts: ReadonlyMap<string, BoardSession> = this.deps.sessions ? await this.deps.sessions(ctx.userID, supervised.map((v) => v.member.sessionID)) : new Map()
+    const open: Line[] = []
+    let cursor: string | undefined
+    do {
+      const page = await this.deps.members.assignments(ctx.userID, ctx.workspace.id, { limit: LIST_LIMIT_MAX, ...(cursor ? { cursor } : {}) })
+      for (const { assignment: a } of page.items) {
+        if (OPEN.has(a.status) && ctx.scope.has(a.memberID)) open.push({ p: false, text: `assignment ${a.id} ${a.memberID} ${a.status}`, k: `a:${a.id}`, f: assignmentFact(a.status, a.memberID) })
+      }
+      cursor = page.cursor
+    } while (cursor)
+    const head: Line = { p: false, text: `workspace ${ctx.workspace.id} revision=${ctx.workspace.revision} supervision=${ctx.supervisionRevision} members=${supervised.length} unresolved=${open.length}` }
+    const memberLines = supervised.map(({ member, presence }): Line => {
+      const fact = facts.get(member.sessionID)
+      const blockers = fact?.blockers ? `blockers=${fact.blockers.length}` : "blockers=?"
+      const text = `member ${member.id} ${member.sessionID} ${member.role} ${presence}${fact ? ` state=${fact.state}` : ""} ${blockers}`
+      const urgent = fact !== undefined && (URGENT_STATES.has(fact.state) || (fact.blockers?.length ?? 0) > 0)
+      const reasons = urgent
+        ? [...new Set([...(URGENT_STATES.has(fact.state) ? [`state:${fact.state}`] : []), ...(fact.blockers ?? []).map((b) => `blocker:${b.kind}`)])].map((r) => `${member.sessionID} ${r}`)
+        : []
+      const x = presence === "online" || presence === "offline" ? { x: { [`p:${member.sessionID}`]: presenceFact(presence === "online") } } : {}
+      return fact ? { p: urgent, text, k: `s:${member.sessionID}`, f: sessionFact(fact.state), ...x, ...(reasons.length ? { b: reasons } : {}) } : { p: false, text, ...x }
+    })
+    return [head, ...memberLines, ...open]
+  }
+
+  /** Sends a claimed batch and records the outcome (only if the ledger still holds that batch). */
+  private async attempt(ctx: Context, key: string, ledger: SupervisorLedger, batch: DigestBatch): Promise<void> {
+    if (!this.leading()) return // the claim stays: after claimGraceMs the next leader resends it
+    const text = this.text(ctx, ledger, batch)
+    let result: { messageID: string; delivery?: string; woke?: boolean } | undefined
+    let failure: "uncertain" | "refused" | undefined
+    try {
+      // Routine batches are admitted for the supervisor's next turn, never starting one (RP-07 #10).
+      result = await this.bounded(this.deps.send(ctx.userID, ctx.supervisor.sessionID, text, { wake: batch.wake ?? true, urgent: batch.budget === "priority" }))
+    } catch (cause) {
+      failure = cause instanceof AgentError && REFUSED.has(cause.code) ? "refused" : "uncertain"
+      this.log(`[hub] workspace coordinator: digest ${batch.id} attempt ${batch.attempts} ${failure}: ${(cause as Error).message}`)
+    }
+    const t = this.now()
+    await updateVersioned<SupervisorLedger>(this.deps.state, ctx.userID, WORKSPACE_COORDINATOR, key, (current) => {
+      if (!current?.batch || current.batch.id !== batch.id) return undefined // resolved by a checkpoint, or revoked
+      const sent = { ...batch, ...(failure ? { last: failure } : {}) }
+      const window = failure === "refused" ? current.window : [...current.window, { at: t, budget: batch.budget }]
+      // The fold window starts only with a wake the hub carried out (not over the wake budget or hop cap).
+      const alerts = result && woke(result) ? this.alerted(current, batch, t) : this.alerted(current, { ...batch, alerts: [] }, t)
+      if (!failure) return { ...without(current, "batch"), window, facts: reported(current, batch), alerts, history: this.outcome(current, sent, "delivered", t, result) }
+      if (batch.attempts >= this.limits.maxAttempts) {
+        return {
+          ...without(current, "batch", "firstAt", "lastAt", "facts"),
+          window,
+          buffer: [],
+          snapshot: { reason: "abandoned" as const, dropped: 0, ...urgentIf(batch.budget === "priority" || batch.wake === true || current.buffer.some((l) => l.p)) },
+          history: this.outcome(current, sent, "abandoned", t),
+        }
+      }
+      const wait = this.limits.retryMs[Math.min(batch.attempts - 1, this.limits.retryMs.length - 1)]!
+      return { ...current, window, batch: { ...without(sent, "claimedBy", "claimedAt"), state: "retry", nextAt: t + wait } }
+    })
+  }
+
+  /** The send, or a rejection after sendTimeoutMs (it may still land: the caller treats that as uncertain). */
+  private bounded<T>(send: Promise<T>): Promise<T> {
+    let handle: unknown
+    const timeout = new Promise<never>((_, reject) => {
+      handle = this.timers.set(() => reject(new Error(`no answer within ${this.limits.sendTimeoutMs} ms`)), this.limits.sendTimeoutMs)
+    })
+    return Promise.race([send, timeout]).finally(() => this.timers.clear(handle))
+  }
+
+  private outcome(ledger: SupervisorLedger, batch: DigestBatch, outcome: DigestOutcome["outcome"], at = this.now(), result?: { messageID: string; delivery?: string }): DigestOutcome[] {
+    const entry: DigestOutcome = {
+      batchID: batch.id,
+      seq: batch.seq,
+      kind: batch.kind,
+      at,
+      attempts: batch.attempts,
+      outcome,
+      ...(result ? { messageID: result.messageID, ...(result.delivery ? { delivery: result.delivery } : {}) } : {}),
+    }
+    return [...ledger.history, entry].slice(-HISTORY_MAX)
+  }
+
+  private text(ctx: Context, ledger: SupervisorLedger, batch: DigestBatch): string {
+    const priority = batch.kind === "delta" ? batch.lines.filter((l) => l.startsWith("!")).length : 0
+    const what =
+      batch.kind === "delta"
+        ? `delta · ${batch.lines.length + batch.more} updates${priority ? ` (${priority} priority)` : ""}`
+        : `snapshot (${
+            {
+              new: "first digest",
+              reset: "the event journal no longer covers your last cursor (expired or the hub restarted); earlier updates may be missing",
+              overflow: `buffer full: ${batch.dropped ?? 0} updates dropped; this snapshot replaces them`,
+              abandoned: "an earlier batch was abandoned after repeated failed sends and may not have arrived",
+            }[batch.reason ?? "new"]
+          })`
+    const previous = ledger.history.at(-1)
+    const delivery = batch.wake === false ? " · routine: queued for your next turn, no turn was started for it" : ""
+    return [
+      `[hub] workspace digest · automated, not from the user · workspace ${ctx.workspace.id} · you supervise as ${ctx.supervisor.id}${delivery}`,
+      `batch ${batch.id} #${batch.seq} · ${what} · attempt ${batch.attempts} · at-least-once: if you already handled ${batch.id}, skip this copy${previous ? ` · previous ${previous.batchID} ${previous.outcome}` : ""}`,
+      ...batch.lines,
+      ...(batch.more ? [`… ${batch.more} more updates not listed`] : []),
+      `cursor ${this.deps.cursors.encode(ctx.userID, batch.position)}`,
+      "No reply needed. IDs only: the user's workspace board has details.",
+    ].join("\n")
+  }
+}