@huynle/hub 0.8.0 → 0.8.2

package/src/central/agent/launch-spec.ts

@@ -92,8 +92,36 @@ export const LAUNCH_TIMEOUT_MAX_MS = 30 * 86_400_000
 const FIELDS = ["key", "name", "roles", "harness", "agent", "model", "workspace", "runtime", "placement", "prompt", "intent", "labels", "end", "agentProfile"]
 const WORKSPACE_FIELDS = ["repo", "mode", "branch", "base", "remote"]
 const RUNTIME_FIELDS = ["kind", "profile"]
-const PLACEMENT_FIELDS = ["labels", "machine", "mode"]
+const PLACEMENT_FIELDS = ["machine", "labels", "mode"]
 const END_FIELDS = ["when", "timeout", "cleanup"]
+/** The nested sections, in the order suggestions name them. */
+const SECTIONS: readonly (readonly [string, readonly string[]])[] = [
+  ["workspace", WORKSPACE_FIELDS],
+  ["placement", PLACEMENT_FIELDS],
+  ["runtime", RUNTIME_FIELDS],
+  ["end", END_FIELDS],
+]
+const TOP_FIELDS = FIELDS.filter((field) => !SECTIONS.some(([section]) => section === field))
+/** (FX-03) The hint every unknown-field answer carries: callers often send a flat spec. */
+export const LAUNCH_SPEC_SHAPE = `A launch spec is nested: ${SECTIONS.map(([section, fields]) => `${section}{${fields.join(", ")}}`).join(", ")}; top level: ${TOP_FIELDS.join(", ")}`
+
+/** How validateLaunchSpec words its hints for one caller. */
+export interface LaunchSpecOptions {
+  /**
+   * (R-04) Team staffing builds the spec: it sets launch.key itself and refuses the caller's, so a misplaced `key`
+   * points at idempotencyKey (the Idempotency-Key header), not "key (top level)".
+   */
+  readonly staffing?: boolean
+}
+
+/** Where a misplaced `key` belongs and the shape hint, for one caller. */
+interface Wording {
+  readonly keyPlace: string
+  readonly shape: string
+}
+
+const PLAIN: Wording = { keyPlace: "key (top level)", shape: LAUNCH_SPEC_SHAPE }
+const STAFFING: Wording = { keyPlace: "idempotencyKey (the Idempotency-Key header)", shape: `${LAUNCH_SPEC_SHAPE}; key is set by staffing: send idempotencyKey (the Idempotency-Key header) instead` }
 
 const KEY = /^[!-~]{1,200}$/
 const SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/
@@ -109,8 +137,22 @@ const PROMPT_CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/
 const invalid = (message: string, hint?: string) => new AgentError("invalid", message, hint ? { hint } : {})
 const isObject = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value)
 
