@huynle/hub 0.10.1 → 0.11.0

package/src/central/agent/delivery.ts

@@ -58,7 +58,7 @@ import { type Party, type PartyInfo, partyFromActor, partyKey, partyLabel, rende
 import { noticeOnly } from "../../../packages/sdk/src/envelope.ts"
 import { AgentError } from "./errors"
 import { type ExpiredReason, parseNotAfter } from "./not-after"
-import { HOP_CAP, HopTracker, MessageLimiter, type MessageLimits, overHopCap } from "./message-limits"
+import { HOP_CAP, HOP_CAP_CEILING, HopTracker, MessageLimiter, type MessageLimits } from "./message-limits"
 import { parseAddress } from "./names"
 import { type Delivery as DeliveryState, type Message, Messages, newMessageID } from "./messages"
 
@@ -126,10 +126,16 @@ 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
+  /** The first over-cap message between two seats of a team, once per persistent chain. */
+  readonly teamHopCap?: (userID: string, input: { readonly teamID: string; readonly sender: string; readonly recipient: string; readonly limit: number }) => Promise<void>
+  /** A quiet, hub-authored note to the team's entry seat; never counts a message hop. */
+  readonly teamHopNotice?: (userID: string, teamID: string) => Promise<string | undefined>
   /** 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>
+  /** Configured global agent-only wake hop limit (default 8, absolute ceiling 100). */
+  readonly hopLimit?: number
   /** 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). */
@@ -141,7 +147,7 @@ export interface DeliveryDeps {
   /** How often the re-wake loop runs (default REWAKE_TICK_MS). */
   readonly tickMs?: number
   /** Team communication policy (HWA-34, ../teams/policy.ts): team addresses and verdicts before anything is stored. */
-  readonly teams?: Pick<TeamPolicy, "prepare" | "answer">
+  readonly teams?: Pick<TeamPolicy, "prepare" | "answer" | "hopContext">
   /** (CON-04) Inbound policy per recipient session (the Concierge inbound rule), checked next to team policy. */
   readonly inbound?: InboundPolicy
 }
@@ -273,6 +279,7 @@ export class Delivery {
   private readonly owner: string
 
   constructor(deps: DeliveryDeps) {
+    if (deps.hopLimit !== undefined && (!Number.isSafeInteger(deps.hopLimit) || deps.hopLimit < 1 || deps.hopLimit > HOP_CAP_CEILING)) throw new Error(`hopLimit must be 1–${HOP_CAP_CEILING}`)
     this.deps = deps
     const now = (this.now = deps.now ?? Date.now)
     this.timers = deps.timers ?? defaultTimers
@@ -348,6 +355,17 @@ export class Delivery {
     return this.hops.humanTurn(userID, sessionID)
   }
 
+  async notifyTeamHopCap(userID: string, teamID: string, decisionID: string): Promise<void> {
+    const entry = await this.deps.teamHopNotice?.(userID, teamID)
+    if (!entry) return
+    const id = this.newID()
+    await this.request(userID, entry, {
+      op: "deliver", sessionID: entry, messageID: id, wake: false,
+      text: `[hub] notice · Team messages reached the hop cap. The user has a Renew Decision ${decisionID}; wait for their choice. · ${id}`,
+      meta: { kind: "msg", from: "hub", to: entry, delivery: "queue" },
+    })
+  }
+
   /** Delivers the user's pending messages whose sessions a deliver-capable spoke reports now, oldest first. */
   /** Delivers the user's pending messages (only `sessionID`'s when given); flushes run one at a time per user. */
   flush(userID: string, sessionID?: string): Promise<void> {
@@ -489,8 +507,12 @@ export class Delivery {
     await this.hops.received(userID, recipient, hop, from)
     this.users.add(userID)
     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 team = "team" in resolved ? resolved.team : undefined
+    const explicitTeamID = typeof team === "object" && team !== null && "teamID" in team && typeof team.teamID === "string" ? team.teamID : undefined
+    const context = await this.deps.teams?.hopContext(userID, from, recipient, explicitTeamID)
+    const limit = Math.min(context?.limit ?? this.deps.hopLimit ?? HOP_CAP, this.deps.hopLimit ?? HOP_CAP)
+    const skipped = await this.wakeFor(userID, message, unwanted, limit, context?.teamID)
+    if (kind === "ask" && unwanted === undefined && hop <= limit) {
       const rewake: Rewake = { messageID: message.id, sessionID, reminders: 0, nextAt: message.at + backoff(0) }
       await this.deps.state.put(userID, REWAKE, message.id, rewake)
     }
@@ -612,7 +634,8 @@ export class Delivery {
     if (message.recipient.kind !== "session") return answered
     const sessionID = message.recipient.sessionID
     const unwanted: WakeSkip | undefined = options.wake === false ? "wake_false" : this.isSubagent(userID, sessionID) ? "subagent" : undefined
-    const skipped = await this.wakeFor(userID, message, unwanted)
+    const context = await this.deps.teams?.hopContext(userID, from, message.recipient)
+    const skipped = await this.wakeFor(userID, message, unwanted, Math.min(context?.limit ?? this.deps.hopLimit ?? HOP_CAP, this.deps.hopLimit ?? HOP_CAP), context?.teamID)
     return { ...(await this.deliver(userID, message, sessionID, skipped, true)), original: answered.original }
   }
 
@@ -620,16 +643,23 @@ export class Delivery {
    * 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> {
+  private async wakeFor(userID: string, message: Message, unwanted: WakeSkip | undefined, limit = this.deps.hopLimit ?? HOP_CAP, teamID?: string): 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) {
+    if (message.hop > limit) {
+      if (teamID && message.from.kind === "session") {
+        try {
+          await this.deps.teamHopCap?.(userID, { teamID, sender: message.from.sessionID, recipient: message.recipient.sessionID, limit })
+        } catch (cause) {
+          // The message has already been stored. A failed Decision must not prevent delivery or wake it.
+          console.error(`[hub] team hop-cap alert failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+        }
+      } else if (message.hop === limit + 1) {
         this.deps.alert?.(userID, {
           kind: "hopCap",
           sessionID: message.recipient.sessionID,
           messageID: message.id,
-          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`,
+          text: `Agent messages went ${limit} hops without you (latest: ${partyLabel(message.from)} → ${partyLabel(message.recipient)}); further messages in this chain no longer wake anyone`,
         })
       }
       return "hop_cap"

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

@@ -1,6 +1,7 @@
 // /api/agent/grants (design §5, §7): the user's grants. User actors only (allow {}): the device cookie (same-origin
 // writes, checked by the agent framework) or a device token. A session or app token never creates, edits, reads
-// or revokes a grant (escalation guard). Answers {grant} / {grants}, never cached; the owner is not echoed.
+// or revokes a grant on the admin routes (escalation guard). /mine is holder-scoped; a user has no holder.
+// Answers {grant} / {grants}, never cached; the owner is not echoed.
 //
 //   POST   /api/agent/grants       create (201)          GET /api/agent/grants      list, newest first
 //   GET    /api/agent/grants/:id   one grant             PUT /api/agent/grants/:id  replace (holder fixed)
@@ -37,6 +38,18 @@ export function grantRoutes(grants: Grants, now: () => number = Date.now, reques
           } satisfies AgentRoute,
         ]
       : []),
+    {
+      method: "GET", path: `${PREFIX}/mine`, allow: { session: true, scope: "messages:read" },
+      handle: async ({ actor }) => Response.json({ grants: (await grants.held(actor)).map((g) => grantView(g, now())) }, { headers: NO_STORE }),
+    },
+    {
+      method: "GET", path: `${PREFIX}/mine/:id`, allow: { session: true, scope: "messages:read" },
+      handle: async ({ actor, params }) => one(await grants.heldGrant(actor, params.id!)),
+    },
+    {
+      method: "DELETE", path: `${PREFIX}/mine/:id`, allow: { session: true, scope: "messages:send" },
+      handle: async ({ actor, params }) => one(await grants.revokeHeld(actor, params.id!)),
+    },
     {
       method: "POST",
       path: PREFIX,

package/src/central/agent/grants.ts

@@ -136,6 +136,29 @@ export class Grants {
     return (await this.all(owner)).sort((a, b) => b.created - a.created || (a.id < b.id ? -1 : 1)).map((g) => ({ ...g, state: grantState(g, at) }))
   }
 
+  /** Grants currently held by this credential; a user credential has no session/app holder. */
+  async held(actor: AgentActor): Promise<GrantView[]> {
+    if (actor.kind === "user") return []
+    return (await this.list(actor.userID)).filter((grant) => grant.owner === actor.userID && this.holds(grant, actor))
+  }
+
+  /** A holder cannot inspect another holder's grant (including an unheld role). */
+  async heldGrant(actor: AgentActor, id: string): Promise<Grant> {
+    if (actor.kind === "user") throw notFound()
+    const grant = await this.get(actor.userID, id)
+    if (grant.owner !== actor.userID || !this.holds(grant, actor)) throw notFound()
+    return grant
+  }
+
+  /** Re-check holder inside the versioned mutation, so a role lost after a read cannot revoke it. */
+  async revokeHeld(actor: AgentActor, id: string): Promise<Grant> {
+    await this.heldGrant(actor, id)
+    return this.change(actor.userID, id, "grant.revoke", (grant, at) => {
+      if (actor.kind === "user" || grant.owner !== actor.userID || !this.holds(grant, actor)) throw notFound()
+      return { ...grant, revokedAt: at }
+    })
+  }
+
   /**
    * Replaces an active grant with a new spec (its expiry restarts now); id, holder (and its pin) and created
    * stay. Changing the holder is invalid (revoke and create instead); an ended grant is gone.

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

@@ -746,7 +746,7 @@ export class LaunchEngine {
         const workspace = work?.workspace ?? (launch ? leftWorkspace(launch, report) : undefined)
         if (!workspace) continue
         if (HARNESS_UP.has(report.phase)) await nodeOps.requestNode(node.connID, { op: "stop", launchID: report.launchID, workspace, mode: "kill" })
-        await nodeOps.requestNode(node.connID, { op: "cleanup", launchID: report.launchID, workspace, policy: work?.cleanup ?? (workspace.reused ? "keep" : "remove") })
+        await nodeOps.requestNode(node.connID, { op: "cleanup", launchID: report.launchID, workspace, policy: work?.cleanup ?? (launch?.spec.end.cleanup ?? (workspace.reused ? "keep" : "remove")) })
         this.cleanupTries.delete(report.launchID)
         this.cleanupLogged.delete(report.launchID)
       } catch (cause) {
@@ -1122,6 +1122,8 @@ export class LaunchEngine {
       // A lost launch whose session a spoke still reports keeps its workspace (never removed under a live session).
       const sessionLive = outcome === "lost" && work.sessionID !== undefined && this.deps.registry.hasSession(work.sessionID)
       const policy: CleanupPolicy = outcome === "needs_user" || sessionLive ? "keep" : !work.prompted ? "remove" : launch.spec.end.cleanup
+      // Reconciliation must replay the policy actually applied, not the launch's original preference.
+      await this.updateWork(userID, id, { cleanup: policy })
       const node = launch.machineID !== undefined ? this.deps.nodes.forMachine(launch.machineID) : undefined
       if (node) {
         if (work.started) {
@@ -1145,11 +1147,9 @@ export class LaunchEngine {
         } catch (cause) {
           // The node may still hold the launch (and its slot): reconcile retries with this policy.
           notes.push(`workspace cleanup failed: ${errorText(cause)}; retried later`)
-          await this.updateWork(userID, id, { cleanup: policy })
         }
       } else {
         notes.push("workspace cleanup waits for the node")
-        await this.updateWork(userID, id, { cleanup: policy })
       }
     }
     try {

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

@@ -28,9 +28,12 @@ import type { Clock, Counters, StateStore } from "../backend/types"
 import { type Party, partyKey } from "./envelope"
 import { AgentError } from "./errors"
 import { updateVersioned } from "./versioned"
+import { TEAM_LIMITS } from "../../protocol"
 
 /** Hops a reply chain may take without a human turn. */
 export const HOP_CAP = 8
+/** Absolute ceiling on user-configured hop limits, independent of hub.json. */
+export const HOP_CAP_CEILING = TEAM_LIMITS.hopLimit
 /** A depth no message refreshed for this long is forgotten. */
 export const HOP_TTL_MS = 24 * 60 * 60_000
 

package/src/central/agent/routes.ts

@@ -67,6 +67,7 @@ import { isConciergeLaunch } from "../concierge/supervisor"
 import type { ConciergeService } from "../concierge/service"
 import type { SessionIntent } from "../../protocol"
 import type { SessionIntents } from "./intents"
+import type { NodeRegistry } from "../nodes"
 import { intentRoutes } from "./intent-routes"
 import { contextCardRoutes } from "../context-cards/routes"
 import type { ContextCardService } from "../context-cards/service"
@@ -98,6 +99,8 @@ export interface AgentRoute {
 /** What the agent API needs from the hub. */
 export interface AgentDeps {
   readonly store: Store
+  /** Owner's connected launch nodes: read-only user route; never expose connection IDs or launch internals. */
+  readonly nodes?: Pick<NodeRegistry, "list">
   /** (AF1) Connect an app: the connected-app token verifier and the app-clients/connections routes when given. */
   readonly connect?: AppConnect
   /** (AF2) Speech for apps: POST /api/agent/speech/{transcribe,speak} (scope speech:use) when given. */
@@ -238,6 +241,14 @@ export function agentRoutes(deps: AgentDeps): AgentRoute[] {
   const feed = deps.feed ?? new MessageFeed()
   const appDecisions = appDecisionParts(deps, feed)
   const routes: AgentRoute[] = [
+    ...(deps.nodes ? [{
+      method: "GET", path: `${AGENT_PREFIX}/launch-nodes`, allow: {},
+      handle: ({ user }) => Response.json({ nodes: deps.nodes!.list(user.id).map((node) => ({
+        machineID: node.machineID, machineName: node.machineName, workspaceRoots: node.workspaceRoots,
+        capacity: node.capacity, used: node.used, free: node.free, runtimes: node.runtimes,
+        labels: node.labels, draining: node.draining,
+      })) }, { headers: { "cache-control": "no-store" } }),
+    } satisfies AgentRoute] : []),
     ...(deps.directory ? directoryRoutes({ directory: deps.directory, store: deps.store, ...(deps.agentEvents ? { events: deps.agentEvents } : {}), ...(deps.registry ? { registry: deps.registry } : {}), ...(deps.grants ? { grants: deps.grants } : {}), ...(deps.acting ? { acting: deps.acting } : {}), ...(deps.audit ? { audit: deps.audit } : {}), ...(deps.eventCursorKeys ? { previewKeys: deps.eventCursorKeys } : {}), ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}), ...intentReads(deps), ...conciergeReads(deps) }) : []),
     ...(deps.directory && deps.intents ? intentRoutes({ intents: deps.intents, directory: deps.directory, store: deps.store, ...(deps.registry ? { registry: deps.registry } : {}), ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}) }) : []),
     ...(deps.directory && deps.contextCards ? contextCardRoutes({ cards: deps.contextCards, directory: deps.directory, ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}) }) : []),

package/src/central/agent/subscriptions.ts

@@ -245,6 +245,8 @@ export interface SubscriptionsDeps {
   readonly send: SubscriptionSend
   /** The session's message hop depth (HopTracker.depth). */
   readonly hopDepth: (userID: string, sessionID: string) => Promise<number>
+  /** Hub-wide hop ceiling (team notices are not session-to-session messages). */
+  readonly hopLimit?: number
   /** Directory facts of these sessions (deleted and unknown ones absent). */
   readonly entries: (userID: string, sessionIDs: readonly string[]) => ReadonlyMap<string, SubscriptionEntry>
   /** The sessions an address names for the subscriber (its visibility); throws not_found / invalid / ambiguous. */
@@ -858,7 +860,7 @@ export class Subscriptions {
       if (scoped && !scoped(subject)) continue
       const cause = isMessage && subject.senderID !== undefined && subject.senderID.startsWith("ses_") ? subject.senderID : (subject.sessionID ?? target)
       const depth = await this.depth(ctx, cause)
-      if (depth + 1 > HOP_CAP) {
+      if (depth + 1 > (this.deps.hopLimit ?? HOP_CAP)) {
         suppressed++
         continue
       }

package/src/central/config.ts

@@ -15,6 +15,7 @@ import { readContextCards, type ContextCardsConfig } from "./context-cards/confi
 import { checkReleaseBase } from "./install/render"
 import { cspMode, type CspMode } from "./csp"
 import { parseDenyCidrs } from "./fetcher"
+import { HOP_CAP, HOP_CAP_CEILING } from "./agent/message-limits"
 
 export const GOOGLE_ISSUER = "https://accounts.google.com"
 
@@ -70,6 +71,8 @@ export interface CentralConfig {
   readonly auth: AuthConfig
   /** hub.json `agents.never`: permission patterns no agent may ever approve, for every user (design §5, §7). */
   readonly agentsNever: readonly string[]
+  /** hub.json `agents.hopLimit`: global maximum agent-only hops before a wake is skipped. */
+  readonly hopLimit: number
   /** hub.json `agents.launches`: per-user launch caps, only those set (placement fills in its defaults). */
   readonly launchCaps?: HubLaunches
   /** hub.json `agents.webhooks.allowPrivate`: webhooks may target http, loopback, private and local hosts (admin opt-in). */
@@ -138,6 +141,7 @@ export interface HubLaunches {
 export interface HubAgents {
   /** Normalised `action[:glob]` patterns (see agent/policy.ts), duplicates dropped. */
   readonly never?: readonly string[]
+  readonly hopLimit?: number
   readonly launches?: HubLaunches
   readonly webhooks?: HubWebhooks
   /** (AF2) Per-credential app speech quotas: any subset of SPEECH_RATE_LIMITS. */
@@ -169,7 +173,7 @@ type Env = Readonly<Record<string, string | undefined>>
 
 const HUB_KEYS = new Set(["host", "port", "publicURL", "stateDir", "speech", "auth", "agents", "cluster", "contextCards"])
 const CLUSTER_KEYS = ["database", "valkey"] as const
-const AGENTS_KEYS = new Set(["never", "launches", "webhooks", "speechQuotas"])
+const AGENTS_KEYS = new Set(["never", "launches", "webhooks", "speechQuotas", "hopLimit"])
 /** The largest speech quota hub.json may set (counts and characters). */
 const SPEECH_QUOTA_MAX = 1_000_000_000
 const WEBHOOK_KEYS = new Set(["allowPrivate", "allowPrivateHosts"])
@@ -350,11 +354,13 @@ function readHubAgents(raw: unknown, file: string, warnings: string[], fail: (me
   if (!isObj(raw)) fail("agents must be an object")
   const input = raw as Record<string, unknown>
   for (const key of Object.keys(input)) if (!AGENTS_KEYS.has(key)) warnings.push(`${file}: unknown key "agents.${key}" ignored`)
+  if (input.hopLimit !== undefined && (!Number.isSafeInteger(input.hopLimit) || (input.hopLimit as number) < 1 || (input.hopLimit as number) > HOP_CAP_CEILING))
+    fail(`agents.hopLimit must be a whole number from 1 to ${HOP_CAP_CEILING}`)
   const launches = input.launches === undefined ? undefined : readHubLaunches(input.launches, file, warnings, fail)
   const never = input.never === undefined ? undefined : readNever(input.never, fail)
   const webhooks = input.webhooks === undefined ? undefined : readHubWebhooks(input.webhooks, file, warnings, fail)
   const speechQuotas = input.speechQuotas === undefined ? undefined : readSpeechQuotas(input.speechQuotas, file, warnings, fail)
-  return { ...(never ? { never } : {}), ...(launches ? { launches } : {}), ...(webhooks ? { webhooks } : {}), ...(speechQuotas ? { speechQuotas } : {}) }
+  return { ...(never ? { never } : {}), ...(input.hopLimit !== undefined ? { hopLimit: input.hopLimit as number } : {}), ...(launches ? { launches } : {}), ...(webhooks ? { webhooks } : {}), ...(speechQuotas ? { speechQuotas } : {}) }
 }
 
 /** (AF2) `agents.speechQuotas`: {transcribe?: {perMinute?, perHour?}, speak?: {perMinute?, perHour?, charsPerHour?}}. */
@@ -601,6 +607,7 @@ export function centralConfig(rawEnv: Env = process.env, home: string = homedir(
     ...(file.speech ? { speech: file.speech } : {}),
     auth,
     agentsNever: [...(file.agents?.never ?? [])],
+    hopLimit: file.agents?.hopLimit ?? HOP_CAP,
     ...(file.agents?.launches ? { launchCaps: { ...file.agents.launches } } : {}),
     ...(file.agents?.webhooks?.allowPrivate === true ? { webhooksAllowPrivate: true as const } : {}),
     ...(file.agents?.webhooks?.allowPrivateHosts?.length ? { webhooksPrivateHosts: [...file.agents.webhooks.allowPrivateHosts] } : {}),

package/src/central/http.ts

@@ -8,7 +8,7 @@ import { diskAssets, type WebAssets } from "./assets"
 import path from "node:path"
 import { promisify } from "node:util"
 import { brotliCompress, constants as zlib, gzip } from "node:zlib"
-import { CONNECT_PATHS, formAnswerProblem, isDeliverResult, isPreviewPath, parseMediaAllowlist, parseMediaRef, PREVIEW_BUNDLE_LIMITS, NOT_A_USER_MESSAGE, RECORDING_AUDIO_RESULT_HEADER, REVERT_BUSY, REVERT_END_BUSY, PROMPT_IMAGE_MIMES, WORKSPACE_LIMITS, promptImagesProblem, redactEmbeddedMedia, type AvailableModel, type CoreOp, type EnrollStart, type FormAnswer, type ModelSelection, type PermissionDecision, type PromptImage, type ResultFor, type SessionModelPrefs } from "../protocol"
+import { CONNECT_PATHS, formAnswerProblem, isDeliverResult, isPreviewPath, parseMediaAllowlist, parseMediaRef, PREVIEW_BUNDLE_LIMITS, NOT_A_USER_MESSAGE, RECORDING_AUDIO_RESULT_HEADER, RECORDING_HEADER, REVERT_BUSY, REVERT_END_BUSY, PROMPT_IMAGE_MIMES, WORKSPACE_LIMITS, promptImagesProblem, redactEmbeddedMedia, type AvailableModel, type CoreOp, type EnrollStart, type FormAnswer, type ModelSelection, type PermissionDecision, type PromptImage, type ResultFor, type SessionModelPrefs, type SessionSummary } from "../protocol"
 import { isLoopbackAddress, isLoopbackHost, isLoopbackURL, loopbackOrigins } from "../loopback"
 import { speakable } from "../speakable"
 import { Auth, RateLimitError, ValidationError } from "./auth"
@@ -60,7 +60,7 @@ import { BusyError, Registry, RELAY_REASON, RelayRefused, type Timers } from "./
 import { RELAY_REASON_CONFIRMED, relayMessage, relayQuestionProblem, STATUS_QUESTION_SOFT_REFUSAL } from "./front-relays"
 import { createActions, type Unsupported, unsupportedMessage } from "./actions"
 import { IntentRetention, SessionIntents, withPromptIntents } from "./agent/intents"
-import { audioFormat, SpeechError } from "./speech/provider"
+import { audioFormat, SpeechError, type TranscribeStats } from "./speech/provider"
 import { SpeechService } from "./speech/service"
 import { NodeRegistry } from "./nodes"
 import { ConnDirectory } from "./cluster/directory"
@@ -85,7 +85,7 @@ import { coordinatorActor, SupervisorCoordinator } from "./workspaces/coordinato
 import { artifactJournalEvent } from "./artifacts/events"
 import { ArtifactMaintenance } from "./artifacts/maintenance"
 import { MemoryBlobStore } from "./backend/memory-blobs"
-import { RecordingService } from "./recording"
+import { RecordingService, type DevLimits } from "./recording"
 import { recordingRoutes } from "./recording/routes"
 import { wrapConciergeSend } from "./recording/concierge-taps"
 import { ARTIFACT_UPLOAD_LIMITS } from "./artifacts/routes"
@@ -100,6 +100,7 @@ import { teamDeniedEvent, TeamPolicy } from "./teams/policy"
 import { TeamSeatStore } from "./teams/seats"
 import { TeamStaffingService } from "./teams/staffing"
 import { intakeActor, TeamIntakeService } from "./teams/intake"
+import { TeamHopStalls } from "./teams/hop-stalls"
 import { TeamStore } from "./teams/store"
 import { ActivityTracker } from "./concierge/activity"
 import { HumanActivity, withHumanActivity } from "./human-activity"
@@ -137,7 +138,8 @@ import { ACTIVITY_INTERVAL_MAX, ACTIVITY_INTERVAL_MIN, LOCAL_USER, PUSH_PREF_KEY
 const HUMAN_ACTIVITY_STOP_MS = 3_000
 
 export interface Speech {
-  transcribe(audio: Uint8Array, format: string): Promise<string>
+  /** `stats` (recording mode): the provider fills in its upstream request's status, bytes and time to headers. */
+  transcribe(audio: Uint8Array, format: string, stats?: TranscribeStats): Promise<string>
   speak(text: string): Promise<Uint8Array<ArrayBuffer>>
   /** Streams the audio as it is synthesized (the built-in providers do; an override may only buffer). */
   speakStream?(text: string, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>
@@ -149,6 +151,8 @@ export interface CentralOptions {
   readonly previewRetention?: { readonly archiveAfterMs?: number; readonly purgeAfterMs?: number }
   /** The registry's timers (tests: a fake clock for its delayed checks); real timers by default. */
   readonly registryTimers?: Timers
+  /** Developer mode's recording limits (tests shrink them; default DEV_LIMITS). */
+  readonly recordingDevLimits?: Partial<DevLimits>
   /** The built web app (web/dist, see web/vite.config.ts) on disk; or pass `web` (e.g. files embedded in a compiled binary). */
   readonly webDir?: string
   readonly web?: WebAssets
@@ -888,7 +892,7 @@ export function startCentral(options: CentralOptions): Central {
   // sessions frame; human turns (console turn/utterance, prompts typed in the harness) reset hop chains.
   // Teams (HWA-33) and their communication policy in delivery (HWA-34): a denial is audited and journaled (IDs only).
   let teamSeats: TeamSeatStore | undefined
-  const teamStore = new TeamStore({ state: backends.state, now, pinnedVersions: (userID, teamID) => teamSeats!.pinnedVersions(userID, teamID) })
+  const teamStore = new TeamStore({ state: backends.state, now, globalHopLimit: config.hopLimit, pinnedVersions: (userID, teamID) => teamSeats!.pinnedVersions(userID, teamID) })
   const teamPresence = directoryPresence(directory, (userID) => store.agentData(userID).sessions ?? [])
   teamSeats = new TeamSeatStore({ state: backends.state, teams: teamStore, now, knowsSession: async (userID, sessionID) => !["unknown", "deleted"].includes(await teamPresence(userID, sessionID)) })
   const teamPolicy = new TeamPolicy({
@@ -901,8 +905,35 @@ export function startCentral(options: CentralOptions): Central {
       await Promise.all([audit.record(userID, { actor: { kind: "session", sessionID: denial.senderID }, verb: "team.denied", target, decision: "forbidden", reason, outcome: "refused" }), agentEvents.append(userID, teamDeniedEvent(denial))])
     },
   })
+  let decisions: Decisions
+  const teamHopStalls = new TeamHopStalls({
+    state: backends.state,
+    now,
+    seats: async (userID, teamID) => [...new Set((await teamSeats!.list(userID, teamID, { current: true })).map((seat) => seat.sessionID))],
+    reset: (userID, sessionID) => delivery.hops.humanTurn(userID, sessionID),
+    close: async (userID, decisionID) => { await decisions.close(userID, decisionID, "A person continued this team's work; renewal is no longer needed") },
+    notice: (userID, teamID, decisionID) => delivery.notifyTeamHopCap(userID, teamID, decisionID),
+    open: async (userID, teamID, sender, recipient, limit) => {
+      const team = await teamStore.require(userID, teamID)
+      const intake = await teamIntake?.list(userID, { kind: "user", userID, deviceID: "hub", via: "cookie" }, teamID, { limit: 50 })
+      const active = intake?.items.find((item) => item.status === "routed" && (item.sessionID === sender || item.sessionID === recipient))
+      const detail = active ? `, intake ${active.id} (${active.title})` : ""
+      const { decision } = await decisions.ask(userID, { kind: "app", userID, tokenID: "team-hop", scopes: [], label: "Hub team hop cap" }, {
+        question: `Team #${team.name}${detail} reached its ${limit}-hop limit (${sender} → ${recipient}). Renew this team's seats?`,
+        options: [{ id: "renew", label: "Renew" }, { id: "leave", label: "Leave stopped", safe: true }],
+        urgency: "high", tier: "tap", about: [recipient],
+      }, { action: { kind: "teamHopRenew", teamID } })
+      return decision.id
+    },
+  })
   const delivery = new Delivery({
+    hopLimit: config.hopLimit,
     teams: teamPolicy,
+    teamHopCap: async (userID, input) => { await teamHopStalls.hit(userID, input.teamID, input.sender, input.recipient, input.limit) },
+    teamHopNotice: async (userID, teamID) => {
+      const team = await teamStore.get(userID, teamID)
+      return (await teamSeats!.list(userID, teamID, { current: true })).find((seat) => seat.role === team?.entryRole)?.sessionID
+    },
     // CON-04 inbound rule: only the user, app:concierge and replies to its asks reach a Concierge session.
     inbound: conciergeInbound({ identity: conciergeTimedIdentity, audit: { record: (userID, entry) => audit.record(userID, entry) } }),
     state: backends.state,
@@ -937,7 +968,7 @@ export function startCentral(options: CentralOptions): Central {
   /** (CON-06) The Concierge tiers (set below, once the Concierge modules exist): proposals' act, via, disarm. */
   let conciergeTierHooks: ConciergeTiers | undefined
   // Decisions (design §12.1): asks to @me; deadlines run over every user's Decisions (survive restarts).
-  const decisions = new Decisions({
+  decisions = new Decisions({
     state: backends.state,
     delivery,
     now,
@@ -954,6 +985,13 @@ export function startCentral(options: CentralOptions): Central {
     // (CON-06) Concierge proposals run their verb as the user (all set up below).
     act: (userID, decision, choice, by) => {
       const kind = decision.action?.kind
+      if (kind === "teamHopRenew") {
+        if (by.userID !== userID || by.via !== "cookie") return Promise.resolve("gone" as const)
+        const teamID = decision.action!.teamID
+        return choice.option === "renew"
+          ? teamHopStalls.renew(userID, teamID, decision.id).then(async () => { await audit.record(userID, { actor: { kind: "user" }, verb: "team.hop.renew", target: {}, decision: "allow", outcome: "ok" }); return "done" as const })
+          : Promise.resolve("done" as const)
+      }
       if (kind === "act") {
         if (!conciergeTierHooks?.act) throw new Error("This decision's action cannot run on this hub")
         return conciergeTierHooks.act(userID, decision, choice, by)
@@ -975,6 +1013,7 @@ export function startCentral(options: CentralOptions): Central {
     const tenant = registry.sessionTenant(sessionID)
     if (tenant === undefined) return
     await delivery.humanTurn(tenant, sessionID).catch((cause) => console.error(`[hub] hop reset failed: ${(cause as Error).message}`))
+    await teamHopStalls.clearForHuman(tenant, sessionID).catch((cause) => console.error(`[hub] team hop reset failed: ${(cause as Error).message}`))
   }
   registry.onSessions((connID) => void delivery.onSessions(connID).catch((cause) => console.error(`[hub] message flush failed: ${(cause as Error).message}`)))
   // Committed revert windows (./revert-windows): the hub message rows of a removed history stay hidden for good.
@@ -1313,6 +1352,23 @@ export function startCentral(options: CentralOptions): Central {
     audit: (entry) => store.audit(entry),
     users: allUsers,
     log: (message) => console.error(message),
+    pod: config.cluster?.podID ?? "hub",
+    // (Developer mode) What ran a turn: the session's model and context size from its spoke (summary), counts only.
+    turnFacts: async (_userID, sessionID) => {
+      const summary = (await spokes.request(ownerOf(sessionID), { op: "summary", sessionID })) as SessionSummary
+      const model = summary?.model
+      const context = summary?.context
+      const agent = registry.session(sessionID)?.agent
+      return {
+        ...(model?.providerID ? { provider: model.providerID } : {}),
+        ...(model?.modelID ? { model: model.modelID } : context?.model ? { model: context.model } : {}),
+        ...(model?.variant ? { variant: model.variant } : {}),
+        ...(agent ? { agent } : {}),
+        ...(typeof context?.used === "number" ? { contextTokens: context.used } : {}),
+        ...(typeof context?.limit === "number" ? { contextLimit: context.limit } : {}),
+      }
+    },
+    ...(options.recordingDevLimits ? { devLimits: options.recordingDevLimits } : {}),
   })
   recordings = recordingService
   registry.recordingTap = recordingService.registryTap
@@ -1378,7 +1434,7 @@ export function startCentral(options: CentralOptions): Central {
   const workspaces = { workspaces: workspaceStore, members: workspaceMembers, supervision: workspaceSupervision, lifecycle: workspaceLifecycle }
   // Team staffing (HWA-35): seats end on session deletion; launched members are staffed when their launch runs.
   const sessionDirectory = (userID: string, sessionID: string) => (registry.sessionTenant(sessionID) === userID ? registry.session(sessionID)?.directory : undefined)
-  const teamStaffing = new TeamStaffingService({ state: backends.state, teams: teamStore, seats: teamSeats, workspaces: workspaceStore, members: workspaceMembers, supervision: workspaceSupervision, presence: teamPresence, sessionDirectory, launches, grants, acting, audit, profiles, events: agentEvents, now, protects: conciergeProtects(conciergeTimedIdentity) })
+  const teamStaffing = new TeamStaffingService({ state: backends.state, teams: teamStore, seats: teamSeats, workspaces: workspaceStore, members: workspaceMembers, supervision: workspaceSupervision, presence: teamPresence, hopStalls: teamHopStalls, sessionDirectory, launches, grants, acting, audit, profiles, events: agentEvents, now, protects: conciergeProtects(conciergeTimedIdentity) })
   registry.onSessionDeleted((sessionID, tenant) => void teamStaffing.sessionEnded(tenant, sessionID).catch((cause) => console.error(`[hub] team session end failed: ${(cause as Error).message}`)))
   launchFeed.subscribe((userID, launch) => void teamStaffing.launchChanged(userID, launch).catch((cause) => console.error(`[hub] team staffing launch failed: ${(cause as Error).message}`)), { origin: true })
   // Team intake (HWA-36): delivered to an entry seat from the fixed party app:team-intake (never the submitter). The
@@ -1435,6 +1491,7 @@ export function startCentral(options: CentralOptions): Central {
   const subscriptionLeader = leader("subscriptions", { onElected: () => subscriptions?.start(), onDeposed: () => subscriptions?.stop() })
   subscriptions = new Subscriptions({
     state: backends.state,
+    hopLimit: config.hopLimit,
     events: agentEvents,
     send: async (userID, sessionID, text, options) => void (await delivery.send(userID, subscriptionActor(userID), sessionID, "msg", text, options)),
     hopDepth: (userID, sessionID) => delivery.hops.depth(userID, { kind: "session", sessionID }),
@@ -1744,7 +1801,7 @@ export function startCentral(options: CentralOptions): Central {
     conversationOf: (sessionID) => registry.conversationOf(sessionID),
     stateOf: (sessionID) => registry.status(sessionID)?.find((s) => s.id === sessionID)?.state ?? "idle",
   }
-  const agentDeps = { contextCards: cards, conversation: { ports: conversationPorts, source: appStreamSource, streams: appStreams, cookieName: COOKIE, ...options.appStreams }, connect: appConnect, speech: speechDeps, recording: { call: (userID: string, sessionID: string, fields: Parameters<RecordingService["conciergeCall"]>[2]) => recordingService.conciergeCall(userID, sessionID, fields) }, intents, teamDiscovery, draining: drainSignal.signal, store, sessionTokens, directory, registry, spokes, delivery, decisions, messageState: backends.state, feed, heartbeatMs, now, audit, grants, grantRequests, acting, actions, escalate, launches, webhooks, subscriptions, agentEvents, eventCursorKeys: tokenKeys, maxPromptChars: MAX_PROMPT_CHARS, profiles, workspaces, workspaceCheckpoints, teamIntake, graph: { teams: { teams: teamStore, seats: teamSeats! } }, teams: { teams: teamStore, seats: teamSeats!, staffing: teamStaffing }, artifacts: { ...(artifacts && backends.blobs ? { artifacts, blobs: backends.blobs } : {}), state: backends.state, now }, artifactHost: { caps: artifactHostCaps, ...(artifacts ? { artifacts } : {}) }, concierge: { state: backends.state, activity: conciergeActivity, results: conciergeResults, identity: conciergeTimedIdentity, protects: conciergeProtects(conciergeTimedIdentity), service: conciergeService, models: machineModels({ serviceFor: (machineID) => registry.serviceFor(machineID), reportedSessions: (connID) => registry.reportedSessions(connID), request: (connID, req) => spokes.request(connID, req) }), routes: () => [...conciergeParts.tiers.routes(), ...conciergeGrantRequestRoutes({ requests: conciergeGrantRequests, identity: conciergeTimedIdentity })], armed: conciergeArmed, timeZone: conciergeBoardDeps.timeZone, coverage: conciergeCoverage, projectGrant: conciergeProjectGrant } }
+  const agentDeps = { nodes, contextCards: cards, conversation: { ports: conversationPorts, source: appStreamSource, streams: appStreams, cookieName: COOKIE, ...options.appStreams }, connect: appConnect, speech: speechDeps, recording: { call: (userID: string, sessionID: string, fields: Parameters<RecordingService["conciergeCall"]>[2]) => recordingService.conciergeCall(userID, sessionID, fields) }, intents, teamDiscovery, draining: drainSignal.signal, store, sessionTokens, directory, registry, spokes, delivery, decisions, messageState: backends.state, feed, heartbeatMs, now, audit, grants, grantRequests, acting, actions, escalate, launches, webhooks, subscriptions, agentEvents, eventCursorKeys: tokenKeys, maxPromptChars: MAX_PROMPT_CHARS, profiles, workspaces, workspaceCheckpoints, teamIntake, graph: { teams: { teams: teamStore, seats: teamSeats! } }, teams: { teams: teamStore, seats: teamSeats!, staffing: teamStaffing }, artifacts: { ...(artifacts && backends.blobs ? { artifacts, blobs: backends.blobs } : {}), state: backends.state, now }, artifactHost: { caps: artifactHostCaps, ...(artifacts ? { artifacts } : {}) }, concierge: { state: backends.state, activity: conciergeActivity, results: conciergeResults, identity: conciergeTimedIdentity, protects: conciergeProtects(conciergeTimedIdentity), service: conciergeService, models: machineModels({ serviceFor: (machineID) => registry.serviceFor(machineID), reportedSessions: (connID) => registry.reportedSessions(connID), request: (connID, req) => spokes.request(connID, req) }), routes: () => [...conciergeParts.tiers.routes(), ...conciergeGrantRequestRoutes({ requests: conciergeGrantRequests, identity: conciergeTimedIdentity })], armed: conciergeArmed, timeZone: conciergeBoardDeps.timeZone, coverage: conciergeCoverage, projectGrant: conciergeProjectGrant } }
   const resolveActor = createResolver({
     cookieName: COOKIE,
     findDevice: (token) => deviceOfToken(token),
@@ -2026,16 +2083,18 @@ export function startCentral(options: CentralOptions): Central {
       await store.removeDevice(device.id)
       return new Response(null, { status: 204, headers: { "set-cookie": cookie("", 0) } })
     }),
-    route("POST", "/api/transcribe", "user", ({ request, user, device }) => transcribe(request, speechFor(user.id), user.id, device.id)),
-    route("POST", "/api/speak", "user", async ({ request, user, device }) => {
-      const text = speakable(String((await body(request)).text ?? ""), config.maxSpeechChars)
-      if (!text) return error(400, "Nothing to speak")
-      const speech = speechFor(user.id)
-      // (REC-01) x-hub-recording (+ x-hub-tts-ref): tts.synth timing; best effort, the audio is never stored.
-      const tap = await recordingService.speakTap(user.id, device.id, request.headers, text.length).catch(() => undefined)
-      const audio = await speakAudio(speech, text, request.signal)
-      return new Response(tap ? tap.wrap(audio) : audio, { headers: { "content-type": "audio/mpeg" } })
-    }),
+    route("POST", "/api/transcribe", "user", ({ request, user, device }) => requestLined(user.id, device.id, request, "transcribe", () => transcribe(request, speechFor(user.id), user.id, device.id))),
+    route("POST", "/api/speak", "user", ({ request, user, device }) =>
+      requestLined(user.id, device.id, request, "speak", async () => {
+        const text = speakable(String((await body(request)).text ?? ""), config.maxSpeechChars)
+        if (!text) return error(400, "Nothing to speak")
+        const speech = speechFor(user.id)
+        // (REC-01) x-hub-recording (+ x-hub-tts-ref): tts.synth timing; in Developer mode the audio is kept too.
+        const tap = await recordingService.speakTap(user.id, device.id, request.headers, text.length).catch(() => undefined)
+        const audio = await speakAudio(speech, text, request.signal)
+        return new Response(tap ? tap.wrap(audio) : audio, { headers: { "content-type": "audio/mpeg" } })
+      }),
+    ),
     // (REC-01) Recording routes: console only ("user": the user's cookie or device token), see docs/voice-recording.md.
     ...recordingRoutes(recordingService, { version: options.version ?? "0.0.0", now, audit: (entry) => store.audit(entry) }).map((r) => route(r.method, r.path, "user", (context) => r.handle(context))),
     route("GET", "/api/push/key", "user", async () => Response.json({ publicKey: await push.publicKey() })),
@@ -3152,6 +3211,28 @@ export function startCentral(options: CentralOptions): Central {
     return answered.outcome === "done" ? new Response(null, { status: 204 }) : error(409, PERMISSION_GONE, "gone")
   }
 
+  /**
+   * (Developer mode) A voice request naming a recording (x-hub-recording): its route, status and time are recorded
+   * as a request line in that recording when it is a developer one (recordingService.requestLine). Never a body.
+   */
+  async function requestLined(userID: string, deviceID: string, request: Request, route: "transcribe" | "speak", handle: () => Promise<Response>): Promise<Response> {
+    const recordingID = request.headers.get(RECORDING_HEADER)
+    if (recordingID === null) return handle()
+    const started = performance.now()
+    let status = 500
+    try {
+      const res = await handle()
+      status = res.status
+      return res
+    } catch (cause) {
+      const s = (cause as { status?: unknown }).status
+      status = cause instanceof SpeechError ? 502 : typeof s === "number" ? s : 500
+      throw cause
+    } finally {
+      void recordingService.requestLine(userID, deviceID, recordingID, { route, method: "POST", status, ms: performance.now() - started }).catch(() => undefined)
+    }
+  }
+
   async function transcribe(request: Request, speech: Speech, userID: string, deviceID: string): Promise<Response> {
     const format = audioFormat(request.headers.get("content-type"))
     if (!format) return error(415, `Unsupported audio type: ${request.headers.get("content-type")}`)
@@ -3163,9 +3244,10 @@ export function startCentral(options: CentralOptions): Central {
     // (REC-01) With x-hub-recording + x-hub-segment: the segment is kept for the recording (no second upload).
     const tap = await recordingService.transcribeTap(userID, deviceID, request.headers, audio, format).catch(() => undefined)
     const started = performance.now()
-    const text = await speech.transcribe(audio, format)
+    const stats: TranscribeStats = {}
+    const text = await (tap ? speech.transcribe(audio, format, stats) : speech.transcribe(audio, format))
     if (!tap) return Response.json({ text })
-    const result = await tap.finish(text, Math.round(performance.now() - started)).catch(() => "failed" as const)
+    const result = await tap.finish(text, Math.round(performance.now() - started), stats).catch(() => "failed" as const)
     return Response.json({ text }, { headers: { [RECORDING_AUDIO_RESULT_HEADER]: result } })
   }