@huynle/hub 0.7.4 → 0.8.0

package/src/central/agent/directory-routes.ts

@@ -3,7 +3,7 @@
 // and every catalog change syncs the affected users (records, lastSeen, derived names).
 //
 // Routes (user actors always; session tokens may read, and write for their OWN session only):
-//   GET  /api/agent/who?project=&role=
+//   GET  /api/agent/who?project=&role=         (entries carry a stored `intent`, CON-02)
 //   POST /api/agent/name           {name, session?}
 //   POST /api/agent/roles/claim    {role, exclusive?, project?, session?}
 //   POST /api/agent/roles/release  {role, project?, session?}
@@ -16,6 +16,7 @@
 // order (kill switch → grant → hourly cap → kill switch), with every outcome in the agent audit (verb roles or
 // roles.release). Reserved roles stay the user's to assign. Each change is in the admin audit and the event
 // journal once (session.named, role.claimed, role.released, session.archived); a no-op is neither.
+import { boundedJson } from "./body"
 import type { ActingSwitch } from "./acting-switch"
 import { auditOf } from "./acting"
 import type { AgentAudit, AuditDecision, AuditOutcome } from "./audit"
@@ -31,6 +32,10 @@ import { ArchiveInactive, parseInactiveFor } from "./archive-inactive"
 import { slugify } from "./names"
 import { AGENT_PREFIX, type AgentContext, type AgentRoute } from "./routes"
 import type { CursorKeys } from "./event-cursor"
+import type { TeamDiscovery } from "../teams/discovery"
+import type { SessionIntent } from "../../protocol"
+import { intentField } from "./intents"
+import { conciergeSelf } from "./read-routes"
 
 /** What the directory reads from the Registry. */
 export interface DirectoryRegistry {
@@ -58,10 +63,11 @@ export function registrySource(registry: Pick<DirectoryRegistry, "catalog" | "se
             if (out.has(s.id) || registry.sessionTenant(s.id) !== userID) continue
             const project = projectOf(s)
             const scope = project ? { project } : {}
-            out.set(s.id, { sessionID: s.id, title: s.title, machineID: s.machineID, ...(s.parentID ? { parentID: s.parentID } : {}), ...scope, state: s.state })
+            const harness = process.harness ? { harness: process.harness } : {}
+            out.set(s.id, { sessionID: s.id, title: s.title, machineID: s.machineID, ...(s.parentID ? { parentID: s.parentID } : {}), ...scope, state: s.state, ...harness })
             for (const child of s.status) {
               if (child.id === s.id || out.has(child.id)) continue
-              out.set(child.id, { sessionID: child.id, title: child.title, machineID: s.machineID, parentID: child.parentID ?? s.id, ...scope, state: child.state })
+              out.set(child.id, { sessionID: child.id, title: child.title, machineID: s.machineID, parentID: child.parentID ?? s.id, ...scope, state: child.state, ...harness })
             }
           }
         }
