@huynle/hub 0.8.0 → 0.8.2

package/src/central/agent/acting.ts

@@ -16,6 +16,9 @@
 //     {verdict, reason, tier, grants}. The `escalate` hook (P3-T8 turns it into a Decision) gets the escalation
 //     first; a request without parsed details, or truncated, is always needs_user (tap).
 //   · deny, answer, prompt and stop need only the grant's verb (a reject is always safe).
+//   · (R-03) the CURRENT Concierge session's approve without any usable grant is needs_user too (a Decision at the hub's tier;
+//     the hub's never rules still forbid; self-tree still applies), never a bare refusal; other agents stay forbidden.
+//     A Concierge escalation recommends approve only when it passed `recommend: true`.
 // - Every outcome after the address resolves is in the agent audit: decision (allow, needs_user, forbidden,
 //   paused, rate_limited) and outcome (ok, gone, offline, unsupported, escalated, refused, failed).
 // - Races: the request answered elsewhere first is gone (410).
@@ -83,8 +86,12 @@ export interface Escalation {
   readonly request?: PermissionRequest
   readonly always: boolean
   readonly evaluation: Evaluation
-  /** The agent's reason (`--why`): its recommendation to approve. */
+  /** The agent's reason (`--why`): its recommendation to approve (a Concierge's: only with `recommend`). */
   readonly why?: string
+  /** (R-03) The actor is a Concierge session: its escalation recommends approve only with `recommend`. */
+  readonly concierge?: true
+  /** (R-03) The Concierge itself advises approving (absent: the user only asked it to try). */
+  readonly recommend?: true
 }
 
 /** The escalation hook: answers the Decision it opened (or nothing); a throw only loses the Decision. */
@@ -111,11 +118,18 @@ export interface ActingDeps {
    * "always", even inside its grant: needs_user, a tap Decision. A failed read counts as yes (fail closed).
    */
   readonly conciergeActor?: (userID: string, sessionID: string) => Promise<boolean>
+  /**
+   * (R-03 verify) Whether the acting session is the user's CURRENT Concierge session (never a retired one). Only it
+   * may escalate an approve without a grant; a failed read counts as no (fail closed: refused).
+   */
+  readonly currentConcierge?: (userID: string, sessionID: string) => Promise<boolean>
 }
 
 /** (CON-13 decision) Why the Concierge escalates a covered request. */
 export const CONCIERGE_TAP_REASON = "Shell, outside folders and tools always need the user's tap"
 export const CONCIERGE_ALWAYS_REASON = "The Concierge never answers “always”: the user decides"
