@huynle/hub 0.7.4 → 0.8.1

package/src/central/concierge/context.ts

@@ -0,0 +1,221 @@
+// CON-04 the Concierge session's per-turn context (contract "Per-turn context"): the plugin's context hook is
+// synchronous, so the hub PUSHES {instructions, board, notes}, tools.deny and lockAgent to the spoke that reports the
+// session (op sessionContext, announced by the OpenCode spoke; the cluster's spokes.request routes it to the pod
+// holding the spoke). The whole set replaces the previous one.
+//
+// - instructions: prompt.ts (versioned constant). board: the grant line, then renderBoard (its header carries "as
+//   of <time>", so a context the spoke kept after a failed send shows its age). notes: the Concierge's notes,
+//   framed as its own memory. Untrusted session text stays inside the board's «…» framing.
+// - tools.allow: CONCIERGE_TOOLS exactly (hub, read, glob, grep, question): every other tool is removed on every
+//   turn, unknown future ones included (fail closed). No subagent/task, execute (Code Mode), web tools, shell, edit,
+//   MCP or plugin tools. The Brain connector is not offered in C1 (settings.ts refuses it).
+// - Revisions grow with the clock (max(now, last + 1)), so a restarted hub never sends an older one; a "stale"
+//   answer (another pod's clock ran ahead) retries once with a later revision.
+// - Unchanged context is not re-sent to the same connection; a session reported on another connection (a spoke
+//   restart or reconnect) gets it again. A failed send keeps the last revision and is retried by the next push.
+// - touch(): board refreshes debounced per user (5 s quiet, 30 s at most; CON-13 `soon`, for a blocker opened or
+//   closed: within 1 s, and later plain touches never push it back). beforeWake(): a push awaited at most 2 s
+//   before a Concierge wake message (CON-05). Nothing here ever rejects.
+import { CONCIERGE_TOOLS, SESSION_CONTEXT_FEATURE, SESSION_CONTEXT_LIMITS, type SessionContextRequest, type SessionContextResult } from "../../../packages/protocol/src/concierge"
+import type { Clock, Timers } from "../backend/types"
+import type { NotesStore } from "./notes"
+import { conciergeInstructions, grantLine, type GrantLineInput, NOTES_HEADER, RETIRED_INSTRUCTIONS } from "./prompt"
+import type { SettingsStore } from "./settings"
+
+export { CONCIERGE_TOOLS } from "../../../packages/protocol/src/concierge"
+export const CONTEXT_TIMING = { quietMs: 5_000, maxMs: 30_000, wakeBudgetMs: 2_000, soonMs: 1_000 } as const
+/** At most one forced re-send (a report without the current revision) per session in this window. */
+export const CONCIERGE_FORCED_PUSH_MS = 2_000
+/** OpenCode's internal agents (title generation, compaction, summaries): never tamper. */
+export const INTERNAL_AGENTS: ReadonlySet<string> = new Set(["title", "compaction", "summary"])
+/** OpenCode's primary agents and the plugin's (an agent outside this list is logged when a Concierge is found on it). */
+export const KNOWN_PRIMARY_AGENTS: ReadonlySet<string> = new Set(["build", "plan", "general", "explore", "voice"])
+const STALE_BUMP_MS = 60_000
+
+/** The grant the board header names (Grants.get with its state); undefined when unknown. */
+export interface ContextGrant {
+  readonly id: string
+  readonly state: "active" | "expired" | "revoked"
+  readonly allow: readonly string[]
+  readonly scope: { readonly projects: readonly string[] }
+  readonly expiresAt: number
+  readonly revokedAt?: number
+  /** (CON-13) Its permission rules, for the grant line. */
+  readonly permissions?: { readonly allow: readonly string[]; readonly never: readonly string[] }
+}
+
+export interface ContextDeps {
+  readonly registry: { sessionTargets(sessionID: string): string[]; supports(connID: string, feature: typeof SESSION_CONTEXT_FEATURE): boolean; connTenant(connID: string): string | undefined }
+  readonly send: (connID: string, req: SessionContextRequest) => Promise<SessionContextResult>
+  /** The rendered board of the user (renderBoard). */
+  readonly board: (userID: string) => Promise<string>
+  readonly notes: Pick<NotesStore, "get">
+  readonly settings: Pick<SettingsStore, "get">
+  readonly grant: (userID: string, grantID: string) => Promise<ContextGrant | undefined>
+  /** (CON-09a) Speech is set up for the user (the instructions mention voice and voice confirm). Absent: false. */
+  readonly voice?: (userID: string) => boolean
+  readonly now?: Clock
+  readonly timers?: Timers
+}
+
+const defaultTimers: Timers = {
+  set: (fn, ms) => {
+    const handle = setTimeout(fn, ms)
+    ;(handle as { unref?: () => void }).unref?.()
+    return handle
+  },
+  clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+}
+
+type Body = Omit<SessionContextRequest, "revision">
+
+const cut = (text: string) => (text.length > SESSION_CONTEXT_LIMITS.partChars ? `${text.slice(0, SESSION_CONTEXT_LIMITS.partChars - 1)}…` : text)
+
+export class ContextPusher {
+  private readonly now: Clock
+  private readonly timers: Timers
+  private last = 0
+  /** Per user + session: what the spoke has (its digest, connection and revision). */
+  private readonly sent = new Map<string, { digest: string; connID: string; revision: number }>()
+  private readonly debounces = new Map<string, { first: number; due: number; timer: unknown }>()
+
+  constructor(private readonly deps: ContextDeps) {
+    this.now = deps.now ?? Date.now
+    this.timers = deps.timers ?? defaultTimers
+  }
+
+  /** The user's connection reporting the session that serves sessionContext (the owner first). */
+  private target(userID: string, sessionID: string): string | undefined {
+    const { registry } = this.deps
+    return registry.sessionTargets(sessionID).find((connID) => registry.connTenant(connID) === userID && registry.supports(connID, SESSION_CONTEXT_FEATURE))
+  }
+
+  private revision(bump = 0): number {
+    this.last = Math.max(this.now() + bump, this.last + 1)
+    return this.last
+  }
+
+  private async grantInput(userID: string, grantID: string | undefined): Promise<GrantLineInput> {
+    if (grantID === undefined) return { state: "none" }
+    const grant = await this.deps.grant(userID, grantID)
+    if (!grant) return { state: "none" }
+    if (grant.state === "active") return { state: "active", id: grant.id, allow: grant.allow, projects: grant.scope.projects, expiresAt: grant.expiresAt, ...(grant.permissions ? { permissions: grant.permissions } : {}) }
+    return { state: "ended", id: grant.id, at: grant.revokedAt ?? grant.expiresAt }
+  }
+
+  private async build(userID: string, sessionID: string): Promise<Body> {
+    const [settings, notes, board] = await Promise.all([this.deps.settings.get(userID), this.deps.notes.get(userID), this.deps.board(userID)])
+    const grant = await this.grantInput(userID, settings.grantID)
+    const parts: SessionContextRequest["parts"][number][] = [
+      { key: "instructions", text: cut(conciergeInstructions({ voice: this.deps.voice?.(userID) === true, timeZone: settings.timeZone })) },
+      { key: "board", text: cut(`${grantLine(grant, settings.timeZone)}\n${board}`) },
+      ...(notes.text ? [{ key: "notes" as const, text: cut(`${NOTES_HEADER}\n${notes.text}`) }] : []),
+    ]
+    return { op: "sessionContext", sessionID, parts, tools: { allow: [...CONCIERGE_TOOLS] }, lockAgent: true }
+  }
+
+  private async send(key: string, connID: string, body: Body, digest: string): Promise<boolean> {
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const revision = this.revision(attempt ? STALE_BUMP_MS : 0)
+      try {
+        const result = await this.deps.send(connID, { ...body, revision } as SessionContextRequest)
+        this.sent.set(key, { digest, connID, revision: result.revision })
+        return true
+      } catch (cause) {
+        if (attempt === 0 && /stale/i.test((cause as Error)?.message ?? "")) continue
+        console.error(`[hub] concierge context push failed: ${(cause as Error)?.message ?? String(cause)}`.slice(0, 300))
+        return false
+      }
+    }
+    return false
+  }
+
+  /** Builds and sends the session's context now (force: even when unchanged). True when the spoke has it. */
+  async push(userID: string, sessionID: string, options: { readonly force?: boolean } = {}): Promise<boolean> {
+    try {
+      const connID = this.target(userID, sessionID)
+      if (connID === undefined) return false
+      const body = await this.build(userID, sessionID)
+      const digest = JSON.stringify(body)
+      const key = `${userID}\n${sessionID}`
+      const known = this.sent.get(key)
+      if (!options.force && known && known.digest === digest && known.connID === connID) return true
+      return await this.send(key, connID, body, digest)
+    } catch (cause) {
+      console.error(`[hub] concierge context build failed: ${(cause as Error)?.message ?? String(cause)}`.slice(0, 300))
+      return false
+    }
+  }
+
+  /** A push awaited at most CONTEXT_TIMING.wakeBudgetMs (before a Concierge wake). */
+  beforeWake(userID: string, sessionID: string): Promise<boolean> {
+    return new Promise<boolean>((resolve) => {
+      const timer = this.timers.set(() => resolve(false), CONTEXT_TIMING.wakeBudgetMs)
+      void this.push(userID, sessionID).then((ok) => {
+        this.timers.clear(timer)
+        resolve(ok)
+      })
+    })
+  }
+
+  /**
+   * Something on the user's board may have changed: a push after 5 s quiet (30 s at most from the first touch).
+   * (CON-13) `soon` (a blocker opened or closed: the Concierge must not tell the user about a form already answered)
+   * caps it at 1 s from now; no later touch moves a push past a cap already set.
+   */
+  touch(userID: string, session: () => Promise<string | undefined>, options: { readonly soon?: boolean } = {}): void {
+    const t = this.now()
+    const known = this.debounces.get(userID)
+    if (known) this.timers.clear(known.timer)
+    const first = known?.first ?? t
+    const due = Math.min(known?.due ?? first + CONTEXT_TIMING.maxMs, options.soon ? t + CONTEXT_TIMING.soonMs : Infinity)
+    const wait = Math.max(0, Math.min(CONTEXT_TIMING.quietMs, due - t))
+    const timer = this.timers.set(() => {
+      this.debounces.delete(userID)
+      void session()
+        .then((sessionID) => (sessionID !== undefined ? this.push(userID, sessionID) : false))
+        .catch(() => false)
+    }, wait)
+    this.debounces.set(userID, { first, due, timer })
+  }
+
+  /** The revision the spoke acknowledged last for the session (undefined: none). */
+  revisionOf(userID: string, sessionID: string): number | undefined {
+    return this.sent.get(`${userID}\n${sessionID}`)?.revision
+  }
+
+  /**
+   * (CON-09a) Retires a previous Concierge session: its context becomes RETIRED_INSTRUCTIONS only, no tools, the
+   * agent locked. Like push, unchanged is not re-sent to the same connection unless `force` (the spoke reported
+   * another revision: it lost it). True when the spoke has it. Never rejects.
+   */
+  async retire(userID: string, sessionID: string, options: { readonly force?: boolean } = {}): Promise<boolean> {
+    try {
+      const connID = this.target(userID, sessionID)
+      if (connID === undefined) return false
+      const body: Body = { op: "sessionContext", sessionID, parts: [{ key: "instructions", text: RETIRED_INSTRUCTIONS }], tools: { allow: [] }, lockAgent: true }
+      const digest = JSON.stringify(body)
+      const key = `${userID}\n${sessionID}`
+      const known = this.sent.get(key)
+      if (!options.force && known && known.digest === digest && known.connID === connID) return true
+      return await this.send(key, connID, body, digest)
+    } catch (cause) {
+      console.error(`[hub] concierge retire failed: ${(cause as Error)?.message ?? String(cause)}`.slice(0, 300))
+      return false
+    }
+  }
+
+  /** Drops the session's context on its spoke (disable). Never rejects. */
+  async clear(userID: string, sessionID: string): Promise<void> {
+    this.sent.delete(`${userID}\n${sessionID}`)
+    const connID = this.target(userID, sessionID)
+    if (connID === undefined) return
+    await this.deps.send(connID, { op: "sessionContext", sessionID, revision: this.revision(), parts: [], clear: true }).catch(() => undefined)
+  }
+
+  /** Forgets everything (the hub stops). */
+  stop(): void {
+    for (const { timer } of this.debounces.values()) this.timers.clear(timer)
+    this.debounces.clear()
+  }
+}

