@huynle/hub 0.11.0 → 0.11.1

package/src/central/http.ts

@@ -36,14 +36,16 @@ import { createResolver, type AgentActor, type BearerVerifier, type CredentialMo
 import { ActingSwitch } from "./agent/acting-switch"
 import { AgentAudit } from "./agent/audit"
 import { Grants } from "./agent/grants"
-import { ANSWER_VIAS, type AnswerVia, Decisions, type Decision, TAP_ONLY } from "./agent/decisions"
+import { ANSWER_VIAS, answerDetail, answerPicks, type AnswerVia, Decisions, type Decision, TAP_ONLY } from "./agent/decisions"
 import { Acting, type Escalate } from "./agent/acting"
 import { Escalations } from "./agent/escalation"
 import { GrantRequests } from "./agent/grant-requests"
 import { ConciergeGrantRequests, conciergeGrantRequestRoutes, watchedProjects } from "./concierge/grant-request"
 import { partyFromActor } from "./agent/envelope"
 import { Delivery } from "./agent/delivery"
+import { AgentLimits } from "./agent/agent-limits"
 import { AGENT_ERROR_STATUS, AgentError, type AgentErrorCode } from "./agent/errors"
+import { apiV1Response, unversionedURL } from "./api-v1"
 import type { Launch } from "./agent/launch-store"
 import { decisionStateQuery, MessageFeed } from "./agent/message-routes"
 import { hubDirectory } from "./agent/directory-routes"
@@ -101,6 +103,15 @@ import { TeamSeatStore } from "./teams/seats"
 import { TeamStaffingService } from "./teams/staffing"
 import { intakeActor, TeamIntakeService } from "./teams/intake"
 import { TeamHopStalls } from "./teams/hop-stalls"
+import { itemEligibility } from "./teams/item-eligibility"
+import { ItemBudgets } from "./teams/budgets"
+import { TeamInvolvement } from "./teams/involvement"
+/** (TA2-8) The hub itself, for a reset it made on observed progress (no user, device or session acted). */
+const HUB_PROGRESS_PARTY = { kind: "app", tokenID: "team-progress", label: "Hub progress" } as const
+import { LoopDetector, type LoopThreshold } from "./teams/loops"
+import { ItemStalls } from "./teams/item-stalls"
+import { ItemDecisions, itemDecisionQuestion } from "./teams/item-decisions"
+import { DiffSampler, ProgressSignals, type ProgressSignal } from "./teams/progress"
 import { TeamStore } from "./teams/store"
 import { ActivityTracker } from "./concierge/activity"
 import { HumanActivity, withHumanActivity } from "./human-activity"
@@ -110,7 +121,7 @@ import { conciergeBoard } from "./concierge/board-routes"
 import { renderFrontBoard } from "./concierge/board-render"
 import { ContextPusher } from "./concierge/context"
 import { C1_ENTITLEMENTS } from "./concierge/entitlements"
-import { ContextCardService, contextCardEvent, type AutoTrigger } from "./context-cards/service"
+import { cardTriggerOf, ContextCardService, contextCardEvent, type AutoTrigger } from "./context-cards/service"
 import { TRANSCRIPT_ROWS } from "./context-cards/inputs"
 import { CONTEXT_CARD_TRIGGERS } from "./../protocol"
 import type { ChatClient } from "./llm/chat"
@@ -204,6 +215,10 @@ export interface CentralOptions {
     readonly leaderTtlMs?: number
     /** How often the decision deadline and message re-wake loops run (see DECISION_TICK_MS, REWAKE_TICK_MS). */
     readonly loopTickMs?: number
+    /** Test-only initial agent-limits retry scheduler; production starts at 1s, doubling to 30s. */
+    readonly agentLimitsRetry?: (ms: number) => Promise<void>
+    /** Bound requests held for initial agent-limits hydration (default 5s; tests shorten it). */
+    readonly agentLimitsInitialWaitMs?: number
     /** drain(): how long it waits for requests in flight, and the bye's retryAfterMs (see DRAIN_TIMEOUT_MS, DRAIN_RETRY_AFTER_MS). */
     readonly drainTimeoutMs?: number
     readonly drainRetryAfterMs?: number
@@ -226,6 +241,7 @@ export interface Central {
   readonly speechSettings: SpeechService
   /** Backends for new code (state, bus, event log, counters, locks, catalog, kv). */
   readonly backends: Backends
+  readonly agentLimits: AgentLimits
   /** Agent messages: store and delivery to sessions (the message routes use it). */
   readonly delivery: Delivery
   /** Decisions (ask @me): answered by the user on /api/decisions. */
@@ -470,6 +486,11 @@ export function startCentral(options: CentralOptions): Central {
   /** The bundle for the config (or the one given). Cluster mode never touches the state dir. */
   const ownBackends = !options.backends
   const backends = options.backends ?? hubBackends(config, { now })
+  const agentLimits = new AgentLimits(backends.state, { hopLimit: config.hopLimit, hopCeiling: config.hopCeiling, ...(config.launchCaps ? { launchCaps: config.launchCaps } : {}) }, { hopLimit: config.agentLimitsSource === "hub.json", hopCeiling: config.hopCeilingSource === "hub.json", launchCaps: config.agentLimitsSource === "hub.json" }, backends.bus, { now, ...(options.timing?.agentLimitsRetry ? { retry: options.timing.agentLimitsRetry } : {}) })
+  // Observe startup failure immediately (no unhandled rejection), but never serve on an unknown cap.
+  const agentLimitsReady = agentLimits.start().catch((cause: unknown) => {
+    console.error("[hub] agent limits could not load; refusing requests:", cause)
+  })
   // Cluster mode: the records are rows in the shared StateStore, cached per pod (loaded on first use; no data
   // migration runs on start). Otherwise state.json in the state dir.
   const store = config.cluster
@@ -892,7 +913,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, globalHopLimit: config.hopLimit, pinnedVersions: (userID, teamID) => teamSeats!.pinnedVersions(userID, teamID) })
+  const teamStore = new TeamStore({ state: backends.state, now, hopCeiling: () => agentLimits.snapshot().hopCeiling, 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({
@@ -909,9 +930,7 @@ export function startCentral(options: CentralOptions): Central {
   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") },
+    close: async (userID, decisionID, reason) => { await decisions.close(userID, decisionID, reason ?? "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)
@@ -919,15 +938,149 @@ export function startCentral(options: CentralOptions): Central {
       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?`,
+        question: `Team #${team.name}${detail} reached its effective ${limit}-hop limit (${team.hopLimit !== undefined && team.hopLimit < agentLimits.snapshot().hopLimit ? "team" : `hub-wide ${agentLimits.snapshot().sources.hopLimit}`}; ${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({
+  const teamInvolvement = new TeamInvolvement({
+    seats: async (userID, teamID) => [...new Set((await teamSeats!.list(userID, teamID, { current: true })).map((seat) => seat.sessionID))],
+    seatsOf: (userID, sessionID) => teamSeats!.seatsOf(userID, sessionID),
+    reset: (userID, sessionID) => delivery.hops.humanTurn(userID, sessionID),
+    stalls: teamHopStalls,
+    audit: async ({ userID, teamID, kind, ref, seats, failed, actor }) => { await audit.record(userID, { actor: kind === "progress" ? HUB_PROGRESS_PARTY : { kind: "user" }, ...(actor?.deviceID ? { deviceID: actor.deviceID } : {}), verb: "team.hops.reset", target: {}, decision: "allow", outcome: "ok", reason: `${teamID} ${kind}:${ref}, ${seats.length} seats, ${failed.length} failed${actor?.via ? `, via ${actor.via}` : ""}` }) },
+    event: async ({ userID, teamID, kind, ref, seats, failed }) => { await agentEvents.append(userID, { type: "team.hops.reset", family: "manage", subject: { teamID }, data: { kind, ref, seats: seats.length, failed: failed.length } }) },
+  })
+  const itemBudgets = new ItemBudgets({
+    state: backends.state, now,
+    limits: async (userID, teamID) => (await teamStore.get(userID, teamID))?.itemBudget ?? agentLimits.snapshot().itemBudget!,
+    exhausted: async (userID, teamID, itemID, reason, limit, usage) => {
+      await agentEvents.append(userID, { type: "team.item_budget.exhausted", family: "manage", subject: { teamID, ...(itemID ? { intakeID: itemID } : {}) }, data: { scope: itemID ? "item" : "pool", reason, limit, usageWakes: usage.wakes, usageHours: Math.round(usage.hours * 10) / 10 } })
+      // (TA2-7) An item opens its one Extend/Stop Decision; the unattributed pool only gets a quiet entry-seat notice.
+      if (itemID) await itemStalls.hit(userID, teamID, itemID, "budget")
+      else await delivery.notifyTeamEntry(userID, teamID, `This team's unattributed wake pool is spent (${limit} wakes per 24 h). Tag messages with their intake item, or wait; the pool opens no Decision.`)
+    },
+  })
+  /** (TA2-7) The effective item-loop threshold: the published team's override, else the hub-wide setting. */
+  const loopThreshold = async (userID: string, teamID: string): Promise<LoopThreshold> => (await teamStore.get(userID, teamID))?.loop ?? agentLimits.snapshot().loop!
+  const loopWindowMs = async (userID: string, teamID: string) => (await loopThreshold(userID, teamID)).windowMinutes * 60_000
+  const itemLoops = new LoopDetector({ thresholds: () => agentLimits.snapshot().loop!, now })
+  const hubReader = (userID: string) => ({ kind: "user" as const, userID, deviceID: "hub", via: "cookie" as const })
+  const itemStalls: ItemStalls = new ItemStalls({
+    state: backends.state,
+    now,
+    open: async (userID, teamID, item, reason, pair) => {
+      const team = await teamStore.require(userID, teamID)
+      const intake = await teamIntake!.get(userID, hubReader(userID), teamID, item)
+      const usage = await itemBudgets.usage(userID, teamID, item, intake.startedAt)
+      const question = itemDecisionQuestion({ userID, teamID, item, title: intake.title, reason, decisionID: "", ...(pair ? { pair } : {}), usage: { wakes: usage.wakes, hours: usage.hours }, limit: usage.budget })!
+      const about = pair ? [...pair] : intake.sessionID ? [intake.sessionID] : undefined
+      const { decision } = await decisions.ask(userID, { kind: "app", userID, tokenID: "team-item", scopes: [], label: "Hub team item budget" }, {
+        question: `Team #${team.name}: ${question}`,
+        options: [{ id: "extend", label: "Extend" }, { id: "stop", label: "Stop", safe: true }],
+        urgency: "high", tier: "tap", ...(about ? { about } : {}),
+      }, { action: { kind: "teamItem", teamID, item, reason, ...(pair ? { pair } : {}) } })
+      return decision.id
+    },
+    notice: async (userID, teamID, item, decisionID) => {
+      await delivery.notifyTeamEntry(userID, teamID, `Item ${item} is paused for the user (Decision ${decisionID}: Extend or Stop). Its messages still arrive without waking anyone; other items keep flowing.`)
+    },
+  })
+  /**
+   * (TA2-7) An item's Extend/Stop Decision ended unanswered. Closed by the hub: clear its stall. Expired: if the item is
+   * still open and still paused (budget still spent, or the pair still stopped), re-open ONE fresh Decision, once; after
+   * that the item stays paused with its stall recorded until the user acts. Otherwise the stall is cleared.
+   */
+  const itemDecisionEnded = async (userID: string, decision: Decision) => {
+    const action = decision.action
+    if (action?.kind !== "teamItem" || (decision.state !== "expired" && decision.state !== "closed")) return
+    const { teamID, item, reason, pair } = action
+    // Lifting a stall also forgets the stopped pair's window, or its next message would stop it again at once.
+    const lift = async () => {
+      if (await itemStalls.clearFor(userID, teamID, item, decision.id) && pair) itemLoops.clear({ userID, teamID, item, from: pair[0], to: pair[1] })
+    }
+    if (decision.state === "closed") { await lift(); return }
+    const intake = await teamIntake!.get(userID, hubReader(userID), teamID, item).catch(() => undefined)
+    const open = intake !== undefined && (intake.status === "queued" || intake.status === "routed")
+    let paused = open && reason === "loop"
+    if (open && reason === "budget") {
+      const usage = await itemBudgets.usage(userID, teamID, item, intake.startedAt)
+      paused = usage.wakes >= usage.budget.wakes || usage.hours >= usage.budget.hours
+    }
+    if (!paused) { await lift(); return }
+    await itemStalls.reopen(userID, teamID, item, decision.id)
+  }
+  /** (TA2-7) The Extend/Stop ports for one answer: Stop fails the intake as the user who tapped it (their device). */
+  const itemDecisionsFor = (teamID: string, by: { readonly userID: string; readonly deviceID: string }) => new ItemDecisions({
+    matches: async (userID, team, item, decisionID) => (await itemStalls.get(userID, team, item))?.decisionID === decisionID,
+    clearStall: async (userID, item, decisionID) => {
+      if ((await itemStalls.get(userID, teamID, item))?.decisionID === decisionID) await itemStalls.clear(userID, teamID, item)
+    },
+    extend: (userID, team, item, decisionID) => itemBudgets.extend(userID, team, item, decisionID),
+    clearLoop: async (userID, item, pair) => { itemLoops.clear({ userID, teamID, item, from: pair[0], to: pair[1] }) },
+    involved: (userID, act) => teamInvolvement.involved(userID, act),
+    stop: async (userID, team, item, reason) => {
+      const actor = { kind: "user" as const, userID, deviceID: by.deviceID, via: "cookie" as const }
+      const current = await teamIntake!.get(userID, actor, team, item)
+      if (current.status === "failed" || current.status === "cancelled") return
+      // A still-queued item can only be cancelled (intake rule); a routed one fails. Either way, as the user, with the reason.
+      await teamIntake!.setStatus(userID, actor, team, item, { status: current.status === "queued" ? "cancelled" : "failed", expectedRevision: current.revision, reason })
+    },
+    audit: async ({ userID, actor, deviceID, verb, reason }) => { await audit.record(userID, { actor, deviceID, verb, target: {}, decision: "allow", outcome: "ok", reason }) },
+  })
+  /**
+   * (TA2-5 → TA2-7/8, decision 90utvfcb) Every qualifying progress signal restarts the item's loop windows, so real work
+   * isn't flagged as a loop. Hop depth is different: the hub sees THAT something was written, not whether it was useful,
+   * so only the seat's first move of an item into in_progress (once per item) resets the charged seats' depth; an
+   * artifact, a diff or a console answer never does (a console act already resets the whole team, phase 1).
+   * Cluster caveat: loop windows live in this pod's memory (best-effort across restarts and pods); the item budget is
+   * stored under CAS and is the authoritative bound.
+   */
+  const onProgress = async (signal: ProgressSignal) => {
+    itemLoops.progress(signal)
+    if (signal.kind !== "intake" || !signal.item) return
+    try {
+      const charged = await itemBudgets.charged(signal.userID, signal.teamID, signal.item, await loopWindowMs(signal.userID, signal.teamID))
+      await teamInvolvement.progress(signal.userID, signal.teamID, signal.item, charged)
+    } catch (cause) { console.error("[hub] item progress reset failed:", cause) }
+  }
+  const seatContext = async (userID: string, sessionID: string) => {
+    const teams: { teamID: string; item?: string }[] = []
+    for (const { teamID } of await teamSeats!.seatsOf(userID, sessionID)) {
+      const item = await itemBudgets.current(userID, teamID, sessionID).catch(() => undefined)
+      teams.push({ teamID, ...(item ? { item } : {}) })
+    }
+    return { teams }
+  }
+  /** (TA2-5) A seat's turn ended (the journal's working → idle|error, the context cards' definition): sample its diff. */
+  const turnEndedDiff = async (userID: string, event: Parameters<typeof cardTriggerOf>[0]) => {
+    const trigger = cardTriggerOf(event)
+    if (trigger?.trigger === "turn-end") await diffSampler.turnEnded(userID, trigger.sessionID).catch((cause) => console.error("[hub] diff progress failed:", cause))
+  }
+  const progressSignals = new ProgressSignals({ seatContext, emit: onProgress, now, loopWindowMs: (userID, teamID) => loopWindowMs(userID, teamID) })
+  const diffSampler = new DiffSampler({
+    seats: async (userID, sessionID) => (await seatContext(userID, sessionID)).teams,
+    summary: async (userID, sessionID) => (registry.sessionTenant(sessionID) === userID ? ((await spokes.request(ownerOf(sessionID), { op: "summary", sessionID })) as SessionSummary) : undefined),
+    emit: onProgress,
+    now,
+    loopWindowMs: (userID, teamID) => loopWindowMs(userID, teamID),
+  })
+  const itemChecks = itemEligibility({ seats: teamSeats!, teams: teamStore, intake: { get: (userID, actor, teamID, itemID) => teamIntake!.get(userID, actor, teamID, itemID) } as Pick<TeamIntakeService, "get"> })
+  const delivery: Delivery = new Delivery({
+    itemBudgets,
+    items: itemChecks,
+    // (TA2-7) Every item-tagged pair message counts against the effective threshold; a stop opens the item's Decision.
+    itemLoop: async (userID, { teamID, item, from, to }) => {
+      const stall = await itemStalls.get(userID, teamID, item).catch(() => undefined)
+      if (stall?.reason === "loop" && stall.pair?.includes(from) && stall.pair.includes(to)) return true
+      if (!itemLoops.message({ userID, teamID, item, from, to }, await loopThreshold(userID, teamID))) return false
+      await itemStalls.hit(userID, teamID, item, "loop", [from, to].sort() as [string, string]).catch((cause) => console.error("[hub] item loop Decision failed:", cause))
+      return true
+    },
     hopLimit: config.hopLimit,
+    currentHopLimit: () => agentLimits.snapshot().hopLimit,
     teams: teamPolicy,
     teamHopCap: async (userID, input) => { await teamHopStalls.hit(userID, input.teamID, input.sender, input.recipient, input.limit) },
     teamHopNotice: async (userID, teamID) => {
@@ -969,6 +1122,11 @@ export function startCentral(options: CentralOptions): Central {
   let conciergeTierHooks: ConciergeTiers | undefined
   // Decisions (design §12.1): asks to @me; deadlines run over every user's Decisions (survive restarts).
   decisions = new Decisions({
+    answered: async (userID, decision, by) => {
+      if (by.via === "cookie" && decision.from.kind === "session") await progressSignals.consoleAnswered(userID, { sessionID: decision.from.sessionID, via: by.via, ref: decision.id, kind: "decision" }).catch((cause) => console.error("[hub] decision progress failed:", cause))
+      if (by.via === "cookie" && decision.action?.kind !== "teamHopRenew" && decision.action?.kind !== "teamItem" && decision.from.kind === "session")
+        await teamInvolvement.involved(userID, { kind: "decision", sessionID: decision.from.sessionID, ref: decision.id, actor: { deviceID: by.deviceID, via: by.via } })
+    },
     state: backends.state,
     delivery,
     now,
@@ -977,6 +1135,7 @@ export function startCentral(options: CentralOptions): Central {
     // The console's live Decision cards: opened, answered (here, by timeout), escalated, expired.
     changed: (userID, decision) => {
       broadcast({ type: "decision", decision }, { tenant: userID })
+      if (decision.action?.kind === "teamItem") void itemDecisionEnded(userID, decision).catch((cause) => console.error("[hub] item Decision end failed:", cause))
       conciergeTierHooks?.decisionChanged?.(userID, decision)
       // (REC-01) decision.opened / decision.answered of a recorded session (best effort).
       recordings?.decisionChanged(userID, decision)
@@ -989,9 +1148,17 @@ export function startCentral(options: CentralOptions): Central {
         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 })
+          ? teamInvolvement.renew(userID, teamID, decision.id, { deviceID: by.deviceID, via: by.via }).then(() => "done" as const)
           : Promise.resolve("done" as const)
       }
+      if (kind === "teamItem") {
+        const action = decision.action as Extract<NonNullable<typeof decision.action>, { kind: "teamItem" }>
+        if (by.userID !== userID || by.via !== "cookie") return Promise.resolve("gone" as const)
+        return (async () => {
+          const usage = await itemBudgets.usage(userID, action.teamID, action.item).catch(() => undefined)
+          return itemDecisionsFor(action.teamID, by).answer({ userID, teamID: action.teamID, item: action.item, title: "", reason: action.reason, decisionID: decision.id, ...(action.pair ? { pair: action.pair } : {}), usage: { wakes: usage?.wakes ?? 0, hours: usage?.hours ?? 0 }, limit: usage?.budget ?? { wakes: 0, hours: 0 } }, choice.option, by)
+        })()
+      }
       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)
@@ -1025,6 +1192,7 @@ export function startCentral(options: CentralOptions): Central {
       void revertWindows.observe(tenant, sessionID, committed).catch((cause) => console.error(`[hub] revert window not kept: ${(cause as Error).message}`))
     }
   })
+  // Spoke-origin human-turn evidence retains its existing per-seat reset only; it is not console authentication.
   registry.onHumanTurn((sessionID) => void humanTurn(sessionID))
   // (Session findability, decision iaspcry7) "Touched by me" and the activity meter: per user, per session; the
   // owner's consoles get each change as {type: "activity", sessionID, activity}.
@@ -1101,6 +1269,7 @@ export function startCentral(options: CentralOptions): Central {
     locks: backends.locks,
     owner: `hub-${process.pid}-${randomBytes(4).toString("hex")}`,
     ...(config.launchCaps ? { caps: config.launchCaps } : {}),
+    currentCaps: () => agentLimits.snapshot().launches,
     nodes,
     nodeOps: spokes,
     registry,
@@ -1211,7 +1380,7 @@ export function startCentral(options: CentralOptions): Central {
     log: backends.agentEvents ?? new MemoryEventLog({ now, max: AGENT_EVENTS_MAX, maxAgeMs: AGENT_EVENTS_AGE_MS }),
     kv: backends.kv,
     now,
-    onAppend: (userID, record) => (void teamIntake?.onEvent(userID, record.event), contextCards?.onEvent(userID, record.event), subscriptions?.observe(userID, record.event), conciergeOnAppend?.(userID, record.event), void conciergeActivity.observe(userID, record.event).catch(() => {}), void conciergeResults.observe(userID, record.event).catch(() => {}), webhooks.publishCanonical(userID, record.event, record.family, record.audience).then((queued) => (queued && !webhookLeader.isLeader() ? webhookLeader.kick() : undefined))),
+    onAppend: (userID, record) => (void teamIntake?.onEvent(userID, record.event), void turnEndedDiff(userID, record.event), contextCards?.onEvent(userID, record.event), subscriptions?.observe(userID, record.event), conciergeOnAppend?.(userID, record.event), void conciergeActivity.observe(userID, record.event).catch(() => {}), void conciergeResults.observe(userID, record.event).catch(() => {}), webhooks.publishCanonical(userID, record.event, record.family, record.audience).then((queued) => (queued && !webhookLeader.isLeader() ? webhookLeader.kick() : undefined))),
   })
   const agentEventWriters = new EventWriters({
     events: agentEvents,
@@ -1235,7 +1404,11 @@ export function startCentral(options: CentralOptions): Central {
         workspaces: artifactWorkspacesFromState(backends.state),
         ...(options.previewRetention?.archiveAfterMs !== undefined ? { previewArchiveAfterMs: options.previewRetention.archiveAfterMs } : {}),
         ...(options.previewRetention?.purgeAfterMs !== undefined ? { previewPurgeAfterMs: options.previewRetention.purgeAfterMs } : {}),
-        onEvent: (userID, event) => void agentEvents.append(userID, artifactJournalEvent(event)).catch((cause) => console.error(`[hub] artifact event failed: ${(cause as Error).message}`)),
+        onEvent: (userID, event) => {
+          void agentEvents.append(userID, artifactJournalEvent(event)).catch((cause) => console.error(`[hub] artifact event failed: ${(cause as Error).message}`))
+          if ((event.type === "artifact.created" || event.type === "artifact.revised") && event.authorSessionID)
+            void progressSignals.artifactChanged(userID, event.artifactID, event.revision, event.authorSessionID).catch((cause) => console.error("[hub] artifact progress failed:", cause))
+        },
       })
     : undefined
   const artifactMaintenance = artifacts ? new ArtifactMaintenance({ artifacts, users: allUsers }) : undefined
@@ -1440,6 +1613,21 @@ export function startCentral(options: CentralOptions): Central {
   // Team intake (HWA-36): delivered to an entry seat from the fixed party app:team-intake (never the submitter). The
   // message inherits the item's notAfter (H4); queued items past it are cancelled by the team-intake leader's sweep.
   teamIntake = new TeamIntakeService({
+    budgets: itemBudgets,
+    parentOf: async (userID, teamID, sessionID) => {
+      const current = await itemBudgets.current(userID, teamID, sessionID)
+      if (!current) return undefined
+      const eligible = await itemChecks.eligible(userID, current, [sessionID])
+      if (!eligible.ok || eligible.teamID !== teamID) return undefined
+      const root = eligible.parentItem ?? (eligible.child ? undefined : current)
+      if (!root) return undefined
+      if (root === current) return root
+      const parent = await itemChecks.eligible(userID, root, [sessionID])
+      return parent.ok && !parent.child && parent.teamID === teamID ? root : undefined
+    },
+    routed: (userID, teamID, intakeID, sessionID) => itemBudgets.setCurrent(userID, teamID, sessionID, intakeID),
+    progressChanged: ({ userID, teamID, item, sessionID, revision, status, actor }) => progressSignals.intake({ userID, teamID, item, revision, status, actor: actor.kind === "session" ? { kind: "session", sessionID: actor.sessionID } : { kind: actor.kind }, ...(sessionID ? { sessionID } : {}) }),
+    submittedByUser: (userID, teamID, intakeID, actor) => actor.via === "cookie" ? teamInvolvement.involved(userID, { kind: "intake", teamIDs: [teamID], ref: intakeID, actor: { deviceID: actor.deviceID, via: actor.via } }) : Promise.resolve(),
     state: backends.state,
     teams: teamStore,
     seats: teamSeats,
@@ -1492,6 +1680,7 @@ export function startCentral(options: CentralOptions): Central {
   subscriptions = new Subscriptions({
     state: backends.state,
     hopLimit: config.hopLimit,
+    currentHopLimit: () => agentLimits.snapshot().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 }),
@@ -1801,7 +1990,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 = { 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 agentDeps = { nodes, agentLimits, 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),
@@ -1834,9 +2023,28 @@ export function startCentral(options: CentralOptions): Central {
 
   async function handle(request: Request, server: Server<SpokeSocketData>): Promise<Response | undefined> {
     const url = new URL(request.url)
+    // /api/v1/<rest> is /api/<rest> of the two route tables, its errors in one envelope (./api-v1.ts). The handlers
+    // get the unversioned URL and the request itself (server.timeout and the body belong to that object).
+    const unversioned = unversionedURL(url)
+    if (!unversioned) return await respond(request, server, url, false)
+    return await apiV1Response((await respond(request, server, unversioned, true)) ?? error(404, "Not found"))
+  }
+
+  async function respond(request: Request, server: Server<SpokeSocketData>, url: URL, v1: boolean): Promise<Response | undefined> {
     const { pathname } = url
     const method = request.method
+    if (!agentLimits.initialLoaded() && !((method === "GET" || method === "HEAD") && (pathname === "/healthz" || pathname === "/readyz"))) {
+      let timer: ReturnType<typeof setTimeout> | undefined
+      await Promise.race([agentLimitsReady, new Promise<void>((resolve) => { timer = setTimeout(resolve, options.timing?.agentLimitsInitialWaitMs ?? 5_000) })])
+      if (timer) clearTimeout(timer)
+      if (!agentLimits.initialLoaded()) return Response.json({ error: "Agent limits unavailable", code: "busy" }, { status: 503, headers: { ...NO_STORE, "retry-after": String(agentLimits.retryAfter()) } })
+    }
     try {
+      // A /api/v1 request reaches the two route tables only: none of the endpoints below and never a static file.
+      if (v1) {
+        await store.ready()
+        return isAgentPath(pathname) ? await agent.handle(request, url) : await api(request, server, url)
+      }
       // HEAD (uptime monitors, `curl -I`) gets GET's status and headers without a body, on the health routes only.
       if ((method === "GET" || method === "HEAD") && (pathname === "/readyz" || pathname === "/healthz")) {
         const response = pathname === "/readyz" ? await readyz() : healthz()
@@ -2210,7 +2418,7 @@ export function startCentral(options: CentralOptions): Central {
       registry.setPresence(device.id, params.session!, visible)
       return new Response(null, { status: 204 })
     }),
-    route("POST", "/api/sessions/:session/turn", "session", ({ request, server, params }) => turn(request, server, params.session!)),
+    route("POST", "/api/sessions/:session/turn", "session", ({ request, server, params, device }) => turn(request, server, params.session!, device.id)),
     route("POST", "/api/sessions/:session/utterance", "session", ({ request, params, device }) => utterance(request, params.session!, device.id), true),
     route(
       "POST",
@@ -2320,8 +2528,8 @@ export function startCentral(options: CentralOptions): Central {
       "session",
       async ({ params }) => Response.json(await spokes.request(ownerOf(params.session!), { op: "context", sessionID: params.session! })),
     ),
-    route("POST", "/api/sessions/:session/permission", "session", ({ request, params, user }) => permission(request, params.session!, user.id)),
-    route("POST", "/api/sessions/:session/form", "session", ({ request, params, user }) => form(request, params.session!, user.id)),
+    route("POST", "/api/sessions/:session/permission", "session", ({ request, params, user, device }) => permission(request, params.session!, user.id, device.id)),
+    route("POST", "/api/sessions/:session/form", "session", ({ request, params, user, device }) => form(request, params.session!, user.id, device.id)),
     route("GET", "/api/sessions/:session/summary", "session", async ({ params }) =>
       Response.json(await spokes.request(ownerOf(params.session!), { op: "summary", sessionID: params.session! }), { headers: NO_STORE })),
     // Context cards (docs/context-cards.md): a session's cards, and a provider's manual refresh.
@@ -2395,6 +2603,13 @@ export function startCentral(options: CentralOptions): Central {
       await store.audit({ actor: user.id, action: enabled ? "agents.acting.resume" : "agents.acting.pause" })
       return Response.json({ enabled }, { headers: NO_STORE })
     }),
+    // RB-1 (plan sjaqp2ay): a team's hop depths, and the user's Renew button. Renew is cookie only (a device token
+    // gets 403; session, app and Concierge tokens never reach console routes) and strict: a failed reset → 500.
+    route("GET", "/api/teams/:id/hops", "user", async ({ params, user }) => teamHopsAnswer(user.id, params.id!)),
+    route("POST", "/api/teams/:id/renew", "user", async ({ request, params, user, device }) => {
+      if ((await resolveActor.mode(request)) !== "cookie") return error(403, "Renew a team from the console", "forbidden")
+      return teamHopsAnswer(user.id, params.id!, (teamID) => teamInvolvement.renewManual(user.id, teamID, { deviceID: device.id, via: "cookie" }))
+    }),
     // Decisions (asks to @me): the user's own; answered only here (tap: the console cookie, not a device token).
     route("GET", "/api/decisions", "user", async ({ url, user }) => {
       try {
@@ -2415,13 +2630,28 @@ export function startCentral(options: CentralOptions): Central {
       try {
         const answered = await decisions.answer(user.id, params.id!, decisionAnswer(input), { kind: "user", userID: user.id, deviceID: device.id, via })
         if (answered.reply) feed.publish(user.id, answered.reply)
-        await store.audit({ actor: user.id, action: "decision.answer", target: params.id!, detail: answered.decision.answer?.option ?? "text" })
+        await store.audit({ actor: user.id, action: "decision.answer", target: params.id!, detail: answerDetail(answered.decision.answer) })
         return Response.json(answered, { headers: NO_STORE })
       } catch (cause) {
         return decisionFailure(cause)
       }
     }),
     route("GET", "/api/settings/speech/default", "admin", () => Response.json(speechSettings.view(), { headers: NO_STORE })),
+    route("GET", "/api/settings/agent-limits", "admin", async () => Response.json(await agentLimits.view(), { headers: NO_STORE })),
+    route("PUT", "/api/settings/agent-limits", "admin", async ({ request, user }) => {
+      // (HC-1) The safety limits change only from the signed-in console (the cookie), never a device token.
+      if ((await resolveActor.mode(request)) !== "cookie") return error(403, "Agent limits change only in the signed-in console", "forbidden", NO_STORE)
+      if (!agentLimits.initialLoaded()) return Response.json({ error: "Agent limits unavailable", code: "busy" }, { status: 503, headers: { ...NO_STORE, "retry-after": String(agentLimits.retryAfter()) } })
+      const before = await agentLimits.view()
+      try {
+        const after = await agentLimits.update(await jsonBody(request))
+        await store.audit({ actor: user.id, action: "agents.limits.set", detail: JSON.stringify({ before: before.invalidStored ? "invalid" : before, after }) })
+        return Response.json(after, { headers: NO_STORE })
+      } catch (cause) {
+        if (cause instanceof AgentError) return error(AGENT_ERROR_STATUS[cause.code], cause.message, cause.code, NO_STORE)
+        throw cause
+      }
+    }),
     route("PUT", "/api/settings/speech/default", "admin", async ({ request, user }) => {
       const view = await speechSettings.update(await jsonBody(request))
       await store.audit({ actor: user.id, action: "speech.default" })
@@ -2494,6 +2724,22 @@ export function startCentral(options: CentralOptions): Central {
     return new Response(null, { status: 204 })
   }
 
+  /** The team's effective hop limit, its seats' depths and whether a hop-cap Decision is open (after `before`). */
+  async function teamHopsAnswer(userID: string, id: string, before?: (teamID: string) => Promise<void>): Promise<Response> {
+    try {
+      const team = (await teamStore.get(userID, id)) ?? (await teamStore.byName(userID, id))
+      if (!team) return error(404, "No such team", "not_found", NO_STORE)
+      await before?.(team.id)
+      const global = agentLimits.snapshot().hopLimit
+      const current = await teamSeats!.list(userID, team.id, { current: true })
+      const seats = await Promise.all(current.map(async (seat) => ({ sessionID: seat.sessionID, role: seat.role, depth: await delivery.hops.depth(userID, { kind: "session", sessionID: seat.sessionID }) })))
+      return Response.json({ limit: Math.min(team.hopLimit ?? global, global), maxDepth: Math.max(0, ...seats.map((seat) => seat.depth)), seats, stalled: await teamHopStalls.open(userID, team.id) }, { headers: NO_STORE })
+    } catch (cause) {
+      if (cause instanceof AgentError) return error(AGENT_ERROR_STATUS[cause.code], cause.message, cause.code, NO_STORE)
+      throw cause
+    }
+  }
+
   /** A connect-flow handler's AgentError as the console's error envelope. */
   async function connectAnswer(run: () => Promise<Response>): Promise<Response> {
     try {
@@ -2585,7 +2831,7 @@ export function startCentral(options: CentralOptions): Central {
     return Response.json(userRow(store.user(id)!))
   }
 
-  async function turn(request: Request, server: Server<SpokeSocketData>, sessionID: string): Promise<Response> {
+  async function turn(request: Request, server: Server<SpokeSocketData>, sessionID: string, deviceID: string): Promise<Response> {
     const input = await body(request)
     const raw = input.text
     const text = typeof raw === "string" ? raw.trim() : ""
@@ -2604,6 +2850,8 @@ export function startCentral(options: CentralOptions): Central {
     const started = await actions.prompt({ sessionID, text, ...(images ? { images } : {}), resetHops: true })
     if (started.outcome === "offline") throw new HttpError(409, NO_OWNER)
     if (started.outcome === "unsupported") throw unsupportedError(started)
+    const tenant = registry.sessionTenant(sessionID)
+    if (tenant !== undefined && (await resolveActor.mode(request)) === "cookie") await teamInvolvement.involved(tenant, { kind: "prompt", sessionID, ref: "console-turn", actor: { deviceID, via: "cookie" } })
     if (started.mode === "steer") return Response.json({ mode: "steer", inboxID: started.inboxID }, { status: 202 })
     const result = started.result
     if (!/(^|[\s,])respond-async\b/i.test(request.headers.get("prefer") ?? "")) return Response.json(await result)
@@ -2614,7 +2862,6 @@ export function startCentral(options: CentralOptions): Central {
       if ("cause" in early) throw early.cause
       return Response.json(early.value)
     }
-    const tenant = registry.sessionTenant(sessionID)
     void result.then(
       (value) => broadcast({ type: "turn", sessionID, ...value }, { tenant }),
       (cause: unknown) => {
@@ -2896,7 +3143,10 @@ export function startCentral(options: CentralOptions): Central {
     const text = typeof raw === "string" ? raw.trim() : ""
     if (!text) return error(400, "Empty utterance")
     if (text.length > MAX_UTTERANCE_CHARS) return error(400, `Utterance longer than ${MAX_UTTERANCE_CHARS} characters`)
-    return Response.json({ inboxID: await sendUtterance(sessionID, text, undefined, deviceID) }, { status: 202 })
+    const inboxID = await sendUtterance(sessionID, text, undefined, deviceID)
+    const tenant = registry.sessionTenant(sessionID)
+    if (tenant !== undefined && (await resolveActor.mode(request)) === "cookie") await teamInvolvement.involved(tenant, { kind: "prompt", sessionID, ref: "utterance", actor: { ...(deviceID ? { deviceID } : {}), via: "cookie" } })
+    return Response.json({ inboxID }, { status: 202 })
   }
 
   /**
@@ -3179,7 +3429,7 @@ export function startCentral(options: CentralOptions): Central {
   const auditUserAnswer = (userID: string, verb: "approve" | "deny" | "answer", target: { sessionID: string; requestID?: string; formID?: string }) =>
     void audit.record(userID, { actor: { kind: "user" }, verb, target, decision: "allow", outcome: "ok" }).catch((cause: unknown) => console.error(`[hub] audit of a console answer failed: ${(cause as Error).message}`))
 
-  async function permission(request: Request, rootID: string, userID: string): Promise<Response> {
+  async function permission(request: Request, rootID: string, userID: string, deviceID: string): Promise<Response> {
     const input = await body(request)
     const decision = input.decision as PermissionDecision
     if (typeof input.requestID !== "string" || !DECISIONS.has(decision)) return error(400, "Invalid decision")
@@ -3187,12 +3437,16 @@ export function startCentral(options: CentralOptions): Central {
     const answered = await actions.answerPermission({ rootID, requestID: input.requestID, decision })
     if (answered.outcome === "unsupported") throw unsupportedError(answered)
     if (answered.outcome === "done") auditUserAnswer(userID, decision === "reject" ? "deny" : "approve", { sessionID: asking, requestID: input.requestID })
+    if (answered.outcome === "done" && (await resolveActor.mode(request)) === "cookie") {
+      await teamInvolvement.involved(userID, { kind: "permission", sessionID: asking, ref: input.requestID, actor: { deviceID, via: "cookie" } })
+      await progressSignals.consoleAnswered(userID, { sessionID: asking, via: "cookie", ref: `permission:${input.requestID}`, kind: "approval" }).catch((cause) => console.error("[hub] approval progress failed:", cause))
+    }
     if (answered.outcome === "done") humanActivity.human(userID, registry.rootOf(rootID) ?? rootID, "answer")
     return answered.outcome === "done" ? new Response(null, { status: 204 }) : error(409, PERMISSION_GONE, "gone")
   }
 
   /** Answers or cancels a pending form (question) in the session's tree, through a process that holds it. */
-  async function form(request: Request, rootID: string, userID: string): Promise<Response> {
+  async function form(request: Request, rootID: string, userID: string, deviceID: string): Promise<Response> {
     const input = await body(request)
     if (typeof input.formID !== "string" || !input.formID || input.formID.length > 300) return error(400, "Expected {formID, answer} or {formID, cancel: true}")
     const cancel = input.cancel === true
@@ -3207,6 +3461,10 @@ export function startCentral(options: CentralOptions): Central {
     )
     if (answered.outcome === "unsupported") throw unsupportedError(answered)
     if (answered.outcome === "done") auditUserAnswer(userID, "answer", { sessionID: asking, formID: input.formID })
+    if (answered.outcome === "done" && (await resolveActor.mode(request)) === "cookie") {
+      await teamInvolvement.involved(userID, { kind: "form", sessionID: asking, ref: input.formID, actor: { deviceID, via: "cookie" } })
+      await progressSignals.consoleAnswered(userID, { sessionID: asking, via: "cookie", ref: `form:${input.formID}`, kind: "approval" }).catch((cause) => console.error("[hub] approval progress failed:", cause))
+    }
     if (answered.outcome === "done") humanActivity.human(userID, registry.rootOf(rootID) ?? rootID, "answer")
     return answered.outcome === "done" ? new Response(null, { status: 204 }) : error(409, PERMISSION_GONE, "gone")
   }
@@ -3376,6 +3634,7 @@ export function startCentral(options: CentralOptions): Central {
   }
 
   async function readyz(): Promise<Response> {
+    if (!agentLimits.initialLoaded()) return Response.json({ ok: false, error: "Agent limits unavailable" }, { status: 503, headers: NO_STORE })
     if (draining) return Response.json({ ok: false, draining: true }, { status: 503, headers: NO_STORE })
     if (config.cluster) {
       let timer: ReturnType<typeof setTimeout> | undefined
@@ -3474,6 +3733,7 @@ export function startCentral(options: CentralOptions): Central {
     push,
     speechSettings,
     backends,
+    agentLimits,
     delivery,
     decisions,
     acting,
@@ -3496,6 +3756,7 @@ export function startCentral(options: CentralOptions): Central {
       return draining
     },
     async stop() {
+      await agentLimits.stop()
       // Step down first (releasing the leases), so another pod takes the timed jobs over at once.
       await Promise.allSettled([...leaders.map((loop) => loop.stop()), recommendations?.stop()])
       launches.shutdown()
@@ -3533,12 +3794,13 @@ const optionalState = (url: URL): { state?: Decision["state"] } => {
 }
 
 /** {option?, text?, via?} of a Decision answer (types only; Decisions validates). */
-function decisionAnswer(input: Record<string, unknown>): { option?: string; text?: string; via?: AnswerVia } {
+function decisionAnswer(input: Record<string, unknown>): { option?: string; text?: string; picks?: Record<string, string>; via?: AnswerVia } {
   for (const key of ["option", "text"] as const) {
     if (input[key] !== undefined && typeof input[key] !== "string") throw new AgentError("invalid", `${key} must be a string`)
   }
   if (input.via !== undefined && !(ANSWER_VIAS as readonly unknown[]).includes(input.via)) throw new AgentError("invalid", `via is one of ${ANSWER_VIAS.join(", ")}`)
-  return { ...(typeof input.option === "string" ? { option: input.option } : {}), ...(typeof input.text === "string" ? { text: input.text } : {}), ...(input.via !== undefined ? { via: input.via as AnswerVia } : {}) }
+  const picks = answerPicks(input.picks)
+  return { ...(typeof input.option === "string" ? { option: input.option } : {}), ...(typeof input.text === "string" ? { text: input.text } : {}), ...(picks ? { picks } : {}), ...(input.via !== undefined ? { via: input.via as AnswerVia } : {}) }
 }
 
 /**

package/src/central/recording/index.ts

@@ -735,7 +735,8 @@ export class RecordingService {
       if (this.opened.size > 2000) this.opened.delete(this.opened.values().next().value as string)
       this.hub(userID, sessionID, "decision.opened", { decisionID: decision.id, from: partyKey(from), tier: decision.tier, urgency: decision.urgency, options: decision.options.map((o) => o.id), text: decision.question })
     } else if (decision.state === "answered" && decision.answer?.answeredBy === "user") {
-      this.hub(userID, sessionID, "decision.answered", { decisionID: decision.id, ...(decision.answer.option !== undefined ? { option: decision.answer.option } : {}), via: decision.answer.via ?? "tap" })
+      const picks = decision.answer.picks && Object.entries(decision.answer.picks).map(([group, option]) => ({ group, option }))
+      this.hub(userID, sessionID, "decision.answered", { decisionID: decision.id, ...(decision.answer.option !== undefined ? { option: decision.answer.option } : {}), ...(picks ? { picks } : {}), via: decision.answer.via ?? "tap" })
     }
   }
 

package/src/central/recording/schema.ts

@@ -134,7 +134,8 @@ export const CONSOLE_FIELDS: Readonly<Record<ConsoleEventKind, Fields>> = {
   },
   "resource.timing": { route: oneOf("transcribe", "speak", "events", "utterance", "recording"), n: int, medianMs: num, maxMs: num, "medianTtfbMs?": num, "bytes?": int },
   "console.log": { level: oneOf("error", "warn", "unhandled"), message: text(L.messageChars), "count?": int, "source?": label },
-  "decision.voice": { decisionID: id, option: id, outcome: oneOf("answered", "refused", "failed") },
+  // DC-1: a choices Decision is answered with picks (one per group) instead of an option.
+  "decision.voice": { decisionID: id, "option?": id, "picks?": list(object({ group: label, option: label }), 12), outcome: oneOf("answered", "refused", "failed") },
   "clock.sync": { t0: num, t1: num, hubAt: num },
   error: { where: oneOf("stt", "tts", "send", "mic", "upload", "audio"), message: text(L.messageChars) },
 }