+/** (R-03) Why the Concierge escalates an approval it holds no grant for. */
+export const CONCIERGE_NO_GRANT_REASON = "No grant lets it approve here: the user decides"
 
 /** Who acts, for which user. */
 export interface Caller {
@@ -127,6 +141,8 @@ export interface ApproveInput {
   readonly requestID: string
   readonly always?: boolean
   readonly why?: string
+  /** (R-03) The Concierge advises approving: its escalation recommends approve (other agents' why always does). */
+  readonly recommend?: boolean
 }
 
 export interface Approved {
@@ -282,6 +298,17 @@ function neverForms(request: PermissionRequest): PermissionRequest[] {
 
 const patterns = (texts: readonly string[]): Pattern[] => texts.flatMap((t) => parsePattern(t) ?? [])
 
+/** Forbidden when a never rule (the hub's, or a usable grant's) matches the request as asked or normalised (saves too, for always). */
+function checkNever(request: PermissionRequest, rules: ReadonlyArray<{ grant: Grant; never: Pattern[] }>, hubNever: readonly Pattern[], always: boolean): void {
+  const sets = rules.length ? rules.map((r) => ({ id: r.grant.id, never: r.never })) : [{ id: undefined, never: [] as Pattern[] }]
+  for (const form of neverForms(request)) {
+    for (const { id, never } of sets) {
+      const verdict = evaluatePermission(form, { grant: { allow: [], never }, hubNever, always, allowAlways: true })
+      if (verdict.verdict === "never") throw forbidden(`never: ${verdict.by === "hub" ? "the hub's" : `grant ${id}'s`} rule ${formatPattern(verdict.pattern)} matches ${verdict.subject}`)
+    }
+  }
+}
+
 const invalid = (message: string) => new AgentError("invalid", message)
 const forbidden = (message: string) => new AgentError("forbidden", message)
 const offline = () => new AgentError("offline", "No spoke reports this session now")
@@ -303,6 +330,8 @@ export class Acting {
     const concierge = await this.isConcierge(caller)
     return this.act(caller, "approve", target, { requestID: input.requestID }, input.why, {
       selfTree: true,
+      // (R-03) The Concierge without a grant escalates (needs_user, a Decision) instead of being refused.
+      ...(concierge ? { withoutGrant: () => this.isCurrentConcierge(caller) } : {}),
       choose: (usable) => this.choosePermission(usable, origin.request, always, concierge),
       escalation: (evaluation) => ({
         verb: "approve",
@@ -314,6 +343,8 @@ export class Acting {
         always,
         evaluation,
         ...(input.why ? { why: input.why } : {}),
+        ...(concierge ? { concierge: true as const } : {}),
+        ...(concierge && input.recommend === true ? { recommend: true as const } : {}),
       }),
       run: async (grant) => {
         const answered = await this.deps.actions.answerPermission({ rootID: target.rootID, requestID: input.requestID, decision })
@@ -519,9 +550,20 @@ export class Acting {
       if (target.parentID) throw invalid("Prompts go to root sessions, not subagent sessions")
       if (actor.kind === "session" && actor.sessionID === target.sessionID) throw invalid("A session never prompts itself")
     }
+    // A prompt commits a staged revert (OpenCode, quirk 9budy9na): only the console's Send (or Restore) ends one.
+    // Checked after the grant (an agent without one learns nothing about the session) and audited like any refusal.
+    const notStaged = () => {
+      if ((this.deps.registry.session(target.sessionID) as { revert?: unknown } | undefined)?.revert) {
+        throw new AgentError("conflict", "A revert is staged in this session: a prompt would make it permanent", { hint: "Restore it or send from the session's console first" })
+      }
+    }
     return this.act(caller, "prompt", target, {}, input.why, {
+      check: notStaged,
       run: async (grant) => {
-        if (!grant) return this.userPrompt(target.sessionID, text, images, input.intent)
+        if (!grant) {
+          notStaged()
+          return this.userPrompt(target.sessionID, text, images, input.intent)
+        }
         return this.agentPrompt(caller, addr, target.sessionID, text, grant, input.delivery)
       },
     })
@@ -584,6 +626,8 @@ export class Acting {
     plan: {
       /** A session never acts in its own tree (permissions and forms). */
       readonly selfTree?: boolean
+      /** (R-03) No usable grant is not forbidden: `choose` gets none and throws NeedsUser (or forbidden). */
+      readonly withoutGrant?: () => Promise<boolean>
       /** The grant to act under (default: the newest usable); throws NeedsUser or forbidden. */
       readonly choose?: (usable: Grant[]) => Grant
       readonly escalation?: (evaluation: Evaluation) => Omit<Escalation, "userID" | "actor">
@@ -610,7 +654,7 @@ export class Acting {
         acting.ensureActing(userID)
         await this.guard(userID, target)
         const usable = await grants.usable(actor, verb, { directory: target.directory })
-        if (!usable.length) throw forbidden(`No grant lets this ${actor.kind} ${verb} in this session`)
+        if (!usable.length && !(plan.choose && plan.withoutGrant && (await plan.withoutGrant()))) throw forbidden(`No grant lets this ${actor.kind} ${verb} in this session`)
         if (plan.selfTree && actor.kind === "session" && (this.deps.registry.rootOf(actor.sessionID) ?? actor.sessionID) === target.rootID) {
           throw forbidden("A session never answers requests in its own session tree")
         }
@@ -670,24 +714,32 @@ export class Acting {
     }
   }
 
+  /** (R-03 verify) The actor is the user's current Concierge session; a failed read (or no reader) is no. */
+  private async isCurrentConcierge(caller: Caller): Promise<boolean> {
+    const { actor } = caller
+    if (actor.kind !== "session" || !this.deps.currentConcierge) return false
+    try {
+      return await this.deps.currentConcierge(caller.userID, actor.sessionID)
+    } catch {
+      return false
+    }
+  }
+
   /**
    * The grant that covers the request, after every never rule; NeedsUser when none does. (CON-13 decision)
    * `concierge`: a Concierge actor's "always", or a covered request of the tap risk tier, is NeedsUser at tap tier.
+   * (R-03 verify) Every never rule (the hub's and each usable grant's, also with no grant) is checked first, before
+   * any NeedsUser: a forbidden request never becomes a Decision, "always" or not.
    */
   private choosePermission(usable: Grant[], request: PermissionRequest | undefined, always: boolean, concierge = false): Grant {
     const hubNever = this.deps.acting.hubNever()
     const ids = usable.map((g) => g.id)
+    const rules = usable.map((g) => ({ grant: g, allow: patterns(g.permissions.allow), never: patterns(g.permissions.never) }))
+    if (request) checkNever(request, rules, hubNever, always)
     if (concierge && always) throw new NeedsUser({ verdict: "outside", reason: CONCIERGE_ALWAYS_REASON, tier: "tap", grants: ids })
     if (!request) throw new NeedsUser({ verdict: "outside", reason: "The request's details are unknown", tier: "tap", grants: ids })
-    const rules = usable.map((g) => ({ grant: g, allow: patterns(g.permissions.allow), never: patterns(g.permissions.never) }))
-    for (const form of neverForms(request)) {
-      for (const { grant, allow, never } of rules) {
-        const verdict = evaluatePermission(form, { grant: { allow, never }, hubNever, always, allowAlways: grant.allowAlways })
-        if (verdict.verdict === "never") {
-          throw forbidden(`never: ${verdict.by === "hub" ? "the hub's" : `grant ${grant.id}'s`} rule ${formatPattern(verdict.pattern)} matches ${verdict.subject}`)
-        }
-      }
-    }
+    // (R-03) The current Concierge holds no grant: anything the never rules let through is the user's, at the hub's tier.
+    if (!usable.length) throw new NeedsUser({ verdict: "outside", reason: CONCIERGE_NO_GRANT_REASON, tier: request.truncated ? "tap" : riskTier(request, hubNever), grants: [] })
     const allNever = [...hubNever, ...rules.flatMap((r) => r.never)]
     if (request.truncated) throw new NeedsUser({ verdict: "outside", reason: "The request was too large to check in full", tier: "tap", grants: ids })
     let reason: string | undefined
@@ -790,6 +842,12 @@ export function auditOf(cause: unknown): [AuditDecision, AuditOutcome] {
       return ["forbidden", "refused"]
     case "rate_limited":
       return ["rate_limited", "refused"]
+    // Allowed, but the session's state refuses it now (a staged revert).
+    case "conflict":
+      return ["allow", "refused"]
+    // (FX-07) The hub's state did not answer in time: refused, and Activity says the hub was busy.
+    case "busy":
+      return ["busy", "refused"]
     case "needs_user":
       return ["needs_user", "refused"]
     case "gone":

package/src/central/agent/audit.ts

@@ -29,7 +29,7 @@ export const AUDIT_PAGE_DEFAULT = 100
 export const AUDIT_PAGE_MAX = 500
 
 /** The policy's decision: allowed, or why not. */
-export type AuditDecision = "allow" | "needs_user" | "forbidden" | "paused" | "rate_limited"
+export type AuditDecision = "allow" | "needs_user" | "forbidden" | "paused" | "rate_limited" | "busy"
 /** What happened: done, failed, raced (gone), the spoke could not (offline, unsupported), escalated or refused. */
 export type AuditOutcome = "ok" | "failed" | "gone" | "offline" | "unsupported" | "escalated" | "refused"
 

package/src/central/agent/decisions.ts

@@ -106,6 +106,8 @@ export interface ActAction {
   readonly target: string
   /** The verb's validated input (requestID, formID, answer, text). */
   readonly input: Readonly<Record<string, unknown>>
+  /** (FX-05) deny: the permission it would deny, for the console's card. */
+  readonly request?: DecisionRequest
 }
 
 /** An escalated permission request: the answer replies to it as the user. */
@@ -118,6 +120,56 @@ export interface PermissionAction {
   readonly sessionID: string
   /** The agent asked to approve it always. */
   readonly always: boolean
+  /** (FX-05) What it asks, for the console's card (absent when the hub did not know the request's details). */
+  readonly request?: DecisionRequest
+  /** (FX-05) Why the hub sent it to the user (the evaluation's reason). */
+  readonly reason?: string
+}
+
+/**
+ * (FX-05) A permission request as a Decision shows it (bounded): its kind, what it applies to and the patterns an
+ * "always" would save. What was not stored is recorded, so a shortened command never reads as complete: the totals
+ * when items were dropped, each cut item with its full length, and `truncated` when the hub received the request
+ * already shortened (src/status.ts permissionRequest). The console renders it as text; the Concierge's Decision reads
+ * leave it out (concierge/board-routes.ts conciergeDecisionView).
+ */
+export interface DecisionRequest {
+  readonly action: string
+  readonly resources: readonly string[]
+  readonly save?: readonly string[]
+  /** How many resources the request had, when more than were stored. */
+  readonly resourcesTotal?: number
+  /** How many save patterns it had, when more than were stored. */
+  readonly savesTotal?: number
+  /** Stored items cut at DECISION_REQUEST_TEXT characters, with their full length. */
+  readonly cut?: readonly { readonly field: "resources" | "save"; readonly index: number; readonly length: number }[]
+  /** The hub received the request already shortened. */
+  readonly truncated?: true
+}
+
+/** Resources (and save patterns) a Decision keeps of a request, and the characters of each. */
+export const DECISION_REQUEST_ITEMS = 20
+export const DECISION_REQUEST_TEXT = 2_000
+
+/** A permission request, bounded for a Decision, with what was not stored. */
+export function decisionRequest(request: { readonly action: string; readonly resources: readonly string[]; readonly save?: readonly string[]; readonly truncated?: true }): DecisionRequest {
+  const cut: { field: "resources" | "save"; index: number; length: number }[] = []
+  const bound = (field: "resources" | "save", list: readonly string[]) =>
+    list.slice(0, DECISION_REQUEST_ITEMS).map((r, index) => {
+      if (r.length > DECISION_REQUEST_TEXT) cut.push({ field, index, length: r.length })
+      return r.slice(0, DECISION_REQUEST_TEXT)
+    })
+  const resources = bound("resources", request.resources)
+  const save = request.save?.length ? bound("save", request.save) : undefined
+  return {
+    action: request.action.slice(0, DECISION_REQUEST_TEXT),
+    resources,
+    ...(save ? { save } : {}),
+    ...(request.resources.length > resources.length ? { resourcesTotal: request.resources.length } : {}),
+    ...(save && request.save!.length > save.length ? { savesTotal: request.save!.length } : {}),
+    ...(cut.length ? { cut } : {}),
+    ...(request.truncated ? { truncated: true as const } : {}),
+  }
 }
 
 /** A grant an agent requested (grant-requests.ts): approving creates it as the user. */
@@ -457,11 +509,15 @@ export class Decisions {
 
   // ---- internals ----------------------------------------------------------------------------------------
 
-  /** Whether the session is one of the user's Concierge sessions; a failed read is no label (never fails the ask). */
+  /**
+   * Whether the session is one of the user's Concierge sessions; a failed read is no label (never fails the ask).
+   * (FX-07) A read that timed out (`busy`) refuses the ask instead: the label could not be checked (fail closed).
+   */
   private async isConcierge(userID: string, sessionID: string): Promise<boolean> {
     try {
       return (await this.deps.concierge?.(userID, sessionID)) === true
-    } catch {
+    } catch (cause) {
+      if (cause instanceof AgentError && cause.code === "busy") throw cause
       return false
     }
   }

package/src/central/agent/delivery.ts

@@ -7,13 +7,16 @@
 //   {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 (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). In a
+//   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. 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
@@ -37,8 +40,12 @@
 //   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"
@@ -61,6 +68,8 @@ export interface DeliveryRegistry {
   idle(sessionID: string): boolean
   /** Higher: more recent activity. */
   recency(sessionID: string): number
+  /** A revert is staged in the session (Registry.revertStaged): nothing is sent to it (absent: never). */
+  revertStaged?(sessionID: string): boolean
 }
 
 /** Address resolution (Directory.resolve) and the primer flag (without primed/markPrimed: no primer). */
@@ -80,8 +89,8 @@ 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
@@ -113,8 +122,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. */
@@ -136,6 +149,11 @@ 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 {
@@ -144,6 +162,8 @@ export interface Sent {
   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. */
@@ -247,7 +267,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 }))
@@ -367,6 +387,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) {
@@ -404,7 +429,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,
@@ -428,7 +453,7 @@ export class Delivery {
     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 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,
@@ -440,15 +465,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 {
@@ -555,33 +580,38 @@ export class Delivery {
     }
     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). */
@@ -619,16 +649,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, woke: wake }
+    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", woke: wake }
+    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). */
@@ -643,8 +675,13 @@ export class Delivery {
     return { message: updated, delivery: result.delivered }
   }
 
-  /** Sends the request to each of the user's deliver-capable connections for the session until one takes it. */
+  /**
+   * Sends the request to each of the user's deliver-capable connections for the session until one takes it. Not at
+   * all while a revert is staged there: admitting anything commits it (decision in docs/session-view.md), so the
+   * message stays pending and goes in on the sessions frame that shows the revert restored or committed.
+   */
   private async request(userID: string, sessionID: string, req: DeliverRequest): Promise<DeliverResult | undefined> {
+    if (this.deps.registry.revertStaged?.(sessionID)) return undefined
     for (const connID of this.targets(userID, sessionID)) {
       let result: unknown
       try {
@@ -671,7 +708,11 @@ export class Delivery {
           this.flushStats.skipped++
           continue
         }
-        const message = value.expiresAt > this.now() ? await this.messages.get(userID, value.messageID) : undefined
+        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 })
@@ -695,6 +736,48 @@ 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}`
+    // Why it waited: a staged revert holds every delivery (request()), else the session was offline or busy.
+    const why = this.deps.registry.revertStaged?.(value.sessionID) ? "a revert stayed staged in its session for 24 h" : "its session stayed offline or busy for 24 h"
+    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: ${why}` })
+    } 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: ${why} · ${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

package/src/central/agent/errors.ts

@@ -35,6 +35,8 @@ export const AGENT_ERROR_STATUS = {
   internal: 500,
   /** The machine is offline (actions only; messages queue instead). */
   offline: 503,
+  /** (FX-07) The hub's state did not answer in time (`retryAfter`, seconds): refused, try again. */
+  busy: 503,
 } as const satisfies Record<string, number>
 
 export type AgentErrorCode = keyof typeof AGENT_ERROR_STATUS