@huynle/hub 0.7.4 → 0.8.1

package/src/central/agent/delivery.ts

@@ -7,14 +7,22 @@
 //   {feature: "deliver"} and nothing is stored. No fallback through steer/turn.
 // - Modes: plain msg → delivery "queue" (after the running turn), ask/reply/decline/urgent → "steer" (also the
 //   first msg after a primer to an idle session: the two then share one model call, quirk hzmcqwpj); wake
-//   unless wake:false, a subagent recipient, the hop cap (alerted once when crossed) or a spent wake budget.
+//   unless wake:false, a subagent recipient, the hop cap (alerted once when crossed) or a spent wake budget; Sent
+//   says whether it woke (woke) and, when not, why (wakeSkipped: wake_false | subagent | hop_cap | budget).
 // - Roles: one holder, the idle one (by real evidence) else the most recently active, else (all offline) the
 //   one seen last; the message records the holder generation. sendAll: every holder, a message each. A session
 //   never messages itself: it is left out of a role it holds, and an address naming only it is invalid.
-// - Pending: no deliver-capable connection reports the recipient (offline) or every one failed → kept for
-//   PENDING_MS in the StateStore and delivered oldest first on the user's next sessions frame (onSessions). In a
+// - Pending: no deliver-capable connection reports the recipient (offline) or every one failed (including an
+//   OpenCode spoke refusing a routine wake:false msg while the recipient's turn runs, RF-05) → kept for
+//   PENDING_MS in the StateStore and delivered oldest first on the user's next sessions frame (onSessions). One
+//   still pending after PENDING_MS expires (the loop's tick, or a flush that finds it): delivery "expired", and its
+//   sender is told (a session by a quiet hub notice, the user by an alert, everyone through the journal). In a
 //   cluster (deps.locks) each (user, session) flush holds a lease (deliver:<user>:<session>) and re-reads the
-//   entry under it, so a spoke reconnecting to another pod meanwhile never gets a message twice.
+//   entry under it, so a spoke reconnecting to another pod meanwhile never gets a message twice. A flush stops at a
+//   session's first failed delivery (its later messages wait, in order, for the next frame: one round trip per busy
+//   or unreachable session per frame), and a waking message first flushes only its own session's pending ones.
+//   Ordering limit: a waking message to a session that is still busy is admitted (queued after the turn) before the
+//   quiet ones pending for it, which follow when the turn ends.
 //   OpenCode holds admitted messages itself across forms, interrupts and restarts (P2-T0), so there is no
 //   "retained" retry loop on the hub.
 // - Re-wake: an open ask to an idle recipient (Registry.idle: native or hooks evidence) is woken again after
@@ -32,11 +40,16 @@
 //   for the user (their stored-only inbox; nothing goes to a spoke); a msg alerts the user ("user"), an ask is a
 //   Decision's carrier (./decisions pushes it). The user cannot message @me; `@me.project` is malformed.
 // - Loop protection (./message-limits): pair/user rate limits before storing, hop per message, human turns
-//   (console, voice, typed in the harness) reset a session's chain (humanTurn).
+//   (console, voice, typed in the harness) reset a session's chain (humanTurn). Apps keep no depth (S1): a new
+//   msg/ask from an app is hop 1 plus its relay depth (what OTHER sessions sent it in the last 5 minutes, so a
+//   relay loop through an app still reaches the hop cap), an app's reply or decline counts up from the message it
+//   answers, and nothing sent to an app raises a persistent depth.
 import type { DeliverRequest, DeliverResult, DeliveryMode, MessageKind as WireKind } from "../../protocol"
+import type { WakeSkip } from "../../../packages/sdk/src/types.ts"
 import { isDeliverResult } from "../../protocol"
 import { randomBytes } from "node:crypto"
 import type { Clock, Counters, Locks, StateStore, Timers } from "../backend/types"
+import type { TeamPolicy } from "../teams/policy"
 import type { AgentActor } from "./actor"
 import type { DirectoryEntry, NamedListener, Resolved } from "./directory"
 import { type Party, type PartyInfo, partyFromActor, partyKey, partyLabel, renderEnvelope, renderPrimer } from "./envelope"
