@huynle/hub 0.7.4 → 0.8.1

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

@@ -25,6 +25,7 @@
 //   user, who owns every party); others get not_found.
 // - Messaging off (UserRecord.agent.messagingPaused): msg, ask, reply and decline answer paused; reading works.
 // - Every stored message is published on the MessageFeed (GET /api/agent/watch 'message' events, waiters).
+import { boundedJson } from "./body"
 import { Feed } from "../cluster/feed"
 import type { Store } from "../store"
 import type { AgentActor } from "./actor"
@@ -70,7 +71,7 @@ const READ = { session: true, scope: "messages:read" } as const
 type Body = Record<string, unknown>
 
 async function bodyOf(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", "Body must be a JSON object")
   return body as Body
 }
@@ -153,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
@@ -269,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

@@ -7,6 +7,7 @@
 // - Caps: each party (session, the user, an app) keeps its latest SESSION_MESSAGES; a message no party keeps
 //   is deleted. Per user, at most USER_MESSAGES messages / USER_BYTES; over either, the oldest go (down to
 //   90%). Eviction keeps open asks while anything else can go.
+//   Deleting a message records the newest evicted `at` (retention(): the graph's `retention.truncated`, HWA-31).
 // - Asks: open → answered (a reply) | declined | expired (at expiresAt, seen on read; expire() persists it).
 //   The first answer wins (version-checked write); later ones get `gone`.
 // - Replies and declines come only from the recipient (anyone else: not_found, like a foreign id) and go to
@@ -39,8 +40,12 @@ export const INBOX_RECENT = 50
 export type MessageKind = "msg" | "ask" | "reply" | "decline"
 /** `sent` for msg/reply/decline; asks are open until answered, declined or expired. */
 export type MessageState = "sent" | "open" | "answered" | "declined" | "expired"
-/** How a message reached its recipient (design §3.3), recorded by the delivery engine. */
-export type Delivery = "steer" | "turn" | "queued" | "retained" | "pending"
+/**
+ * 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. "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" | "expired"
 
 export interface Message {
   readonly id: string
@@ -117,11 +122,18 @@ export interface Usage {
   readonly bytes: number
 }
 
+/** What the store retains (the interaction graph's retention disclosure, HWA-31). */
+export interface Retention extends Usage {
+  /** The newest `at` of a message the caps deleted; absent while nothing was evicted. */
+  readonly evictedAt?: number
+}
+
 const MESSAGES = "messages"
 const INDEX = "message-index"
 const USAGE = "message-usage"
 const MUTES = "message-mutes"
 const USAGE_KEY = "total"
+const EVICTED_KEY = "evicted"
 /** Version-checked attempts to detach a contended message. */
 const DETACH_ATTEMPTS = 16
 
@@ -261,6 +273,18 @@ export class Messages {
     return (await this.state.get<Usage>(userID, USAGE, USAGE_KEY))?.value ?? { count: 0, bytes: 0 }
   }
 