@@ -104,7 +110,7 @@ export function hubDirectory(options: { registry: DirectoryRegistry; store: Pick
 type Body = Record<string, unknown>
 
 async function readBody(request: Request): Promise<Body> {
-  const body = await request.json()
+  const body = await boundedJson(request)
   if (typeof body !== "object" || body === null || Array.isArray(body)) throw new AgentError("invalid", "Expected a JSON object")
   return body as Body
 }
@@ -152,6 +158,12 @@ export interface DirectoryRoutesDeps {
   readonly acting?: Pick<ActingSwitch, "ensureActing">
   readonly audit?: Pick<AgentAudit, "record">
   readonly previewKeys?: CursorKeys
+  /** Team-aware who (HWA-40); without it, the owner-wide directory. */
+  readonly discovery?: TeamDiscovery
+  /** (CON-02) The stored intents of these sessions: who entries carry `intent` when present. */
+  readonly intents?: (userID: string, sessionIDs: readonly string[]) => Promise<ReadonlyMap<string, SessionIntent>>
+  /** (CON-04) The user's Concierge sessions: who marks them `concierge: true`; archive-inactive never archives them. */
+  readonly concierge?: (userID: string) => Promise<readonly string[]>
 }
 
 const MANAGE = { session: true, scope: "sessions:manage" } as const
@@ -202,7 +214,10 @@ export function directoryRoutes(deps: DirectoryRoutesDeps): AgentRoute[] {
         const inactive = new ArchiveInactive({ secret: deps.previewKeys!.active().secret })
         const body = await readBody(context.request)
         const prefs = store.viewPrefs(context.user.id)
-        const entries = (store.agentData(context.user.id).sessions ?? []).map((s) => ({ sessionID: s.sessionID, online: !!deps.registry?.session(s.sessionID), ...(s.lastSeen !== undefined ? { lastSeen: s.lastSeen } : {}), roles: [] }))
+        const concierge = new Set(deps.concierge ? await deps.concierge(context.user.id) : [])
+        const entries = (store.agentData(context.user.id).sessions ?? [])
+          .filter((s) => !concierge.has(s.sessionID))
+          .map((s) => ({ sessionID: s.sessionID, online: !!deps.registry?.session(s.sessionID), ...(s.lastSeen !== undefined ? { lastSeen: s.lastSeen } : {}), roles: [] }))
         if (body.preview === true) {
           const limit = body.limit
           if (!Number.isInteger(limit) || Number(limit) < 1 || Number(limit) > 200) throw new AgentError("invalid", "limit must be a whole number from 1 to 200")
@@ -261,10 +276,20 @@ export function directoryRoutes(deps: DirectoryRoutesDeps): AgentRoute[] {
       path: `${AGENT_PREFIX}/who`,
       // Reading the directory: sessions, and app tokens holding sessions:read; writes stay users and sessions.
       allow: { session: true, scope: "sessions:read" },
-      handle: ({ url, user }) => {
+      handle: async ({ url, user, actor }) => {
         const project = url.searchParams.get("project") || undefined
         const role = url.searchParams.get("role") || undefined
-        return ok({ sessions: directory.who(user.id, { ...(project ? { project } : {}), ...(role ? { role } : {}) }) })
+        const team = url.searchParams.get("team") || undefined
+        const answer = deps.discovery
+          ? deps.discovery.who(await deps.discovery.census(user.id, actor), { ...(project ? { project } : {}), ...(role ? { role } : {}), ...(team ? { team } : {}) })
+          : { sessions: directory.who(user.id, { ...(project ? { project } : {}), ...(role ? { role } : {}) }) }
+        if (!answer.sessions.length || (!deps.intents && !deps.concierge)) return ok(answer)
+        // (CON-09a) The Concierge's own who leaves out its sessions (current and previous).
+        const self = await conciergeSelf(deps.concierge, user.id, actor)
+        const shown = self.size ? answer.sessions.filter((entry) => !self.has(entry.sessionID)) : answer.sessions
+        const intents = deps.intents ? await deps.intents(user.id, shown.map((entry) => entry.sessionID)) : new Map<string, SessionIntent>()
+        const concierge = new Set(deps.concierge ? await deps.concierge(user.id) : [])
+        return ok({ ...answer, sessions: shown.map((entry) => ({ ...entry, ...intentField(intents.get(entry.sessionID)), ...(concierge.has(entry.sessionID) ? { concierge: true } : {}) })) })
       },
     },
     {
@@ -291,6 +316,11 @@ export function directoryRoutes(deps: DirectoryRoutesDeps): AgentRoute[] {
         const exclusive = flag(body, "exclusive")
         const project = text(body, "project")
         const sessionID = target(directory, context, text(body, "session"))
+        // (CON-04) A Concierge session holds @@concierge only (claimed by the hub): no other role, for anyone, so it
+        // never inherits another role's grants.
+        if (deps.concierge && (await deps.concierge(context.user.id)).includes(sessionID)) {
+          throw new AgentError("forbidden", "The Concierge holds no role but @@concierge", { extra: { policy: "concierge" } })
+        }
         const claim = await roleWrite(context, "roles", sessionID, async () => {
           const before = directory.resolveOne(context.user.id, sessionID).roles
           const claim = await directory.claimRole(context.user.id, sessionID, role, {

package/src/central/agent/directory.ts

@@ -28,7 +28,7 @@
 import { roleKey, type AgentData, type AgentName, type AgentRole, type AgentSession } from "../agent-data"
 import type { Store } from "../store"
 import { AgentError } from "./errors"
-import { deriveName, isPlaceholderTitle, isReservedName, isReservedRole, parseAddress, validName, withSuffix, type Address } from "./names"
+import { addressProblem, deriveName, isManagedRole, isPlaceholderTitle, isReservedName, isReservedRole, MANAGED_ROLE_MESSAGE, parseAddress, validName, withSuffix, type Address } from "./names"
 
 const MINUTE = 60_000
 const HOUR = 60 * MINUTE
@@ -52,6 +52,8 @@ export interface ReportedSession {
   /** Project name, lowercased (the `.project` scope). */
   readonly project?: string
   readonly state?: string
+  /** The harness kind of the process reporting it (kept on the record as the last-known harness). */
+  readonly harness?: string
 }
 
 /** What the directory needs to know about the user's live sessions. */
@@ -97,6 +99,11 @@ export interface DirectoryEntry {
 /** Hears an explicit name change (setName); derived names are never announced. */
 export type NamedListener = (userID: string, sessionID: string, name: string) => void
 
+/** Team-aware discovery (HWA-40): sessions the caller may not see resolve like unknown ones. */
+export interface ResolveOptions {
+  readonly visible?: (sessionID: string) => boolean
+}
+
 export interface Resolved {
   readonly address: Address
   /** One session for an ID or @name; every live holder for a @@role. */
@@ -118,6 +125,9 @@ const ended = (s: AgentSession | undefined): number | undefined => {
   return times.length ? Math.min(...times) : undefined
 }
 
+/** Sessions remembered as unnamed before the directory knew them (Directory.unname). */
+export const UNNAMED_MAX = 500
+
 export class Directory {
   private readonly store: DirectoryStore
   private readonly source: SessionSource
@@ -202,16 +212,39 @@ export class Directory {
     })
   }
 
+  /**
+   * (CON-09a) Sessions that hold no @name (the Concierge's: hub-managed): their names and aliases are dropped (free
+   * again at once) and they are never derived one later. A session the directory does not know yet is remembered
+   * (UNNAMED_MAX, oldest dropped) until its record appears. Answers how many names went.
+   */
+  async unname(userID: string, sessionIDs: readonly string[]): Promise<number> {
+    const ids = new Set(sessionIDs)
+    return this.update(userID, (draft) => {
+      const pending = new Set(draft.data.unnamed ?? [])
+      for (const id of ids) {
+        const record = draft.byID.get(id)
+        if (!record) pending.add(id)
+        else if (record.named !== true) record.named = true
+      }
+      if (pending.size) draft.data.unnamed = [...pending].slice(-UNNAMED_MAX)
+      const before = draft.names.length
+      draft.names = draft.names.filter((n) => !ids.has(n.sessionID))
+      return before - draft.names.length
+    })
+  }
+
   // ---------- roles ----------
 
   /**
    * Claims `role` (or `role.project`) for a session. Each new holder gets the next holder generation of
    * (role, project). An exclusive claim fails (name_taken) while another live holder exists, and nobody else
    * can claim while an exclusive holder is live. Reserved roles (orchestrator…) need `byUser`
-   * (grants with `roles` come in phase 3). Exclusivity and generations are per (role, project scope).
+   * (grants with `roles` come in phase 3). Managed roles (concierge, CON-04) need `managed`: only the hub's own
+   * service passes it. Exclusivity and generations are per (role, project scope).
    */
-  async claimRole(userID: string, sessionID: string, requested: string, options: { exclusive?: boolean; project?: string; byUser?: boolean } = {}): Promise<RoleView> {
+  async claimRole(userID: string, sessionID: string, requested: string, options: { exclusive?: boolean; project?: string; byUser?: boolean; managed?: boolean } = {}): Promise<RoleView> {
     const { role, project } = parseRole(requested, options.project)
+    if (isManagedRole(role) && !options.managed) throw new AgentError("forbidden", MANAGED_ROLE_MESSAGE(role))
     if (isReservedRole(role) && !options.byUser) throw new AgentError("forbidden", `@@${role} is reserved: only the user can assign it`)
     return this.update(userID, (draft) => {
       this.known(draft, sessionID)
@@ -236,9 +269,10 @@ export class Directory {
     })
   }
 
-  /** Gives a role up; not_found when the session does not hold it. */
-  async releaseRole(userID: string, sessionID: string, requested: string, scope?: string): Promise<{ role: string; project?: string }> {
+  /** Gives a role up; not_found when the session does not hold it. A managed role (CON-04) needs `managed`. */
+  async releaseRole(userID: string, sessionID: string, requested: string, scope?: string, options: { managed?: boolean } = {}): Promise<{ role: string; project?: string }> {
     const { role, project } = parseRole(requested, scope)
+    if (isManagedRole(role) && !options.managed) throw new AgentError("forbidden", MANAGED_ROLE_MESSAGE(role))
     return this.update(userID, (draft) => {
       const held = draft.roles.find((r) => r.sessionID === sessionID && r.role === role && r.project === project)
       if (!held) throw new AgentError("not_found", `Not holding @@${scoped(role, project)}`)
@@ -263,16 +297,31 @@ export class Directory {
     )
   }
 
+  /** (RP-08) The entries of these sessions in one read (unknown and deleted ones are absent). */
+  entries(userID: string, sessionIDs: readonly string[]): Map<string, DirectoryEntry> {
+    return this.read(userID, (draft) => {
+      const out = new Map<string, DirectoryEntry>()
+      for (const id of sessionIDs) {
+        const record = draft.byID.get(id)
+        if (record && record.deletedAt === undefined) out.set(id, this.entry(draft, id))
+      }
+      return out
+    })
+  }
+
   // ---------- resolution ----------
 
   /**
    * The sessions an address names, for this user only: `ses_…` (an ID or a unique ID prefix), `@name[.project]`
    * or `@@role[.project]` (every live holder). Throws invalid (malformed), not_found or ambiguous {candidates}.
    */
-  resolve(userID: string, addr: string): Resolved {
+  resolve(userID: string, addr: string, options: ResolveOptions = {}): Resolved {
     const address = parseAddress(addr)
-    if (!address) throw new AgentError("invalid", `Not an address: use ses_…, @name or @@role`)
-    return this.read(userID, (draft) => ({ address, sessions: this.lookup(draft, address, addr) }))
+    if (!address) {
+      const { message, hint } = addressProblem(addr)
+      throw new AgentError("invalid", message, { hint })
+    }
+    return this.read(userID, (draft) => ({ address, sessions: this.lookup(draft, address, addr, options.visible ?? (() => true)) }))
   }
 
   /** Exactly one session; several (a role with several holders) is ambiguous. */
@@ -282,11 +331,11 @@ export class Directory {
     return sessions[0]!
   }
 
-  private lookup(draft: Draft, address: Address, addr: string): DirectoryEntry[] {
+  private lookup(draft: Draft, address: Address, addr: string, visible: (sessionID: string) => boolean): DirectoryEntry[] {
     const missing = () => new AgentError("not_found", `No session ${addr}`)
     if (address.kind === "id") {
-      if (draft.byID.has(address.id)) return [this.entry(draft, address.id)]
-      const matches = draft.sessions.filter((s) => s.sessionID.startsWith(address.id)).map((s) => this.entry(draft, s.sessionID))
+      if (draft.byID.has(address.id) && visible(address.id)) return [this.entry(draft, address.id)]
+      const matches = draft.sessions.filter((s) => s.sessionID.startsWith(address.id) && visible(s.sessionID)).map((s) => this.entry(draft, s.sessionID))
       if (matches.length > 1) throw ambiguous(addr, matches)
       if (!matches.length) throw missing()
       return matches
@@ -294,11 +343,11 @@ export class Directory {
     if (address.kind === "name") {
       const held = draft.names.find((n) => n.name === address.name)
       const entry = held && this.entry(draft, held.sessionID)
-      if (!entry || (address.project !== undefined && entry.project !== address.project)) throw missing()
+      if (!entry || !visible(entry.sessionID) || (address.project !== undefined && entry.project !== address.project)) throw missing()
       return [entry]
     }
     const holders = draft.roles.filter((r) => r.role === address.role && inScope(r.project, draft.byID.get(r.sessionID)?.project, address.project))
-    const ids = [...new Set(holders.map((r) => r.sessionID))]
+    const ids = [...new Set(holders.map((r) => r.sessionID))].filter(visible)
     if (!ids.length) throw missing()
     return ids.map((id) => this.entry(draft, id))
   }
@@ -377,10 +426,17 @@ export class Directory {
       let record = byID.get(live.sessionID)
       if (!record) {
         record = { sessionID: live.sessionID, firstSeen: t }
+        // (CON-09a) Unnamed before it was known: never derived a name.
+        if (data.unnamed?.includes(live.sessionID)) {
+          record.named = true
+          const rest = data.unnamed.filter((id) => id !== live.sessionID)
+          if (rest.length) data.unnamed = rest
+          else delete data.unnamed
+        }
         sessions.push(record)
         byID.set(live.sessionID, record)
       }
-      for (const field of ["machineID", "parentID", "project", "title"] as const) {
+      for (const field of ["machineID", "parentID", "project", "title", "harness"] as const) {
         const value = live[field]
         if (value !== undefined && value !== "" && record[field] !== value) record[field] = value
       }

package/src/central/agent/errors.ts

@@ -21,6 +21,8 @@ export const AGENT_ERROR_STATUS = {
   ambiguous: 409,
   /** Explicit name or exclusive role already held. */
   name_taken: 409,
+  /** A stale expectedRevision / base revision, or an Idempotency-Key reused with another body (`currentRevision`). */
+  conflict: 409,
   /** Already answered, expired or ended. */
   gone: 410,
   /** The spoke or node lacks the feature or runtime (`feature`, `harness`). */
@@ -41,6 +43,8 @@ export interface AgentErrorOptions {
   readonly hint?: string
   /** More fields in the envelope, e.g. candidates, retryAfter, feature; never code or message. */
   readonly extra?: Record<string, unknown>
+  /** Answer with `Connection: close` (the request body was left unread on the socket: agent/body.ts). */
+  readonly close?: boolean
 }
 
 /** Throw from an agent handler; answered as the envelope with the code's status. */
@@ -59,6 +63,7 @@ export function agentError(error: AgentError): Response {
   const headers: Record<string, string> = { "cache-control": "no-store" }
   const retryAfter = extra.retryAfter
   if (typeof retryAfter === "number" && Number.isFinite(retryAfter) && retryAfter >= 0) headers["retry-after"] = String(Math.ceil(retryAfter))
+  if (error.options.close) headers.connection = "close"
   return Response.json(
     { error: { ...extra, code: error.code, message: error.message, ...(hint ? { hint } : {}) } },
     { status: AGENT_ERROR_STATUS[error.code], headers },

package/src/central/agent/events-routes.ts

@@ -13,7 +13,9 @@
 //
 // Who sees what: the user everything. App tokens need events:subscribe for the route and, per family, sessions:read
 // (session), sessions:manage (manage), messages:read and being a party (message), sessions:launch and having started
-// it (launch). Session tokens see session and manage events, messages they are a party to and launches they started.
+// it (launch). Session tokens see session and manage events, messages they are a party to and launches they started;
+// a session holding a team seat (team-scoped, HWA-40) additionally sees no event naming a session or team that team
+// discovery hides from it (deps.scope), with or without filters, so IDs of hidden sessions never leak.
 // Reader-only fields (family, audience, position) never leave the hub.
 import type { AgentActor } from "./actor"
 import type { Directory } from "./directory"
@@ -29,7 +31,7 @@ export const EVENTS_LIMIT_MAX = 200
 export const EVENTS_LIMIT_DEFAULT = 50
 export const INSPECT_MAX = 1000
 export const RECHECK_MS = 1000
-export const RESET_REFRESH = ["status", "sessions", "inbox", "decisions", "launches"] as const
+export const RESET_REFRESH = ["status", "sessions", "inbox", "decisions", "launches", "workspaces"] as const
 const FILTER_MAX = 20
 const TYPE = /^[a-z][a-z0-9_]*(\.[a-z0-9_]+)*(\.\*)?$/
 
@@ -39,6 +41,16 @@ export interface EventsRouteDeps {
   readonly events: Pick<AgentEvents, "latest" | "since" | "appended">
   readonly keys: CursorKeys
   readonly directory: Pick<Directory, "resolve">
+  /**
+   * Narrows what a caller reads beyond scopes (HWA-28/40: a team-scoped session sees no events naming sessions or
+   * teams hidden from it). Read fresh per inspected batch; undefined: no narrowing.
+   */
+  readonly scope?: (userID: string, actor: AgentActor) => Promise<((subject: AgentEvent["subject"]) => boolean) | undefined>
+  /**
+   * Resolves `?session=` addresses for the caller (HWA-28/40: a session hidden from a team-scoped caller is not_found
+   * exactly like an unknown one, as watch?session= answers). Absent: the directory.
+   */
+  readonly resolve?: (userID: string, actor: AgentActor, addr: string) => Promise<readonly string[]>
 }
 
 export interface EventsPage {
@@ -73,6 +85,9 @@ export function visible(record: EventRecord, actor: AgentActor): boolean {
       return has("messages:read") && (record.audience?.parties ?? []).includes(party)
     case "launch":
       return has("sessions:launch") && record.audience?.by === launchedBy(actor)
+    case "artifact":
+      // Artifact IDs of the user's library: app tokens with artifacts:read; sessions never (most are private).
+      return actor.kind === "app" && actor.scopes.includes("artifacts:read")
   }
 }
 
@@ -89,7 +104,8 @@ export function eventsRoutes(deps: EventsRouteDeps): AgentRoute[] {
         const addrs = url.searchParams.getAll("session").filter(Boolean)
         if (types.length > FILTER_MAX || addrs.length > FILTER_MAX) throw invalid(`At most ${FILTER_MAX} type and ${FILTER_MAX} session filters`)
         if (types.some((t) => t.length > 100 || !TYPE.test(t))) throw invalid("type must be an event type such as session.changed or launch.*")
-        const sessions = addrs.length ? new Set(addrs.flatMap((addr) => deps.directory.resolve(user.id, addr).sessions.map((s) => s.sessionID))) : undefined
+        const resolve = deps.resolve ?? (async (userID: string, _actor: AgentActor, addr: string) => deps.directory.resolve(userID, addr).sessions.map((s) => s.sessionID))
+        const sessions = addrs.length ? new Set((await Promise.all(addrs.map((addr) => resolve(user.id, actor, addr)))).flat()) : undefined
         const page = await read(deps, user.id, actor, { cursor: url.searchParams.get("cursor") ?? undefined, wait, limit, types, sessions }, request.signal)
         return Response.json(page, { headers: NO_STORE })
       },
@@ -131,8 +147,9 @@ export async function read(deps: EventsRouteDeps, userID: string, actor: AgentAc
     if ("reset" in result) return { events: [], cursor: encodeCursor(keys, userID, await events.latest(userID)), more: false, reset: true, refresh: RESET_REFRESH }
     const found: AgentEvent[] = []
     let more = result.records.length > INSPECT_MAX
+    const scoped = result.records.length && deps.scope && actor.kind === "session" ? await deps.scope(userID, actor) : undefined
     for (const record of result.records.slice(0, INSPECT_MAX)) {
-      if (visible(record, actor) && typeMatches(options.types, record.event.type) && sessionMatches(options.sessions, record.event)) {
+      if (visible(record, actor) && (!scoped || scoped(record.event.subject)) && typeMatches(options.types, record.event.type) && sessionMatches(options.sessions, record.event)) {
         if (found.length === options.limit) {
           more = true
           break

package/src/central/agent/events.ts

@@ -23,8 +23,8 @@ export const AGENT_EVENTS_AGE_MS = 86_400_000
 /** Record format version (readers reject others rather than skip them). */
 export const AGENT_EVENT_VERSION = 1
 
-/** The scope family a reader needs: sessions:read, sessions:manage, messages:read, sessions:launch. */
-export type EventFamily = "session" | "manage" | "message" | "launch"
+/** The scope family a reader needs: sessions:read, sessions:manage, messages:read, sessions:launch, artifacts:read. */
+export type EventFamily = "session" | "manage" | "message" | "launch" | "artifact"
 
 export type EventSubject = Readonly<Record<string, string>>
 export type EventData = Readonly<Record<string, string | number | boolean>>
@@ -66,7 +66,7 @@ export interface EventRecord {
 /** Records after a position, or `reset` when the journal no longer covers it (expired, trimmed, restarted). */
 export type EventsSince = { readonly records: EventRecord[] } | { readonly reset: true }
 
-const FAMILIES: ReadonlySet<string> = new Set<EventFamily>(["session", "manage", "message", "launch"])
+const FAMILIES: ReadonlySet<string> = new Set<EventFamily>(["session", "manage", "message", "launch", "artifact"])
 const EVENT_ID = /^evt_[0-9a-f]{20}$/
 
 export const newEventID = (): string => `evt_${randomBytes(10).toString("hex")}`
@@ -203,6 +203,14 @@ export const archiveEvent = (sessionID: string, archived: boolean): EventInput =
 
 export const pinnedEvent = (sessionID: string, pinned: boolean): EventInput => ({ type: "session.pinned", family: "manage", subject: { sessionID }, data: { pinned } })
 
+/**
+ * (CON-04) The user's Concierge changed: its status (state, holder generation) or a record's revision. IDs, enums and
+ * counts only: never settings, notes, intents or board text.
+ */
+export function conciergeEvent(data: { readonly what: "status"; readonly state: string; readonly generation: number } | { readonly what: "watchlist" | "settings" | "notes"; readonly revision: number }): EventInput {
+  return { type: "concierge.changed", family: "manage", subject: {}, data: { ...data } }
+}
+
 /** A session was explicitly named (names are validated slugs: a-z, 0-9 and -). */
 export const namedEvent = (sessionID: string, name: string): EventInput => ({ type: "session.named", family: "manage", subject: { sessionID }, data: { name } })
 

package/src/central/agent/form-check.ts

@@ -0,0 +1,85 @@
+// CON-13 an agent's form answer, checked against the form's schema (the blocker's fields, src/status.ts) before the
+// hub acts on it or proposes it: one problem at a time, naming the field and what it takes, so a model corrects
+// itself instead of sending OpenCode an answer it refuses. Only the fields the hub knows are checked: a form without
+// fields (an older spoke, or fields it could not render) is left to OpenCode.
+import type { FormAnswer } from "../../protocol"
+import type { FormFieldSpec } from "../../status"
+
+type Value = FormAnswer[string]
+
+const quote = (s: string) => JSON.stringify(s.length > 80 ? `${s.slice(0, 80)}…` : s)
+const listed = (items: readonly string[], max = 10) => items.slice(0, max).map(quote).join(", ") + (items.length > max ? ` (${items.length - max} more)` : "")
+
+/** Whether the field's `when` conditions hold for the answer (as OpenCode compares them). */
+function visible(field: FormFieldSpec, answer: FormAnswer): boolean {
+  return (field.when ?? []).every((w) => (w.op === "eq" ? answer[w.key] === w.value : answer[w.key] !== w.value))
+}
+
+function optionsProblem(field: FormFieldSpec, values: readonly string[]): string | undefined {
+  if (!field.options?.length || field.custom) return undefined
+  const allowed = field.options.map((o) => o.value)
+  const wrong = values.find((v) => !allowed.includes(v))
+  if (wrong === undefined) return undefined
+  return `Form field ${quote(field.key)}: ${quote(wrong)} is not one of the options; use an option value: ${listed(allowed)}`
+}
+
+function valueProblem(field: FormFieldSpec, value: Value): string | undefined {
+  const name = `Form field ${quote(field.key)}`
+  switch (field.type) {
+    case "external":
+      return `${name} is a link for the user: leave it out`
+    case "boolean":
+      return typeof value === "boolean" ? undefined : `${name} takes true or false`
+    case "number":
+    case "integer": {
+      if (typeof value !== "number" || !Number.isFinite(value)) return `${name} takes a number`
+      if (field.type === "integer" && !Number.isInteger(value)) return `${name} takes a whole number`
+      if (field.minimum !== undefined && value < field.minimum) return `${name} is at least ${field.minimum}`
+      if (field.maximum !== undefined && value > field.maximum) return `${name} is at most ${field.maximum}`
+      return undefined
+    }
+    case "multiselect": {
+      if (!Array.isArray(value)) return `${name} takes a list of option values`
+      if (field.minItems !== undefined && value.length < field.minItems) return `${name} takes at least ${field.minItems} choice${field.minItems === 1 ? "" : "s"}`
+      if (field.maxItems !== undefined && value.length > field.maxItems) return `${name} takes at most ${field.maxItems} choice${field.maxItems === 1 ? "" : "s"}`
+      return optionsProblem(field, value)
+    }
+    case "string": {
+      if (typeof value !== "string") return `${name} takes text`
+      const options = optionsProblem(field, [value])
+      if (options) return options
+      if (field.minLength !== undefined && value.length < field.minLength) return `${name} is at least ${field.minLength} characters`
+      if (field.maxLength !== undefined && value.length > field.maxLength) return `${name} is at most ${field.maxLength} characters`
+      if (field.pattern) {
+        let pattern: RegExp | undefined
+        try {
+          pattern = new RegExp(field.pattern)
+        } catch {
+          // a pattern the hub cannot compile is left to OpenCode
+        }
+        if (pattern && !pattern.test(value)) return `${name} does not match its pattern ${field.pattern}`
+      }
+      return undefined
+    }
+  }
+}
+
+/** The first problem of `answer` for these fields (undefined: none, or no fields known). */
+export function formAnswerFieldProblem(fields: readonly FormFieldSpec[], answer: FormAnswer): string | undefined {
+  if (!fields.length) return undefined
+  const byKey = new Map(fields.map((f) => [f.key, f]))
+  for (const key of Object.keys(answer)) {
+    if (!byKey.has(key)) return `Unknown form field ${quote(key)}: the form's fields are ${listed(fields.map((f) => f.key))} (read them with the form's schema)`
+  }
+  for (const field of fields) {
+    const value = answer[field.key]
+    // (CON-13 decision) A hidden field's value is checked too; only its required flag waits for its condition.
+    if (value === undefined) {
+      if (visible(field, answer) && field.required && field.type !== "external" && field.type !== "boolean") return `Form field ${quote(field.key)} is required`
+      continue
+    }
+    const problem = valueProblem(field, value)
+    if (problem) return problem
+  }
+  return undefined
+}

package/src/central/agent/grant-requests.ts

@@ -50,7 +50,7 @@ export interface GrantRequestsDeps {
   readonly state: StateStore
   readonly counters: Counters
   readonly decisions: Pick<Decisions, "ask" | "get">
-  readonly grants: Pick<Grants, "create">
+  readonly grants: Pick<Grants, "create"> & Partial<Pick<Grants, "assertHolder">>
   readonly directory: Pick<Directory, "resolve">
   readonly audit?: Pick<AgentAudit, "record">
   /** The requester as envelopes name it; default: from the actor alone. */
@@ -83,6 +83,7 @@ export class GrantRequests {
     const own = ownHolder(actor)
     const spec = validateGrant({ ...body.grant, holder: body.grant.holder ?? own })
     const holder = this.holder(userID, actor, spec.holder, own)
+    await this.deps.grants.assertHolder?.(userID, holder)
     const grant = canonical({ ...spec, holder })
 
     const requester = this.describe(userID, actor)

package/src/central/agent/grant-routes.ts

@@ -9,6 +9,7 @@
 // Agents only request one (grant-requests.ts): POST /api/agent/grants/requests {grant, why} from a session (any of
 // its tokens) or an app token with messages:send → 201 {message, decision} (a tap Decision for the user); the user
 // gets invalid (create it directly).
+import { boundedJson } from "./body"
 import type { GrantRequests } from "./grant-requests"
 import { type Grant, type Grants, grantState } from "./grants"
 import type { AgentRoute } from "./routes"
@@ -32,7 +33,7 @@ export function grantRoutes(grants: Grants, now: () => number = Date.now, reques
             method: "POST",
             path: `${PREFIX}/requests`,
             allow: { session: true, scope: "messages:send" },
-            handle: async ({ request, actor, user }) => Response.json(await requests.request(user.id, actor, await request.json()), { status: 201, headers: NO_STORE }),
+            handle: async ({ request, actor, user }) => Response.json(await requests.request(user.id, actor, await boundedJson(request)), { status: 201, headers: NO_STORE }),
           } satisfies AgentRoute,
         ]
       : []),
@@ -40,7 +41,7 @@ export function grantRoutes(grants: Grants, now: () => number = Date.now, reques
       method: "POST",
       path: PREFIX,
       allow: {},
-      handle: async ({ request, user }) => one(await grants.create(user.id, await request.json()), 201),
+      handle: async ({ request, user }) => one(await grants.create(user.id, await boundedJson(request)), 201),
     },
     {
       method: "GET",
@@ -58,7 +59,7 @@ export function grantRoutes(grants: Grants, now: () => number = Date.now, reques
       method: "PUT",
       path: `${PREFIX}/:id`,
       allow: {},
-      handle: async ({ params, request, user }) => one(await grants.update(user.id, params.id!, await request.json())),
+      handle: async ({ params, request, user }) => one(await grants.update(user.id, params.id!, await boundedJson(request))),
     },
     {
       method: "DELETE",

package/src/central/agent/grants.ts

@@ -20,6 +20,7 @@ import { AgentError } from "./errors"
 import type { AgentActor, AppActor, SessionActor } from "./actor"
 import { type GrantSpec, type GrantVerb, inProjects, validateGrant } from "./policy"
 import { updateVersioned } from "./versioned"
+import { isManagedRole } from "./names"
 
 /** Active (unexpired, unrevoked) grants per user. */
 export const GRANTS_ACTIVE_MAX = 50
@@ -63,6 +64,8 @@ export interface GrantsDeps {
   /** The hub-wide admin audit (Store): summaries only. */
   readonly admin?: { audit(entry: Omit<AuditEntry, "at">): void | Promise<void> }
   readonly now?: () => number
+  /** (CON-04) The user's Concierge sessions: only the Concierge service (managed) grants to them or to @@concierge. */
+  readonly concierge?: (owner: string) => Promise<readonly string[]>
 }
 
 const notFound = () => new AgentError("not_found", "No such grant")
@@ -74,10 +77,33 @@ export class Grants {
     this.now = deps.now ?? Date.now
   }
 
+  /**
+   * (CON-04) Refuses a holder that is the Concierge (a concierge* role, or a Concierge session by ID or name) unless
+   * the Concierge service itself (managed) grants it: 403 {policy: "concierge"}.
+   */
+  async assertHolder(owner: string, holder: string, options: { readonly managed?: boolean } = {}): Promise<void> {
+    if (options.managed) return
+    const role = holder.startsWith("@@") ? holder.slice(2).split(".")[0]! : undefined
+    let concierge = role !== undefined && isManagedRole(role)
+    if (!concierge && role === undefined && !holder.startsWith("app:") && this.deps.concierge) {
+      const hidden = await this.deps.concierge(owner)
+      if (hidden.includes(holder)) concierge = true
+      else {
+        try {
+          concierge = this.deps.directory.resolve(owner, holder).sessions.some((s) => hidden.includes(s.sessionID))
+        } catch {
+          concierge = false
+        }
+      }
+    }
+    if (concierge) throw new AgentError("forbidden", "The Concierge's grant is managed by the hub", { hint: "Use Settings → Concierge", extra: { policy: "concierge" } })
+  }
+
   /** Validates and stores a new grant of the owner (the holder resolved and pinned for the owner). */
-  async create(owner: string, input: unknown): Promise<Grant> {
+  async create(owner: string, input: unknown, options: { readonly managed?: boolean } = {}): Promise<Grant> {
     this.owner(owner)
     const spec = validateGrant(input)
+    await this.assertHolder(owner, spec.holder, options)
     const holderSessionID = this.pin(owner, spec.holder)
     const all = await this.all(owner)
     const at = this.now()
@@ -109,8 +135,9 @@ export class Grants {
    * Replaces an active grant with a new spec (its expiry restarts now); id, holder (and its pin) and created
    * stay. Changing the holder is invalid (revoke and create instead); an ended grant is gone.
    */
-  async update(owner: string, id: string, input: unknown): Promise<Grant> {
+  async update(owner: string, id: string, input: unknown, options: { readonly managed?: boolean } = {}): Promise<Grant> {
     const spec = validateGrant(input)
+    await this.assertHolder(owner, spec.holder, options)
     return this.change(owner, id, "grant.update", (grant, at) => {
       if (spec.holder !== grant.holder) throw new AgentError("invalid", "A grant's holder cannot change: revoke it and create another")
       return { ...grant, ...fields(spec, at), updated: at }