@huynle/hub 0.7.4 → 0.8.0

package/src/central/concierge/tiers.ts

@@ -0,0 +1,260 @@
+// CON-06 approval tiers (contract "Approval tiers (CON-06)"): the tiers slot of the Concierge modules (index.ts).
+//
+// | Tier    | When                                                        | How                                       |
+// | auto    | inside the @@concierge grant (the acting engine allows)     | it acts; audit as: "concierge" (audit.ts) |
+// | confirm | escalations whose riskTier is confirm; stop/deny proposals  | tap, or voice/text in the Concierge panel |
+// | tap     | riskTier tap; prompt/answer proposals                        | console cookie only, never voice          |
+//
+// Routes (Concierge-only authority: the user's CURRENT Concierge session through its act token; every other agent
+// credential, app tokens included, is 404; the user is 403 where the route is the Concierge's own):
+//
+//   POST /api/agent/concierge/proposals {verb, session, input?, why?, requestID?|formID?} → 201 {decision} (proposals.ts)
+//   POST /api/agent/concierge/arm {decisionID | null}  the Concierge → {armed | null}
+//   GET  /api/agent/concierge/arm                      user; the Concierge → {armed | null}
+//   GET  /api/agent/concierge/sessions/:addr/forms/:form  user; the Concierge → {form: PendingForm} (CON-13)
+//
+// (CON-13) The form read is a pending form's SCHEMA only (title, field keys, types, option values and labels,
+// required, limits; acting.ts form()): never the session's other text. It is checked like the answer verb short of
+// the grant (kill switch, tenancy, the Concierge guard, pending, self-tree), so the Concierge can answer or propose
+// an answer that fits; an answer that does not is 400 with the field's problem (form-check.ts).
+//
+// Arming marks one OPEN CONFIRM Decision of the user as the one under discussion (one per user, replaced by the
+// next, ARM_TTL_MS; tap → 400 invalid; not open → 410 gone; unknown → 404). It is durable (arm.ts) and goes to the
+// console as SSE {type: "concierge", armed}. An answered/closed/expired Decision is disarmed (decisionChanged). When
+// an arm lapses (ARM_TTL_MS) the pod that armed it says so: SSE {type: "concierge", armed: null} (lapse watch below).
+// The board marks the live armed Decision (`armedID`, ConciergeBoardDecision.armed).
+//
+// via (checkVia, Decisions' via hook): a voice/text answer is admitted only when the Decision is confirm tier, open
+// and armed by the CURRENT Concierge session, and the answering device is the user's and has presence on that
+// session (within PRESENCE_WINDOW_MS; the registry's presence, set by POST /api/sessions/:id/presence). Anything
+// else (and a failed read) → 403 "Answer this decision with a tap". The model never answers: the route is the
+// console's (devices only), and matching speech to an option happens on the device.
+import type { ConciergeArmed } from "../../../packages/protocol/src/concierge"
+import type { Counters, StateStore } from "../backend/types"
+import type { Acting } from "../agent/acting"
+import { type AgentActor, canActAsSession, type UserActor } from "../agent/actor"
+import type { AgentAudit } from "../agent/audit"
+import { boundedJson } from "../agent/body"
+import { type ActOutcome, type Decision, type Decisions, TAP_ONLY } from "../agent/decisions"
+import type { Party } from "../agent/envelope"
+import { AgentError } from "../agent/errors"
+import { RouteIdempotency } from "../agent/idempotency"
+import type { Message } from "../agent/messages"
+import type { AgentRoute } from "../agent/routes"
+import { ArmStore, type ArmedDecision } from "./arm"
+import type { ConciergePorts, ConciergeTiers } from "./index"
+import { parseProposal, Proposals } from "./proposals"
+
+const PATH = "/api/agent/concierge"
+const NO_STORE = { "cache-control": "no-store" }
+const IDEMPOTENCY_COLLECTION = "concierge-proposal-keys"
+/** How often a live arm's lapse watch looks at the clock (it reads the store only once the arm is due). */
+const LAPSE_POLL_MS = 1_000
+
+/** What the tiers need from the hub besides the Concierge ports (http.ts fills it). */
+export interface TierPorts {
+  readonly state: StateStore
+  readonly counters: Pick<Counters, "incr" | "get">
+  readonly decisions: Pick<Decisions, "ask" | "list" | "get">
+  readonly acting: Pick<Acting, "preflight" | "stop" | "deny" | "prompt" | "answer" | "form">
+  readonly audit?: Pick<AgentAudit, "record">
+  readonly protects?: (userID: string, sessionID: string) => Promise<boolean>
+  readonly published?: (userID: string, message: Message) => void
+  readonly describe?: (userID: string, actor: AgentActor) => Party
+  /** Whether the device reported the session visible within the presence window (any pod). */
+  readonly present: (deviceID: string, sessionID: string) => boolean
+  /** The device's owner (undefined: no such device). */
+  readonly deviceOwner: (deviceID: string) => string | undefined
+  /** The console's live event {type: "concierge", armed}. Never throws through. */
+  readonly armed: (userID: string, armed: ArmedView | null) => void
+  readonly now?: () => number
+}
+
+/** What clients see of the armed Decision. */
+export type ArmedView = ConciergeArmed
+
+const view = (armed: ArmedDecision | undefined): ArmedView | null => (armed ? { decisionID: armed.decisionID, at: armed.at, expiresAt: armed.expiresAt } : null)
+const notFound = () => new AgentError("not_found", "Not found")
+const tapOnly = () => new AgentError("forbidden", TAP_ONLY, { hint: "Tap an option" })
+
+/** The tiers module for the Concierge ports; without `ports.tiers` it is the no-op (no routes). */
+export function conciergeTiers(ports: ConciergePorts): ConciergeTiers {
+  const hub = ports.tiers
+  if (!hub) return { routes: () => [] }
+  const { identity } = ports
+  const arms = new ArmStore({ state: hub.state, ...(hub.now ? { now: hub.now } : {}) })
+  const proposals = new Proposals({
+    decisions: hub.decisions,
+    acting: hub.acting,
+    counters: hub.counters,
+    ...(hub.audit ? { audit: hub.audit } : {}),
+    ...(hub.protects ? { protects: hub.protects } : {}),
+    ...(hub.published ? { published: hub.published } : {}),
+    ...(hub.describe ? { describe: hub.describe } : {}),
+  })
+  const idempotency = new RouteIdempotency({ state: hub.state, collection: IDEMPOTENCY_COLLECTION, ...(hub.now ? { now: hub.now } : {}) })
+  const tell = (userID: string, armed: ArmedView | null) => {
+    try {
+      hub.armed(userID, armed)
+    } catch (cause) {
+      console.error(`[hub] concierge armed event failed: ${(cause as Error).message}`)
+    }
+  }
+  const clock = hub.now ?? Date.now
+
+  // Lapse watch: one timer per user for the arm this pod made. It checks the clock every LAPSE_POLL_MS and, once the
+  // arm is due, reads the record: replaced by a newer arm (another pod's, or this pod's own watch) → nothing; still
+  // live (clock skew) → keep watching; gone or expired → SSE armed: null (harmless if a disarm already said so).
+  const lapses = new Map<string, ReturnType<typeof setTimeout>>()
+  const unwatch = (userID: string) => {
+    const timer = lapses.get(userID)
+    if (timer !== undefined) clearTimeout(timer)
+    lapses.delete(userID)
+  }
+  const watchLapse = (userID: string, armed: ArmedDecision) => {
+    unwatch(userID)
+    const schedule = () => {
+      const timer = setTimeout(check, Math.min(LAPSE_POLL_MS, Math.max(0, armed.expiresAt - clock()) + 5))
+      ;(timer as { unref?: () => void }).unref?.()
+      lapses.set(userID, timer)
+    }
+    const check = () => {
+      if (clock() < armed.expiresAt) return schedule()
+      lapses.delete(userID)
+      void arms
+        .current(userID)
+        .then((current) => {
+          if (current && (current.at !== armed.at || current.decisionID !== armed.decisionID)) return
+          if (current) {
+            if (!lapses.has(userID)) schedule()
+            return
+          }
+          tell(userID, null)
+        })
+        .catch((cause: unknown) => console.error(`[hub] concierge arm lapse check failed: ${(cause as Error).message}`))
+    }
+    schedule()
+  }
+
+  /** The user's current Concierge session through its act token; else 404 (the user: 403 when `userForbidden`). */
+  const conciergeOnly = async (actor: AgentActor, userID: string, userForbidden?: string): Promise<string> => {
+    if (actor.kind === "user") {
+      if (userForbidden) throw new AgentError("forbidden", userForbidden)
+      return ""
+    }
+    if (actor.kind === "session" && canActAsSession(actor) && actor.userID === userID) {
+      const { sessionID } = await identity.current(userID)
+      if (sessionID !== undefined && sessionID === actor.sessionID) return sessionID
+    }
+    throw notFound()
+  }
+
+  /** The armed Decision as of now: open, and armed by the current Concierge session. */
+  const live = async (userID: string): Promise<ArmedDecision | undefined> => {
+    const armed = await arms.current(userID)
+    if (!armed) return undefined
+    const [{ sessionID }, decision] = await Promise.all([identity.current(userID), hub.decisions.get(userID, armed.decisionID)])
+    return sessionID === armed.sessionID && decision?.state === "open" && decision.tier === "confirm" ? armed : undefined
+  }
+
+  const routes: AgentRoute[] = [
+    {
+      method: "POST",
+      path: `${PATH}/proposals`,
+      allow: { session: true, app: true },
+      handle: async ({ actor, request, user }) => {
+        const sessionID = await conciergeOnly(actor, user.id, "The Concierge proposes; act on the session yourself")
+        const body = await boundedJson(request)
+        // Keys are per Concierge session: a relaunched Concierge never gets an earlier session's result.
+        return idempotency.run(user.id, `POST /concierge/proposals ${sessionID}`, request.headers.get("idempotency-key"), body, async () => {
+          const decision = await proposals.propose(user.id, actor, parseProposal(body))
+          return { status: 201, body: { decision } }
+        })
+      },
+    },
+    {
+      method: "GET",
+      path: `${PATH}/sessions/:addr/forms/:form`,
+      allow: { session: true, app: true },
+      handle: async ({ actor, params, user }) => {
+        await conciergeOnly(actor, user.id)
+        return Response.json({ form: await hub.acting.form({ actor, userID: user.id }, params.addr!, params.form!) }, { headers: NO_STORE })
+      },
+    },
+    {
+      method: "GET",
+      path: `${PATH}/arm`,
+      allow: { session: true, app: true },
+      handle: async ({ actor, user }) => {
+        await conciergeOnly(actor, user.id)
+        return Response.json({ armed: view(await live(user.id)) }, { headers: NO_STORE })
+      },
+    },
+    {
+      method: "POST",
+      path: `${PATH}/arm`,
+      allow: { session: true, app: true },
+      handle: async ({ actor, request, user }) => {
+        const sessionID = await conciergeOnly(actor, user.id, "Only the Concierge arms a Decision")
+        const body = await boundedJson(request)
+        if (typeof body !== "object" || body === null || Array.isArray(body)) throw new AgentError("invalid", "Body must be a JSON object")
+        const fields = body as Record<string, unknown>
+        for (const key of Object.keys(fields)) if (key !== "decisionID") throw new AgentError("invalid", `Unknown field ${key}`)
+        const id = fields.decisionID
+        if (id === null) {
+          unwatch(user.id)
+          if (await arms.disarm(user.id)) tell(user.id, null)
+          return Response.json({ armed: null }, { headers: NO_STORE })
+        }
+        if (typeof id !== "string" || !id || id.length > 64) throw new AgentError("invalid", "decisionID is a Decision ID (or null to disarm)")
+        const decision = await hub.decisions.get(user.id, id)
+        if (!decision) throw new AgentError("not_found", "No such decision")
+        if (decision.state !== "open") throw new AgentError("gone", "The decision is already answered or expired")
+        if (decision.tier !== "confirm") throw new AgentError("invalid", "A tap-tier decision is answered with a tap in the console: it cannot be armed")
+        const record = await arms.arm(user.id, { decisionID: id, sessionID })
+        watchLapse(user.id, record)
+        const armed = view(record)
+        tell(user.id, armed)
+        return Response.json({ armed }, { headers: NO_STORE })
+      },
+    },
+  ]
+
+  return {
+    routes: () => routes,
+    act: (userID: string, decision: Decision, choice: { readonly option?: string }, by: UserActor): Promise<ActOutcome> => proposals.act(userID, decision, choice, by),
+    checkVia: async (userID: string, decision: Decision, _via: "voice" | "text", by: UserActor): Promise<void> => {
+      let ok = false
+      try {
+        const { sessionID } = await identity.current(userID)
+        const armed = await arms.current(userID)
+        ok =
+          sessionID !== undefined &&
+          armed !== undefined &&
+          armed.decisionID === decision.id &&
+          armed.sessionID === sessionID &&
+          decision.state === "open" &&
+          decision.tier === "confirm" &&
+          by.userID === userID &&
+          hub.deviceOwner(by.deviceID) === userID &&
+          hub.present(by.deviceID, sessionID)
+      } catch (cause) {
+        console.error(`[hub] concierge via check failed: ${(cause as Error).message}`)
+        ok = false
+      }
+      if (!ok) throw tapOnly()
+    },
+    decisionChanged: (userID: string, decision: Decision): void => {
+      if (decision.state === "open") return
+      void arms
+        .disarm(userID, decision.id)
+        .then((ended) => (ended ? (unwatch(userID), tell(userID, null)) : undefined))
+        .catch((cause: unknown) => console.error(`[hub] concierge disarm failed: ${(cause as Error).message}`))
+    },
+    armedID: async (userID: string) => (await live(userID))?.decisionID,
+    stop: () => {
+      for (const timer of lapses.values()) clearTimeout(timer)
+      lapses.clear()
+    },
+  }
+}

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