+  /** Every retained message of the user, oldest first, as of now: one scan, for whole-user projections. */
+  async all(userID: string): Promise<Message[]> {
+    const entries = await this.state.list<StoredMessage>(userID, MESSAGES)
+    return entries.map((entry) => this.view(entry.value.message)).sort((a, b) => a.at - b.at || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  }
+
+  /** Usage and the newest evicted message's time (older interactions may be missing). */
+  async retention(userID: string): Promise<Retention> {
+    const [usage, evicted] = await Promise.all([this.usage(userID), this.state.get<number>(userID, USAGE, EVICTED_KEY)])
+    return { ...usage, ...(evicted ? { evictedAt: evicted.value } : {}) }
+  }
+
   /** Records how the message was delivered; undefined when there is no such message. */
   async setDelivery(userID: string, id: string, delivery: Delivery): Promise<Message | undefined> {
     const at = this.now()
@@ -431,6 +455,8 @@ export class Messages {
         if ((await this.state.put<StoredMessage>(userID, MESSAGES, id, { ...current.value, indexed }, { ifVersion: current.version })).ok) return
       } else if ((await this.state.delete(userID, MESSAGES, id, { ifVersion: current.version })).ok) {
         await this.addUsage(userID, -1, -current.value.bytes)
+        const at = current.value.message.at
+        await updateVersioned<number>(this.state, userID, USAGE, EVICTED_KEY, (marked) => (marked !== undefined && marked >= at ? undefined : at))
         return
       }
     }

package/src/central/agent/names.ts

@@ -4,7 +4,7 @@
 
 import { NAME_MAX, validName } from "../../../packages/sdk/src/address.ts"
 
-export { NAME_MAX, parseAddress, validName, type Address } from "../../../packages/sdk/src/address.ts"
+export { addressProblem, NAME_MAX, parseAddress, validName, type Address, type AddressProblem } from "../../../packages/sdk/src/address.ts"
 
 /**
  * OpenCode's fallback titles: "New session" / "Child session" (display labels) and the historical
@@ -43,10 +43,20 @@ export function withSuffix(base: string, taken: (name: string) => boolean): stri
 export const isReservedName = (name: string): boolean => name === "me"
 
 /** Roles only the user may claim in phase 1 (grants including `roles` come in phase 3). */
-const RESERVED_ROLES = ["orchestrator"]
+const RESERVED_ROLES = ["orchestrator", "concierge"]
 
 export const isReservedRole = (role: string): boolean => RESERVED_ROLES.some((prefix) => role.startsWith(prefix))
 
+/**
+ * (CON-04) Roles only the hub itself claims and releases (reserved too): not the user, a session, an app under a
+ * `roles` grant or a launch spec. `concierge`: the Concierge service holds it for the user's current Concierge.
+ */
+const MANAGED_ROLES = ["concierge"]
+
+export const isManagedRole = (role: string): boolean => MANAGED_ROLES.some((prefix) => role.startsWith(prefix))
+
+export const MANAGED_ROLE_MESSAGE = (role: string) => `@@${role} is managed by the hub: use Settings → Concierge`
+
 /** The longest derived name: a few words, short enough to type and read in an address (@send-hello-to-session). */
 export const DERIVED_NAME_MAX = 24
 /** At most this many words of the title make a derived name. */

package/src/central/agent/placement.ts

@@ -5,7 +5,7 @@
 //   announcing "launch" (each harness has its own service spoke: a Claude Code one never serves an OpenCode launch),
 //   and for openshell launches the node feature "sandbox" (it starts and stops the harness itself; the sandbox's
 //   launch-bound spoke creates the session, so no service spoke is needed)), then the placement's machine and labels (mode require: hard; prefer: ranking only), then
-//   free slots (capacity minus used minus reservations). The best node has the preference, then most free slots,
+//   free slots (capacity minus used minus reservations; a capacity wait gives each full node's counts). The best node has the preference, then most free slots,
 //   then the lowest machine ID. A launch that cannot be placed waits for capacity (a fitting node is full) or for a
 //   match (no node fits; the reason names each node's first problem).
 // - Admission (per user, hub.json agents.launches): admit() refuses a new launch with rate_limited while maxQueued
@@ -17,13 +17,17 @@
 //   the end. A pass first returns launches left placing by a dead holder to the queue, then walks queued launches
 //   oldest first: while fewer than maxActive are placing/provisioning/running, each is matched against the
 //   user's nodes and moved queued → placing → provisioning on the machine. A launch that cannot be placed now is
-//   reported as waiting and does not hold back later ones; earlier launches always pick first. Reservations are
+//   reported as waiting and does not hold back later ones; earlier launches always pick first. The active wait names
+//   who holds the cap (counts by launcher label; a revoked app token's launches are flagged). The Concierge's own
+//   launch (by app:concierge with label hub/system=concierge) neither counts toward maxActive nor waits for it; it
+//   still takes a node slot. Reservations are
 //   launches provisioning or running on a machine that its node does not report (yet); slots taken in the pass
 //   count at once. Reasons go on the launch only when it moves; waiting reasons are returned for the engine.
 // - PlacementLoop runs passes: kick(user) when something changed (a launch queued or ended, a node connected or
 //   reported capacity, a service spoke came), coalescing kicks during a pass into one more, plus a sweep over
 //   users() every intervalMs for whatever a kick missed (e.g. another process held the lease). Each placed launch
-//   goes to onPlaced (the launch engine starts provisioning); failures go to onError and never stop the loop.
+//   goes to onPlaced (the launch engine starts provisioning), then the pass's waiting launches to onWaiting (the
+//   engine stores the reason on the launch); failures go to onError and never stop the loop.
 // - Node and spoke info come through PlacementNodes / PlacementSpokes, which the launch engine adapts from the
 //   NodeRegistry and the Registry; memory is not matched (a spec has no memory need yet).
 import type { NodeCapacity, NodeRuntimeInfo } from "../../protocol"
@@ -62,7 +66,7 @@ export interface Candidate extends PlacementNode {
 
 export type Match =
   | { readonly ok: true; readonly node: PlacementNode; readonly preferred: boolean }
-  | { readonly ok: false; readonly wait: "capacity" | "no_match"; readonly reason: string }
+  | { readonly ok: false; readonly wait: "capacity" | "no_match"; readonly reason: string; readonly shared?: string }
 
 const label = (node: PlacementNode) => node.name ?? node.machineID
 
@@ -102,13 +106,13 @@ export function matchNode(userID: string, spec: LaunchSpec, candidates: readonly
   const own = candidates.filter((node) => node.owner === userID)
   if (own.length === 0) return { ok: false, wait: "no_match", reason: "No node is connected" }
   const require = spec.placement.mode === "require"
-  const problems: string[] = []
+  const problems: { node: string; problem: string }[] = []
   const full: Candidate[] = []
   const free: { node: Candidate; preferred: boolean }[] = []
   for (const node of own) {
     const placement = placementProblem(spec, node)
     const problem = hardProblem(spec, node) ?? (require ? placement : undefined)
-    if (problem) problems.push(`${label(node)} ${problem}`)
+    if (problem) problems.push({ node: label(node), problem })
     else if (freeSlots(node) <= 0) full.push(node)
     else free.push({ node, preferred: placement === undefined })
   }
@@ -122,8 +126,17 @@ export function matchNode(userID: string, spec: LaunchSpec, candidates: readonly
     const best = free[0]!
     return { ok: true, node: best.node, preferred: best.preferred }
   }
-  if (full.length > 0) return { ok: false, wait: "capacity", reason: `Waiting for a free slot on ${full.map(label).join(", ")}` }
-  return { ok: false, wait: "no_match", reason: `No node fits: ${problems.join("; ")}` }
+  if (full.length > 0) {
+    const used = (node: Candidate) => `${node.used.slots}/${node.capacity.slots} used, ${node.reserved} reserved`
+    return {
+      ok: false,
+      wait: "capacity",
+      reason: `Waiting for a free slot on ${full.map((node) => `${label(node)} (${used(node)})`).join(", ")}`,
+      // An app or session may not see the user's machines: no names.
+      shared: full.length === 1 ? `Waiting for a free slot on the fitting machine (${used(full[0]!)})` : `Waiting for a free slot on ${full.length} fitting machines (all full)`,
+    }
+  }
+  return { ok: false, wait: "no_match", reason: `No node fits: ${problems.map((p) => `${p.node} ${p.problem}`).join("; ")}`, shared: `No machine fits: ${[...new Set(problems.map((p) => p.problem))].join("; ")}` }
 }
 
 
@@ -157,6 +170,27 @@ export interface PlacementSpokes {
   launchHarnesses(userID: string, machineID: string): readonly string[] | Promise<readonly string[]>
 }
 
+/** Who launched what (the launch engine adapts the user's app tokens). */
+export interface PlacementLaunchers {
+  /** Whether the launcher (`app:<token id>`) was revoked: its launches still count, flagged. */
+  revoked(userID: string, by: string): boolean
+}
+
+/** The hub's own Concierge party (packages/protocol concierge.ts CONCIERGE_PARTY) and its launch label. */
+const CONCIERGE_BY = "app:concierge"
+/** The Concierge's own launch: neither counts toward nor waits for maxActive (it still takes a node slot). */
+export const isSystemLaunch = (launch: Pick<Launch, "by" | "spec">): boolean => launch.by === CONCIERGE_BY && launch.spec.labels["hub/system"] === "concierge"
+
+/** A launcher as a waiting reason names it: you, app "label" (or its token ID), a session's label or ID. */
+function launcherText(launch: Pick<Launch, "by" | "byLabel">, revoked: boolean): string {
+  const { by, byLabel } = launch
+  let text: string
+  if (by === undefined || by === "user") text = "you"
+  else if (by.startsWith("app:")) text = byLabel ? `app ${JSON.stringify(byLabel)}` : `app ${by.slice(4)}`
+  else text = byLabel ?? by
+  return revoked ? `${text} (launcher revoked)` : text
+}
+
 export interface PlacementDeps {
   readonly store: LaunchStore
   readonly nodes: PlacementNodes
@@ -168,6 +202,8 @@ export interface PlacementDeps {
   readonly caps?: HubLaunches
   readonly now?: Clock
   readonly leaseMs?: number
+  /** Revoked launchers (flagged in the active wait); without it none is. */
+  readonly launchers?: PlacementLaunchers
 }
 
 /** A launch the pass placed: it is now provisioning on the node's machine. */
@@ -184,7 +220,10 @@ export interface Waiting {
   readonly launchID: string
   /** capacity: a fitting node is full; no_match: no node fits; active: the user's maxActive is reached. */
   readonly wait: "capacity" | "no_match" | "active"
+  /** For the user: names other launchers and machines. */
   readonly reason: string
+  /** For the launch's own launcher (app or session), when it differs: counts only, no names. */
+  readonly shared?: string
 }
 
 /** One pass. leased false: another holder has the user's lease, or it was lost mid-pass (placed: before that). */
@@ -251,16 +290,18 @@ export class Placement {
       launches = await store.list(userID)
       const queued = launches.filter((l) => l.state === "queued")
       if (queued.length === 0) return { leased: true, placed, waiting }
-      let active = launches.filter((l) => ACTIVE.includes(l.state)).length
+      const counted = launches.filter((l) => ACTIVE.includes(l.state) && !isSystemLaunch(l))
+      let active = counted.length
       const candidates = await this.candidates(userID, launches)
       for (const launch of queued) {
-        if (active >= this.caps.maxActive) {
-          waiting.push({ launchID: launch.id, wait: "active", reason: `Waiting: ${active} launches are active (the most per user)` })
+        const system = isSystemLaunch(launch)
+        if (!system && active >= this.caps.maxActive) {
+          waiting.push({ launchID: launch.id, wait: "active", ...this.activeReason(userID, counted, launch) })
           continue
         }
         const match = matchNode(userID, launch.spec, candidates)
         if (!match.ok) {
-          waiting.push({ launchID: launch.id, wait: match.wait, reason: match.reason })
+          waiting.push({ launchID: launch.id, wait: match.wait, reason: match.reason, ...(match.shared !== undefined ? { shared: match.shared } : {}) })
           continue
         }
         const name = match.node.name ?? match.node.machineID
@@ -268,14 +309,21 @@ export class Placement {
         const placing = await skipGone(store.transition(userID, launch.id, "placing", { reason: `Placing on ${name}`, from: ["queued"] }))
         if (!placing) continue
         if (!(await held())) return lost()
-        const provisioning = await store.transition(userID, launch.id, "provisioning", {
-          reason: `Placed on ${name}${match.preferred ? "" : " (preferred placement not available)"}`,
-          machineID: match.node.machineID,
-          from: ["placing"],
-        })
+        // A stop between the two steps (e.g. the Concierge reaping an orphan) wins: skipped, not an error.
+        const provisioning = await skipGone(
+          store.transition(userID, launch.id, "provisioning", {
+            reason: `Placed on ${name}${match.preferred ? "" : " (preferred placement not available)"}`,
+            machineID: match.node.machineID,
+            from: ["placing"],
+          }),
+        )
+        if (!provisioning) continue
         const index = candidates.findIndex((c) => c.machineID === match.node.machineID)
         candidates[index] = { ...candidates[index]!, reserved: candidates[index]!.reserved + 1 }
-        active++
+        if (!system) {
+          active++
+          counted.push(provisioning)
+        }
         placed.push({ userID, launch: provisioning, node: match.node, preferred: match.preferred, fence: lease.fence })
       }
       return { leased: true, placed, waiting }
@@ -284,6 +332,25 @@ export class Placement {
     }
   }
 
+  /**
+   * The user's text names who holds the cap, most first ("Waiting: 4 of 4 active launches: 3 by app "ci", 1 by you;
+   * …"); the launcher's own text gives counts only: its own launches and the others'.
+   */
+  private activeReason(userID: string, active: readonly Launch[], waiting: Launch): { reason: string; shared: string } {
+    const own = active.filter((l) => (l.by ?? "user") === (waiting.by ?? "user")).length
+    const others = active.length - own
+    const split = [own ? `${own} yours` : undefined, others ? `${others} by others` : undefined].filter(Boolean).join(", ")
+    const shared = `Waiting: ${active.length} of ${this.caps.maxActive} active launches (${split}); ask the user to stop one or raise agents.launches.maxActive`
+    const counts = new Map<string, number>()
+    for (const launch of active) {
+      const revoked = launch.by !== undefined && launch.by.startsWith("app:") && this.deps.launchers?.revoked(userID, launch.by) === true
+      const text = launcherText(launch, revoked)
+      counts.set(text, (counts.get(text) ?? 0) + 1)
+    }
+    const holders = [...counts].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)).map(([text, n]) => `${n} by ${text}`)
+    return { reason: `Waiting: ${active.length} of ${this.caps.maxActive} active launches: ${holders.join(", ")}; stop one or raise agents.launches.maxActive`, shared }
+  }
+
   /** The user's nodes with their service spoke and reservations (placed launches the node does not report yet). */
   private async candidates(userID: string, launches: readonly Launch[]): Promise<Candidate[]> {
     const nodes = (await this.deps.nodes.nodes(userID)).filter((node) => node.owner === userID)
@@ -323,6 +390,8 @@ export interface PlacementLoopDeps {
   readonly users: () => Promise<readonly string[]>
   /** The engine takes a placed (provisioning) launch from here. */
   readonly onPlaced: (placed: Placed) => void | Promise<void>
+  /** The launches the pass could not place, with why (only for a pass that held the user's lease). */
+  readonly onWaiting?: (userID: string, waiting: readonly Waiting[]) => void | Promise<void>
   readonly onError?: (cause: unknown, userID?: string) => void
   readonly timers?: Timers
   readonly intervalMs?: number
@@ -415,5 +484,11 @@ export class PlacementLoop {
         this.onError(cause, userID)
       }
     }
+    if (!result.leased || !this.deps.onWaiting) return
+    try {
+      await this.deps.onWaiting(userID, result.waiting)
+    } catch (cause) {
+      this.onError(cause, userID)
+    }
   }
 }