@huynle/hub 0.10.1 → 0.11.1

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

@@ -120,6 +120,7 @@ export interface LaunchEngineDeps {
   /** This process (pod), as placement lease owner. */
   readonly owner: string
   readonly caps?: HubLaunches
+  readonly currentCaps?: () => { readonly maxQueued: number; readonly maxActive: number; readonly perHour: number; readonly lostAfterMinutes?: number | false }
   readonly nodes: EngineNodes
   readonly nodeOps: EngineNodeOps
   readonly registry: EngineRegistry
@@ -334,7 +335,10 @@ export class LaunchEngine {
   private readonly timers: Timers
   private tickTimer: unknown
   /** How long the reporting node instance may omit a running launch (NODE_UNREPORTED_MS, or caps.lostAfterMinutes; undefined: never). */
-  private readonly nodeLostMs: number | undefined
+  private get nodeLostMs(): number | undefined {
+    const lostAfter = this.deps.currentCaps?.().lostAfterMinutes ?? this.deps.caps?.lostAfterMinutes
+    return lostAfter === false || lostAfter === 0 ? undefined : lostAfter !== undefined ? lostAfter * 60_000 : NODE_UNREPORTED_MS
+  }
   /** Machines being reconciled now. */
   private readonly reconciling = new Set<string>()
   /** Reconcile cleanup retries per launch, and the launches whose failing retry was logged. */
@@ -352,8 +356,6 @@ export class LaunchEngine {
     this.now = deps.now ?? Date.now
     this.timers = deps.timers ?? defaultTimers
     this.store = new LaunchStore({ state: deps.state, now: this.now })
-    const lostAfter = deps.caps?.lostAfterMinutes
-    this.nodeLostMs = lostAfter === false || lostAfter === 0 ? undefined : lostAfter !== undefined ? lostAfter * 60_000 : NODE_UNREPORTED_MS
     const { registry } = deps
     this.placement = new Placement({
       store: this.store,
@@ -369,6 +371,7 @@ export class LaunchEngine {
       locks: deps.locks,
       owner: deps.owner,
       ...(deps.caps ? { caps: deps.caps } : {}),
+      ...(deps.currentCaps ? { currentCaps: deps.currentCaps } : {}),
       ...(deps.launchers ? { launchers: deps.launchers } : {}),
       now: this.now,
     })
@@ -746,7 +749,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 +1125,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 +1150,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
+/** (HC-1) The absolute bound of any configured hop limit or ceiling (the live ceiling is in AgentLimits). */
+export const HOP_ABSOLUTE_MAX = TEAM_LIMITS.hopLimit
 /** A depth no message refreshed for this long is forgotten. */
 export const HOP_TTL_MS = 24 * 60 * 60_000
 
@@ -160,6 +163,9 @@ export class MessageLimiter {
   private readonly now: Clock
   private readonly limits: MessageLimits
 
+  /** The configured recipient wake cap for the current 10-minute window. */
+  get wakeLimit(): number { return this.limits.wake }
+
   constructor(deps: { readonly counters: Counters; readonly now?: Clock; readonly limits?: Partial<MessageLimits> }) {
     this.counters = deps.counters
     this.now = deps.now ?? Date.now

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

@@ -43,6 +43,7 @@ import type { AgentActor } from "./actor"
 import { type AskInput, DECISION_STATES, type DecisionState, type Decisions, type Tier, type Urgency } from "./decisions"
 import type { Delivery, SendOptions, Sent } from "./delivery"
 import type { Directory } from "./directory"
+import { isContractID } from "../../protocol"
 import { partyFromActor, partyKey } from "./envelope"
 import { AgentError } from "./errors"
 import { idempotencyKeyOf, REPLAYED_HEADER, RouteIdempotency } from "./idempotency"
@@ -136,7 +137,7 @@ const sendOptions = (body: Body, delivery: Pick<Delivery, "checkNotAfter">): Sen
 /** The user's address (also the malformed `@me.project`, which the delivery engine refuses). */
 const isMe = (to: string) => to === "@me" || to.startsWith("@me.")
 
-const DECISION_FIELDS = ["options", "recommendation", "urgency", "tier", "deadline", "onTimeout", "about"] as const
+const DECISION_FIELDS = ["options", "recommendation", "choices", "kind", "urgency", "tier", "deadline", "onTimeout", "about"] as const
 
 /** The state query parameter of a Decision listing, or undefined. */
 export function decisionStateQuery(raw: string | null): DecisionState | undefined {
@@ -162,7 +163,21 @@ function decisionFields(body: Body): Omit<AskInput, "question" | "about" | "expi
     if (typeof r !== "object" || r === null || Array.isArray(r)) throw new AgentError("invalid", "recommendation must be {option, why?}")
     out.recommendation = { option: r.option, ...(r.why === undefined ? {} : { why: r.why }) }
   }
-  for (const key of ["urgency", "tier", "onTimeout"] as const) {
+  if (body.choices !== undefined) {
+    const shape = "choices must be a list of {id, label, options: [{id, label, recommended?}]}"
+    if (!Array.isArray(body.choices)) throw new AgentError("invalid", shape)
+    out.choices = body.choices.map((group: unknown) => {
+      if (typeof group !== "object" || group === null || Array.isArray(group)) throw new AgentError("invalid", shape)
+      const { id, label, options } = group as Record<string, unknown>
+      if (!Array.isArray(options)) throw new AgentError("invalid", shape)
+      return { id, label, options: options.map((option: unknown) => {
+        if (typeof option !== "object" || option === null || Array.isArray(option)) throw new AgentError("invalid", shape)
+        const o = option as Record<string, unknown>
+        return { id: o.id, label: o.label, ...(o.recommended === undefined ? {} : { recommended: o.recommended }) }
+      }) }
+    })
+  }
+  for (const key of ["urgency", "tier", "onTimeout", "kind"] as const) {
     if (body[key] === undefined) continue
     if (typeof body[key] !== "string") throw new AgentError("invalid", `${key} must be a string`)
     out[key] = body[key]
@@ -177,11 +192,12 @@ function decisionFields(body: Body): Omit<AskInput, "question" | "about" | "expi
 }
 
 /** The stored message, how it was delivered and, for a session recipient, whether it woke it (and why not). */
-const sentView = ({ message, delivery, woke, wakeSkipped }: Sent) => ({
+const sentView = ({ message, delivery, woke, wakeSkipped, wakeLimit }: Sent) => ({
   message,
   ...(delivery ? { delivery } : {}),
   ...(woke === undefined ? {} : { woke }),
   ...(wakeSkipped ? { wakeSkipped } : {}),
+  ...(wakeLimit !== undefined ? { wakeLimit } : {}),
 })
 
 export function messageRoutes(deps: MessageDeps): AgentRoute[] {
@@ -271,6 +287,13 @@ export function messageRoutes(deps: MessageDeps): AgentRoute[] {
     return sent
   }
 
+  async function explicitItem(userID: string, actor: AgentActor, to: string, raw: unknown): Promise<string | undefined> {
+    if (raw === undefined) return undefined
+    if (!isContractID("intake", raw)) throw new AgentError("invalid", "item must be an itk_ ID")
+    if (isMe(to) || actor.kind !== "session") throw new AgentError("invalid", "item applies to messages between team members")
+    return raw
+  }
+
   return [
     {
       method: "POST",
@@ -281,7 +304,8 @@ export function messageRoutes(deps: MessageDeps): AgentRoute[] {
         const to = string(body, "to")
         const text = string(body, "text", TEXT_MAX)
         const all = flag(body, "all")
-        const sent = await send(user.id, actor, to, "msg", text, sendOptions(body, delivery), all)
+        const item = await explicitItem(user.id, actor, to, body.item)
+        const sent = await send(user.id, actor, to, "msg", text, { ...sendOptions(body, delivery), ...(item ? { item } : {}) }, all)
         return ok(all ? { sent: sent.map(sentView) } : sentView(sent[0]!), 201)
       }),
     },
@@ -293,11 +317,12 @@ export function messageRoutes(deps: MessageDeps): AgentRoute[] {
         const body = await bodyOf(request)
         const to = string(body, "to")
         const text = string(body, "text", TEXT_MAX)
+        const item = await explicitItem(user.id, actor, to, body.item)
         const all = flag(body, "all")
         const expiresIn = seconds(body.expiresIn, "expiresIn")
         const wait = seconds(body.wait, "wait", WAIT_MAX_S)
         if (all && wait !== undefined) throw new AgentError("invalid", "wait cannot be combined with all")
-        const options: SendOptions = { ...sendOptions(body, delivery), ...(expiresIn === undefined ? {} : { expiresInMs: Math.round(expiresIn * 1000) }) }
+        const options: SendOptions = { ...sendOptions(body, delivery), ...(item ? { item } : {}), ...(expiresIn === undefined ? {} : { expiresInMs: Math.round(expiresIn * 1000) }) }
         const decisionAsked = DECISION_FIELDS.some((key) => body[key] !== undefined)
         if (isMe(to) && deps.decisions) {
           if (all) throw new AgentError("invalid", "all cannot be combined with @me")
@@ -314,7 +339,7 @@ export function messageRoutes(deps: MessageDeps): AgentRoute[] {
           const done = await settled(user.id, message, wait, request.signal)
           return ok({ ...done, decision: (await deps.decisions.get(user.id, decision.id)) ?? decision }, 201)
         }
-        if (decisionAsked) throw new AgentError("invalid", "options, recommendation, urgency, tier, deadline, onTimeout and about are for asks to @me")
+        if (decisionAsked) throw new AgentError("invalid", "options, recommendation, choices, kind, urgency, tier, deadline, onTimeout and about are for asks to @me")
         const sent = await send(user.id, actor, to, "ask", text, options, all)
         if (all) return ok({ sent: sent.map(sentView) }, 201)
         return ok({ ...sentView(sent[0]!), ...(await settled(user.id, sent[0]!.message, wait, request.signal)) }, 201)
@@ -326,6 +351,7 @@ export function messageRoutes(deps: MessageDeps): AgentRoute[] {
       allow: SEND,
       async handle({ request, user, actor }) {
         const body = await bodyOf(request)
+        if (body.item !== undefined) throw new AgentError("invalid", "item is not accepted on replies", { hint: "replies inherit the item of the message they answer" })
         const replyTo = string(body, "replyTo")
         const text = string(body, "text", TEXT_MAX)
         const wake = flag(body, "wake")
@@ -342,6 +368,7 @@ export function messageRoutes(deps: MessageDeps): AgentRoute[] {
       allow: SEND,
       async handle({ request, user, actor }) {
         const body = await bodyOf(request)
+        if (body.item !== undefined) throw new AgentError("invalid", "item is not accepted on declines", { hint: "replies inherit the item of the message they answer" })
         const replyTo = string(body, "replyTo")
         const why = string(body, "why", WHY_MAX)
         ensureOn(user.id)

package/src/central/agent/messages.ts

@@ -59,6 +59,8 @@ export interface Message {
   /** The role holder generation it reached (role addresses). */
   readonly generation?: number
   readonly text: string
+  /** Explicit intake item attribution, checked against the sender's current team seat. */
+  readonly item?: string
   /** What a reply or decline answers. */
   readonly replyTo?: string
   readonly state: MessageState
@@ -90,6 +92,7 @@ export interface SendInput {
   readonly recipient: Party
   readonly kind: "msg" | "ask"
   readonly text: string
+  readonly item?: string
   readonly generation?: number
   /** From HopTracker.next (default 0). */
   readonly hop?: number
@@ -106,6 +109,8 @@ export interface AnswerInput {
   /** The replier's current role holder generation, when it holds the role the original reached. */
   readonly generation?: number
   readonly hop?: number
+  /** Only when both parties still hold seats and the answered item's team is active/open. */
+  readonly item?: string
 }
 
 export interface Answered {
@@ -228,6 +233,7 @@ export class Messages {
       recipient: input.recipient,
       ...(input.generation === undefined ? {} : { generation: input.generation }),
       text,
+      ...(input.item ? { item: input.item } : {}),
       state: input.kind === "ask" ? "open" : "sent",
       at,
       hop: input.hop ?? 0,
@@ -377,6 +383,7 @@ export class Messages {
       recipient: original.from,
       text,
       replyTo: original.id,
+      ...(input.item ? { item: input.item } : {}),
       state: "sent",
       at,
       hop: input.hop ?? 0,

package/src/central/agent/placement.ts

@@ -203,6 +203,7 @@ export interface PlacementDeps {
   /** This process (pod) as lease owner. */
   readonly owner: string
   readonly caps?: HubLaunches
+  readonly currentCaps?: () => LaunchCaps
   readonly now?: Clock
   readonly leaseMs?: number
   /** Revoked launchers (flagged in the active wait); without it none is. */
@@ -244,12 +245,13 @@ export const pastNotAfter = (launch: Pick<Launch, "spec">, now: number): boolean
 export const placementLeaseKey = (userID: string) => `placement:${userID}`
 
 export class Placement {
-  readonly caps: LaunchCaps
+  get caps(): LaunchCaps { return this.deps.currentCaps?.() ?? this.initialCaps }
+  private readonly initialCaps: LaunchCaps
   private readonly now: Clock
   private readonly leaseMs: number
 
   constructor(private readonly deps: PlacementDeps) {
-    this.caps = { ...DEFAULT_LAUNCH_CAPS, ...deps.caps }
+    this.initialCaps = { ...DEFAULT_LAUNCH_CAPS, ...deps.caps }
     this.now = deps.now ?? Date.now
     this.leaseMs = deps.leaseMs ?? PLACEMENT_LEASE_MS
   }

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

@@ -26,6 +26,7 @@ import type { EventsRouteDeps } from "./events-routes"
 import { type Census, type TeamDiscovery, visible } from "../teams/discovery"
 import type { SessionIntent } from "../../protocol"
 import { intentField } from "./intents"
+import type { SessionHealth } from "../health/classify"
 
 /** Labels per session ID. */
 export type SessionLabels = ReadonlyMap<string, Readonly<Record<string, string>>>
@@ -86,6 +87,8 @@ export interface AgentSessionView {
   readonly harness: string
   readonly parentID?: string
   readonly busySince?: number
+  /** (SS-1) Why it is not making progress (provider retry, quota, auth, …); absent: ok. */
+  readonly health?: SessionHealth
   readonly now?: string
   readonly blockers: { kind: string; id: string; summary: string; sessionID?: string }[]
   readonly children: number
@@ -139,6 +142,7 @@ function view({ session: s, harness }: Row, entry: DirectoryEntry | undefined, l
     harness,
     ...(s.parentID ? { parentID: s.parentID } : {}),
     ...(own?.since !== undefined ? { busySince: own.since } : {}),
+    ...(own?.health ? { health: own.health } : {}),
     ...(s.now ? { now: nowText(s.now) } : {}),
     blockers: s.blockers.map((b) => ({ kind: b.kind, id: b.id, summary: b.summary, ...(b.sessionID !== s.id ? { sessionID: b.sessionID } : {}) })),
     children: s.status.filter((e) => e.parentID === s.id).length,
@@ -290,6 +294,7 @@ async function show(deps: ReadDeps, userID: string, addr: string, census?: Censu
     directory: live.directory,
     ...(live.parentID ? { parentID: live.parentID } : {}),
     ...(own?.since !== undefined ? { busySince: own.since } : {}),
+    ...(own?.health ? { health: own.health } : {}),
     ...(live.now ? { now: nowText(live.now), activity: live.now } : {}),
     blockers: live.blockers.map(({ sessionTitle: _, ...b }) => b),
     children: live.status.filter((e) => e.parentID === live.id).length,

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"
@@ -97,7 +98,10 @@ export interface AgentRoute {
 
 /** What the agent API needs from the hub. */
 export interface AgentDeps {
+  readonly agentLimits?: { view(): Promise<unknown> }
   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 +242,15 @@ 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.agentLimits ? [{ method: "GET", path: `${AGENT_PREFIX}/agent-limits`, allow: { session: true, app: true }, handle: async () => Response.json(await deps.agentLimits!.view(), { headers: { "cache-control": "no-store" } }) }] : []),
     ...(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

@@ -54,7 +54,7 @@ import type { AgentActor, AppActor, SessionActor } from "./actor"
 import { sanitizeLabel } from "./envelope"
 import { AgentError } from "./errors"
 import { parsePosition } from "./event-cursor"
-import type { AgentEvent, AgentEvents, EventInput, EventRecord } from "./events"
+import { stateChanged, type AgentEvent, type AgentEvents, type EventInput, type EventRecord } from "./events"
 import { visible as actorSees } from "./events-routes"
 import { HOP_CAP } from "./message-limits"
 import { parseAddress } from "./names"
@@ -245,6 +245,9 @@ 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
+  readonly currentHopLimit?: () => 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. */
@@ -307,7 +310,7 @@ export function typeMatches(patterns: readonly string[], event: Pick<AgentEvent,
   return patterns.some((p) => {
     if (p === "*") return true
     if (Object.hasOwn(SUBSCRIPTION_FAMILIES, p)) return SUBSCRIPTION_FAMILIES[p]!.includes(type)
-    if (p.startsWith("state:")) return type === "session.changed" && event.data.state === p.slice(6)
+    if (p.startsWith("state:")) return type === "session.changed" && event.data.state === p.slice(6) && stateChanged(event.data)
     return p.endsWith(".*") ? type.startsWith(p.slice(0, -1)) : p === type
   })
 }
@@ -318,12 +321,20 @@ export function typeMatches(patterns: readonly string[], event: Pick<AgentEvent,
 const tok = (v: unknown): string => (typeof v === "string" && /^[A-Za-z0-9_.:@#-]{1,80}$/.test(v) ? v : typeof v === "number" || typeof v === "boolean" ? String(v) : "other")
 const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? "" : "s"}`
 
+/** (SS-1) " (quota until 2026-11-18 10:00 UTC)", " (retrying)", " (ok)": the health a session.changed carries, else "". */
+function healthNote(d: Readonly<Record<string, unknown>>): string {
+  if (d.healthKind === undefined) return ""
+  const at = typeof d.healthResetAt === "number" && Number.isFinite(d.healthResetAt) ? new Date(d.healthResetAt) : undefined
+  const until = at && !Number.isNaN(at.getTime()) ? ` until ${at.toISOString().slice(0, 16).replace("T", " ")} UTC` : ""
+  return ` (${tok(d.healthKind)}${until})`
+}
+
 function describe(event: AgentEvent): string {
   const d = event.data
   const s = event.subject
   switch (event.type) {
     case "session.changed":
-      return `${tok(d.state)}${d.state === "idle" && d.prev === "working" ? " (turn done)" : ""}`
+      return `${tok(d.state)}${d.state === "idle" && d.prev === "working" ? " (turn done)" : ""}${healthNote(d)}`
     case "session.added":
       return "online"
     case "session.removed":
@@ -858,7 +869,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.currentHopLimit?.() ?? this.deps.hopLimit ?? HOP_CAP)) {
         suppressed++
         continue
       }

package/src/central/api-v1.ts

@@ -0,0 +1,115 @@
+// The /api/v1 boundary (docs/plans/2026-11-12-api-v1-contract-and-native-app-design.md §1.1, §1.2), without hub
+// state. /api/v1/<rest> is an alias of /api/<rest> in the console and agent route tables: handle() in http.ts gives
+// the handlers a copy of the URL on the unversioned path (never another Request), so routes, access checks and
+// idempotency keys are the unversioned ones. Every error answered under /api/v1 is the agent API's envelope
+// {error: {code, message, ...extra}}: console handlers keep answering {error: string, code?, ...extra} (the web
+// console reads it on the unversioned paths) and apiV1Response rewrites that on the way out. Answers below 400 go
+// out as they are, unread: the live stream and streamed audio are never buffered.
+import { API_V1_PREFIX } from "../protocol"
+
+const API_PREFIX = "/api"
+
+/**
+ * The unversioned path a /api/v1 path is an alias of, or undefined outside /api/v1. One prefix only: /api/v1/v1/me
+ * is /api/v1/me, which no table has; the bare prefix is /api or /api/, which no table has either.
+ */
+export function unversionedPath(pathname: string): string | undefined {
+  if (pathname !== API_V1_PREFIX && !pathname.startsWith(`${API_V1_PREFIX}/`)) return undefined
+  return `${API_PREFIX}${pathname.slice(API_V1_PREFIX.length)}`
+}
+
+/** A copy of a /api/v1 URL on its unversioned path (query string kept), or undefined outside /api/v1. */
+export function unversionedURL(url: URL): URL | undefined {
+  const pathname = unversionedPath(url.pathname)
+  if (pathname === undefined) return undefined
+  const copy = new URL(url)
+  copy.pathname = pathname
+  return copy
+}
+
+/** The code of a console error that names none, by status (design §1.2). */
+const STATUS_CODES: Readonly<Record<number, string>> = {
+  400: "invalid",
+  401: "unauthorized",
+  403: "forbidden",
+  404: "not_found",
+  408: "timeout",
+  409: "conflict",
+  410: "gone",
+  413: "too_large",
+  422: "unsupported",
+  429: "rate_limited",
+  500: "internal",
+  502: "upstream_failed",
+  503: "unavailable",
+  504: "timeout",
+}
+
+export const apiV1ErrorCode = (status: number): string => STATUS_CODES[status] ?? (status >= 500 ? "internal" : "invalid")
+
+/** The message of an error whose answer had none to keep, by code. */
+const MESSAGES: Readonly<Record<string, string>> = {
+  invalid: "Bad request",
+  unauthorized: "Unauthorized",
+  forbidden: "Forbidden",
+  not_found: "Not found",
+  timeout: "Timed out",
+  conflict: "Conflict",
+  gone: "Gone",
+  too_large: "Too large",
+  unsupported: "Unsupported",
+  rate_limited: "Too many requests",
+  internal: "Internal error",
+  upstream_failed: "Upstream failed",
+  unavailable: "Unavailable",
+}
+
+/** A text/* error body longer than this is not a message (a page, a trace). */
+const TEXT_MESSAGE_MAX_CHARS = 300
+
+export interface ApiV1Error {
+  readonly error: { readonly code: string; readonly message: string; readonly [extra: string]: unknown }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value)
+
+/**
+ * The v1 envelope of an error answer: `body` is its parsed JSON (if it was JSON), `text` its text/* body. An
+ * envelope is returned as it is (the same object); a console error keeps its message, its code (else the
+ * status's) and moves its other fields inside `error`; anything else gets the status's code and a generic message.
+ */
+export function apiV1ErrorBody(status: number, body: unknown, text?: string): ApiV1Error {
+  if (isRecord(body)) {
+    const { error, code, ...extra } = body
+    if (isRecord(error) && typeof error.code === "string" && typeof error.message === "string") return body as unknown as ApiV1Error
+    if (typeof error === "string") return { error: { ...extra, code: typeof code === "string" && code ? code : apiV1ErrorCode(status), message: error } }
+  }
+  const code = apiV1ErrorCode(status)
+  const short = text?.trim()
+  return { error: { code, message: short && short.length <= TEXT_MESSAGE_MAX_CHARS ? short : MESSAGES[code] ?? "Request failed" } }
+}
+
+/** An answer on its way out of /api/v1: errors (400 and up) in the v1 envelope, same status and headers. */
+export async function apiV1Response(response: Response): Promise<Response> {
+  if (response.status < 400) return response
+  const type = (response.headers.get("content-type") ?? "").split(";", 1)[0]!.trim().toLowerCase()
+  const json = type === "application/json" || type.endsWith("+json")
+  // An event stream has no end to read to.
+  const text = type.startsWith("text/") && type !== "text/event-stream"
+  // A copy is read, so an answer that is already the envelope (every agent route's) goes out as its handler made it.
+  const raw = json || text ? await response.clone().text() : undefined
+  let parsed: unknown
+  if (json) {
+    try {
+      parsed = JSON.parse(raw!)
+    } catch {}
+  }
+  const body = apiV1ErrorBody(response.status, parsed, text ? raw : undefined)
+  if (body === parsed) return response
+  void response.body?.cancel().catch(() => {})
+  const bytes = new TextEncoder().encode(JSON.stringify(body))
+  const headers = new Headers(response.headers)
+  headers.set("content-type", "application/json;charset=utf-8")
+  headers.set("content-length", String(bytes.length))
+  return new Response(bytes, { status: response.status, statusText: response.statusText, headers })
+}

package/src/central/artifacts/store.ts

@@ -95,6 +95,8 @@ export interface ArtifactEvent {
   readonly number?: number
   /** artifact.archived: the state it moved to (archive and unarchive share the event). */
   readonly state?: RecordState
+  /** created/revised by a session (in-process only: never journaled; TA2-5 progress credit). */
+  readonly authorSessionID?: string
 }
 
 export interface ArtifactStoreOptions {
@@ -393,7 +395,7 @@ export class ArtifactStore {
       if (!written.ok) throw conflict("Artifact ID collision; retry", undefined)
       return artifact
     })
-    this.emit(userID, { type: "artifact.created", artifactID, kind: published.artifact.kind, revision: 1, revisionID: published.revision.id, number: 1 })
+    this.emit(userID, { type: "artifact.created", artifactID, kind: published.artifact.kind, revision: 1, revisionID: published.revision.id, number: 1, ...(published.revision.author.kind === "session" ? { authorSessionID: published.revision.author.sessionID } : {}) })
     return published
   }
 
@@ -426,7 +428,7 @@ export class ArtifactStore {
       }
       throw conflict("The artifact kept changing; retry", undefined)
     })
-    this.emit(userID, { type: "artifact.revised", artifactID: id, kind: published.artifact.kind, revision: published.artifact.revision, revisionID: published.revision.id, number })
+    this.emit(userID, { type: "artifact.revised", artifactID: id, kind: published.artifact.kind, revision: published.artifact.revision, revisionID: published.revision.id, number, ...(published.revision.author.kind === "session" ? { authorSessionID: published.revision.author.sessionID } : {}) })
     return published
   }
 

package/src/central/concierge/board-results.ts

@@ -17,7 +17,7 @@
 // stalled store further results are dropped. observe() never throws or rejects (it is called with `void`).
 import type { ConciergeResultOutcome } from "../../../packages/protocol/src/concierge"
 import { isHubSessionID } from "../../../packages/protocol/src/harness-events"
-import type { AgentEvent } from "../agent/events"
+import { stateChanged, type AgentEvent } from "../agent/events"
 import { updateVersioned } from "../agent/versioned"
 import type { Clock, StateStore } from "../backend/types"
 import type { LastResult } from "./board"
@@ -56,6 +56,7 @@ export function resultOf(event: Pick<AgentEvent, "type" | "subject" | "data"> |
   if (!isHubSessionID(sessionID)) return undefined
   if (event.type === "session.changed") {
     if (subject.rootID !== undefined && subject.rootID !== sessionID) return undefined
+    if (!stateChanged(data)) return undefined
     if (data.state === "error") return { sessionID, outcome: "error" }
     if (data.state === "idle" && (data.prev === "working" || data.prev === "blocked")) return { sessionID, outcome: "turn_done" }
     return undefined