-function onlyFields(value: Record<string, unknown>, allowed: readonly string[], what: string): void {
-  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw invalid(`Unknown ${what} field ${key}`)
+/** Where an unknown `key` at level `what` (launch, or a section) belongs instead: `section.key`s, or the top level. */
+function placesOf(key: string, what: string, wording: Wording): string[] {
+  const places = SECTIONS.filter(([section, fields]) => section !== what && fields.includes(key)).map(([section]) => `${section}.${key}`)
+  if (what !== "launch" && TOP_FIELDS.includes(key)) places.push(key === "key" ? wording.keyPlace : `${key} (top level)`)
+  return places
+}
+
+/** Refuses every field outside `allowed` at once, naming where a misplaced one belongs (FX-03). */
+function onlyFields(value: Record<string, unknown>, allowed: readonly string[], what: string, wording: Wording = PLAIN): void {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key))
+  if (unknown.length === 0) return
+  const suggestions = unknown.slice(0, 10).map((key) => placesOf(key, what, wording)).filter((places) => places.length > 0).map((places) => places.join(" or "))
+  // Keys are the caller's: bounded in number and length.
+  const shown = [...unknown.slice(0, 10).map((key) => key.slice(0, 40)), ...(unknown.length > 10 ? ["…"] : [])]
+  const message = `Unknown ${what} field${unknown.length > 1 ? "s" : ""} ${shown.join(", ")}${suggestions.length ? `: did you mean ${suggestions.join(", ")}?` : ""}`
+  throw invalid(message, wording.shape)
 }
 
 function oneOf<T extends string>(value: unknown, options: readonly T[], fallback: T, what: string): T {
@@ -178,9 +220,9 @@ function validRoles(value: unknown): string[] {
   return roles
 }
 
-function validWorkspace(value: unknown): LaunchWorkspace {
+function validWorkspace(value: unknown, wording: Wording): LaunchWorkspace {
   if (!isObject(value)) throw invalid("workspace is {repo, mode?, branch?, base?, remote?}")
-  onlyFields(value, WORKSPACE_FIELDS, "workspace")
+  onlyFields(value, WORKSPACE_FIELDS, "workspace", wording)
   // canonicalProject rejects relative, `~` and root paths.
   const repo = typeof value.repo === "string" ? canonicalProject(value.repo) : undefined
   if (repo === undefined) throw invalid("workspace.repo is an absolute repository path")
@@ -200,10 +242,10 @@ function validWorkspace(value: unknown): LaunchWorkspace {
   }
 }
 
-function validRuntime(value: unknown, workspace: LaunchWorkspace): LaunchRuntime {
+function validRuntime(value: unknown, workspace: LaunchWorkspace, wording: Wording): LaunchRuntime {
   if (value === undefined) return { kind: "host" }
   if (!isObject(value)) throw invalid("runtime is {kind, profile?}")
-  onlyFields(value, RUNTIME_FIELDS, "runtime")
+  onlyFields(value, RUNTIME_FIELDS, "runtime", wording)
   const kind = oneOf<RuntimeKind>(value.kind, ["host", "openshell"], "host", "runtime.kind")
   const profile = matching(value.profile, SLUG, "runtime.profile")
   if (kind === "host" && profile !== undefined) throw invalid("runtime.profile applies to the openshell runtime only")
@@ -211,20 +253,20 @@ function validRuntime(value: unknown, workspace: LaunchWorkspace): LaunchRuntime
   return { kind, ...(profile !== undefined ? { profile } : {}) }
 }
 
-function validPlacement(value: unknown): LaunchPlacement {
+function validPlacement(value: unknown, wording: Wording): LaunchPlacement {
   if (value === undefined) return { labels: {}, mode: "require" }
   if (!isObject(value)) throw invalid("placement is {labels?, machine?, mode?}")
-  onlyFields(value, PLACEMENT_FIELDS, "placement")
+  onlyFields(value, PLACEMENT_FIELDS, "placement", wording)
   const labels = validLabels(value.labels, "placement.labels")
   const machine = matching(value.machine, MACHINE, "placement.machine")
   const mode = oneOf<PlacementMode>(value.mode, ["require", "prefer"], "require", "placement.mode")
   return { labels, ...(machine !== undefined ? { machine } : {}), mode }
 }
 
-function validEnd(value: unknown): LaunchEnd {
+function validEnd(value: unknown, wording: Wording): LaunchEnd {
   if (value === undefined) return { when: "idle", cleanup: "keep" }
   if (!isObject(value)) throw invalid("end is {when?, timeout?, cleanup?}")
-  onlyFields(value, END_FIELDS, "end")
+  onlyFields(value, END_FIELDS, "end", wording)
   const when = oneOf<EndWhen>(value.when, ["idle", "asked", "never"], "idle", "end.when")
   let timeoutMs: number | undefined
   if (value.timeout !== undefined) {
@@ -238,10 +280,11 @@ function validEnd(value: unknown): LaunchEnd {
 // ---------- spec ----------
 
 /** Validates a launch body into a LaunchSpec (a fresh copy, defaults filled in); throws AgentError invalid. */
-export function validateLaunchSpec(input: unknown): LaunchSpec {
+export function validateLaunchSpec(input: unknown, options: LaunchSpecOptions = {}): LaunchSpec {
+  const wording = options.staffing ? STAFFING : PLAIN
   if (!isObject(input)) throw invalid("A launch is an object")
   if ("grant" in input) throw invalid("grant is not supported yet: a launched session has its launcher's powers only")
-  onlyFields(input, FIELDS, "launch")
+  onlyFields(input, FIELDS, "launch", wording)
   const key = matching(input.key, KEY, `key (1–${KEY_MAX} visible characters)`)
   let name: string | undefined
   if (input.name !== undefined) {
@@ -252,9 +295,9 @@ export function validateLaunchSpec(input: unknown): LaunchSpec {
   const harness = matching(input.harness, SLUG, "harness") ?? "opencode"
   const agent = matching(input.agent, AGENT, "agent")
   const model = matching(input.model, MODEL, "model (provider/model)", MODEL_MAX)
-  const workspace = validWorkspace(input.workspace)
-  const runtime = validRuntime(input.runtime, workspace)
-  const placement = validPlacement(input.placement)
+  const workspace = validWorkspace(input.workspace, wording)
+  const runtime = validRuntime(input.runtime, workspace, wording)
+  const placement = validPlacement(input.placement, wording)
   let prompt: string | undefined
   if (input.prompt !== undefined) {
     if (typeof input.prompt !== "string" || input.prompt.length > PROMPT_MAX || PROMPT_CONTROL.test(input.prompt)) throw invalid(`prompt is text of up to ${PROMPT_MAX} characters`)
@@ -263,7 +306,7 @@ export function validateLaunchSpec(input: unknown): LaunchSpec {
   // (CON-02) What the session is for: untrusted, sanitised to one line, at most INTENT_MAX characters.
   const intent = input.intent === undefined ? undefined : intentText(input.intent)
   const labels = validLabels(input.labels, "labels")
-  const end = validEnd(input.end)
+  const end = validEnd(input.end, wording)
   const profileProblem = input.agentProfile === undefined ? undefined : launchAgentProfileProblem(input.agentProfile)
   if (profileProblem) throw invalid(profileProblem)
   const agentProfile = input.agentProfile === undefined ? undefined : { profileID: (input.agentProfile as LaunchAgentProfile).profileID, version: (input.agentProfile as LaunchAgentProfile).version }

package/src/central/agent/launch-store.ts

@@ -11,6 +11,9 @@
 //   id) before the launch is stored. The same key with an equivalent body returns the existing launch (even an
 //   ended one, until it is pruned); a different body is invalid with a hint. A claim whose launch never appeared
 //   (its creator crashed) blocks the key for RESERVATION_MS, then is taken over.
+// - Waiting (FX-02): a queued launch carries why it waits (`waiting`, from placement): setWaiting writes it only
+//   while the launch is queued and only when it changed (no history step; `since` kept while the wait kind is the
+//   same), and mirrors it into `reason`; every transition clears it.
 // - Pruning: ended launches older than endedKeepMs, and all but the newest endedMax ended ones, are removed and
 //   their keys released. Live launches are never pruned.
 import { randomBytes } from "node:crypto"
@@ -26,6 +29,8 @@ export const ENDED_KEEP_MS = 7 * 86_400_000
 export const ENDED_MAX = 500
 /** How long a key claim without its launch (a creator that may still be writing) blocks the key. */
 export const RESERVATION_MS = 60_000
+/** The longest launcher label kept on a launch. */
+const LABEL_MAX = 100
 /** Reads of a key holder's launch: its creator may be between the claim and the write, so a miss is re-read. */
 const READS = 5
 /** Claim attempts (a stale claim is taken over between them). */
@@ -45,6 +50,21 @@ const NEXT: Record<LaunchState, readonly LaunchState[]> = {
   ended: [],
 }
 
+/** Why a queued launch waits (placement's Waiting without the launch ID). */
+export interface LaunchWaitReason {
+  /** capacity: a fitting node is full; no_match: no node fits; active: the user's maxActive is reached. */
+  readonly wait: "capacity" | "no_match" | "active"
+  /** The full text, for the user (names other launchers and machines). */
+  readonly reason: string
+  /** The text for the launch's own launcher (an app or session) when it differs: counts only, no other launchers or machine names. */
+  readonly shared?: string
+}
+
+/** A queued launch's wait, since it first waited for this kind of reason. */
+export interface LaunchWaiting extends LaunchWaitReason {
+  readonly since: number
+}
+
 export interface LaunchStep {
   readonly state: LaunchState
   readonly reason: string
@@ -59,6 +79,8 @@ export interface Launch {
   readonly spec: LaunchSpec
   /** Who launched it, as the caller describes them (e.g. `app:<token id>`, `ses_…`, `user`). */
   readonly by?: string
+  /** The launcher's label when it launched (an app token's label, a session's @name); never a secret. */
+  readonly byLabel?: string
   readonly state: LaunchState
   readonly reason: string
   /** When it entered its state. */
@@ -68,6 +90,8 @@ export interface Launch {
   readonly sessionID?: string
   readonly name?: string
   readonly artifacts?: Readonly<Record<string, unknown>>
+  /** Only while queued: why it waits (placement). */
+  readonly waiting?: LaunchWaiting
   readonly created: number
   readonly history: readonly LaunchStep[]
 }
@@ -138,7 +162,7 @@ export class LaunchStore {
    * Stores a new queued launch, or (same key, equivalent body) returns the existing one with created false.
    * Throws invalid (key reused with another body) or rate_limited (the key's launch is still being created).
    */
-  async create(userID: string, spec: LaunchSpec, options: { readonly by?: string } = {}): Promise<{ launch: Launch; created: boolean }> {
+  async create(userID: string, spec: LaunchSpec, options: { readonly by?: string; readonly byLabel?: string } = {}): Promise<{ launch: Launch; created: boolean }> {
     const id = this.newID()
     if (spec.key !== undefined) {
       const existing = await this.claimKey(userID, spec.key, id)
@@ -157,6 +181,7 @@ export class LaunchStore {
       owner: userID,
       spec,
       ...(options.by !== undefined ? { by: options.by } : {}),
+      ...(options.byLabel ? { byLabel: cleanReason(options.byLabel).slice(0, LABEL_MAX) } : {}),
       state: "queued",
       reason: "Queued",
       at,
@@ -190,8 +215,9 @@ export class LaunchStore {
       if (!NEXT[current.state].includes(to) || (input.from && !input.from.includes(current.state))) throw new LaunchTransitionError(current.state, to)
       checkDetails(to, input)
       const step: LaunchStep = { state: to, reason, at, ...(input.outcome !== undefined ? { outcome: input.outcome } : {}) }
+      const { waiting: _cleared, ...rest } = current
       return {
-        ...current,
+        ...rest,
         state: to,
         reason,
         at,
@@ -206,6 +232,33 @@ export class LaunchStore {
     return next!
   }
 
+  /**
+   * Records why a queued launch waits (undefined: it no longer waits). Writes nothing (resolves undefined) when the
+   * launch is not queued or the wait and reason are unchanged; else resolves with the launch as written. The
+   * reason shows as the launch's reason; `since` stays while the wait kind stays the same.
+   */
+  async setWaiting(userID: string, id: string, waiting: LaunchWaitReason | undefined): Promise<Launch | undefined> {
+    const reason = waiting ? cleanReason(waiting.reason) : undefined
+    const shared = waiting?.shared !== undefined ? cleanReason(waiting.shared) : undefined
+    let written = false
+    const next = await updateVersioned<Launch>(this.deps.state, userID, LAUNCHES, id, (current) => {
+      written = false
+      if (!current || current.state !== "queued") return undefined
+      const was = current.waiting
+      if (!waiting) {
+        if (!was) return undefined
+        const { waiting: _cleared, ...rest } = current
+        written = true
+        return { ...rest, reason: "Queued" }
+      }
+      if (was && was.wait === waiting.wait && was.reason === reason && was.shared === shared) return undefined
+      written = true
+      const since = was?.wait === waiting.wait ? was.since : this.now()
+      return { ...current, reason: reason!, waiting: { wait: waiting.wait, reason: reason!, ...(shared !== undefined ? { shared } : {}), since } }
+    })
+    return written ? next : undefined
+  }
+
   /** Removes ended launches past endedKeepMs or beyond the newest endedMax; resolves with the removed ids. */
   async prune(userID: string): Promise<string[]> {
     const { state } = this.deps

package/src/central/agent/message-limits.ts

@@ -1,9 +1,27 @@
 // Loop protection for agent messages (design §3.4), over the backend interfaces with an injected clock.
 //
-// - HopTracker: every message carries a hop. A session's (or app's) depth is the deepest hop that reached it
-//   since its last human turn; what it sends carries depth + 1. The user sends hop 0, and a hop-0 message (or a
-//   human turn in the session) resets the depth. A hop over HOP_CAP is delivered without waking and the user
-//   is alerted (the delivery engine does both).
+// - HopTracker: every message carries a hop. A session's depth is the deepest hop that reached it since its last
+//   human turn; what it sends (msg, ask, reply, decline) carries depth + 1. The user sends hop 0, and a hop-0
+//   message (or a human turn in the session) resets the depth. A hop over HOP_CAP is delivered without waking and
+//   the user is alerted (the delivery engine does both).
+// - Apps (app:<tokenID>, including the hub's own app:concierge, the workspace coordinator and team intake) keep NO
+//   depth (S1, bug wge0vjdz; decision in Brain, tag fixup-0.8.1): one token serves many unrelated conversations and
+//   has no human turn to reset it, so a shared depth grew by 2 per ask/reply round trip and silenced the app for
+//   24 h after 4 of them. Instead the hop is per conversation: a NEW msg or ask from an app is hop 1, a reply or
+//   decline from an app is the hop of the message it answers + 1, and messages to an app raise nothing. Reply
+//   ping-pong through an app still counts up (the session side keeps its depth) and hits HOP_CAP. Session-to-session
+//   behaviour is unchanged.
+// - Relay depth (0.8.1 verify finding 1): so an app cannot launder a chain by relaying between sessions as NEW
+//   messages (A → app → B → app → A, each hop 1), an app remembers, per (user, app) and per sending session, the
+//   deepest hop it RECEIVED from a session in the last RELAY_WINDOW_MS (5 min; refreshed by each message, then it
+//   fades). Its new msg/ask carries that relay depth + 1 (else 1), counting only what OTHER sessions sent it: what
+//   the recipient itself sent is the same conversation, not a relay, so a one-to-one app conversation stays at hop 1
+//   at any pace (the S1 case; an app answering one session with new messages forever is held by the pair limit and
+//   the recipient's wake budget instead). A relay loop through an app thus reaches HOP_CAP after ~8 hops. Only
+//   session senders count (the user's hop 0 and other apps do not), and the hub's own parties (HUB_APP_TOKENS:
+//   app:concierge, the workspace coordinator, team intake) keep none: they send on events and submissions, not on
+//   the messages they receive (team intake carries the submitter's depth + 1 itself, SendOptions.chainHop). It is
+//   not a persistent depth: messages to an app still raise nothing beyond this time-boxed memory.
 // - MessageLimiter: fixed windows aligned to the clock (so retryAfter is exact): messages per sender→recipient
 //   pair and per user (refused with rate_limited), and wakes per recipient (exhausted: deliver without waking).
 import type { Clock, Counters, StateStore } from "../backend/types"
@@ -18,26 +36,67 @@ export const HOP_TTL_MS = 24 * 60 * 60_000
 
 export const overHopCap = (hop: number): boolean => hop > HOP_CAP
 
+/** How long what an app received from a session raises the app's new messages (relay depth). */
+export const RELAY_WINDOW_MS = 5 * 60_000
+/** Sending sessions remembered per (user, app); the oldest go first. */
+export const RELAY_SOURCES_MAX = 32
+/** The hub's own app parties (app:<tokenID>): no relay depth (see the header). */
+export const HUB_APP_TOKENS: ReadonlySet<string> = new Set(["concierge", "workspace-coordinator", "team-intake"])
+
 /** StateStore collection: partyKey → HopDepth. */
 const HOPS = "message-hops"
+/** StateStore collection: partyKey of an app → RelayDepth. */
+const RELAYS = "message-relays"
 
 interface HopDepth {
   readonly depth: number
   readonly at: number
 }
 
+interface RelayDepth {
+  /** Sending session → the deepest hop it sent the app, and when it last sent one. */
+  readonly sources: Readonly<Record<string, HopDepth>>
+}
+
+/** What a message continues: the message a reply or decline answers, and its recipient. */
+export interface HopContext {
+  readonly answering?: { readonly hop: number }
+  readonly to?: Party
+}
+
+const relays = (party: Party): party is Extract<Party, { kind: "app" }> => party.kind === "app" && !HUB_APP_TOKENS.has(party.tokenID)
+
 export class HopTracker {
   private readonly state: StateStore
   private readonly now: Clock
+  private readonly relayWindowMs: number
 
-  constructor(deps: { readonly state: StateStore; readonly now?: Clock }) {
+  constructor(deps: { readonly state: StateStore; readonly now?: Clock; readonly relayWindowMs?: number }) {
     this.state = deps.state
     this.now = deps.now ?? Date.now
+    this.relayWindowMs = deps.relayWindowMs ?? RELAY_WINDOW_MS
+  }
+
+  /**
+   * The hop a message from `from` carries. The user: 0. An app: a reply or decline (`answering`) is the answered
+   * message's hop + 1; a new msg or ask is its relay depth toward `to` + 1 (see the header). A session: its depth + 1.
+   */
+  async next(userID: string, from: Party, context: HopContext = {}): Promise<number> {
+    if (from.kind === "user") return 0
+    if (from.kind === "app") return (context.answering ? context.answering.hop : await this.relayDepth(userID, from, context.to)) + 1
+    return (await this.depth(userID, from)) + 1
   }
 
-  /** The hop a new message from `from` carries. */
-  async next(userID: string, from: Party): Promise<number> {
-    return from.kind === "user" ? 0 : (await this.depth(userID, from)) + 1
+  /** The deepest hop sessions other than `to` sent the app within the relay window (0: none; hub parties: 0). */
+  async relayDepth(userID: string, app: Party, to?: Party): Promise<number> {
+    if (!relays(app)) return 0
+    const entry = (await this.state.get<RelayDepth>(userID, RELAYS, partyKey(app)))?.value
+    const skip = to?.kind === "session" ? to.sessionID : undefined
+    let deepest = 0
+    for (const [sessionID, source] of Object.entries(entry?.sources ?? {})) {
+      if (sessionID !== skip && this.relayLive(source)) deepest = Math.max(deepest, source.depth)
+    }
+    return deepest
   }
 
   /** The deepest hop that reached the party since its last human turn (0: none, or forgotten). */
@@ -45,9 +104,13 @@ export class HopTracker {
     return this.live((await this.state.get<HopDepth>(userID, HOPS, partyKey(party)))?.value)
   }
 
-  /** A message with `hop` reached the party. */
-  async received(userID: string, to: Party, hop: number): Promise<void> {
-    if (to.kind === "user") return
+  /**
+   * A message with `hop` from `from` reached the party. Sessions keep a depth; an app (not a hub party) only
+   * remembers, for RELAY_WINDOW_MS, what each session sent it (relay depth); the user keeps nothing.
+   */
+  async received(userID: string, to: Party, hop: number, from?: Party): Promise<void> {
+    if (relays(to) && from?.kind === "session") return this.relayed(userID, to, from.sessionID, hop)
+    if (to.kind !== "session") return
     const at = this.now()
     await updateVersioned<HopDepth>(this.state, userID, HOPS, partyKey(to), (current) => ({ depth: hop === 0 ? 0 : Math.max(this.live(current), hop), at }))
   }
@@ -57,6 +120,21 @@ export class HopTracker {
     await this.state.delete(userID, HOPS, partyKey({ kind: "session", sessionID }))
   }
 
+  private async relayed(userID: string, app: Party, sessionID: string, hop: number): Promise<void> {
+    const at = this.now()
+    await updateVersioned<RelayDepth>(this.state, userID, RELAYS, partyKey(app), (current) => {
+      const live = Object.entries(current?.sources ?? {}).filter(([id, source]) => id !== sessionID && this.relayLive(source))
+      const previous = current?.sources[sessionID]
+      const depth = Math.max(previous && this.relayLive(previous) ? previous.depth : 0, hop)
+      const kept = live.sort((a, b) => b[1].at - a[1].at).slice(0, RELAY_SOURCES_MAX - 1)
+      return { sources: Object.fromEntries([[sessionID, { depth, at }], ...kept]) }
+    })
+  }
+
+  private relayLive(source: HopDepth): boolean {
+    return this.now() - source.at < this.relayWindowMs
+  }
+
   private live(entry: HopDepth | undefined): number {
     return entry && this.now() - entry.at < HOP_TTL_MS ? entry.depth : 0
   }

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

@@ -154,7 +154,13 @@ function decisionFields(body: Body): Omit<AskInput, "question" | "about" | "expi
   return out as Omit<AskInput, "question" | "about" | "expiresInMs"> & { urgency?: Urgency; tier?: Tier; about?: string[] }
 }
 
-const sentView = ({ message, delivery }: Sent) => ({ message, ...(delivery ? { delivery } : {}) })
+/** The stored message, how it was delivered and, for a session recipient, whether it woke it (and why not). */
+const sentView = ({ message, delivery, woke, wakeSkipped }: Sent) => ({
+  message,
+  ...(delivery ? { delivery } : {}),
+  ...(woke === undefined ? {} : { woke }),
+  ...(wakeSkipped ? { wakeSkipped } : {}),
+})
 
 export function messageRoutes(deps: MessageDeps): AgentRoute[] {
   const { delivery, feed } = deps
@@ -270,8 +276,7 @@ export function messageRoutes(deps: MessageDeps): AgentRoute[] {
         if (decisionAsked) throw new AgentError("invalid", "options, recommendation, urgency, tier, deadline, onTimeout and about are for asks to @me")
         const sent = await send(user.id, actor, to, "ask", text, options, all)
         if (all) return ok({ sent: sent.map(sentView) }, 201)
-        const { message, delivery: how } = sent[0]!
-        return ok({ ...sentView({ message, ...(how ? { delivery: how } : {}) }), ...(await settled(user.id, message, wait, request.signal)) }, 201)
+        return ok({ ...sentView(sent[0]!), ...(await settled(user.id, sent[0]!.message, wait, request.signal)) }, 201)
       },
     },
     {

package/src/central/agent/messages.ts

@@ -42,9 +42,10 @@ export type MessageKind = "msg" | "ask" | "reply" | "decline"
 export type MessageState = "sent" | "open" | "answered" | "declined" | "expired"
 /**
  * How a message reached its recipient (design §3.3), recorded by the delivery engine. (CON-10) "dropped": it was
- * pending for a session that ended for good (a retired Concierge session) and will never be delivered.
+ * pending for a session that ended for good (a retired Concierge session) and will never be delivered. "expired": it
+ * was pending for PENDING_MS (its recipient stayed offline or busy) and will never be delivered; its sender was told.
  */
-export type Delivery = "steer" | "turn" | "queued" | "retained" | "pending" | "dropped"
+export type Delivery = "steer" | "turn" | "queued" | "retained" | "pending" | "dropped" | "expired"
 
 export interface Message {
   readonly id: string