package/src/central/concierge/entitlements.ts

@@ -0,0 +1,13 @@
+// CON-04 entitlements hook (contract "C2 hook point (not built)"): the service calls check() on enable and before
+// every launch or relaunch, and record() after each launch, wake or digest. C1 has no licensing, metering or
+// hosting: the default always answers ok and records nothing.
+
+export interface ConciergeEntitlements {
+  check(userID: string): Promise<{ ok: true } | { ok: false; reason: string }>
+  record(userID: string, usage: { kind: "launch" | "wake" | "digest"; n: number }): void
+}
+
+export const C1_ENTITLEMENTS: ConciergeEntitlements = {
+  check: async () => ({ ok: true }),
+  record: () => undefined,
+}

package/src/central/concierge/guard.ts

@@ -0,0 +1,120 @@
+// CON-04 manage paths that must not touch a Concierge session (current or hidden): its identity, prompt, presence
+// and placement are the hub's. Apps and sessions (the Concierge itself included) get 403 forbidden {policy:
+// "concierge"} on intent, archive and pin. EVERYONE (the user too) is refused on naming (the Concierge holds no
+// @name), profile pinning (its prompt is hub-owned), and on making it a workspace member or master (by sessionID,
+// @name, @@role or launchID), a side-chat source, or a team seat (attach, replace): it is hub-owned. Assignments
+// and supervision name members, which it can never be. Role claims are guarded in directory-routes.ts, grants in
+// grants.ts, messages in inbound.ts, act verbs in acting.ts.
+//
+// guardConciergeRoutes wraps the routes listed in CONCIERGE_GUARDED: before the route runs, it resolves the
+// targets (the `:addr` path parameter, the listed body fields of a bounded clone of the body, or the calling
+// session when a self route names none) for the caller's user and refuses when one is a Concierge session.
+// Unresolvable targets are left to the route (its own not_found / invalid).
+import type { AgentActor } from "../agent/actor"
+import { boundedJson } from "../agent/body"
+import { AgentError } from "../agent/errors"
+import type { AgentContext, AgentRoute } from "../agent/routes"
+import type { ConciergeIdentity } from "./watchlist-routes"
+
+export interface GuardRule {
+  readonly method: string
+  readonly path: string
+  /** The user is refused too. */
+  readonly everyone?: boolean
+  /** The `:addr` path parameter names the target. */
+  readonly addr?: boolean
+  /** Body fields naming the target (an address or a session ID). */
+  readonly body?: readonly string[]
+  /** Body fields naming a launch: its session, and any Concierge launch itself, is the target. */
+  readonly launch?: readonly string[]
+  /** A session caller that names no target acts on itself. */
+  readonly self?: boolean
+}
+
+const A = "/api/agent"
+export const CONCIERGE_GUARDED: readonly GuardRule[] = [
+  { method: "PUT", path: `${A}/sessions/:addr/intent`, addr: true },
+  { method: "PUT", path: `${A}/sessions/:addr/archive`, addr: true },
+  { method: "PUT", path: `${A}/sessions/:addr/pin`, addr: true },
+  { method: "POST", path: `${A}/name`, everyone: true, body: ["session"], self: true },
+  { method: "PUT", path: `${A}/sessions/:addr/profile`, everyone: true, addr: true },
+  { method: "POST", path: `${A}/workspaces/:id/members`, everyone: true, body: ["sessionID"] },
+  { method: "POST", path: `${A}/workspaces/:id/master`, everyone: true, body: ["sessionID"], launch: ["launchID"] },
+  { method: "POST", path: `${A}/workspaces/:id/side-chats`, everyone: true, body: ["sourceSessionID"] },
+  { method: "PUT", path: `${A}/teams/:id/staffing`, everyone: true, body: ["sessionID"] },
+  { method: "POST", path: `${A}/teams/:id/staffing/:staffing/replace`, everyone: true, body: ["sessionID"] },
+]
+
+export const conciergeRefusal = (message = "This does not apply to the Concierge: the hub manages it") => new AgentError("forbidden", message, { extra: { policy: "concierge" } })
+
+export interface GuardDeps {
+  readonly identity: ConciergeIdentity
+  /** The session IDs an address names for the user (empty when it names none). */
+  readonly resolve: (userID: string, addr: string) => readonly string[]
+  /** A launch of the user: its session and whether it is a Concierge launch (undefined: unknown). */
+  readonly launch?: (userID: string, launchID: string) => Promise<{ readonly sessionID?: string; readonly concierge: boolean } | undefined>
+}
+
+const CONCIERGE_LAUNCH = "\u0000concierge-launch"
+
+async function targets(rule: GuardRule, context: AgentContext, deps: GuardDeps): Promise<string[]> {
+  const { user, actor, params, request } = context
+  const out: string[] = []
+  const add = (addr: unknown) => {
+    if (typeof addr !== "string" || !addr) return
+    out.push(addr)
+    try {
+      out.push(...deps.resolve(user.id, addr))
+    } catch {
+      // Unknown or malformed: the route answers it.
+    }
+  }
+  if (rule.addr && params.addr !== undefined) add(params.addr)
+  let named = false
+  if (rule.body || rule.launch) {
+    let body: unknown
+    try {
+      body = await boundedJson(request.clone())
+    } catch {
+      body = undefined
+    }
+    if (typeof body === "object" && body !== null) {
+      for (const key of rule.body ?? []) {
+        const value = (body as Record<string, unknown>)[key]
+        if (value !== undefined) named = true
+        add(value)
+      }
+      for (const key of rule.launch ?? []) {
+        const value = (body as Record<string, unknown>)[key]
+        if (typeof value !== "string" || !deps.launch) continue
+        named = true
+        const launch = await deps.launch(user.id, value).catch(() => undefined)
+        if (launch?.concierge) out.push(CONCIERGE_LAUNCH)
+        if (launch?.sessionID !== undefined) out.push(launch.sessionID)
+      }
+    }
+  }
+  if (rule.self && !named && actor.kind === "session") out.push(actor.sessionID)
+  return out
+}
+
+const applies = (rule: GuardRule, actor: AgentActor) => rule.everyone === true || actor.kind !== "user"
+
+/** The routes with the Concierge guard in front of the listed ones. */
+export function guardConciergeRoutes(routes: readonly AgentRoute[], deps: GuardDeps): AgentRoute[] {
+  return routes.map((route) => {
+    const rule = CONCIERGE_GUARDED.find((r) => r.method === route.method && r.path === route.path)
+    if (!rule) return route
+    return {
+      ...route,
+      handle: async (context: AgentContext) => {
+        if (applies(rule, context.actor)) {
+          const hidden = new Set((await deps.identity.current(context.user.id)).hiddenSessionIDs)
+          const named = await targets(rule, context, deps)
+          if (named.includes(CONCIERGE_LAUNCH) || (hidden.size && named.some((id) => hidden.has(id)))) throw conciergeRefusal()
+        }
+        return route.handle(context)
+      },
+    }
+  })
+}

