@huynle/hub 0.7.3 → 0.8.0

package/src/central/concierge/notifier.ts

@@ -0,0 +1,986 @@
+// CON-05 event-driven Concierge turns, digests and quiet hours (contract: docs/plans/2026-11-01-concierge-contracts.md
+// "Event-driven turns, digests, quiet hours (CON-05)"). It follows the workspace coordinator's batching model
+// (src/central/workspaces/coordinator.ts, RP-07 #10, RF-05) as its own module, for one recipient per user: the
+// user's CURRENT Concierge session, reached only through the Concierge port `send` (Delivery.send as app:concierge,
+// admitted by the CON-04 inbound rule). Nothing is read through the Concierge's token.
+//
+// What the Concierge hears: the user's journal (AgentEvents.since, cursor in the ledger), filtered to the watchlist
+// (watched roots; subagents roll up into their root) and classed:
+// - priority: a blocker opened, a session in error, an ask to @me (a Decision) about a watched session, a launch
+//   ended failed/lost/needs_user/timeout → the next pass, a wake.
+// - notable: a turn done (working → idle), a launch ended idle (goal reached) → a wake after 30 s quiet (2 min max).
+// - routine: presence, resolved blockers, → working, machines, intents, pins → wake:false (admitted for its next
+//   turn, never starting one; RF-05) after 2 min quiet (15 min max).
+// Routine and notable lines held when a wake goes out go along with it. Wakes are queued, never steered (`urgent` is
+// never set): a steer would cut into a live voice turn.
+//
+// Lines carry hub IDs, enums and counts only (`! ses_… blocker:permission per_…`). Event values that are not a known
+// enum, or an ID matching its own kind's pattern (ses_…, msg_…, dec_…, mch_…, l_<hex>, a harness blocker ID), are
+// replaced ("other") or left out (an unmatched subject drops the line), never echoed: no titles, intents, prompts, message bodies,
+// blocker summaries, Decision text or machine names, and no @names either (the directory derives them from titles, so
+// they are title text). The Concierge reads details, names included, on its board, where untrusted text is framed. Each message starts `Concierge update b<seq> (attempt n) · board r<rev>`.
+//
+// Self-trigger guard: events about any of the Concierge's sessions (current and every past one, identity), messages
+// from or to it (app:concierge, @@concierge, its sessions), and launches by app:concierge or any of its sessions are
+// ignored, so its own
+// turns and our deliveries never wake it.
+//
+// Cooldown (fold): a priority reason (same root + same blocker kind or state, or the same Decision/launch) it was
+// woken about within foldMs (15 min) is routine. Budgets per user and rolling hour: 12 priority, 12 notable, 30
+// routine; over budget priority falls to notable (its timing), notable to routine, routine waits. Each wake (and
+// digest) is recorded through ConciergeEntitlements.record.
+//
+// Quiet hours (settings.quietHours, in their own zone): only priority lines wake, and only with quietAllowsUrgent;
+// everything else is held and goes out as one wake when they end (digest class: no hourly budget). Digests
+// (settings.digests, settings.timeZone; schedule.ts): one wake per entry per local day, `Concierge digest (<HH:MM>
+// <zone>) …: <counts since the last digest>`, carrying what is held; a digest due in quiet hours goes out when they
+// end. Quiet hours hold retries and stale-claim resends too: a pending batch that is not priority-with-
+// quietAllowsUrgent is put back (its lines, snapshot and digest), and the release says it carries that batch again
+// ("Includes the updates of b<n>, which may already have arrived"). Idle costs nothing: no watched activity and no digest → no send, no context push.
+//
+// Not running: while the state is not `running` nothing is sent; lines are held up to bufferLines (200), beyond
+// that the next batch is a snapshot ("board r<rev> is current; N changes were missed"). A journal reset (cursor no
+// longer covered) is a priority snapshot (quiet hours apply) that cannot count: "some changes were missed; read your
+// board". Disabled: nothing is sent;
+// the ledger is deleted (disabled(), and any pass that finds the Concierge disabled). A relaunched Concierge (a new
+// session) learns again: the ledger's delivered facts and folds start over.
+//
+// Durability and leadership: one ledger per user in the StateStore (collection `concierge-notifier`, key `ledger`:
+// cursor, held lines, delivered facts, alerts, pending batch, attempts, budget window, digest keys). Passes run on
+// the `concierge` leader; isLeader is checked before each user and each send; every write is version-checked. A
+// batch is stored before it is sent and claimed first; a claim unrecorded after claimGraceMs is resent with the SAME
+// batch ID (at-least-once: the text says the attempt and asks to skip a batch already handled); refusals that store
+// nothing are retried; after maxAttempts the batch is abandoned and the next one is a snapshot. A journal position
+// the log no longer covers (expired, standalone restart) is a reset: the next batch is a snapshot.
+//
+// observe(): every journal append on this pod; cheap (a Set lookup) and never throws: on the leader a priority-type
+// append (a blocker, an ask, a launch, a session in error) schedules one early pass (observeDelayMs) instead of
+// waiting for the tick, and a turn done schedules one when its 30 s quiet window ends. After each pass, held notable
+// lines arm a pass for when they come due, so a lone turn done wakes ~30 s after it, not on the tick after that.
+//
+// Timing (CON-09a): a wake's quiet and max windows count from its own lines' event times (Line.t), so routine churn
+// of other watched sessions (which goes along) never holds a turn done back; and a turn done is always news, even
+// when the last state told was idle (the routine working line in between was replaced while held, so a second short
+// turn of a session used to be dropped). A line replacing held ones of its subject keeps the earliest undelivered turn
+// done (Line.t0), so a session flipping faster than the quiet window still wakes once its max window ends (a routine
+// line carrying it is then that turn done). Passes are armed only for a FUTURE due: lines held by quiet hours or a
+// spent budget wait for the tick (no 0 ms timer loop).
+import { CONCIERGE_PARTY, CONCIERGE_ROLE, type ConciergeSettings } from "../../../packages/protocol/src/concierge"
+import { AgentError } from "../agent/errors"
+import type { AgentEvent, 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 { ConciergeNotifier, ConciergePorts } from "./index"
+import { localStamp } from "./board-render"
+import { DIGEST_GRACE_MS, dueDigests, inQuietHours, zoneOrUTC } from "./schedule"
+import { resolveWatchlist, rootsOf } from "./watchlist"
+import { type WatchFactDeps, watchFacts, WatchlistStore } from "./watchlist-routes"
+
+export const NOTIFIER_COLLECTION = "concierge-notifier"
+const KEY = "ledger"
+/** The leader's pass interval (digests have minute resolution). */
+export const NOTIFIER_TICK_MS = 30_000
+const HOUR_MS = 3_600_000
+const DAY_MS = 86_400_000
+
+export type LineClass = "priority" | "notable" | "routine"
+
+export interface NotifierLimits {
+  readonly priorityPerHour: number
+  readonly notablePerHour: number
+  readonly routinePerHour: number
+  readonly notableQuietMs: number
+  readonly notableMaxMs: number
+  readonly routineQuietMs: number
+  readonly routineMaxMs: number
+  /** A priority reason woken about this recently is routine (RF-05). */
+  readonly foldMs: number
+  /** Delivered facts and alerts kept. */
+  readonly factsMax: number
+  /** Lines held; beyond it the next batch is a snapshot. */
+  readonly bufferLines: number
+  readonly linesPerBatch: number
+  readonly maxAttempts: number
+  readonly retryMs: readonly number[]
+  readonly sendTimeoutMs: number
+  readonly claimGraceMs: number
+  /** The board push before a wake (ConciergePorts.beforeWake) is awaited at most this long. */
+  readonly beforeWakeMs: number
+  /** A priority-type append on the leader runs a pass this soon. */
+  readonly observeDelayMs: number
+  readonly digestGraceMs: number
+  readonly historyMax: number
+}
+
+export const NOTIFIER_LIMITS: NotifierLimits = {
+  priorityPerHour: 12,
+  notablePerHour: 12,
+  routinePerHour: 30,
+  notableQuietMs: 30_000,
+  notableMaxMs: 2 * 60_000,
+  routineQuietMs: 2 * 60_000,
+  routineMaxMs: 15 * 60_000,
+  foldMs: 15 * 60_000,
+  factsMax: 400,
+  bufferLines: 200,
+  linesPerBatch: 40,
+  maxAttempts: 6,
+  retryMs: [30_000, 2 * 60_000, 10 * 60_000, 30 * 60_000],
+  sendTimeoutMs: 60_000,
+  claimGraceMs: 2 * 60_000,
+  beforeWakeMs: 2_000,
+  observeDelayMs: 1_000,
+  digestGraceMs: DIGEST_GRACE_MS,
+  historyMax: 20,
+}
+
+/** What the notifier knows about the watchlist at a pass: watched roots and each session's root. */
+export interface WatchedView {
+  readonly watched: ReadonlySet<string>
+  readonly roots: ReadonlyMap<string, string>
+}
+
+/** The notifier's own hub ports (journal, ledger store, watchlist, board revision, leadership, clock). */
+export interface NotifierJournal {
+  readonly events: Pick<AgentEvents, "since" | "latest">
+  readonly state: StateStore
+  readonly watched: (userID: string, hidden: readonly string[]) => Promise<WatchedView>
+  /** The board revision the Concierge has (after beforeWake); absent or failing: "r?". */
+  readonly boardRevision?: (userID: string, hidden: readonly string[]) => Promise<number>
+  /** The Decision an ask to @me opened (its ID and what it is about). */
+  readonly decisionOf?: (userID: string, messageID: string) => Promise<{ readonly id: string; readonly about: readonly string[] } | undefined>
+  readonly isLeader?: () => boolean
+  readonly owner?: string
+  readonly now?: Clock
+  readonly timers?: Timers
+  readonly tickMs?: number
+  readonly limits?: Partial<NotifierLimits>
+  readonly log?: (message: string) => void
+}
+
+// ---- Classing ---------------------------------------------------------------------------------------------
+
+export interface Line {
+  readonly c: LineClass
+  readonly text: string
+  /** A state line's subject (later lines replace it while held) and the state it reports. */
+  readonly k?: string
+  readonly f?: string
+  /** Reported once: dropped when the Concierge already has this fact (an open Decision, an ended launch). */
+  readonly o?: true
+  /** Priority reasons (fold keys). */
+  readonly b?: readonly string[]
+  /** When its event happened (the journal's time): a wake's quiet and max windows count from its own lines. */
+  readonly t?: number
+  /**
+   * When the subject's first notable (or priority) line still held was: a state line that replaced held ones keeps
+   * it, so a session flipping faster than the quiet window still wakes within the max window.
+   */
+  readonly t0?: number
+}
+
+export interface ClassifyContext {
+  /** The Concierge's sessions, current and past. */
+  readonly hidden: ReadonlySet<string>
+  readonly view: WatchedView
+  /** For an ask to @me: the Decision it opened. */
+  readonly decision?: { readonly id: string; readonly about: readonly string[] }
+}
+
+/** Hub and harness IDs by kind: a value that does not match its own kind's pattern never reaches a line. */
+const IDS = {
+  session: /^ses_[A-Za-z0-9]{1,64}$/,
+  message: /^msg_[A-Za-z0-9]{1,40}$/,
+  decision: /^dec_[A-Za-z0-9]{1,40}$/,
+  machine: /^mch_[A-Za-z0-9]{1,64}$/,
+  launch: /^l_[0-9a-f]{16}$/,
+  /** Harness blocker IDs (OpenCode per_…, que_…): a short lowercase prefix. */
+  blocker: /^[a-z]{2,4}_[A-Za-z0-9]{1,64}$/,
+} as const
+const BLOCKER_KINDS: ReadonlySet<unknown> = new Set(["permission", "question", "form"])
+const STATES: ReadonlySet<unknown> = new Set(["idle", "working", "blocked", "error", "offline"])
+const INTENT_SOURCES: ReadonlySet<unknown> = new Set(["user", "launch", "self", "prompt", "title"])
+const LAUNCH_PRIORITY: ReadonlySet<unknown> = new Set(["failed", "lost", "needs_user", "timeout"])
+const CONCIERGE_ADDRESS = `@@${CONCIERGE_ROLE}`
+
+const idOf = (kind: keyof typeof IDS, v: unknown): string | undefined => (typeof v === "string" && IDS[kind].test(v) ? v : undefined)
+const enumOf = (v: unknown, known: ReadonlySet<unknown>): string => (known.has(v) ? (v as string) : "other")
+const MARK: Record<LineClass, string> = { priority: "!", notable: "+", routine: "-" }
+
+/** Whether the record is the Concierge's own doing or about it (any of its sessions, its party, its role). */
+function selfTouched(record: Pick<EventRecord, "event" | "audience">, hidden: ReadonlySet<string>): boolean {
+  const s = record.event.subject ?? {}
+  const d = record.event.data ?? {}
+  if ((s.sessionID && hidden.has(s.sessionID)) || (s.senderID && hidden.has(s.senderID))) return true
+  const audience = record.audience
+  const by = audience?.by
+  // Launches by the Concierge's party or by any of its sessions (however the launcher is written).
+  if (by === CONCIERGE_PARTY || (by !== undefined && (hidden.has(by) || (by.startsWith("ses:") && hidden.has(by.slice(4)))))) return true
+  for (const party of audience?.parties ?? []) if (party === CONCIERGE_PARTY || (party.startsWith("ses:") && hidden.has(party.slice(4)))) return true
+  for (const v of [d.from, d.to]) {
+    if (typeof v !== "string") continue
+    if (v === CONCIERGE_PARTY || v.startsWith(CONCIERGE_ADDRESS) || hidden.has(v)) return true
+  }
+  return false
+}
+
+/** A watched session as lines name it (`<root>[ (sub <id>)]`), or undefined when not watched. */
+function whoOf(sessionID: unknown, ctx: ClassifyContext): { root: string; id: string; who: string } | undefined {
+  const id = idOf("session", sessionID)
+  if (!id) return undefined
+  const root = ctx.view.roots.get(id) ?? id
+  if (!IDS.session.test(root) || ctx.hidden.has(root) || !ctx.view.watched.has(root)) return undefined
+  return { root, id, who: `${root}${id !== root ? ` (sub ${id})` : ""}` }
+}
+
+const line = (c: LineClass, text: string, extra: Omit<Line, "c" | "text"> = {}): Line => ({ c, text: `${MARK[c]} ${text}`, ...extra })
+
+function classify(record: Pick<EventRecord, "event" | "family" | "audience">, ctx: ClassifyContext): Line | undefined {
+  const event = record?.event
+  if (!event || typeof event.type !== "string" || !event.subject || !event.data) return undefined
+  if (selfTouched(record, ctx.hidden)) return undefined
+  const s = event.subject
+  const d = event.data
+  switch (event.type) {
+    case "machine.changed": {
+      const id = idOf("machine", s.machineID)
+      const online = d.online !== false
+      return id ? line("routine", `machine ${id} ${online ? "online" : "offline"}`, { k: `m:${id}`, f: online ? "online" : "offline" }) : undefined
+    }
+    case "message.changed": {
+      if (d.kind !== "ask" || d.state !== "open" || d.to !== "@me") return undefined
+      const messageID = idOf("message", s.messageID)
+      if (!messageID) return undefined
+      const about = ctx.decision ? ctx.decision.about : s.senderID ? [s.senderID] : []
+      const target = about.map((id) => whoOf(id, ctx)).find((w) => w !== undefined)
+      if (!target) return undefined
+      const id = idOf("decision", ctx.decision?.id) ?? messageID
+      return line("priority", `${target.who} decision ${id}`, { k: `d:${messageID}`, f: "open", o: true, b: [`${target.root} decision:${id}`] })
+    }
+    case "launch.changed": {
+      if (d.state !== "ended") return undefined
+      const target = whoOf(s.sessionID, ctx)
+      const launchID = idOf("launch", s.launchID)
+      if (!target || !launchID) return undefined
+      const outcome = d.outcome
+      const once = { k: `l:${launchID}`, f: String(outcome), o: true as const }
+      if (LAUNCH_PRIORITY.has(outcome)) return line("priority", `${target.who} launch ${launchID} ended:${outcome}`, { ...once, b: [`${target.root} launch:${outcome}`] })
+      if (outcome === "idle") return line("notable", `${target.who} launch ${launchID} ended:idle`, once)
+      return undefined
+    }
+  }
+  const target = whoOf(s.sessionID, ctx)
+  if (!target) return undefined
+  const { who, root, id } = target
+  switch (event.type) {
+    case "blocker.opened": {
+      const kind = enumOf(d.kind, BLOCKER_KINDS)
+      const blockerID = idOf("blocker", d.blockerID)
+      // (CON-13) The fold key names the request: a NEW permission or form on a session woken about minutes ago is
+      // news (it waited ~60–75 s for the Concierge's next turn as routine); only the same request again folds.
+      return line("priority", `${who} blocker:${kind}${blockerID ? ` ${blockerID}` : ""}`, { b: [`${root} blocker:${kind}${blockerID ? `:${blockerID}` : ""}`] })
+    }
+    case "blocker.closed": {
+      const blockerID = idOf("blocker", d.blockerID)
+      return line("routine", `${who} blocker_closed${blockerID ? ` ${blockerID}` : ""}`)
+    }
+    case "session.changed": {
+      const state = enumOf(d.state, STATES)
+      const k = `s:${id}`
+      if (state === "error") return line("priority", `${who} state:error`, { k, f: state, b: [`${root} state:error`] })
+      if (state === "idle" && d.prev === "working") return line("notable", `${who} turn_done`, { k, f: state })
+      return line("routine", `${who} state:${state}`, { k, f: state })
+    }
+    case "session.added":
+    case "session.removed": {
+      const presence = event.type === "session.added" ? "online" : "offline"
+      return line("routine", `${who} ${presence}`, { k: `p:${id}`, f: presence })
+    }
+    case "session.intent": {
+      const revision = Number.isSafeInteger(d.revision) ? ` r${d.revision}` : ""
+      const source = enumOf(d.source, INTENT_SOURCES)
+      // (CON-11) Source "title": no intent is left (the user cleared it), so the session shows its title again. That
+      // is not a title change: say so (the Concierge read "intent:title" as "its title changed").
+      if (source === "title") return line("routine", `${who} intent_cleared${revision}`)
+      return line("routine", `${who} intent:${source}${revision}`)
+    }
+    case "session.pinned": {
+      const pinned = d.pinned === true ? "pinned" : "unpinned"
+      return line("routine", `${who} ${pinned}`, { k: `pin:${id}`, f: pinned })
+    }
+    default:
+      return undefined
+  }
+}
+
+/** The line a journal record is for the Concierge, or undefined (not watched, its own doing, not news). Never throws. */
+export function classifyEvent(record: Pick<EventRecord, "event" | "family" | "audience">, ctx: ClassifyContext): Line | undefined {
+  try {
+    return classify(record, ctx)
+  } catch {
+    return undefined
+  }
+}
+
+/** Journal types the notifier reads (others are skipped before any lookup). */
+const RELEVANT: ReadonlySet<string> = new Set([
+  "blocker.opened",
+  "blocker.closed",
+  "session.changed",
+  "session.added",
+  "session.removed",
+  "session.intent",
+  "session.pinned",
+  "machine.changed",
+  "message.changed",
+  "launch.changed",
+])
+/** A routine state line carrying an undelivered turn done past the max window: notable, saying so. */
+function overdueTurn(l: Line): Line {
+  const body = l.text.slice(2)
+  const m = / state:([a-z]+)$/.exec(body)
+  return { ...l, c: "notable", text: `${MARK.notable} ${m ? `${body.slice(0, m.index)} turn_done (now ${m[1]})` : body}` }
+}
+
+/** Types that may be priority: on the leader, an append of one runs an early pass. */
+const EARLY: ReadonlySet<string> = new Set(["blocker.opened", "message.changed", "launch.changed"])
+
+/** Whether an append may be a priority line (an early pass): EARLY types, and a session going into error. */
+const early = (event: AgentEvent): boolean => EARLY.has(event.type) || (event.type === "session.changed" && event.data?.state === "error")
+/** Whether an append may be a notable line (a turn done): a pass when its quiet window ends. */
+const notable = (event: AgentEvent): boolean => event.type === "session.changed" && event.data?.state === "idle" && event.data?.prev === "working"
+
+// ---- Watchlist port (hub wiring) --------------------------------------------------------------------------
+
+export type WatchedDeps = WatchFactDeps & { readonly state: StateStore }
+
+/** The watched view for a pass: the resolved watchlist (CON-01) and every session's root. */
+export async function watchedSessions(deps: WatchedDeps, userID: string, hidden: readonly string[]): Promise<WatchedView> {
+  const [config, facts] = await Promise.all([new WatchlistStore(deps.state).get(userID), watchFacts(deps, userID, hidden)])
+  return { watched: new Set(resolveWatchlist(config, facts).entries.map((e) => e.sessionID)), roots: rootsOf(facts.sessions) }
+}
+
+// ---- Ledger -----------------------------------------------------------------------------------------------
+
+type Counts = { priority: number; notable: number; routine: number }
+type SnapshotReason = "reset" | "overflow" | "abandoned"
+type BatchKind = "delta" | "snapshot" | "release" | "digest"
+/** The budget a batch uses: an hourly class, or "digest" (digests and quiet-hours releases: none). */
+type Budget = LineClass | "digest"
+
+export interface NotifierBatch {
+  readonly id: string
+  readonly seq: number
+  readonly kind: BatchKind
+  readonly budget: Budget
+  readonly wake: boolean
+  readonly lines: readonly string[]
+  readonly more: number
+  /** Lines listed per class (the header). */
+  readonly counts: Counts
+  readonly facts?: Readonly<Record<string, string>>
+  readonly alerts?: readonly string[]
+  /** A snapshot (or a digest/release carrying one): why, and how many changes were missed. */
+  readonly snapshot?: { readonly reason: SnapshotReason; readonly missed: number; readonly unknown?: true }
+  readonly digest?: { readonly key?: string; readonly label: string; readonly zone: string; readonly since: number; readonly counts: Counts }
+  /** The lines it lists (so a batch deferred by quiet hours can be held again). */
+  readonly held?: readonly Line[]
+  /** Earlier batches whose lines it carries again (deferred after a send that may have landed). */
+  readonly supersedes?: readonly string[]
+  readonly cutAt: number
+  readonly state: "ready" | "sending" | "retry"
+  readonly attempts: number
+  readonly nextAt?: number
+  readonly claimedBy?: string
+  readonly claimedAt?: number
+  readonly last?: "uncertain" | "refused"
+}
+
+export interface NotifierLedger {
+  readonly v: 1
+  /** The Concierge session the delivered facts were told to. */
+  readonly sessionID?: string
+  /** Journal position scanned up to. */
+  readonly position: string
+  readonly buffer: readonly Line[]
+  readonly firstAt?: number
+  readonly lastAt?: number
+  /** `unknown`: how many were missed is not known (a journal reset). */
+  readonly snapshot?: { readonly reason: SnapshotReason; readonly missed: number; readonly unknown?: true; readonly urgent?: true }
+  /** Batches deferred by quiet hours after a send attempt (the next batch says it carries their lines). */
+  readonly supersedes?: readonly string[]
+  /** Lines were held by quiet hours: their end releases one wake. */
+  readonly quietHeld?: true
+  readonly batch?: NotifierBatch
+  readonly window: readonly { readonly at: number; readonly budget: LineClass }[]
+  readonly seq: number
+  readonly facts: Readonly<Record<string, string>>
+  readonly alerts: Readonly<Record<string, number>>
+  /** Digest keys (digest:<date>:<i>) → when they came due. */
+  readonly digests: Readonly<Record<string, number>>
+  readonly owedDigest?: { readonly key: string; readonly label: string; readonly at: number }
+  /** Classed lines since the last digest. */
+  readonly counts: Counts
+  readonly countsSince: number
+  readonly history: readonly { readonly id: string; readonly kind: BatchKind; readonly at: number; readonly attempts: number; readonly outcome: "delivered" | "abandoned"; readonly messageID?: string }[]
+}
+
+const ZERO: Counts = { priority: 0, notable: 0, routine: 0 }
+/** 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", "conflict"])
+
+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
+}
+
+/** Keeps the newest `max` entries of a record (insertion order). */
+function bounded<V>(record: Record<string, V>, max: number): Record<string, V> {
+  const keys = Object.keys(record)
+  for (const key of keys.slice(0, Math.max(0, keys.length - max))) delete record[key]
+  return record
+}
+
+function stamp(at: number): string {
+  const d = new Date(at)
+  const pad = (n: number) => String(n).padStart(2, "0")
+  return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}Z`
+}
+
+const countsText = (c: Counts, all = false) =>
+  (["priority", "notable", "routine"] as const)
+    .filter((k) => all || c[k] > 0)
+    .map((k) => `${c[k]} ${k}`)
+    .join(", ")
+
+const SNAPSHOT_WHY: Record<SnapshotReason, string> = {
+  reset: "the event journal no longer covers the last position",
+  overflow: "too many updates were held",
+  abandoned: "an earlier update could not be delivered",
+}
+
+/** One wake/queued message's text: IDs, enums and counts only. */
+export function renderBatch(batch: NotifierBatch, revision: number | undefined): string {
+  const board = `board r${revision ?? "?"}`
+  const attempt = `b${batch.seq} (attempt ${batch.attempts})`
+  const auto = "automated by the hub, not the user"
+  const missed = batch.snapshot
+    ? batch.snapshot.unknown
+      ? `${board} is current; some changes were missed (${SNAPSHOT_WHY[batch.snapshot.reason]}); read your board`
+      : `${board} is current; ${batch.snapshot.missed} changes were missed (${SNAPSHOT_WHY[batch.snapshot.reason]})`
+    : undefined
+  const again = batch.supersedes?.length ? `Includes the updates of ${batch.supersedes.join(", ")}, which may already have arrived: skip what you already handled.` : undefined
+  let head: string
+  if (batch.kind === "digest") {
+    const d = batch.digest!
+    // (CON-10) "since" in the digest's zone (the user's), never a UTC "Z" time.
+    head = `Concierge digest (${d.label} ${d.zone}) ${attempt} · ${board} · since ${localStamp(d.since, d.zone) ?? stamp(d.since)}: ${countsText(d.counts, true)}`
+  } else if (batch.kind === "release") {
+    head = `Concierge update ${attempt} · ${board} · quiet hours ended: ${batch.lines.length + batch.more} held updates · ${auto}`
+  } else if (batch.kind === "snapshot") {
+    head = `Concierge update ${attempt} · ${missed} · ${auto}`
+  } else {
+    head = `Concierge update ${attempt} · ${board} · ${countsText(batch.counts)} · ${auto}`
+  }
+  const footer = [
+    `IDs and states only: details are on your board (hub concierge_board). If you already handled b${batch.seq}, skip it.`,
+    ...(batch.wake ? [] : ["Routine: queued for your next turn; no turn was started for it."]),
+    ...(batch.kind === "digest" ? ["Summarize for the user if it helps; msg @me only when something needs them."] : []),
+  ].join(" ")
+  return [
+    head,
+    ...(missed && batch.kind !== "snapshot" ? [missed] : []),
+    ...(again ? [again] : []),
+    ...batch.lines,
+    ...(batch.more ? [`… ${batch.more} more updates not listed`] : []),
+    footer,
+  ].join("\n")
+}
+
+// ---- The notifier -----------------------------------------------------------------------------------------
+
+/** The run-on-the-leader notifier (CONCIERGE_SLOTS.notifier). Inert without `ports.journal`. */
+export class ConciergeNotifierImpl implements ConciergeNotifier {
+  readonly limits: NotifierLimits
+  private readonly ports: ConciergePorts
+  private readonly journal: NotifierJournal | undefined
+  private readonly now: Clock
+  private readonly timers: Timers
+  private readonly owner: string
+  private readonly log: (message: string) => void
+  private running: Promise<void> | undefined
+  private timer: unknown
+  private soon: unknown
+  /** A pass when held notable lines come due (their quiet or max window ends), sooner than the next tick. */
+  private due: unknown
+  private dueAt: number | undefined
+  private started = false
+  private stopped = false
+
+  constructor(ports: ConciergePorts) {
+    this.ports = ports
+    this.journal = ports.journal
+    this.limits = { ...NOTIFIER_LIMITS, ...this.journal?.limits }
+    this.now = this.journal?.now ?? Date.now
+    this.timers = this.journal?.timers ?? realTimers
+    this.owner = this.journal?.owner ?? `concierge-notifier-${process.pid}`
+    this.log = this.journal?.log ?? ((message) => console.error(message))
+  }
+
+  start(): void {
+    this.stopped = false
+    if (this.started || !this.journal) return
+    this.started = true
+    this.schedule()
+  }
+
+  stop(): void {
+    this.stopped = true
+    this.started = false
+    if (this.timer !== undefined) this.timers.clear(this.timer)
+    if (this.soon !== undefined) this.timers.clear(this.soon)
+    if (this.due !== undefined) this.timers.clear(this.due)
+    this.timer = this.soon = this.due = this.dueAt = undefined
+  }
+
+  observe(userID: string, event: AgentEvent): void {
+    try {
+      if (!this.started || typeof userID !== "string" || typeof event?.type !== "string") return
+      if (early(event)) {
+        if (this.soon !== undefined) return
+        this.soon = this.timers.set(() => {
+          this.soon = undefined
+          this.passSoon()
+        }, this.limits.observeDelayMs)
+      } else if (notable(event)) this.armDue(this.now() + this.limits.notableQuietMs + this.limits.observeDelayMs)
+    } catch {
+      // Never throws (called on every journal append, never awaited).
+    }
+  }
+
+  async disabled(userID: string): Promise<void> {
+    try {
+      await this.journal?.state.delete(userID, NOTIFIER_COLLECTION, KEY)
+    } catch (cause) {
+      this.log(`[hub] concierge notifier: ledger delete failed: ${(cause as Error).message}`)
+    }
+  }
+
+  /** One pass over every user (passes never overlap). */
+  tick(): Promise<void> {
+    if (!this.journal) return Promise.resolve()
+    this.running ??= this.pass().finally(() => {
+      this.running = undefined
+    })
+    return this.running
+  }
+
+  /** The user's ledger (tests, diagnostics). */
+  async ledger(userID: string): Promise<NotifierLedger | undefined> {
+    return (await this.journal?.state.get<NotifierLedger>(userID, NOTIFIER_COLLECTION, KEY))?.value
+  }
+
+  // ---------- internals ----------
+
+  /** A pass now, after the one running (if any). */
+  private passSoon(): void {
+    const after = this.running ? this.running.then(() => this.tick()) : this.tick()
+    void after.catch(() => undefined)
+  }
+
+  /** One pass at `at` (on the leader loop only), unless one is already due by then. */
+  private armDue(at: number): void {
+    if (!this.started || at <= this.now() || (this.dueAt !== undefined && this.dueAt <= at)) return
+    if (this.due !== undefined) this.timers.clear(this.due)
+    this.dueAt = at
+    this.due = this.timers.set(() => {
+      this.due = this.dueAt = undefined
+      this.passSoon()
+    }, Math.max(0, at - this.now()))
+  }
+
+  /** When held notable (or demoted priority) lines come due: their quiet window ends, or their max one. */
+  private notableDue(ledger: NotifierLedger): number | undefined {
+    const timed = ledger.buffer.filter((l) => l.c !== "routine")
+    const carried = ledger.buffer.flatMap((l) => (l.c === "routine" && l.t0 !== undefined ? [l.t0] : []))
+    if (!timed.length && !carried.length) return undefined
+    const firsts = [...timed.map((l) => l.t0 ?? l.t ?? ledger.firstAt ?? this.now()), ...carried]
+    const max = Math.min(...firsts) + this.limits.notableMaxMs
+    if (!timed.length) return max
+    const times = timed.map((l) => l.t ?? ledger.lastAt ?? this.now())
+    return Math.min(Math.max(...times) + this.limits.notableQuietMs, max)
+  }
+
+  private leading(): boolean {
+    return !this.stopped && (this.journal?.isLeader?.() ?? true)
+  }
+
+  private schedule(): void {
+    this.timer = this.timers.set(() => {
+      this.timer = undefined
+      void this.tick().finally(() => {
+        if (this.started) this.schedule()
+      })
+    }, this.journal?.tickMs ?? NOTIFIER_TICK_MS)
+  }
+
+  private async pass(): Promise<void> {
+    if (!this.leading()) return
+    let users: string[]
+    try {
+      users = [...(await this.ports.users())]
+    } catch (cause) {
+      this.log(`[hub] concierge notifier: 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] concierge notifier: pass failed: ${(cause as Error).message}`)
+      }
+    }
+  }
+
+  private fresh(position: string, t: number, sessionID: string | undefined): NotifierLedger {
+    return { v: 1, ...(sessionID ? { sessionID } : {}), position, buffer: [], window: [], seq: 0, facts: {}, alerts: {}, digests: {}, counts: { ...ZERO }, countsSince: t, history: [] }
+  }
+
+  private async user(userID: string): Promise<void> {
+    const journal = this.journal!
+    const [settings, status] = await Promise.all([this.ports.settings(userID), this.ports.status(userID)])
+    if (!settings.enabled || status.state === "disabled") {
+      // Nothing to a disabled Concierge, and nothing kept for it.
+      if (await journal.state.get(userID, NOTIFIER_COLLECTION, KEY)) await journal.state.delete(userID, NOTIFIER_COLLECTION, KEY)
+      return
+    }
+    const identity = await this.ports.identity.current(userID)
+    const t = this.now()
+    const latest = await journal.events.latest(userID)
+    const stored = await journal.state.get<NotifierLedger>(userID, NOTIFIER_COLLECTION, KEY)
+    let ledger = stored?.value ?? this.fresh(latest, t, identity.sessionID)
+    // Someone may be sending it right now (another pod before failover, or a pass in flight).
+    if (ledger.batch?.state === "sending" && (ledger.batch.claimedAt ?? 0) + this.limits.claimGraceMs > t) return
+    const running = status.state === "running" && identity.sessionID !== undefined
+    // A relaunched Concierge is a new session: it knows nothing the old one was told.
+    if (running && ledger.sessionID !== identity.sessionID) ledger = { ...ledger, sessionID: identity.sessionID, facts: {}, alerts: {} }
+    if (ledger.position !== latest) ledger = await this.scan(userID, ledger, identity.hiddenSessionIDs, t)
+    ledger = this.housekeeping(ledger, t)
+    ledger = this.digestsDue(ledger, settings, t)
+    // Quiet hours also hold retries and stale-claim resends: only a priority batch with quietAllowsUrgent goes now;
+    // any other is held again and goes with the release (or the digest) when they end.
+    if (ledger.batch && inQuietHours(settings.quietHours, t) && !(ledger.batch.budget === "priority" && settings.quietAllowsUrgent)) ledger = this.defer(ledger, ledger.batch)
+    if (!ledger.batch && running) ledger = this.cut(ledger, settings, t)
+    // Held notable lines: a pass when they come due, not on the next tick after that. Only a FUTURE due: held lines
+    // already due were just declined by cut (quiet hours, a spent budget), which only time or the tick changes.
+    if (running && !ledger.batch) {
+      const due = this.notableDue(ledger)
+      if (due !== undefined && due > t) this.armDue(due)
+    }
+
+    const batch = ledger.batch
+    const sendable = running && batch !== undefined && (batch.state === "ready" || batch.state === "sending" || (batch.state === "retry" && (batch.nextAt ?? 0) <= t))
+    let claimed: NotifierBatch | undefined
+    if (sendable) {
+      claimed = { ...batch, state: "sending", attempts: batch.attempts + 1, claimedBy: this.owner, claimedAt: t, ...(batch.state === "sending" ? { last: "uncertain" as const } : {}) }
+      ledger = { ...ledger, batch: claimed }
+    }
+    if (!this.leading()) return
+    if (!claimed && stored && JSON.stringify(stored.value) === JSON.stringify(ledger)) return
+    const put = await journal.state.put(userID, NOTIFIER_COLLECTION, KEY, ledger, { ifVersion: stored?.version ?? 0 })
+    if (!put.ok || !claimed) return
+    await this.attempt(userID, identity.hiddenSessionIDs, claimed)
+  }
+
+  /** Reads the journal after the ledger's position into its buffer (or owes a snapshot). */
+  private async scan(userID: string, ledger: NotifierLedger, hiddenIDs: readonly string[], t: number): Promise<NotifierLedger> {
+    const journal = this.journal!
+    const result: EventsSince = await journal.events.since(userID, ledger.position)
+    if ("reset" in result) {
+      const position = await journal.events.latest(userID)
+      // How much the journal dropped is unknown: a priority snapshot (quiet hours still apply) that says so.
+      const missed = (ledger.snapshot?.missed ?? 0) + ledger.buffer.length
+      return { ...without(ledger, "firstAt", "lastAt"), position, buffer: [], snapshot: { reason: "reset", missed, unknown: true, urgent: true } }
+    }
+    if (!result.records.length) return ledger
+    const hidden = new Set(hiddenIDs)
+    let view: WatchedView | undefined
+    let { snapshot, firstAt, lastAt } = ledger
+    let buffer: Line[] = [...ledger.buffer]
+    const counts = { ...ledger.counts }
+    for (const record of result.records) {
+      if (!RELEVANT.has(record.event.type)) continue
+      view ??= await journal.watched(userID, hiddenIDs)
+      let decision: ClassifyContext["decision"]
+      if (record.event.type === "message.changed" && record.event.data.kind === "ask" && record.event.data.to === "@me" && typeof record.event.subject.messageID === "string") {
+        decision = await journal.decisionOf?.(userID, record.event.subject.messageID).catch(() => undefined)
+      }
+      const raw = classifyEvent(record, { hidden, view, ...(decision ? { decision } : {}) })
+      if (!raw) continue
+      counts[raw.c]++
+      const held = this.fold(raw, ledger.alerts, t)
+      if (snapshot) {
+        snapshot = { ...snapshot, missed: snapshot.missed + 1, ...(held.c === "priority" ? { urgent: true as const } : {}) }
+        continue
+      }
+      if (held.o && buffer.some((l) => l.k === held.k && l.f === held.f)) continue
+      // A state line replaces the routine one held for the same subject, never a held priority line; it keeps the
+      // earliest notable time of what it replaced (the max window).
+      let t0: number | undefined
+      if (held.k !== undefined) {
+        for (const l of buffer) {
+          if (l.k !== held.k || l.c === "priority") continue
+          const first = l.t0 ?? (l.c !== "routine" ? l.t : undefined)
+          if (first !== undefined && (t0 === undefined || first < t0)) t0 = first
+        }
+        buffer = buffer.filter((l) => l.k !== held.k || l.c === "priority")
+      }
+      if (buffer.length >= this.limits.bufferLines) {
+        const urgent = held.c === "priority" || buffer.some((l) => l.c === "priority")
+        snapshot = { reason: "overflow", missed: buffer.length + 1, ...(urgent ? { urgent: true as const } : {}) }
+        buffer = []
+        firstAt = lastAt = undefined
+        continue
+      }
+      buffer.push({ ...held, t: record.event.at, ...(t0 !== undefined ? { t0 } : {}) })
+      firstAt ??= record.event.at
+      lastAt = record.event.at
+    }
+    const base = without(ledger, "firstAt", "lastAt", "snapshot")
+    return { ...base, position: result.records.at(-1)!.position, buffer, counts, ...(snapshot ? { snapshot } : {}), ...(buffer.length && firstAt !== undefined ? { firstAt, lastAt: lastAt! } : {}) }
+  }
+
+  /** A pending batch held again (quiet hours): its lines, snapshot and digest go back to the ledger, marked quiet-held. */
+  private defer(ledger: NotifierLedger, batch: NotifierBatch): NotifierLedger {
+    let buffer: Line[] = [...(batch.held ?? []), ...ledger.buffer]
+    let snapshot = ledger.snapshot
+    if (batch.snapshot) {
+      const unknown = batch.snapshot.unknown || snapshot?.unknown
+      const urgent = batch.budget === "priority" || snapshot?.urgent
+      snapshot = { reason: batch.snapshot.reason, missed: batch.snapshot.missed + (snapshot?.missed ?? 0), ...(unknown ? { unknown: true as const } : {}), ...(urgent ? { urgent: true as const } : {}) }
+    }
+    if (buffer.length > this.limits.bufferLines) {
+      const urgent = snapshot?.urgent || buffer.some((l) => l.c === "priority")
+      snapshot = { reason: "overflow", missed: (snapshot?.missed ?? 0) + buffer.length, ...(snapshot?.unknown ? { unknown: true as const } : {}), ...(urgent ? { urgent: true as const } : {}) }
+      buffer = []
+    }
+    const supersedes = batch.attempts > 0 ? [...(ledger.supersedes ?? []), batch.id].slice(-10) : ledger.supersedes
+    const d = batch.digest
+    const digest = d
+      ? {
+          owedDigest: ledger.owedDigest ?? { key: d.key ?? `digest:${batch.id}`, label: d.label, at: batch.cutAt },
+          counts: { priority: d.counts.priority + ledger.counts.priority, notable: d.counts.notable + ledger.counts.notable, routine: d.counts.routine + ledger.counts.routine },
+          countsSince: d.since,
+        }
+      : {}
+    const at = { firstAt: ledger.firstAt ?? batch.cutAt, lastAt: ledger.lastAt ?? batch.cutAt }
+    return {
+      ...without(ledger, "batch", "snapshot", "firstAt", "lastAt"),
+      buffer,
+      ...(buffer.length ? at : {}),
+      ...(snapshot ? { snapshot } : {}),
+      ...(supersedes?.length ? { supersedes } : {}),
+      ...digest,
+      quietHeld: true,
+    }
+  }
+
+  /** A priority line about a reason it was woken about within foldMs: routine instead (RF-05). */
+  private fold(line: Line, alerts: Readonly<Record<string, number>>, t: number): Line {
+    if (line.c !== "priority" || !line.b?.length) return line
+    const known = line.b.every((key) => alerts[key] !== undefined && t - alerts[key]! < this.limits.foldMs)
+    return known ? { ...without(line, "b"), c: "routine", text: `-${line.text.slice(1)}` } : line
+  }
+
+  private housekeeping(ledger: NotifierLedger, t: number): NotifierLedger {
+    const alerts: Record<string, number> = {}
+    for (const [key, at] of Object.entries(ledger.alerts)) if (t - at < this.limits.foldMs) alerts[key] = at
+    const digests: Record<string, number> = {}
+    for (const [key, at] of Object.entries(ledger.digests)) if (t - at < 8 * DAY_MS) digests[key] = at
+    return { ...ledger, window: ledger.window.filter((w) => w.at > t - HOUR_MS), alerts, digests }
+  }
+
+  /** Marks each due digest (once per key) and owes the latest. */
+  private digestsDue(ledger: NotifierLedger, settings: ConciergeSettings, t: number): NotifierLedger {
+    let next = ledger
+    for (const due of dueDigests(settings.digests ?? [], settings.timeZone, t, this.limits.digestGraceMs)) {
+      if (next.digests[due.key] !== undefined) continue
+      next = { ...next, digests: { ...next.digests, [due.key]: t }, owedDigest: { key: due.key, label: due.label, at: due.occurredAt } }
+    }
+    return next
+  }
+
+  /** What the Concierge does not know yet: a state line repeating the last delivered state is dropped. */
+  private news(ledger: NotifierLedger): Line[] {
+    const known = ledger.facts
+    const urgentSubjects = new Set(ledger.buffer.flatMap((l) => (l.c === "priority" && l.k !== undefined ? [l.k] : [])))
+    return ledger.buffer.filter((l) => {
+      if (l.k === undefined) return true
+      if (l.o) return known[l.k] !== l.f
+      // It carries an undelivered turn done (t0): news even when its state is the one told last.
+      if (l.t0 !== undefined) return true
+      // A turn done is news even when the last state told was idle: the working in between was never told (a routine
+      // line it replaced while held).
+      return l.c === "priority" || l.c === "notable" || urgentSubjects.has(l.k) || known[l.k] !== l.f
+    })
+  }
+
+  /** Turns held lines, an owed snapshot or digest into the next batch, when due. */
+  private cut(ledger: NotifierLedger, settings: ConciergeSettings, t: number): NotifierLedger {
+    const L = this.limits
+    const used = (b: LineClass) => ledger.window.filter((w) => w.budget === b).length
+    const room: Record<LineClass, boolean> = { priority: used("priority") < L.priorityPerHour, notable: used("notable") < L.notablePerHour, routine: used("routine") < L.routinePerHour }
+    const quiet = inQuietHours(settings.quietHours, t)
+    // A state line that replaced an undelivered turn done (t0) past the max window is that turn done: notable.
+    const news = this.news(ledger).map((l) => (l.c === "routine" && l.t0 !== undefined && t - l.t0 >= L.notableMaxMs ? overdueTurn(l) : l))
+    const rest = { ...ledger, buffer: news, ...(news.length ? {} : { firstAt: undefined, lastAt: undefined }) } as NotifierLedger
+    const clean = (l: NotifierLedger) => (l.buffer.length ? l : (without(l, "firstAt", "lastAt") as NotifierLedger))
+
+    // A digest (not in quiet hours): everything held goes with it, quiet-hours releases included.
+    if (ledger.owedDigest && !quiet) {
+      const digest = { key: ledger.owedDigest.key, label: ledger.owedDigest.label, zone: zoneOrUTC(settings.timeZone), since: ledger.countsSince, counts: ledger.counts }
+      const next = this.compose({ ...rest, buffer: [] }, news, { kind: "digest", budget: "digest", wake: true, digest, ...(ledger.snapshot ? { snapshot: ledger.snapshot } : {}) }, t)
+      return clean({ ...without(next, "owedDigest", "quietHeld", "snapshot"), counts: { ...ZERO }, countsSince: t })
+    }
+    if (quiet) {
+      const priority = news.filter((l) => l.c === "priority")
+      const urgent = priority.length > 0 || ledger.snapshot?.urgent === true
+      const holding = news.length > 0 || ledger.snapshot !== undefined || ledger.owedDigest !== undefined
+      if (settings.quietAllowsUrgent && urgent && room.priority) {
+        const others = news.filter((l) => l.c !== "priority")
+        const next = this.compose({ ...rest, buffer: others }, priority, { kind: ledger.snapshot?.urgent ? "snapshot" : "delta", budget: "priority", wake: true, ...(ledger.snapshot?.urgent ? { snapshot: ledger.snapshot } : {}) }, t)
+        const cleared: NotifierLedger = ledger.snapshot?.urgent ? without(next, "snapshot") : next
+        return clean(others.length || cleared.snapshot || cleared.owedDigest ? { ...cleared, quietHeld: true } : cleared)
+      }
+      return clean(holding ? { ...rest, quietHeld: true } : rest)
+    }
+    if (ledger.quietHeld) {
+      if (!news.length && !ledger.snapshot) return clean(without(rest, "quietHeld"))
+      return clean(without(this.compose({ ...rest, buffer: [] }, news, { kind: "release", budget: "digest", wake: true, ...(ledger.snapshot ? { snapshot: ledger.snapshot } : {}) }, t), "quietHeld", "snapshot"))
+    }
+    if (ledger.snapshot) {
+      const urgent = ledger.snapshot.urgent === true
+      const budget: LineClass | undefined = urgent ? (room.priority ? "priority" : room.notable ? "notable" : room.routine ? "routine" : undefined) : room.routine ? "routine" : undefined
+      if (!budget) return clean(rest)
+      return clean(without(this.compose({ ...rest, buffer: [] }, [], { kind: "snapshot", budget, wake: budget !== "routine", snapshot: ledger.snapshot }, t), "snapshot"))
+    }
+    if (!news.length) return clean(rest)
+    const top: LineClass = news.some((l) => l.c === "priority") ? "priority" : news.some((l) => l.c === "notable") ? "notable" : "routine"
+    const order: LineClass[] = top === "priority" ? ["priority", "notable", "routine"] : top === "notable" ? ["notable", "routine"] : ["routine"]
+    const budget = order.find((b) => room[b])
+    if (!budget) return clean(rest)
+    if (budget !== "priority") {
+      const quietMs = budget === "notable" ? L.notableQuietMs : L.routineQuietMs
+      const maxMs = budget === "notable" ? L.notableMaxMs : L.routineMaxMs
+      // A wake's windows count from its own (notable and demoted priority) lines: routine churn of other sessions,
+      // which goes along, never holds it back.
+      const timed = budget === "notable" ? news.filter((l) => l.c !== "routine") : []
+      const last = timed.length ? Math.max(...timed.map((l) => l.t ?? ledger.lastAt ?? t)) : (ledger.lastAt ?? t)
+      const first = timed.length ? Math.min(...timed.map((l) => l.t0 ?? l.t ?? ledger.firstAt ?? t)) : (ledger.firstAt ?? t)
+      const quietEnough = t - last >= quietMs
+      const late = t - first >= maxMs
+      if (!quietEnough && !late) return clean(rest)
+    }
+    return clean(this.compose({ ...rest, buffer: [] }, news, { kind: "delta", budget, wake: budget !== "routine" }, t))
+  }
+
+  /** A batch of `lines` (priority first), with the ledger's owed snapshot noted; `ledger.buffer` is what stays. */
+  private compose(
+    ledger: NotifierLedger,
+    lines: readonly Line[],
+    options: { kind: BatchKind; budget: Budget; wake: boolean; digest?: NotifierBatch["digest"]; snapshot?: NotifierLedger["snapshot"] },
+    t: number,
+  ): NotifierLedger {
+    const rank: Record<LineClass, number> = { priority: 0, notable: 1, routine: 2 }
+    const ordered = [...lines].sort((a, b) => rank[a.c] - rank[b.c])
+    const listed = ordered.slice(0, this.limits.linesPerBatch)
+    const counts = { ...ZERO }
+    for (const l of listed) counts[l.c]++
+    const facts = Object.fromEntries(listed.flatMap((l) => (l.k !== undefined && l.f !== undefined ? [[l.k, l.f] as const] : [])))
+    const alerts = options.wake ? [...new Set(listed.flatMap((l) => (l.c === "priority" ? (l.b ?? []) : [])))] : []
+    const seq = ledger.seq + 1
+    const batch: NotifierBatch = {
+      id: `b${seq}`,
+      seq,
+      kind: options.kind,
+      budget: options.budget,
+      wake: options.wake,
+      lines: listed.map((l) => l.text),
+      more: ordered.length - listed.length,
+      counts,
+      facts,
+      ...(alerts.length ? { alerts } : {}),
+      ...(options.snapshot ? { snapshot: { reason: options.snapshot.reason, missed: options.snapshot.missed, ...(options.snapshot.unknown ? { unknown: true as const } : {}) } } : {}),
+      held: listed,
+      ...(ledger.supersedes?.length ? { supersedes: ledger.supersedes } : {}),
+      ...(options.digest ? { digest: options.digest } : {}),
+      cutAt: t,
+      state: "ready",
+      attempts: 0,
+    }
+    return { ...without(ledger, "supersedes"), seq, batch }
+  }
+
+  /** Sends a claimed batch and records the outcome (only if the ledger still holds that batch). */
+  private async attempt(userID: string, hidden: readonly string[], batch: NotifierBatch): Promise<void> {
+    if (!this.leading()) return // the claim stays: after claimGraceMs the next leader resends it
+    const journal = this.journal!
+    // The board is on the session before a wake (2 s budget); a failed push keeps the last one (its age shows).
+    if (batch.wake) await this.within(this.ports.beforeWake(userID), this.limits.beforeWakeMs).catch(() => false)
+    const revision = journal.boardRevision ? await this.within(journal.boardRevision(userID, hidden), this.limits.beforeWakeMs).catch(() => undefined) : undefined
+    const text = renderBatch(batch, revision)
+    let result: { messageID: string; woke?: boolean } | undefined
+    let failure: "uncertain" | "refused" | undefined
+    try {
+      if (!this.leading()) return
+      // Queued, never steered: no `urgent`.
+      result = await this.within(this.ports.send(userID, text, { wake: batch.wake }), this.limits.sendTimeoutMs)
+    } catch (cause) {
+      failure = cause instanceof AgentError && REFUSED.has(cause.code) ? "refused" : "uncertain"
+      this.log(`[hub] concierge notifier: ${batch.id} attempt ${batch.attempts} ${failure}: ${(cause as Error).message}`)
+    }
+    const t = this.now()
+    const L = this.limits
+    const recorded = await updateVersioned<NotifierLedger>(journal.state, userID, NOTIFIER_COLLECTION, KEY, (current) => {
+      if (!current?.batch || current.batch.id !== batch.id) return undefined // revoked (disabled) meanwhile
+      const window = failure === "refused" || batch.budget === "digest" ? current.window : [...current.window, { at: t, budget: batch.budget }]
+      if (!failure) {
+        const facts = bounded({ ...(batch.kind === "snapshot" ? {} : current.facts), ...batch.facts }, L.factsMax)
+        const woke = batch.wake && result?.woke !== false
+        const alerts: Record<string, number> = { ...current.alerts }
+        if (woke) for (const key of batch.alerts ?? []) alerts[key] = t
+        const history = [...current.history, { id: batch.id, kind: batch.kind, at: t, attempts: batch.attempts, outcome: "delivered" as const, messageID: result!.messageID }].slice(-L.historyMax)
+        return { ...without(current, "batch"), window, facts, alerts: bounded(alerts, L.factsMax), history }
+      }
+      if (batch.attempts >= L.maxAttempts) {
+        const urgent = batch.wake || current.buffer.some((l) => l.c === "priority")
+        const history = [...current.history, { id: batch.id, kind: batch.kind, at: t, attempts: batch.attempts, outcome: "abandoned" as const }].slice(-L.historyMax)
+        const missed = batch.lines.length + batch.more + current.buffer.length + (current.snapshot?.missed ?? 0)
+        const unknown = current.snapshot?.unknown || batch.snapshot?.unknown
+        return { ...without(current, "batch", "firstAt", "lastAt"), window, buffer: [], facts: {}, snapshot: { reason: "abandoned" as const, missed, ...(unknown ? { unknown: true as const } : {}), ...(urgent ? { urgent: true as const } : {}) }, history }
+      }
+      const wait = L.retryMs[Math.min(batch.attempts - 1, L.retryMs.length - 1)] ?? 60_000
+      return { ...current, window, batch: { ...without(batch, "claimedBy", "claimedAt"), ...(failure ? { last: failure } : {}), state: "retry", nextAt: t + wait } }
+    })
+    if (!failure && recorded) {
+      try {
+        if (batch.kind === "digest") this.ports.entitlements.record(userID, { kind: "digest", n: 1 })
+        else if (batch.wake && result?.woke !== false) this.ports.entitlements.record(userID, { kind: "wake", n: 1 })
+      } catch (cause) {
+        this.log(`[hub] concierge notifier: entitlements failed: ${(cause as Error).message}`)
+      }
+    }
+  }
+
+  /** The promise, or a rejection after `ms` (it may still settle: the caller treats that as uncertain). */
+  private within<T>(promise: Promise<T>, ms: number): Promise<T> {
+    let handle: unknown
+    const timeout = new Promise<never>((_, reject) => {
+      handle = this.timers.set(() => reject(new Error(`no answer within ${ms} ms`)), ms)
+    })
+    return Promise.race([promise, timeout]).finally(() => this.timers.clear(handle))
+  }
+}