@huynle/hub 0.11.0 → 0.11.1

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

@@ -32,8 +32,8 @@ 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
+/** (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
 
@@ -163,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

@@ -98,6 +98,7 @@ 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">
@@ -249,6 +250,7 @@ export function agentRoutes(deps: AgentDeps): AgentRoute[] {
         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"
@@ -247,6 +247,7 @@ export interface SubscriptionsDeps {
   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. */
@@ -309,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
   })
 }
@@ -320,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":
@@ -860,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 > (this.deps.hopLimit ?? 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

package/src/central/concierge/notifier.ts

@@ -67,7 +67,7 @@
 // spent budget wait for the tick (no 0 ms timer loop).
 import { CONCIERGE_PARTY, CONCIERGE_ROLE, type ConciergeSettings } from "../../../packages/protocol/src/concierge"
 import { AgentError } from "../agent/errors"
-import type { AgentEvent, AgentEvents, EventRecord, EventsSince } from "../agent/events"
+import { stateChanged, type AgentEvent, type AgentEvents, type EventRecord, type EventsSince } from "../agent/events"
 import { updateVersioned } from "../agent/versioned"
 import { realTimers } from "../backend/memory-bus"
 import type { Clock, StateStore, Timers } from "../backend/types"
@@ -286,6 +286,8 @@ function classify(record: Pick<EventRecord, "event" | "family" | "audience">, ct
       return line("routine", `${who} blocker_closed${blockerID ? ` ${blockerID}` : ""}`)
     }
     case "session.changed": {
+      // (SS-1) A change of health alone is no new state line (SS-4 adds the health line).
+      if (!stateChanged(d)) return undefined
       const state = enumOf(d.state, STATES)
       const k = `s:${id}`
       if (state === "error") return line("priority", `${who} state:error`, { k, f: state, b: [`${root} state:error`] })
@@ -347,7 +349,7 @@ function overdueTurn(l: Line): Line {
 const EARLY: ReadonlySet<string> = new Set(["blocker.opened", "message.changed", "launch.changed"])
 
 /** Whether an append may be a priority line (an early pass): EARLY types, and a session going into error. */
-const early = (event: AgentEvent): boolean => EARLY.has(event.type) || (event.type === "session.changed" && event.data?.state === "error")
+const early = (event: AgentEvent): boolean => EARLY.has(event.type) || (event.type === "session.changed" && event.data?.state === "error" && stateChanged(event.data))
 /** Whether an append may be a notable line (a turn done): a pass when its quiet window ends. */
 const notable = (event: AgentEvent): boolean => event.type === "session.changed" && event.data?.state === "idle" && event.data?.prev === "working"
 

package/src/central/config.ts

@@ -8,14 +8,14 @@ import { hubEnv } from "../env"
 import { isLoopbackHost } from "../loopback"
 import { formatPattern, parsePattern } from "./agent/policy"
 import type { SpeechQuotaOverrides } from "./agent/speech-routes"
-import { SPEECH_RATE_LIMITS } from "../protocol"
+import { HOP_CEILING_DEFAULT, SPEECH_RATE_LIMITS } from "../protocol"
 import { APP_DIR, configBase, legacyPaths, migrateFirst, migrateStateDir, resolveHubStateDir, stateLegacyPaths } from "../migrate"
 import { updateSpeech, type StoredSpeech } from "./speech/settings"
 import { readContextCards, type ContextCardsConfig } from "./context-cards/config"
 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"
+import { HOP_ABSOLUTE_MAX, HOP_CAP } from "./agent/message-limits"
 
 export const GOOGLE_ISSUER = "https://accounts.google.com"
 
@@ -73,6 +73,12 @@ export interface CentralConfig {
   readonly agentsNever: readonly string[]
   /** hub.json `agents.hopLimit`: global maximum agent-only hops before a wake is skipped. */
   readonly hopLimit: number
+  /** (HC-1) hub.json `agents.hopCeiling` (default 100): the highest hop limit accepted. */
+  readonly hopCeiling: number
+  /** (HC-1) Whether hub.json set the ceiling (else the default). */
+  readonly hopCeilingSource?: "default" | "hub.json"
+  /** Which source supplied the hub-wide agent limits before console overrides. */
+  readonly agentLimitsSource?: "default" | "hub.json"
   /** 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). */
@@ -142,6 +148,8 @@ export interface HubAgents {
   /** Normalised `action[:glob]` patterns (see agent/policy.ts), duplicates dropped. */
   readonly never?: readonly string[]
   readonly hopLimit?: number
+  /** (HC-1) The highest hop limit the hub accepts (1–10,000, default 100); the console may override it. */
+  readonly hopCeiling?: number
   readonly launches?: HubLaunches
   readonly webhooks?: HubWebhooks
   /** (AF2) Per-credential app speech quotas: any subset of SPEECH_RATE_LIMITS. */
@@ -173,7 +181,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", "hopLimit"])
+const AGENTS_KEYS = new Set(["never", "launches", "webhooks", "speechQuotas", "hopLimit", "hopCeiling"])
 /** 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"])
@@ -354,13 +362,16 @@ 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}`)
+  if (input.hopCeiling !== undefined && (!Number.isSafeInteger(input.hopCeiling) || (input.hopCeiling as number) < 1 || (input.hopCeiling as number) > HOP_ABSOLUTE_MAX))
+    fail(`agents.hopCeiling must be a whole number from 1 to ${HOP_ABSOLUTE_MAX}`)
+  const ceiling = (input.hopCeiling as number | undefined) ?? HOP_CEILING_DEFAULT
+  if (input.hopLimit !== undefined && (!Number.isSafeInteger(input.hopLimit) || (input.hopLimit as number) < 1 || (input.hopLimit as number) > ceiling))
+    fail(`agents.hopLimit must be a whole number from 1 to the hop ceiling (${ceiling}; agents.hopCeiling raises it)`)
   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 } : {}), ...(input.hopLimit !== undefined ? { hopLimit: input.hopLimit as number } : {}), ...(launches ? { launches } : {}), ...(webhooks ? { webhooks } : {}), ...(speechQuotas ? { speechQuotas } : {}) }
+  return { ...(never ? { never } : {}), ...(input.hopLimit !== undefined ? { hopLimit: input.hopLimit as number } : {}), ...(input.hopCeiling !== undefined ? { hopCeiling: input.hopCeiling as number } : {}), ...(launches ? { launches } : {}), ...(webhooks ? { webhooks } : {}), ...(speechQuotas ? { speechQuotas } : {}) }
 }
 
 /** (AF2) `agents.speechQuotas`: {transcribe?: {perMinute?, perHour?}, speak?: {perMinute?, perHour?, charsPerHour?}}. */
@@ -608,6 +619,9 @@ export function centralConfig(rawEnv: Env = process.env, home: string = homedir(
     auth,
     agentsNever: [...(file.agents?.never ?? [])],
     hopLimit: file.agents?.hopLimit ?? HOP_CAP,
+    hopCeiling: file.agents?.hopCeiling ?? HOP_CEILING_DEFAULT,
+    hopCeilingSource: file.agents?.hopCeiling !== undefined ? "hub.json" : "default",
+    agentLimitsSource: file.agents?.hopLimit !== undefined || file.agents?.launches !== undefined ? "hub.json" : "default",
     ...(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] } : {}),