@@ -74,14 +87,27 @@ export type DeliverSend = (connID: string, req: DeliverRequest) => Promise<Deliv
  * ask stayed unanswered by an idle recipient after every re-wake.
  */
 export interface DeliveryAlert {
-  /** user: a session or app sent the user (@me) a message. */
-  readonly kind: "hopCap" | "unanswered" | "user"
+  /** user: a session or app sent the user (@me) a message; expired: the user's message stayed pending for 24 h. */
+  readonly kind: "hopCap" | "unanswered" | "user" | "expired"
   /** The recipient session (user: the sending session, "" for an app). */
   readonly sessionID: string
   readonly messageID: string
   readonly text: string
 }
 
+/** What a message to a session is, for the inbound policy. */
+export type InboundKind = "msg" | "ask" | "reply" | "decline"
+
+/**
+ * (CON-04) Who may message a session, beyond the existing rules: `admit` throws (forbidden) to refuse before anything
+ * is stored. `original`: the message a reply or decline answers. The hub passes the Concierge inbound rule.
+ */
+export interface InboundPolicy {
+  admit(userID: string, from: Party, sessionID: string, kind: InboundKind, original?: Message): Promise<void>
+  /** Who a sender may reach at all (the Concierge: only @me, and replies to asks addressed to it); throws to refuse. */
+  outbound?(userID: string, from: Party, kind: InboundKind, original?: Message): Promise<void>
+}
+
 export interface DeliveryDeps {
   readonly state: StateStore
   readonly counters: Counters
@@ -94,8 +120,12 @@ export interface DeliveryDeps {
   /** Labels of a session sender (default: its @name from the directory). */
   readonly describe?: (userID: string, sessionID: string) => PartyInfo
   readonly alert?: (userID: string, alert: DeliveryAlert) => void
+  /** A pending message expired undelivered (its sender was told): the hub journals the change. Never throws through. */
+  readonly expired?: (userID: string, message: Message) => void
   /** Limiter caps (default PAIR_LIMIT, USER_LIMIT, WAKE_BUDGET). */
   readonly limits?: Partial<MessageLimits>
+  /** How long what an app received from a session raises its new messages (message-limits RELAY_WINDOW_MS). */
+  readonly relayWindowMs?: number
   /** The users the re-wake loop looks at (every user of the hub; default: the users seen by this process since start). */
   readonly users?: () => Iterable<string> | Promise<Iterable<string>>
   /** Cluster mode: a pending flush holds a lease per (user, session), so two pods never deliver the same message. */
@@ -104,6 +134,10 @@ export interface DeliveryDeps {
   readonly owner?: string
   /** How often the re-wake loop runs (default REWAKE_TICK_MS). */
   readonly tickMs?: number
+  /** Team communication policy (HWA-34, ../teams/policy.ts): team addresses and verdicts before anything is stored. */
+  readonly teams?: Pick<TeamPolicy, "prepare" | "answer">
+  /** (CON-04) Inbound policy per recipient session (the Concierge inbound rule), checked next to team policy. */
+  readonly inbound?: InboundPolicy
 }
 
 export interface SendOptions {
@@ -113,12 +147,21 @@ export interface SendOptions {
   readonly urgent?: boolean
   /** Asks only. */
   readonly expiresInMs?: number
+  /**
+   * Hub-internal, never from a request body: the message continues a chain at least this deep (its hop is the
+   * larger of its own and this). Team intake passes the submitting session's depth + 1.
+   */
+  readonly chainHop?: number
 }
 
 export interface Sent {
   readonly message: Message
   /** How it reached the recipient; undefined when the recipient is not a session (stored only). */
   readonly delivery?: DeliveryState
+  /** Whether it was sent to wake its recipient (false: wake:false, a subagent, the hop cap or a spent wake budget). */
+  readonly woke?: boolean
+  /** Why it was not (only when woke is false). */
+  readonly wakeSkipped?: WakeSkip
 }
 
 /** A reply or decline as sent, with the message it answered. */
@@ -202,6 +245,11 @@ export class Delivery {
   private readonly newID: () => string
   /** Per user: the flush in progress (flushes run one at a time). */
   private readonly flushing = new Map<string, Promise<void>>()
+  /**
+   * Pending flush counters since start (no message text): attempts that failed (offline spokes, a busy OpenCode
+   * session refusing a routine quiet msg) and messages skipped behind such a failure until the next frame.
+   */
+  readonly flushStats = { failed: 0, skipped: 0 }
   /** Per user and session: the primer in flight (one at a time); true once it was admitted. */
   private readonly priming = new Map<string, Promise<boolean>>()
   /** Users seen since start (sent a message, or one of their spokes reported sessions): the loop looks at these. */
@@ -217,7 +265,7 @@ export class Delivery {
     this.newID = deps.newID ?? newMessageID
     this.owner = deps.owner ?? `delivery-${process.pid}-${randomBytes(4).toString("hex")}`
     this.messages = new Messages({ state: deps.state, now, newID: this.newID })
-    this.hops = new HopTracker({ state: deps.state, now })
+    this.hops = new HopTracker({ state: deps.state, now, ...(deps.relayWindowMs === undefined ? {} : { relayWindowMs: deps.relayWindowMs }) })
     this.limiter = new MessageLimiter({ counters: deps.counters, now, ...(deps.limits ? { limits: deps.limits } : {}) })
     // An explicit (re)name primes again, so the session learns its new address.
     deps.directory.onNamed?.((userID, sessionID) => void this.prime(userID, sessionID, { again: true }))
@@ -250,7 +298,7 @@ export class Delivery {
   async send(userID: string, actor: AgentActor, addr: string, kind: "msg" | "ask", text: string, options: SendOptions = {}): Promise<Sent> {
     if (isUserAddress(addr)) return this.sendToUser(userID, actor, addr, kind, text, options)
     const from = this.party(userID, actor)
-    const resolved = this.others(actor, this.deps.directory.resolve(userID, addr))
+    const resolved = await this.resolveFor(userID, actor, from, addr, kind)
     return this.sendTo(userID, from, addr, resolved, this.pick(resolved), kind, text, options)
   }
 
@@ -258,7 +306,7 @@ export class Delivery {
   async sendAll(userID: string, actor: AgentActor, addr: string, kind: "msg" | "ask", text: string, options: SendOptions = {}): Promise<Sent[]> {
     if (isUserAddress(addr)) return [await this.sendToUser(userID, actor, addr, kind, text, options)]
     const from = this.party(userID, actor)
-    const resolved = this.others(actor, this.deps.directory.resolve(userID, addr))
+    const resolved = await this.resolveFor(userID, actor, from, addr, kind)
     const sent: Sent[] = []
     for (const entry of resolved.sessions) sent.push(await this.sendTo(userID, from, addr, resolved, entry, kind, text, options))
     return sent
@@ -266,12 +314,12 @@ export class Delivery {
 
   /** Replies to a message, from its recipient to its real sender (never via a role), and delivers the reply. */
   reply(userID: string, actor: AgentActor, replyTo: string, text: string, options: SendOptions = {}): Promise<Replied> {
-    return this.answer(userID, actor, replyTo, options, (input) => this.messages.reply(userID, { ...input, text }))
+    return this.answer(userID, actor, replyTo, options, "reply", (input) => this.messages.reply(userID, { ...input, text }))
   }
 
   /** Declines an ask, with a reason, and delivers the decline to the asker. */
   decline(userID: string, actor: AgentActor, replyTo: string, why: string, options: SendOptions = {}): Promise<Replied> {
-    return this.answer(userID, actor, replyTo, options, (input) => this.messages.decline(userID, { ...input, why }))
+    return this.answer(userID, actor, replyTo, options, "decline", (input) => this.messages.decline(userID, { ...input, why }))
   }
 
   /** A human turn in the session (console prompt or utterance, or typed in the harness): its hop chain starts over. */
@@ -280,9 +328,10 @@ export class Delivery {
   }
 
   /** Delivers the user's pending messages whose sessions a deliver-capable spoke reports now, oldest first. */
-  flush(userID: string): Promise<void> {
+  /** Delivers the user's pending messages (only `sessionID`'s when given); flushes run one at a time per user. */
+  flush(userID: string, sessionID?: string): Promise<void> {
     const previous = this.flushing.get(userID) ?? Promise.resolve()
-    const run = previous.then(() => this.flushNow(userID))
+    const run = previous.then(() => this.flushNow(userID, sessionID))
     const tracked = run.finally(() => {
       if (this.flushing.get(userID) === tracked) this.flushing.delete(userID)
     })
@@ -290,6 +339,21 @@ export class Delivery {
     return run
   }
 
+  /**
+   * (CON-10) Drops the messages still pending for a session that ended for good (a retired Concierge session): they
+   * are never delivered later, and their delivery reads "dropped" (never waiting). Answers how many were dropped.
+   */
+  async dropPending(userID: string, sessionID: string): Promise<number> {
+    let dropped = 0
+    for (const { key, value, version } of await this.deps.state.list<Pending>(userID, PENDING)) {
+      if (value.sessionID !== sessionID) continue
+      if (!(await this.deps.state.delete(userID, PENDING, key, { ifVersion: version })).ok) continue
+      await this.messages.setDelivery(userID, value.messageID, "dropped")
+      dropped++
+    }
+    return dropped
+  }
+
   /** Registry.onSessions: a spoke reported its sessions (connected, reconnected, or its periodic snapshot). */
   async onSessions(connID: string): Promise<void> {
     const userID = this.deps.registry.connTenant(connID)
@@ -321,6 +385,11 @@ export class Delivery {
       return
     }
     for (const userID of users) {
+      try {
+        await this.expirePending(userID)
+      } catch (cause) {
+        console.error(`[hub] pending expiry failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+      }
       try {
         await this.rewake(userID)
       } catch (cause) {
@@ -358,7 +427,7 @@ export class Delivery {
     const from = this.party(userID, actor)
     const recipient: Party = { kind: "user" }
     await this.limiter.admit(userID, from, recipient)
-    const hop = await this.hops.next(userID, from)
+    const hop = await this.hops.next(userID, from, { to: recipient })
     const message = await this.messages.send(userID, {
       from,
       to: USER_ADDRESS,
@@ -378,10 +447,12 @@ export class Delivery {
   private async sendTo(userID: string, from: Party, addr: string, resolved: Resolved, entry: DirectoryEntry, kind: "msg" | "ask", text: string, options: SendOptions): Promise<Sent> {
     const sessionID = entry.sessionID
     const recipient: Party = { kind: "session", sessionID, ...(entry.name ? { name: entry.name } : {}) }
+    await this.deps.inbound?.outbound?.(userID, from, kind)
+    await this.deps.inbound?.admit(userID, from, sessionID, kind)
     this.gate(userID, sessionID)
     await this.limiter.admit(userID, from, recipient)
-    const hop = await this.hops.next(userID, from)
-    const generation = resolved.address.kind === "role" ? roleGeneration(entry, resolved.address) : undefined
+    const hop = Math.max(await this.hops.next(userID, from, { to: recipient }), options.chainHop ?? 0)
+    const generation = resolved.address.kind === "role" && !("team" in resolved) ? roleGeneration(entry, resolved.address) : undefined
     const message = await this.messages.send(userID, {
       from,
       to: addr,
@@ -392,15 +463,15 @@ export class Delivery {
       ...(generation === undefined ? {} : { generation }),
       ...(options.expiresInMs === undefined ? {} : { expiresInMs: options.expiresInMs }),
     })
-    await this.hops.received(userID, recipient, hop)
+    await this.hops.received(userID, recipient, hop, from)
     this.users.add(userID)
-    const wanted = options.wake !== false && entry.parentID === undefined
-    const wake = await this.wakeFor(userID, message, wanted)
-    if (kind === "ask" && wanted && !overHopCap(hop)) {
+    const unwanted: WakeSkip | undefined = options.wake === false ? "wake_false" : entry.parentID !== undefined ? "subagent" : undefined
+    const skipped = await this.wakeFor(userID, message, unwanted)
+    if (kind === "ask" && unwanted === undefined && !overHopCap(hop)) {
       const rewake: Rewake = { messageID: message.id, sessionID, reminders: 0, nextAt: message.at + backoff(0) }
       await this.deps.state.put(userID, REWAKE, message.id, rewake)
     }
-    return this.deliver(userID, message, sessionID, wake, options.urgent === true)
+    return this.deliver(userID, message, sessionID, skipped, options.urgent === true)
   }
 
   private schedule(): void {
@@ -463,6 +534,13 @@ export class Delivery {
     return (await this.request(userID, sessionID, req)) !== undefined
   }
 
+  /** The address's sessions (team-aware, HWA-34) without the sender, narrowed to those team policy permits. */
+  private async resolveFor(userID: string, actor: AgentActor, from: Party, addr: string, kind: "msg" | "ask"): Promise<Resolved> {
+    const team = await this.deps.teams?.prepare(userID, from, addr)
+    const resolved = this.others(actor, team?.resolved ?? this.deps.directory.resolve(userID, addr))
+    return team ? { ...resolved, sessions: await team.admit(resolved.sessions, kind, this.limiter) } : resolved
+  }
+
   /** The resolved sessions without the sending session itself; invalid when only it is left (no self-messages). */
   private others(actor: AgentActor, resolved: Resolved): Resolved {
     if (actor.kind !== "session") return resolved
@@ -487,40 +565,51 @@ export class Delivery {
     actor: AgentActor,
     replyTo: string,
     options: SendOptions,
+    kind: "reply" | "decline",
     store: (input: { from: Party; replyTo: string; hop: number; generation?: number }) => Promise<{ message: Message; original: Message }>,
   ): Promise<Replied> {
     const from = this.party(userID, actor)
     const original = await this.messages.get(userID, replyTo)
     const to = original && partyKey(original.recipient) === partyKey(from) ? original.from : undefined
-    if (to?.kind === "session") this.gate(userID, to.sessionID)
+    if (original) await this.deps.inbound?.outbound?.(userID, from, kind, original)
+    if (to?.kind === "session") {
+      await this.deps.inbound?.admit(userID, from, to.sessionID, kind, original)
+      this.gate(userID, to.sessionID)
+    }
+    if (to && original) await this.deps.teams?.answer(userID, from, original, to, kind, this.limiter)
     if (to) await this.limiter.admit(userID, from, to)
-    const hop = await this.hops.next(userID, from)
+    const hop = await this.hops.next(userID, from, original ? { answering: original, ...(to ? { to } : {}) } : {})
     const generation = original && actor.kind === "session" ? this.holderGeneration(userID, actor.sessionID, original) : undefined
     const answered = await store({ from, replyTo, hop, ...(generation === undefined ? {} : { generation }) })
     const { message } = answered
-    await this.hops.received(userID, message.recipient, hop)
+    await this.hops.received(userID, message.recipient, hop, from)
     this.users.add(userID)
     if (message.recipient.kind !== "session") return answered
     const sessionID = message.recipient.sessionID
-    const wake = await this.wakeFor(userID, message, options.wake !== false && !this.isSubagent(userID, sessionID))
-    return { ...(await this.deliver(userID, message, sessionID, wake, true)), original: answered.original }
+    const unwanted: WakeSkip | undefined = options.wake === false ? "wake_false" : this.isSubagent(userID, sessionID) ? "subagent" : undefined
+    const skipped = await this.wakeFor(userID, message, unwanted)
+    return { ...(await this.deliver(userID, message, sessionID, skipped, true)), original: answered.original }
   }
 
-  /** Whether the message may start a turn: wanted, under the hop cap (alerting once at the cap), wake budget left. */
-  private async wakeFor(userID: string, message: Message, wanted: boolean): Promise<boolean> {
-    if (!wanted || message.recipient.kind !== "session") return false
+  /**
+   * Why the message may not start a turn (undefined: it may): `unwanted` (wake:false or a subagent recipient), over
+   * the hop cap (alerting once at the cap), or no wake budget left.
+   */
+  private async wakeFor(userID: string, message: Message, unwanted: WakeSkip | undefined): Promise<WakeSkip | undefined> {
+    if (unwanted) return unwanted
+    if (message.recipient.kind !== "session") return "wake_false"
     if (overHopCap(message.hop)) {
       if (message.hop === HOP_CAP + 1) {
         this.deps.alert?.(userID, {
           kind: "hopCap",
           sessionID: message.recipient.sessionID,
           messageID: message.id,
-          text: `Sessions messaged each other ${HOP_CAP} times without you; further messages no longer wake them`,
+          text: `Agent messages went ${HOP_CAP} hops without you (latest: ${partyLabel(message.from)} → ${partyLabel(message.recipient)}); further messages in this chain no longer wake anyone`,
         })
       }
-      return false
+      return "hop_cap"
     }
-    return this.limiter.wake(userID, message.recipient)
+    return (await this.limiter.wake(userID, message.recipient)) ? undefined : "budget"
   }
 
   /** The replier's generation of the role the original reached (undefined: not a role, or not held now). */
@@ -558,13 +647,18 @@ export class Delivery {
   }
 
   /** Delivers now, or queues the message as pending when no spoke takes it. */
-  private async deliver(userID: string, message: Message, sessionID: string, wake: boolean, urgent: boolean): Promise<Sent> {
+  private async deliver(userID: string, message: Message, sessionID: string, skipped: WakeSkip | undefined, urgent: boolean): Promise<Sent> {
+    const wake = skipped === undefined
+    const woke = wake ? { woke: true } : { woke: false, wakeSkipped: skipped }
+    // Messages still pending for this session go first (e.g. a quiet one a busy spoke refused, RF-05): the turn this
+    // one starts then carries them, instead of them arriving inside it.
+    if (wake && (await this.deps.state.list<Pending>(userID, PENDING)).some((p) => p.value.sessionID === sessionID)) await this.flush(userID, sessionID)
     const delivered = await this.attempt(userID, message, sessionID, wake, urgent)
-    if (delivered) return delivered
+    if (delivered) return { ...delivered, ...woke }
     const at = this.now()
     const pending: Pending = { messageID: message.id, sessionID, wake, urgent, at, expiresAt: at + PENDING_MS }
     await this.deps.state.put(userID, PENDING, message.id, pending)
-    return { message: (await this.messages.setDelivery(userID, message.id, "pending")) ?? message, delivery: "pending" }
+    return { message: (await this.messages.setDelivery(userID, message.id, "pending")) ?? message, delivery: "pending", ...woke }
   }
 
   /** Tries each deliver-capable connection in turn (same message id: the harness dedupes it). */
@@ -593,13 +687,25 @@ export class Delivery {
     return undefined
   }
 
-  private async flushNow(userID: string): Promise<void> {
-    const entries = (await this.deps.state.list<Pending>(userID, PENDING)).sort((a, b) => a.value.at - b.value.at || (a.key < b.key ? -1 : 1))
+  private async flushNow(userID: string, only?: string): Promise<void> {
+    const entries = (await this.deps.state.list<Pending>(userID, PENDING))
+      .filter((e) => only === undefined || e.value.sessionID === only)
+      .sort((a, b) => a.value.at - b.value.at || (a.key < b.key ? -1 : 1))
     /** Cluster mode: the sessions whose lease this flush holds (true) or another process holds (false). */
     const leases = new Map<string, boolean>()
+    /** Sessions whose delivery failed in this flush: their later messages wait for the next frame (in order). */
+    const failed = new Set<string>()
     try {
       for (const { key, value, version } of entries) {
-        const message = value.expiresAt > this.now() ? await this.messages.get(userID, value.messageID) : undefined
+        if (failed.has(value.sessionID)) {
+          this.flushStats.skipped++
+          continue
+        }
+        if (value.expiresAt <= this.now()) {
+          await this.expireEntry(userID, key, value, version)
+          continue
+        }
+        const message = await this.messages.get(userID, value.messageID)
         // Gone, or an ask that closed (expired) while it waited: nothing to deliver.
         if (!message || (message.kind === "ask" && message.state !== "open")) {
           await this.deps.state.delete(userID, PENDING, key, { ifVersion: version })
@@ -610,6 +716,10 @@ export class Delivery {
         // Another process may have delivered it before this one took the lease.
         if (this.deps.locks && !(await this.deps.state.get(userID, PENDING, key))) continue
         if (await this.attempt(userID, message, value.sessionID, value.wake, value.urgent)) await this.deps.state.delete(userID, PENDING, key)
+        else {
+          failed.add(value.sessionID)
+          this.flushStats.failed++
+        }
       }
     } finally {
       const { locks } = this.deps
@@ -619,6 +729,46 @@ export class Delivery {
     }
   }
 
+  /** The loop's sweep: the user's messages pending past PENDING_MS expire (their senders are told). */
+  private async expirePending(userID: string): Promise<void> {
+    const t = this.now()
+    for (const { key, value, version } of await this.deps.state.list<Pending>(userID, PENDING)) {
+      if (value.expiresAt <= t) await this.expireEntry(userID, key, value, version)
+    }
+  }
+
+  /**
+   * A pending message that waited PENDING_MS: removed (once: version-checked), marked "expired", and its sender
+   * told: a session by a quiet notice (wake:false, never the message text), the user by an alert; the change is
+   * journaled (deps.expired) for every sender, an app included. An ask that already closed is dropped silently.
+   */
+  private async expireEntry(userID: string, key: string, value: Pending, version: number): Promise<void> {
+    if (!(await this.deps.state.delete(userID, PENDING, key, { ifVersion: version })).ok) return
+    const current = await this.messages.get(userID, value.messageID)
+    if (!current || (current.kind === "ask" && current.state !== "open" && current.state !== "expired")) return
+    const message = (await this.messages.setDelivery(userID, current.id, "expired")) ?? current
+    const what = `${message.kind} ${message.id} to ${message.to}`
+    try {
+      this.deps.expired?.(userID, message)
+    } catch (cause) {
+      console.error(`[hub] pending expiry journal failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+    }
+    const { from } = message
+    if (from.kind === "user") {
+      this.deps.alert?.(userID, { kind: "expired", sessionID: value.sessionID, messageID: message.id, text: `Your ${message.kind} to ${message.to} was not delivered: its session stayed offline or busy for 24 h` })
+    } else if (from.kind === "session") {
+      const id = this.newID()
+      await this.request(userID, from.sessionID, {
+        op: "deliver",
+        sessionID: from.sessionID,
+        messageID: id,
+        text: `[hub] notice · ${what} was not delivered: its session stayed offline or busy for 24 h · ${id}`,
+        wake: false,
+        meta: { kind: "msg", from: "hub", to: wireAddress(from), delivery: "queue" },
+      })
+    }
+  }
+
   /** Takes the (user, session) flush lease once per flush (always true without locks); false: another process flushes it. */
   private async lease(userID: string, sessionID: string, leases: Map<string, boolean>): Promise<boolean> {
     const { locks } = this.deps
@@ -635,7 +785,11 @@ export class Delivery {
     return held
   }
 
-  /** `steer`: urgent, or the first msg after a primer to an idle session (see attempt). */
+  /**
+   * `steer`: urgent, or the first msg after a primer to an idle session (see attempt). A wake:false msg keeps
+   * "queue" unless urgent: that marks it routine, and the OpenCode spoke (RF-05) admits it steered without resume,
+   * refusing it while a turn runs so it stays pending here until the turn ends (never a model call of its own).
+   */
   private deliverRequest(message: Message, sessionID: string, wake: boolean, steer: boolean): DeliverRequest {
     const delivery: DeliveryMode = message.kind === "msg" && !steer ? "queue" : "steer"
     return {

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, {