package/src/central/concierge/inbound.ts

@@ -0,0 +1,86 @@
+// CON-04 inbound rule (contract: docs/plans/2026-11-01-concierge-contracts.md, "Inbound rule"). The Concierge
+// holds a grant, so other parties must not steer it: delivery TO any of the user's Concierge sessions (the current
+// one and the hidden previous ones) is admitted only from
+//   - the user,
+//   - the fixed hub party app:concierge (conciergeActor: the Concierge service's events and digests), and
+//   - a reply or decline to an ask the Concierge session itself sent.
+// Anything else is 403 forbidden {policy: "concierge"} before anything is stored, with an agent audit entry
+// (verb msg, decision forbidden; never the text). Outbound (coordinator decision): a Concierge session messages and
+// asks only @me, and replies or declines only asks addressed to it; it reaches other sessions only through its
+// grant-gated act verbs. The acting guard (conciergeProtects) keeps agents from acting
+// on a Concierge session under a grant (prompt, stop, approve…): only the user does. A failed identity read
+// refuses (fails closed).
+import { CONCIERGE_PARTY } from "../../../packages/protocol/src/concierge"
+import type { AppActor } from "../agent/actor"
+import type { AgentAudit } from "../agent/audit"
+import type { InboundKind, InboundPolicy } from "../agent/delivery"
+import type { Party } from "../agent/envelope"
+import { AgentError } from "../agent/errors"
+import type { Message } from "../agent/messages"
+import type { ConciergeIdentity } from "./watchlist-routes"
+
+/** The token ID of the fixed hub party app:concierge (never a real token: those are hat_<16 hex>). */
+export const CONCIERGE_TOKEN = CONCIERGE_PARTY.slice("app:".length)
+
+/** The Concierge service as a sender: launches and its event and digest messages (never the user). */
+export const conciergeActor = (userID: string): AppActor => ({ kind: "app", userID, tokenID: CONCIERGE_TOKEN, scopes: [], label: "concierge" })
+
+export const CONCIERGE_INBOUND_MESSAGE = "The Concierge takes messages only from you and the hub: sessions reach the user with ask @me"
+
+const isConcierge = (current: { readonly sessionID?: string; readonly hiddenSessionIDs: readonly string[] }, sessionID: string) =>
+  current.sessionID === sessionID || current.hiddenSessionIDs.includes(sessionID)
+
+/** Whether `from` may send `kind` to the Concierge session `sessionID` (see the header). */
+export function admitted(from: Party, sessionID: string, kind: InboundKind, original?: Message): boolean {
+  if (from.kind === "user") return true
+  if (from.kind === "app" && from.tokenID === CONCIERGE_TOKEN) return true
+  if ((kind === "reply" || kind === "decline") && original?.kind === "ask" && original.from.kind === "session" && original.from.sessionID === sessionID) return true
+  return false
+}
+
+export interface ConciergeInboundDeps {
+  readonly identity: ConciergeIdentity
+  readonly audit?: Pick<AgentAudit, "record">
+}
+
+/** The Delivery inbound policy (Delivery deps.inbound). */
+export function conciergeInbound(deps: ConciergeInboundDeps): InboundPolicy {
+  const current = async (userID: string) => {
+    try {
+      return await deps.identity.current(userID)
+    } catch (cause) {
+      // (FX-07) A timed-out read is `busy` (503, refused); any other failure an internal error (refused too).
+      if (cause instanceof AgentError) throw cause
+      throw new AgentError("internal", `Could not check the Concierge inbound rule: ${(cause as Error).message}`.slice(0, 200))
+    }
+  }
+  return {
+    async outbound(userID, from, kind, original) {
+      if (from.kind !== "session") return
+      if (!isConcierge(await current(userID), from.sessionID) || outboundAdmitted(kind, original)) return
+      await deps.audit
+        ?.record(userID, { actor: from, verb: "msg", target: {}, decision: "forbidden", reason: "concierge outbound rule", outcome: "refused" })
+        .catch((cause) => console.error(`[hub] concierge outbound audit failed: ${(cause as Error).message}`))
+      throw new AgentError("forbidden", "The Concierge messages only you (@me); it acts on sessions only through its grant", { extra: { policy: "concierge" } })
+    },
+    async admit(userID, from, sessionID, kind, original) {
+      if (from.kind === "user") return
+      const now = await current(userID)
+      if (!isConcierge(now, sessionID) || admitted(from, sessionID, kind, original)) return
+      await deps.audit
+        ?.record(userID, { actor: from, verb: "msg", target: { sessionID }, decision: "forbidden", reason: "concierge inbound rule", outcome: "refused" })
+        .catch((cause) => console.error(`[hub] concierge inbound audit failed: ${(cause as Error).message}`))
+      throw new AgentError("forbidden", CONCIERGE_INBOUND_MESSAGE, { extra: { policy: "concierge" } })
+    },
+  }
+}
+
+/** The outbound rule's verdict: the Concierge messages only @me (not via Delivery.sendTo) and answers asks to it. */
+export function outboundAdmitted(kind: InboundKind, original?: Message): boolean {
+  return (kind === "reply" || kind === "decline") && original?.kind === "ask"
+}
+
+/** The acting guard: true for the user's current and previous Concierge sessions (only the user acts on them). */
+export function conciergeProtects(identity: ConciergeIdentity): (userID: string, sessionID: string) => Promise<boolean> {
+  return async (userID, sessionID) => isConcierge(await identity.current(userID), sessionID)
+}