@@ -0,0 +1,277 @@
+// CON-01 watchlist routes on /api/agent (contract: docs/plans/2026-11-01-concierge-contracts.md, "Watchlist
+// (CON-01)"), the per-user config record and the facts the resolution reads:
+//
+//   GET  /api/agent/concierge/watchlist                       user; app sessions:read; the Concierge → {config, entries, truncated}
+//   PUT  /api/agent/concierge/watchlist {…fields, expectedRevision}   user; app sessions:manage → {config}
+//   POST /api/agent/concierge/watchlist/{watch,unwatch,mute,unmute} {session: <addr>}
+//                                                             user; app sessions:manage; the Concierge → {config, sessionID, changed}
+//
+// The Concierge is admitted only as the user's CURRENT Concierge session through its act token (canActAsSession and
+// ConciergeIdentity.current, CON-04's state record; checked on every call, so a relaunch revokes the old session at
+// once). Every other session credential gets 404 on the routes it is admitted to (the route does not reveal itself)
+// and 403 on PUT (framework route class). The verbs change only `sessions` and `muted` and grant nothing.
+//
+// Storage: StateStore collection `concierge-watchlist`, key `config`, per user (the tenant key). A change bumps
+// `revision` (a no-op does not: verbs are idempotent), appends `concierge.changed {what: "watchlist", revision}`
+// (family manage, no subject, never config contents) and adds an admin audit `{actor: owner, action:
+// "concierge.watchlist"}`. Addresses resolve for the caller's user only: another user's session is 404 like an
+// unknown one. Facts come from the hub's own directory, catalog, Decisions, launch labels and the activity tracker;
+// no spoke is called.
+import type { WatchlistConfig, WatchlistView } from "../../../packages/protocol/src/concierge"
+import { WATCHLIST_LIMITS } from "../../../packages/protocol/src/concierge"
+import { isHubSessionID } from "../../../packages/protocol/src/harness-events"
+import { type AgentActor, canActAsSession } from "../agent/actor"
+import { boundedJson } from "../agent/body"
+import type { Decisions } from "../agent/decisions"
+import type { Directory } from "../agent/directory"
+import { AgentError } from "../agent/errors"
+import type { AgentEvents, EventInput } from "../agent/events"
+import type { ReadRegistry } from "../agent/read-routes"
+import type { AgentContext, AgentRoute } from "../agent/routes"
+import type { Clock, StateStore } from "../backend/types"
+import type { CatalogMachine } from "../registry"
+import type { Store } from "../store"
+import type { ActivityTracker } from "./activity"
+import { defaultWatchlist, parseWatchlistUpdate, resolveWatchlist, type WatchFact, type WatchFacts } from "./watchlist"
+
+export const WATCHLIST_COLLECTION = "concierge-watchlist"
+const KEY = "config"
+/** Literal, not from AGENT_PREFIX: routes.ts imports this module (a module-level read would hit the import cycle). */
+const PATH = "/api/agent/concierge/watchlist"
+const NO_STORE = { "cache-control": "no-store" }
+/** Version-checked retries of a contended write: full-jitter backoff from backoffBaseMs, doubling, capped at backoffMaxMs. */
+export const WATCHLIST_STORE_LIMITS = { attempts: 16, backoffBaseMs: 4, backoffMaxMs: 100 } as const
+
+const backoff = (attempt: number) => {
+  const cap = Math.min(WATCHLIST_STORE_LIMITS.backoffMaxMs, WATCHLIST_STORE_LIMITS.backoffBaseMs * 2 ** attempt)
+  return new Promise<void>((resolve) => setTimeout(resolve, Math.random() * cap))
+}
+
+/** The user's Concierge sessions (CON-04's state record); absent until CON-04 lands: no Concierge. */
+export interface ConciergeIdentity {
+  current(userID: string): Promise<{ readonly sessionID?: string; readonly hiddenSessionIDs: readonly string[] }>
+}
+
+export const NO_CONCIERGE: ConciergeIdentity = { current: async () => ({ hiddenSessionIDs: [] }) }
+
+export interface WatchlistRouteDeps {
+  readonly state: StateStore
+  readonly activity: Pick<ActivityTracker, "list">
+  readonly directory: Pick<Directory, "resolveOne" | "entries">
+  readonly store: Pick<Store, "agentData" | "viewPrefs" | "audit">
+  readonly registry: Pick<ReadRegistry, "catalog" | "sessionTenant">
+  readonly decisions?: Pick<Decisions, "list">
+  /** Launched sessions' labels (the latest launch wins). */
+  readonly labels?: (userID: string) => Promise<ReadonlyMap<string, Readonly<Record<string, string>>>>
+  readonly identity?: ConciergeIdentity
+  readonly events?: Pick<AgentEvents, "append">
+  readonly now?: Clock
+}
+
+// ---- Config record ---------------------------------------------------------------------------------------
+
+const sameConfig = (a: WatchlistConfig, b: WatchlistConfig) => JSON.stringify({ ...a, revision: 0 }) === JSON.stringify({ ...b, revision: 0 })
+
+/** The user's watchlist config record: version-checked writes, revision bumped only by a real change. */
+export class WatchlistStore {
+  constructor(private readonly state: StateStore) {}
+
+  async get(userID: string): Promise<WatchlistConfig> {
+    return (await this.state.get<WatchlistConfig>(userID, WATCHLIST_COLLECTION, KEY))?.value ?? defaultWatchlist()
+  }
+
+  /**
+   * Applies `change` to the current config (re-read on every attempt; a lost race backs off with jitter, at most
+   * WATCHLIST_STORE_LIMITS.attempts tries) and stores the result (`change` may throw an AgentError, e.g. a stale revision)
+   * with the next revision when it differs. Resolves with the stored config and whether it changed.
+   */
+  async update(userID: string, change: (current: WatchlistConfig) => WatchlistConfig): Promise<{ config: WatchlistConfig; changed: boolean }> {
+    for (let attempt = 0; attempt < WATCHLIST_STORE_LIMITS.attempts; attempt++) {
+      if (attempt > 0) await backoff(attempt - 1)
+      const stored = await this.state.get<WatchlistConfig>(userID, WATCHLIST_COLLECTION, KEY)
+      const current = stored?.value ?? defaultWatchlist()
+      const next = change(current)
+      if (sameConfig(current, next)) return { config: current, changed: false }
+      const config = { ...next, revision: current.revision + 1 }
+      const put = await this.state.put(userID, WATCHLIST_COLLECTION, KEY, config, { ifVersion: stored?.version ?? 0 })
+      if (put.ok) return { config, changed: true }
+    }
+    throw new AgentError("conflict", "The watchlist kept changing; retry", { hint: "Retry shortly" })
+  }
+}
+
+// ---- Facts -----------------------------------------------------------------------------------------------
+
+const STATE_RANK: Record<string, number> = { error: 4, blocked: 3, working: 2, idle: 1 }
+const worse = (a: string | undefined, b: string | undefined) => ((STATE_RANK[b ?? ""] ?? 0) > (STATE_RANK[a ?? ""] ?? 0) ? b : a)
+
+/** What watchFacts reads (CON-03's board passes the same, with one catalog and one Decisions list per render). */
+export type WatchFactDeps = Pick<WatchlistRouteDeps, "activity" | "registry" | "decisions" | "labels" | "now"> & { readonly store: Pick<Store, "agentData" | "viewPrefs"> }
+
+/**
+ * The resolution's facts for one user: directory records, this hub's catalog (read here unless the caller already
+ * did), open Decisions, labels, activity.
+ */
+export async function watchFacts(deps: WatchFactDeps, userID: string, hidden: readonly string[], catalog: readonly CatalogMachine[] = deps.registry.catalog()): Promise<WatchFacts> {
+  const facts = new Map<string, { -readonly [K in keyof WatchFact]: WatchFact[K] }>()
+  const add = (fact: WatchFact) => {
+    const known = facts.get(fact.sessionID)
+    if (!known) return void facts.set(fact.sessionID, { ...fact })
+    known.state = worse(known.state, fact.state)
+    known.blockers = Math.max(known.blockers, fact.blockers)
+    known.directory ??= fact.directory
+    known.project ??= fact.project
+    known.herdrWorkspace ??= fact.herdrWorkspace
+    if (fact.archived) known.archived = true
+  }
+  for (const machine of catalog) {
+    for (const process of machine.processes) {
+      for (const s of process.sessions) {
+        if (deps.registry.sessionTenant(s.id) !== userID) continue
+        const herdr = s.open && s.terminal?.source === "herdr" && s.terminal.workspaceID ? { herdrWorkspace: s.terminal.workspaceID } : {}
+        const where = { ...(s.directory ? { directory: s.directory } : {}), ...(s.project ? { project: s.project } : {}) }
+        add({ sessionID: s.id, ...(s.parentID ? { parentID: s.parentID } : {}), state: s.state, blockers: s.blockers.length, ...where, ...herdr, ...(s.archived ? { archived: true } : {}) })
+        for (const child of s.status) {
+          if (child.id === s.id) continue
+          add({ sessionID: child.id, parentID: child.parentID ?? s.id, state: child.state, blockers: child.blockers.length, ...where })
+        }
+      }
+    }
+  }
+  const prefs = deps.store.viewPrefs(userID)
+  const archived = new Set(prefs.hiddenSessions)
+  // (CON-12) Machines that report their sessions now: a session one of them no longer reports went away.
+  const reporting = new Set(catalog.filter((m) => m.processes.length > 0).map((m) => m.id))
+  for (const record of deps.store.agentData(userID).sessions ?? []) {
+    const known = facts.get(record.sessionID)
+    if (!known) {
+      const gone = record.machineID !== undefined && reporting.has(record.machineID)
+      add({ sessionID: record.sessionID, ...(record.parentID ? { parentID: record.parentID } : {}), state: "offline", blockers: 0, ...(gone ? { gone: true } : {}) })
+    }
+    const fact = facts.get(record.sessionID)!
+    if (typeof record.project === "string" && record.project) fact.projectSlug = record.project
+    if (record.archivedAt !== undefined) fact.archived = true
+    if (record.deletedAt !== undefined) fact.deleted = true
+  }
+  for (const fact of facts.values()) if (archived.has(fact.sessionID)) fact.archived = true
+
+  const [activity, labels, open] = await Promise.all([deps.activity.list(userID), deps.labels ? deps.labels(userID) : new Map(), deps.decisions ? deps.decisions.list(userID, { state: "open" }) : []])
+  for (const [sessionID, at] of activity) {
+    const fact = facts.get(sessionID)
+    if (fact) fact.lastActiveAt = at
+  }
+  for (const [sessionID, set] of labels) {
+    const fact = facts.get(sessionID)
+    if (fact) fact.labels = set
+  }
+  const decisions = new Set<string>()
+  for (const d of open) {
+    for (const id of d.about) decisions.add(id)
+    if (d.from.kind === "session") decisions.add(d.from.sessionID)
+  }
+  return { sessions: [...facts.values()], pins: { sessions: prefs.pinnedSessions, workspaces: prefs.pinnedWorkspaces }, decisions: [...decisions], hidden, now: (deps.now ?? Date.now)() }
+}
+
+// ---- Routes ----------------------------------------------------------------------------------------------
+
+type ListName = "sessions" | "muted"
+const VERBS: readonly { readonly verb: string; readonly list: ListName; readonly add: boolean }[] = [
+  { verb: "watch", list: "sessions", add: true },
+  { verb: "unwatch", list: "sessions", add: false },
+  { verb: "mute", list: "muted", add: true },
+  { verb: "unmute", list: "muted", add: false },
+]
+const CAP: Record<ListName, number> = { sessions: WATCHLIST_LIMITS.sessions, muted: WATCHLIST_LIMITS.muted }
+
+const notFound = () => new AgentError("not_found", "Not found")
+
+export function watchlistRoutes(deps: WatchlistRouteDeps): AgentRoute[] {
+  const records = new WatchlistStore(deps.state)
+  const identity = deps.identity ?? NO_CONCIERGE
+
+  /** Session callers: only the user's current Concierge, through its act token; anyone else is 404. */
+  const admit = async (actor: AgentActor, userID: string) => {
+    const current = await identity.current(userID)
+    if (actor.kind === "session" && !(canActAsSession(actor) && current.sessionID !== undefined && current.sessionID === actor.sessionID)) throw notFound()
+    return current
+  }
+
+  const changed = async (userID: string, config: WatchlistConfig) => {
+    const event: EventInput = { type: "concierge.changed", family: "manage", subject: {}, data: { what: "watchlist", revision: config.revision } }
+    await deps.events?.append(userID, event).catch((cause) => console.error(`[hub] concierge watchlist event: ${(cause as Error).message}`))
+    await deps.store.audit({ actor: userID, action: "concierge.watchlist" })
+  }
+
+  /** The root of a resolved session (subagents roll up into their root). */
+  const rootOf = (userID: string, sessionID: string, parentID: string | undefined): string => {
+    const seen = new Set([sessionID])
+    let id = sessionID
+    let parent = parentID
+    while (parent !== undefined && !seen.has(parent)) {
+      const entry = deps.directory.entries(userID, [parent]).get(parent)
+      if (!entry) break
+      seen.add(parent)
+      id = entry.sessionID
+      parent = entry.parentID
+    }
+    return id
+  }
+
+  const verbRoute = ({ verb, list, add }: (typeof VERBS)[number]): AgentRoute => ({
+    method: "POST",
+    path: `${PATH}/${verb}`,
+    allow: { session: true, scope: "sessions:manage" },
+    async handle({ request, actor, user }: AgentContext) {
+      await admit(actor, user.id)
+      const body = await boundedJson(request)
+      if (typeof body !== "object" || body === null || Array.isArray(body)) throw new AgentError("invalid", "The body is {session: <addr>}")
+      const extra = Object.keys(body).find((k) => k !== "session")
+      if (extra !== undefined) throw new AgentError("invalid", `Unknown field ${extra.slice(0, 40)}`)
+      const addr = (body as { session?: unknown }).session
+      if (typeof addr !== "string" || !addr.trim()) throw new AgentError("invalid", "session (an address: ses_…, @name, @@role) is required")
+      let sessionID: string
+      // A listed ID can be removed even when its session is gone from the directory.
+      if (!add && isHubSessionID(addr) && (await records.get(user.id))[list].includes(addr)) sessionID = addr
+      else {
+        const entry = deps.directory.resolveOne(user.id, addr)
+        sessionID = rootOf(user.id, entry.sessionID, entry.parentID)
+      }
+      const result = await records.update(user.id, (current) => {
+        const has = current[list].includes(sessionID)
+        if (add === has) return current
+        if (add && current[list].length >= CAP[list]) throw new AgentError("rate_limited", `The watchlist's ${list} list has at most ${CAP[list]} sessions`, { extra: { limit: CAP[list] } })
+        return { ...current, [list]: add ? [...current[list], sessionID] : current[list].filter((id) => id !== sessionID) }
+      })
+      if (result.changed) await changed(user.id, result.config)
+      return Response.json({ config: result.config, sessionID, changed: result.changed }, { headers: NO_STORE })
+    },
+  })
+
+  return [
+    {
+      method: "GET",
+      path: PATH,
+      allow: { session: true, scope: "sessions:read" },
+      async handle({ actor, user }) {
+        const current = await admit(actor, user.id)
+        const config = await records.get(user.id)
+        const facts = await watchFacts(deps, user.id, current.hiddenSessionIDs)
+        const { entries, truncated } = resolveWatchlist(config, facts)
+        const view: WatchlistView = { config, entries, truncated }
+        return Response.json(view, { headers: NO_STORE })
+      },
+    },
+    {
+      method: "PUT",
+      path: PATH,
+      allow: { scope: "sessions:manage" },
+      async handle({ request, user }) {
+        const body = await boundedJson(request)
+        const result = await records.update(user.id, (current) => parseWatchlistUpdate(body, current))
+        if (result.changed) await changed(user.id, result.config)
+        return Response.json({ config: result.config }, { headers: NO_STORE })
+      },
+    },
+    ...VERBS.map(verbRoute),
+  ]
+}