package/src/central/concierge/index.ts

@@ -0,0 +1,84 @@
+// CON-04 the Concierge's module slots (contract "Parallel safety of CON-05/06/07"). The service wires these ports;
+// CON-05 (notifier.ts) and CON-06 (tiers.ts) each fill one slot line in CONCIERGE_SLOTS and touch nothing else here.
+// Every slot defaults to a no-op, so the hub runs the same without them.
+import type { ConciergeSettings, ConciergeStatus } from "../../../packages/protocol/src/concierge"
+import type { UserActor } from "../agent/actor"
+import type { ActOutcome, Decision } from "../agent/decisions"
+import type { AgentEvent } from "../agent/events"
+import type { AgentRoute } from "../agent/routes"
+import type { ConciergeEntitlements } from "./entitlements"
+import { ConciergeNotifierImpl, type NotifierJournal } from "./notifier"
+import { conciergeTiers, type TierPorts } from "./tiers"
+import type { ConciergeIdentity } from "./watchlist-routes"
+
+/** What the Concierge modules get from the hub. */
+export interface ConciergePorts {
+  /** The user's current Concierge session and every hidden one (the Concierge-only authority). */
+  readonly identity: ConciergeIdentity
+  readonly status: (userID: string) => Promise<ConciergeStatus>
+  readonly settings: (userID: string) => Promise<ConciergeSettings>
+  /** Pushes the board context to the current session, awaited at most 2 s (before a wake). False: not there. */
+  readonly beforeWake: (userID: string) => Promise<boolean>
+  /**
+   * Sends a message to the user's current Concierge session as app:concierge (Delivery.send; the inbound rule admits
+   * it). Throws not_found when there is no current session.
+   */
+  readonly send: (userID: string, text: string, options: { readonly wake: boolean; readonly urgent?: boolean }) => Promise<{ readonly messageID: string; readonly woke?: boolean }>
+  readonly entitlements: ConciergeEntitlements
+  /** Every user of the hub (leader loops). */
+  readonly users: () => Promise<Iterable<string>>
+  /** (CON-05) The notifier's journal, ledger store, watchlist view, board revision and leadership; absent: inert. */
+  readonly journal?: NotifierJournal
+  /** (CON-06) What the tiers slot needs from the hub (Decisions, acting, presence, devices, SSE). */
+  readonly tiers?: TierPorts
+}
+
+/** CON-05: event-driven turns, digests, quiet hours (runs on the `concierge` leader). */
+export interface ConciergeNotifier {
+  /** The concierge leader was elected (start) or deposed (stop). */
+  start(): void
+  stop(): void
+  /** Every journal append of the user, on the appending pod. Must never throw (never awaited). */
+  observe(userID: string, event: AgentEvent): void
+  /** The Concierge was disabled: forget the user's ledger. Must never reject. */
+  disabled(userID: string): Promise<void>
+}
+
+/** CON-06: approval tiers, proposals and arming (its Concierge-only routes). */
+export interface ConciergeTiers {
+  routes(): AgentRoute[]
+  /** Runs a proposal Decision's `act` action when the user answers (absent: it cannot run on this hub). */
+  act?(userID: string, decision: Decision, choice: { readonly option?: string }, by: UserActor): Promise<ActOutcome>
+  /** Admits a voice/text answer (throws forbidden "Answer this decision with a tap"); absent: never admitted. */
+  checkVia?(userID: string, decision: Decision, via: "voice" | "text", by: UserActor): Promise<void>
+  /** A Decision changed (Decisions' changed listener): an answered/closed one is disarmed. Never throws. */
+  decisionChanged?(userID: string, decision: Decision): void
+  /** The Decision armed now by the current Concierge session, if any (the board's `armed` flag). */
+  armedID?(userID: string): Promise<string | undefined>
+  /** The hub is stopping: drop timers. */
+  stop?(): void
+}
+
+export const NO_NOTIFIER: ConciergeNotifier = { start: () => undefined, stop: () => undefined, observe: () => undefined, disabled: async () => undefined }
+export const NO_TIERS: ConciergeTiers = { routes: () => [] }
+
+export interface ConciergeSlots {
+  readonly notifier?: (ports: ConciergePorts) => ConciergeNotifier
+  readonly tiers?: (ports: ConciergePorts) => ConciergeTiers
+}
+
+/** The filled slots (one line each). */
+export const CONCIERGE_SLOTS: ConciergeSlots = {
+  notifier: (ports) => new ConciergeNotifierImpl(ports), // CON-05
+  tiers: (ports) => conciergeTiers(ports), // CON-06
+}
+
+export interface ConciergeModules {
+  readonly notifier: ConciergeNotifier
+  readonly tiers: ConciergeTiers
+}
+
+/** The modules for these ports: each slot's own, else its no-op. */
+export function conciergeModules(ports: ConciergePorts, slots: ConciergeSlots = CONCIERGE_SLOTS): ConciergeModules {
+  return { notifier: slots.notifier?.(ports) ?? NO_NOTIFIER, tiers: slots.tiers?.(ports) ?? NO_TIERS }
+}

package/src/central/concierge/notes.ts

@@ -0,0 +1,41 @@
+// CON-04 Concierge notes: the Concierge's own memory across relaunches (contract "GET/PUT /concierge/notes"). One
+// record per user (collection `concierge`, key `notes`): {text ≤ 32 KiB UTF-8, revision, updatedAt}. Control
+// characters other than newline and tab are dropped. Writes are version-checked (expectedRevision; a stale one is
+// 409 conflict {currentRevision}). The text never reaches the journal, the board or the admin audit.
+import { CONCIERGE_LIMITS } from "../../../packages/protocol/src/concierge"
+import type { Clock, StateStore } from "../backend/types"
+import { AgentError } from "../agent/errors"
+
+export const CONCIERGE_COLLECTION = "concierge"
+const KEY = "notes"
+/** C0 controls except tab and newline, DEL and C1 controls. */
+const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g
+
+export interface ConciergeNotes {
+  readonly text: string
+  readonly revision: number
+  readonly updatedAt?: number
+}
+
+export class NotesStore {
+  constructor(
+    private readonly state: StateStore,
+    private readonly now: Clock = Date.now,
+  ) {}
+
+  async get(userID: string): Promise<ConciergeNotes> {
+    return (await this.state.get<ConciergeNotes>(userID, CONCIERGE_COLLECTION, KEY))?.value ?? { text: "", revision: 0 }
+  }
+
+  async put(userID: string, raw: string, expectedRevision: number): Promise<ConciergeNotes> {
+    const text = raw.replace(CONTROL, "")
+    if (Buffer.byteLength(text, "utf8") > CONCIERGE_LIMITS.notesBytes) throw new AgentError("invalid", `Notes are at most ${CONCIERGE_LIMITS.notesBytes} bytes`)
+    const stored = await this.state.get<ConciergeNotes>(userID, CONCIERGE_COLLECTION, KEY)
+    const current = stored?.value ?? { text: "", revision: 0 }
+    if (current.revision !== expectedRevision) throw new AgentError("conflict", "The notes changed meanwhile", { extra: { currentRevision: current.revision } })
+    const next: ConciergeNotes = { text, revision: current.revision + 1, updatedAt: this.now() }
+    const put = await this.state.put(userID, CONCIERGE_COLLECTION, KEY, next, { ifVersion: stored?.version ?? 0 })
+    if (!put.ok) throw new AgentError("conflict", "The notes changed meanwhile", { extra: { currentRevision: (await this.get(userID)).revision } })
+    return next
+  }
+}