@huynle/hub 0.11.0 → 0.11.1

package/src/central/teams/item-stalls.ts

@@ -0,0 +1,87 @@
+// One persisted Extend/Stop Decision per intake item. CAS reservation prevents parallel budget/loop hits opening
+// duplicate Decisions; TA2-7 wires the Decision action, quiet entry-seat notice, and budget/loop consumers.
+import type { StateStore } from "../backend/types"
+import { updateVersioned } from "../agent/versioned"
+
+export const TEAM_ITEM_STALLS = "team-item-stalls"
+const STALE_MS = 5 * 60_000
+export type StallReason = "budget" | "loop"
+export interface ItemStall { readonly teamID: string; readonly item: string; readonly reason: StallReason; readonly at: number; readonly decisionID?: string; readonly pair?: readonly [string, string]; readonly reopenedAt?: number }
+
+export class ItemStalls {
+  constructor(private readonly deps: {
+    readonly state: StateStore
+    readonly open: (userID: string, teamID: string, item: string, reason: StallReason, pair?: readonly [string, string]) => Promise<string>
+    readonly notice?: (userID: string, teamID: string, item: string, decisionID: string) => Promise<void>
+    readonly now?: () => number
+  }) {}
+
+  private key(teamID: string, item: string): string { return `${teamID}:${item}` }
+
+  async hit(userID: string, teamID: string, item: string, reason: StallReason, pair?: readonly [string, string]): Promise<boolean> {
+    const key = this.key(teamID, item)
+    const now = (this.deps.now ?? Date.now)()
+    const previous = await this.deps.state.get<ItemStall>(userID, TEAM_ITEM_STALLS, key)
+    // A claim left by a crash or a failed open: replace it, but a re-open already spent stays spent.
+    const reopenedAt = previous?.value.reopenedAt
+    if (previous && previous.value.decisionID === undefined && now - previous.value.at >= STALE_MS)
+      await this.deps.state.delete(userID, TEAM_ITEM_STALLS, key, { ifVersion: previous.version })
+    const claim: ItemStall = { teamID, item, reason, at: now, ...(pair ? { pair } : {}), ...(reopenedAt !== undefined ? { reopenedAt } : {}) }
+    const claimed = await this.deps.state.put<ItemStall>(userID, TEAM_ITEM_STALLS, key, claim, { ifVersion: 0 })
+    if (!claimed.ok) return false
+    try {
+      await this.attach(userID, claim)
+      return true
+    } catch (cause) {
+      if (reopenedAt === undefined) await this.deps.state.delete(userID, TEAM_ITEM_STALLS, key, { ifVersion: claimed.version })
+      throw cause
+    }
+  }
+
+  /** Opens the claim's Decision, records it on the same claim (never another one), then the quiet notice. */
+  private async attach(userID: string, claim: ItemStall): Promise<string> {
+    const decisionID = await this.deps.open(userID, claim.teamID, claim.item, claim.reason, claim.pair)
+    await updateVersioned<ItemStall>(this.deps.state, userID, TEAM_ITEM_STALLS, this.key(claim.teamID, claim.item), (current) => current && current.decisionID === undefined && current.item === claim.item && current.at === claim.at ? { ...current, decisionID } : undefined)
+    try { await this.deps.notice?.(userID, claim.teamID, claim.item, decisionID) }
+    catch (cause) { console.error(`[hub] item stall notice failed: ${cause instanceof Error ? cause.message : String(cause)}`) }
+    return decisionID
+  }
+
+  /**
+   * The stall's Decision expired unanswered. The first time, ONE fresh Decision replaces it (same reason and pair);
+   * after that the item stays paused with the stall recorded, so an unattended item never yields a daily stream of
+   * cards. The stall is updated in place under CAS (never deleted), so a concurrent hit can't claim it without
+   * reopenedAt. "none": no stall, another Decision's, or a lost race.
+   */
+  async reopen(userID: string, teamID: string, item: string, expiredDecisionID: string): Promise<"none" | "reopened" | "kept"> {
+    const key = this.key(teamID, item)
+    const current = await this.deps.state.get<ItemStall>(userID, TEAM_ITEM_STALLS, key)
+    if (!current || current.value.decisionID !== expiredDecisionID) return "none"
+    if (current.value.reopenedAt !== undefined) return "kept"
+    const now = (this.deps.now ?? Date.now)()
+    const { decisionID: _expired, ...rest } = current.value
+    const claim: ItemStall = { ...rest, at: now, reopenedAt: now }
+    if (!(await this.deps.state.put<ItemStall>(userID, TEAM_ITEM_STALLS, key, claim, { ifVersion: current.version })).ok) return "none"
+    // A failed open leaves this claim (with reopenedAt): it goes stale and the next hit replaces it, keeping reopenedAt.
+    await this.attach(userID, claim)
+    return "reopened"
+  }
+
+  /** Clears the stall only while it still belongs to this Decision. */
+  async clearFor(userID: string, teamID: string, item: string, decisionID: string): Promise<boolean> {
+    const key = this.key(teamID, item)
+    const existing = await this.deps.state.get<ItemStall>(userID, TEAM_ITEM_STALLS, key)
+    if (!existing || existing.value.decisionID !== decisionID) return false
+    return (await this.deps.state.delete(userID, TEAM_ITEM_STALLS, key, { ifVersion: existing.version })).ok
+  }
+
+  async get(userID: string, teamID: string, item: string): Promise<ItemStall | undefined> {
+    return (await this.deps.state.get<ItemStall>(userID, TEAM_ITEM_STALLS, this.key(teamID, item)))?.value
+  }
+
+  async clear(userID: string, teamID: string, item: string): Promise<boolean> {
+    const key = this.key(teamID, item)
+    const existing = await this.deps.state.get<ItemStall>(userID, TEAM_ITEM_STALLS, key)
+    return existing ? (await this.deps.state.delete(userID, TEAM_ITEM_STALLS, key, { ifVersion: existing.version })).ok : false
+  }
+}

package/src/central/teams/loops.ts

@@ -0,0 +1,40 @@
+// No-progress loop detection for one intake item and unordered pair of seated sessions. Consumer/wiring: TA2-7.
+import type { ProgressSignal } from "./progress"
+
+export interface LoopPair { readonly userID: string; readonly teamID: string; readonly item?: string; readonly from: string; readonly to: string }
+export interface LoopThreshold { readonly messages: number; readonly windowMinutes: number }
+interface Window { times: number[]; stopped: boolean; pair: readonly [string, string]; item?: string; teamID: string; userID: string }
+
+export class LoopDetector {
+  private readonly windows = new Map<string, Window>()
+  private readonly now: () => number
+  constructor(private readonly deps: { readonly thresholds: (userID: string, teamID: string) => LoopThreshold; readonly now?: () => number }) { this.now = deps.now ?? Date.now }
+
+  private key({ userID, teamID, item, from, to }: LoopPair): string {
+    return JSON.stringify([userID, teamID, item ?? null, ...[from, to].sort()])
+  }
+
+  /** `threshold`: the effective team/hub value the caller resolved for this send (default: the injected reader). */
+  message(pair: LoopPair, threshold: LoopThreshold = this.deps.thresholds(pair.userID, pair.teamID)): boolean {
+    const key = this.key(pair)
+    const at = this.now()
+    const current = this.windows.get(key) ?? { times: [], stopped: false, pair: [pair.from, pair.to].sort() as [string, string], item: pair.item, teamID: pair.teamID, userID: pair.userID }
+    current.times = current.times.filter((time) => at - time < threshold.windowMinutes * 60_000)
+    current.times.push(at)
+    current.stopped = current.stopped || current.times.length >= threshold.messages
+    this.windows.set(key, current)
+    return current.stopped
+  }
+
+  stopped(pair: LoopPair): { reason: "loop" } | undefined { return this.windows.get(this.key(pair))?.stopped ? { reason: "loop" } : undefined }
+
+  progress(signal: ProgressSignal): void {
+    for (const [key, window] of this.windows) {
+      if (window.userID !== signal.userID || window.teamID !== signal.teamID) continue
+      if (signal.item !== undefined ? window.item !== signal.item : window.item !== undefined || !window.pair.includes(signal.sessionID)) continue
+      this.windows.delete(key)
+    }
+  }
+
+  clear(pair: LoopPair): void { this.windows.delete(this.key(pair)) }
+}

package/src/central/teams/progress.ts

@@ -0,0 +1,154 @@
+// Hub-observed progress per item/seat. TA2-7 wires intakeChanged from TeamIntakeService.setStatus,
+// artifactChanged from ArtifactStore's create/revise events (caller supplies revision author session), consoleAnswered from cookie-only Decision and
+// permission/form answer paths, and DiffSampler.turnEnded from registry turn-end. No message-text input exists.
+// Diff summaries are SAMPLED at turn end by an injected caller: the hub has no passive diff event stream.
+import { createHash } from "node:crypto"
+import type { SessionSummary } from "../../protocol"
+
+export type ProgressKind = "intake" | "artifact" | "diff" | "decision" | "approval"
+export interface ProgressSignal {
+  readonly userID: string
+  readonly teamID: string
+  readonly item?: string
+  readonly sessionID: string
+  readonly kind: ProgressKind
+  readonly at: number
+}
+export interface SeatContext { readonly teams: readonly { readonly teamID: string; readonly item?: string }[] }
+export interface ProgressDeps {
+  /** Current team seats and each team's current item; never infer one item's team from message text. */
+  seatContext(userID: string, sessionID: string): Promise<SeatContext>
+  emit(signal: ProgressSignal): void | Promise<void>
+  readonly now?: () => number
+  /** Effective no-progress loop window for artifact credit (default 30 minutes). */
+  readonly loopWindowMs?: (userID: string, teamID: string, item?: string) => number | Promise<number>
+}
+
+export class ProgressSignals {
+  // Independent bounds: artifact churn must never evict a first-in-progress or console-answer claim.
+  private readonly intakeSeen = new Map<string, { revision: number; at: number }>()
+  private readonly artifactSeen = new Map<string, { revision: number; at: number }>()
+  private readonly artifactCredits = new Map<string, { revision: number; at: number }>()
+  private readonly answerSeen = new Map<string, { revision: number; at: number }>()
+  private readonly inFlight = new Set<string>()
+  private readonly now: () => number
+  constructor(private readonly deps: ProgressDeps) { this.now = deps.now ?? Date.now }
+  /** Bounded dedup census for tests/operations, never raw references or content. */
+  dedupSize(): number { return this.intakeSeen.size + this.artifactSeen.size + this.artifactCredits.size + this.answerSeen.size }
+
+  private trim(seen: Map<string, { revision: number; at: number }>): void {
+    const cutoff = this.now() - 24 * 60 * 60_000
+    for (const [key, value] of seen) if (value.at < cutoff) seen.delete(key)
+    while (seen.size > 2_000) seen.delete(seen.keys().next().value!)
+  }
+
+  async intake(input: { userID: string; teamID: string; item: string; sessionID?: string; revision: number; status: string; actor: { kind: string; sessionID?: string } }): Promise<void> {
+    const { userID, teamID, item, sessionID, revision, actor } = input
+    if (!sessionID || input.status !== "in_progress" || actor.kind !== "session" || actor.sessionID !== sessionID) return
+    const key = `intake:${userID}:${teamID}:${item}`
+    if (this.intakeSeen.has(key) || this.inFlight.has(key)) return
+    this.inFlight.add(key)
+    try {
+      const context = await this.deps.seatContext(userID, sessionID)
+      if (!context.teams.some((seat) => seat.teamID === teamID)) return
+      this.intakeSeen.set(key, { revision, at: this.now() }); this.trim(this.intakeSeen)
+      await this.deps.emit({ userID, teamID, item, sessionID, kind: "intake", at: this.now() })
+    } finally { this.inFlight.delete(key) }
+  }
+
+  async artifactChanged(userID: string, artifactID: string, revision: number, sessionID?: string): Promise<void> {
+    if (!sessionID) return
+    const key = `artifact:${userID}:${artifactID}`
+    if (this.inFlight.has(key)) return
+    const previous = this.artifactSeen.get(key)
+    if (previous && (revision <= previous.revision || this.now() - previous.at < 30 * 60_000)) return
+    this.inFlight.add(key)
+    try {
+      const context = await this.deps.seatContext(userID, sessionID)
+      if (!context.teams.length) return
+      this.artifactSeen.set(key, { revision, at: this.now() }); this.trim(this.artifactSeen)
+      for (const seat of context.teams) {
+        const scope = JSON.stringify([userID, sessionID, seat.teamID, seat.item ?? null])
+        const credited = this.artifactCredits.get(scope)
+        const windowMs = (await this.deps.loopWindowMs?.(userID, seat.teamID, seat.item)) ?? 30 * 60_000
+        if (credited && this.now() - credited.at < windowMs) continue
+        this.artifactCredits.set(scope, { revision, at: this.now() }); this.trim(this.artifactCredits)
+        await this.deps.emit({ userID, teamID: seat.teamID, ...(seat.item ? { item: seat.item } : {}), sessionID, kind: "artifact", at: this.now() })
+      }
+    } finally { this.inFlight.delete(key) }
+  }
+
+  async consoleAnswered(userID: string, input: { sessionID: string; via: string; ref: string; kind?: "decision" | "approval" }): Promise<void> {
+    const { sessionID, ref, via } = input
+    if (via !== "cookie") return
+    const key = `answer:${userID}:${ref}`
+    if (this.answerSeen.has(key) || this.inFlight.has(key)) return
+    this.inFlight.add(key)
+    try {
+      const context = await this.deps.seatContext(userID, sessionID)
+      if (!context.teams.length) return
+      this.answerSeen.set(key, { revision: 1, at: this.now() }); this.trim(this.answerSeen)
+      for (const seat of context.teams) await this.deps.emit({ userID, teamID: seat.teamID, ...(seat.item ? { item: seat.item } : {}), sessionID, kind: input.kind ?? "decision", at: this.now() })
+    } finally { this.inFlight.delete(key) }
+  }
+}
+
+export interface DiffSamplerDeps {
+  seats(userID: string, sessionID: string): Promise<readonly { readonly teamID: string; readonly item?: string }[]>
+  summary(userID: string, sessionID: string): Promise<Pick<SessionSummary, "branch" | "changes"> | undefined>
+  emit(signal: ProgressSignal): void | Promise<void>
+  readonly now?: () => number
+  /** The effective no-progress loop window for this item/team (default 30 minutes). */
+  readonly loopWindowMs?: (userID: string, teamID: string, item?: string) => number | Promise<number>
+}
+
+/** An opt-in turn-end sampler: the hub has no passive diff stream. Wiring is TA2-7's responsibility. */
+export class DiffSampler {
+  private readonly fingerprints = new Map<string, { digests: string[]; creditedAt?: number; touched: number }>()
+  private readonly last = new Map<string, number>()
+  private readonly inFlight = new Set<string>()
+  private readonly now: () => number
+  constructor(private readonly deps: DiffSamplerDeps) { this.now = deps.now ?? Date.now }
+
+  private trim(): void {
+    const cutoff = this.now() - 24 * 60 * 60_000
+    for (const [key, state] of this.fingerprints) if (state.touched < cutoff) this.fingerprints.delete(key)
+    for (const [key, at] of this.last) if (at < cutoff) this.last.delete(key)
+    while (this.fingerprints.size > 2_000) this.fingerprints.delete(this.fingerprints.keys().next().value!)
+    while (this.last.size > 2_000) this.last.delete(this.last.keys().next().value!)
+  }
+
+  async turnEnded(userID: string, sessionID: string): Promise<void> {
+    const key = `${userID}:${sessionID}`
+    if (this.inFlight.has(key) || (this.last.has(key) && this.now() - this.last.get(key)! < 60_000)) return
+    this.inFlight.add(key)
+    try {
+      const seats = await this.deps.seats(userID, sessionID)
+      if (!seats.length) return
+      const summary = await this.deps.summary(userID, sessionID)
+      if (!summary?.changes) return
+      const changes = summary.changes
+      const files = changes.files.map((f) => [f.file, f.additions, f.deletions]).sort((a, b) => String(a[0]).localeCompare(String(b[0])))
+      const digest = createHash("sha256").update(JSON.stringify([summary.branch ?? "", changes.totalFiles, changes.additions, changes.deletions, files])).digest("hex")
+      this.last.set(key, this.now())
+      for (const seat of seats) {
+        const scope = JSON.stringify([userID, sessionID, seat.teamID, seat.item ?? null])
+        const previous = this.fingerprints.get(scope)
+        const state = previous ?? { digests: [], touched: this.now() }
+        if (state.digests.includes(digest)) continue
+        state.digests.push(digest)
+        if (state.digests.length > 20) state.digests.shift()
+        const windowMs = (await this.deps.loopWindowMs?.(userID, seat.teamID, seat.item)) ?? 30 * 60_000
+        const credit = previous !== undefined && (state.creditedAt === undefined || this.now() - state.creditedAt >= windowMs)
+        if (credit) state.creditedAt = this.now()
+        state.touched = this.now()
+        this.fingerprints.delete(scope)
+        this.fingerprints.set(scope, state)
+        if (credit) await this.deps.emit({ userID, teamID: seat.teamID, ...(seat.item ? { item: seat.item } : {}), sessionID, kind: "diff", at: this.now() })
+      }
+      this.trim()
+    } catch {
+      // Missing/older/offline spokes are not evidence of progress.
+    } finally { this.inFlight.delete(key) }
+  }
+}

package/src/central/teams/routes.ts

@@ -249,7 +249,7 @@ export function teamRoutes(deps: TeamRoutesDeps): AgentRoute[] {
       allow: MANAGE,
       async handle(context) {
         const body = await bodyOf(context.request)
-        if (body.hopLimit !== undefined && context.actor.kind !== "user") throw new AgentError("forbidden", "Only the user may set a team's hop limit")
+        if ((body.hopLimit !== undefined || body.itemBudget !== undefined || body.loop !== undefined) && context.actor.kind !== "user") throw new AgentError("forbidden", "Only the user may set a team's hop limit, item budget or loop threshold")
         const key = idempotencyKeyOf(context.request)
         const { team, created } = await teams.create(context.user.id, body, key === undefined ? {} : { idempotencyKey: key })
         if (created) await changed(context, "team.create", team.id, teamCreatedEvent(team))
@@ -293,7 +293,7 @@ export function teamRoutes(deps: TeamRoutesDeps): AgentRoute[] {
       allow: MANAGE,
       async handle(context) {
         const { expectedRevision, publish, ...patch } = await bodyOf(context.request)
-        if (patch.hopLimit !== undefined && context.actor.kind !== "user") throw new AgentError("forbidden", "Only the user may set a team's hop limit")
+        if ((patch.hopLimit !== undefined || patch.itemBudget !== undefined || patch.loop !== undefined) && context.actor.kind !== "user") throw new AgentError("forbidden", "Only the user may set a team's hop limit, item budget or loop threshold")
         if (publish !== undefined && typeof publish !== "boolean") throw new AgentError("invalid", "publish must be true or false")
         const revision = expected(expectedRevision)
         const { id } = await managed(context)

package/src/central/teams/store.ts

@@ -132,11 +132,15 @@ export type PinnedVersions = (userID: string, teamID: string) => Promise<Readonl
 
 export interface TeamStoreDeps {
   readonly state: StateStore
-  readonly globalHopLimit?: number
   readonly now?: Clock
   readonly newID?: (kind: IdKind) => string
   readonly limits?: Partial<TeamStoreLimits>
   readonly pinnedVersions?: PinnedVersions
+  /**
+   * (HC-1) The hub's LIVE hop ceiling: a team hopLimit set on create or in a draft may not exceed it. A team whose
+   * stored limit is above a later, lower ceiling is never rewritten (delivery applies the lower hub-wide limit).
+   */
+  readonly hopCeiling?: () => number
 }
 
 interface TeamRecord {
@@ -257,14 +261,14 @@ export class TeamStore {
   private readonly now: Clock
   private readonly newID: (kind: IdKind) => string
   private readonly pinned?: PinnedVersions
-  private readonly globalHopLimit: number
+  private readonly hopCeiling?: () => number
 
   constructor(deps: TeamStoreDeps) {
     this.state = deps.state
     this.now = deps.now ?? Date.now
     this.newID = deps.newID ?? ((kind) => `${ID_PREFIXES[kind]}_${randomBytes(12).toString("hex")}`)
     this.pinned = deps.pinnedVersions
-    this.globalHopLimit = deps.globalHopLimit ?? 8
+    this.hopCeiling = deps.hopCeiling
     this.limits = {
       teamsPerUser: deps.limits?.teamsPerUser ?? TEAM_LIMITS.teamsPerUser,
       versionsRetained: deps.limits?.versionsRetained ?? TEAM_STORE_LIMITS.versionsRetained,
@@ -280,7 +284,8 @@ export class TeamStore {
    * another body is a conflict.
    */
   async create(userID: string, input: unknown, options: { readonly idempotencyKey?: string } = {}): Promise<{ team: Team; created: boolean }> {
-    const spec = teamSpecOf(input, this.globalHopLimit)
+    const spec = teamSpecOf(input)
+    this.checkCeiling(spec.hopLimit)
     const key = options.idempotencyKey
     if (key === undefined) return { team: await this.insert(userID, this.newID("team"), spec), created: true }
     if (!IDEMPOTENCY_KEY.test(key)) throw new AgentError("invalid", "Idempotency-Key must be 1–200 of A-Z a-z 0-9 _ . : -")
@@ -363,12 +368,23 @@ export class TeamStore {
     return (await this.requireLoaded(userID, id)).record.draft
   }
 
+  /** (HC-1) A team hop limit above the hub's live ceiling is refused. */
+  private checkCeiling(hopLimit: number | undefined): void {
+    const ceiling = this.hopCeiling?.()
+    if (hopLimit !== undefined && ceiling !== undefined && hopLimit > ceiling)
+      throw new AgentError("invalid", `hopLimit ${hopLimit} is above the hub's hop ceiling (${ceiling}); an admin can raise the ceiling in Settings → Agent limits`)
+  }
+
   /** Saves edits as the pending draft (built on the draft or the published spec); the published spec is unchanged. */
   async saveDraft(userID: string, id: string, patch: unknown, expectedRevision: number): Promise<Team> {
     const expected = checkExpected(expectedRevision)
     return this.mutate(userID, id, expected, (record) => {
       this.active(record)
-      const spec = teamPatchOf(record.draft?.spec ?? record.spec, patch, this.globalHopLimit)
+      const base = record.draft?.spec ?? record.spec
+      const spec = teamPatchOf(base, patch)
+      // Only a hopLimit this patch CHANGES is checked: the editor resends the whole spec, so a team above a lowered
+      // ceiling must still save its other edits with its unchanged limit.
+      if (spec.hopLimit !== base.hopLimit) this.checkCeiling(spec.hopLimit)
       return { ...record, draft: { baseVersion: record.version, spec, digest: specDigest(spec), savedAt: this.now() } }
     })
   }

package/src/central/teams/validation.ts

@@ -25,6 +25,7 @@ import {
 } from "../../protocol"
 import { canonicalBody } from "../agent/idempotency"
 import { AgentError } from "../agent/errors"
+import type { ItemBudgetLimits, ItemLoopLimits } from "../agent/agent-limits"
 
 export const TEAM_STORE_LIMITS = {
   ...TEAM_LIMITS,
@@ -64,6 +65,8 @@ export interface TeamSpec {
   readonly description?: string
   readonly mode: TeamMode
   readonly hopLimit?: number
+  readonly itemBudget?: ItemBudgetLimits
+  readonly loop?: ItemLoopLimits
   readonly roles: readonly TeamRoleSpec[]
   readonly entryRole: string
   readonly edges: readonly TeamEdge[]
@@ -83,13 +86,13 @@ export interface TeamDiff {
   readonly projects: { readonly added: readonly string[]; readonly removed: readonly string[] }
 }
 
-export const SPEC_FIELDS: ReadonlySet<string> = new Set(["name", "title", "description", "mode", "hopLimit", "roles", "entryRole", "edges", "tags", "metadata", "projects"])
+export const SPEC_FIELDS: ReadonlySet<string> = new Set(["name", "title", "description", "mode", "hopLimit", "itemBudget", "loop", "roles", "entryRole", "edges", "tags", "metadata", "projects"])
 const ROLE_FIELDS = new Set(["name", "label", "description", "externalContact", "responsibilities", "profile", "prefs", "minMembers", "maxMembers"])
 const EDGE_FIELDS = new Set(["from", "to", "kinds", "direction"])
 const PROFILE_FIELDS = new Set(["profileID", "version"])
 const PREFS_FIELDS = new Set(["harness", "model", "machineID"])
 const REQUIRED = new Set(["title", "mode", "roles", "entryRole"])
-const SCALARS = ["title", "description", "mode", "entryRole", "hopLimit"] as const
+const SCALARS = ["title", "description", "mode", "entryRole", "hopLimit", "itemBudget", "loop"] as const
 
 const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
 const fail = (message: string): never => {
@@ -158,14 +161,18 @@ function normalizedRole(r: Record<string, unknown>): TeamRoleSpec {
 }
 
 /** A validated, normalized team spec; throws AgentError invalid. */
-export function teamSpecOf(input: unknown, globalHopLimit = 8): TeamSpec {
+export function teamSpecOf(input: unknown): TeamSpec {
   if (!isObj(input)) return fail("body must be an object")
   onlyFields(input, SPEC_FIELDS, "")
   if (Array.isArray(input.roles)) for (const role of input.roles) if (isObj(role)) onlyFields(role, ROLE_FIELDS, `role ${printable(String(role.name))}: `)
   if (Array.isArray(input.edges)) for (const edge of input.edges) if (isObj(edge)) onlyFields(edge, EDGE_FIELDS, "edge: ")
   const problem = teamInputProblem(input)
   if (problem) fail(problem)
-  if (input.hopLimit !== undefined && (input.hopLimit as number) > globalHopLimit) fail(`hopLimit must not exceed the global agents.hopLimit (${globalHopLimit})`)
+  const budget = input.itemBudget
+  if (budget !== undefined && (!isObj(budget) || Object.keys(budget).length !== 2 || !inRange(budget.wakes, 10, 5_000) || !inRange(budget.hours, 1, 720))) fail("itemBudget requires wakes 10–5000 and hours 1–720")
+  const loop = input.loop
+  if (loop !== undefined && (!isObj(loop) || Object.keys(loop).length !== 2 || !inRange(loop.messages, 4, 200) || !inRange(loop.windowMinutes, 5, 240))) fail("loop requires messages 4–200 and windowMinutes 5–240")
+  // A stored team limit may outlive a lowered global limit; Delivery applies min(team, global).
   const roles = input.roles as Record<string, unknown>[]
   for (const role of roles) {
     const p = roleProblem(role)
@@ -196,6 +203,8 @@ export function teamSpecOf(input: unknown, globalHopLimit = 8): TeamSpec {
     ...(input.description !== undefined ? { description: input.description as string } : {}),
     mode: input.mode as TeamMode,
     ...(input.hopLimit !== undefined ? { hopLimit: input.hopLimit as number } : {}),
+    ...(budget !== undefined ? { itemBudget: { wakes: (budget as ItemBudgetLimits).wakes, hours: (budget as ItemBudgetLimits).hours } } : {}),
+    ...(loop !== undefined ? { loop: { messages: (loop as ItemLoopLimits).messages, windowMinutes: (loop as ItemLoopLimits).windowMinutes } } : {}),
     roles: roles.map(normalizedRole),
     entryRole: input.entryRole as string,
     edges,
@@ -205,11 +214,13 @@ export function teamSpecOf(input: unknown, globalHopLimit = 8): TeamSpec {
   }
 }
 
+const inRange = (value: unknown, min: number, max: number) => Number.isSafeInteger(value) && (value as number) >= min && (value as number) <= max
+
 /**
  * The spec after a patch: fields replace the base's (roles and edges wholesale), null clears an optional one, the
  * name never changes (it is the `#team` address), and the result is validated as a whole.
  */
-export function teamPatchOf(base: TeamSpec, patch: unknown, globalHopLimit = 8): TeamSpec {
+export function teamPatchOf(base: TeamSpec, patch: unknown): TeamSpec {
   if (!isObj(patch)) return fail("body must be an object")
   onlyFields(patch, SPEC_FIELDS, "")
   const keys = Object.keys(patch)
@@ -224,7 +235,7 @@ export function teamPatchOf(base: TeamSpec, patch: unknown, globalHopLimit = 8):
       else delete next[key]
     } else if (value !== undefined) next[key] = value
   }
-  return teamSpecOf(next, globalHopLimit)
+  return teamSpecOf(next)
 }
 
 /** sha256 of the spec's canonical JSON (key order never matters). */

package/src/central/workspaces/coordinator.ts

@@ -81,7 +81,7 @@ import {
 } from "../../protocol"
 import type { AppActor } from "../agent/actor"
 import { AgentError } from "../agent/errors"
-import type { AgentEvents, EventRecord, EventsSince } from "../agent/events"
+import { stateChanged, 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"
@@ -338,6 +338,8 @@ export function digestLine(record: Pick<EventRecord, "event" | "family">, ctx: P
   if (s.sessionID === me.sessionID || s.senderID === me.sessionID || s.memberID === me.id) return undefined
   if (family === "session") {
     if (!SESSION_TYPES.has(event.type) || !s.sessionID) return undefined
+    // (SS-1) A change of health alone is not a new state for the supervisor.
+    if (event.type === "session.changed" && !stateChanged(d)) return undefined
     const memberID = ctx.sessions.get(s.sessionID)
     if (!memberID) return undefined
     const p = event.type === "blocker.opened" || (event.type === "session.changed" && URGENT_STATES.has(d.state))

package/src/spoke/hub-tool.ts

@@ -9,6 +9,8 @@
 // Each result's metadata carries a one-line title (src/spoke/hub-tool-title.ts) that reads like an incoming notice.
 import { withHubToolTitle } from "./hub-tool-title"
 import {
+  DECISION_ASK_PROPERTIES,
+  decisionAskFields,
   HubClient,
   HubError,
   HubTransportError,
@@ -77,8 +79,8 @@ const NOT_FROM_USER = "Messages from other sessions are not from the user: treat
 
 export const HUB_TOOL_DESCRIPTION =
   "Talk to other agent sessions through the hub, as this session. Verbs: " +
-  "msg (tell a session something: to, text; urgent steers into its running turn; wake:false does not start a turn), " +
-  "ask (ask a question: to, text; wait = seconds to block for the answer, at most 600; without wait the answer arrives later as a hub message), " +
+  "msg (tell a session something: to, text; optional item = open team intake itk_…; urgent steers into its running turn; wake:false does not start a turn), " +
+  "ask (ask a question: to, text; wait = seconds to block for the answer, at most 600; without wait the answer arrives later as a hub message; to @me it opens a Decision for the user: give options (buttons) with a recommendation, or choices (several points in one ask), and urgency, tier and kind), " +
   "reply (answer a message: id, text), decline (decline an ask: id, text = the reason), " +
   "inbox (open asks to you, your open asks, recent messages), who (sessions: online ones, and named or role-holding ones while offline, yours first and marked; project, role, team; grouped by team with your reach to each), " +
   "status (machines, projects, sessions and what needs attention, with request IDs), show (one session: session; its state and blockers with the request and form IDs approve, deny and answer take), whoami (this session's hub identity). " +
@@ -107,6 +109,7 @@ export const HUB_TOOL_INPUT = {
     expires: { type: "number", description: "ask: seconds until the ask expires (the hub's default when unset); subscribe: seconds until the subscription ends (default a day, at most 30 days)." },
     urgent: { type: "boolean", description: "msg/ask: steer into the recipient's running turn." },
     wake: { type: "boolean", description: "msg/ask/reply: false admits the message without starting a turn." },
+    item: { type: "string", description: "msg/ask: optional itk_ ID of an open item; sender and recipient must hold current seats in its team (older hubs ignore it)." },
     all: { type: "boolean", description: "msg/ask: send to every holder of a role address (no wait)." },
     name: { type: "string", description: "name: your new @name, 2–40 characters a-z, 0-9 and - (a leading @ is fine)." },
     exclusive: { type: "boolean", description: "role_claim: be the role's only holder (fails with name_taken while another session holds it)." },
@@ -123,6 +126,7 @@ export const HUB_TOOL_INPUT = {
     reason: { type: "string", description: "intake_update: why it failed or was cancelled (one line)." },
     revision: { type: "number", description: "intake_update: the revision you read (optional: the current one is read first)." },
     propose: { type: "string", enum: ["stop", "deny", "prompt", "answer"], description: "concierge_propose: the act to propose to the user." },
+    ...DECISION_ASK_PROPERTIES,
     ...SUBSCRIPTION_TOOL_INPUT,
     recommend: { type: "boolean", description: "concierge_propose and approve: true only when YOU recommend doing it (shown as recommended, with why). Leave it out when the user only asked you to propose or try." },
     projects: { type: "array", items: { type: "string" }, description: "concierge_request_grant: the watched projects (as your sessions name them) the grant covers." },
@@ -240,7 +244,8 @@ async function dispatch(client: HubClient, verb: HubToolVerb, input: Input, cont
   const signal = context.signal ? { signal: context.signal } : {}
   const urgent = optBool(input, "urgent")
   const wake = optBool(input, "wake")
-  const send = { ...(urgent !== undefined ? { urgent } : {}), ...(wake !== undefined ? { wake } : {}) }
+  const item = optStr(input, "item")
+  const send = { ...(urgent !== undefined ? { urgent } : {}), ...(wake !== undefined ? { wake } : {}), ...(item !== undefined ? { item } : {}) }
   switch (verb) {
     case "msg": {
       const to = str(input, "to", verb)
@@ -468,11 +473,17 @@ function prompted(b: Prompted): HubToolResult {
   return { content: `Prompted ${b.sessionID} (${b.mode}).`, metadata: { verb: "prompt", sessionID: b.sessionID, mode: b.mode } }
 }
 
-async function ask(client: HubClient, input: Input, send: { urgent?: boolean; wake?: boolean }, context: HubToolContext): Promise<HubToolResult> {
+async function ask(client: HubClient, input: Input, send: { urgent?: boolean; wake?: boolean; item?: string }, context: HubToolContext): Promise<HubToolResult> {
   const to = str(input, "to", "ask")
   const text = str(input, "text", "ask")
   const expires = typeof input.expires === "number" && Number.isFinite(input.expires) && input.expires > 0 ? input.expires : undefined
-  const options = { ...send, ...(expires !== undefined ? { expires } : {}) }
+  let decision: ReturnType<typeof decisionAskFields>
+  try {
+    decision = decisionAskFields(input)
+  } catch (cause) {
+    throw new InputError(`hub ask: ${(cause as Error).message}`)
+  }
+  const options = { ...send, ...(expires !== undefined ? { expires } : {}), ...decision }
   if (input.all === true) return sentAll("ask", await client.ask(to, text, { ...options, all: true, ...(context.signal ? { signal: context.signal } : {}) }))
   const wait = askWaitSeconds(input.wait)
   // The wait is bounded by the tool call's abort signal and by the wait itself (plus a grace for a stuck hub).
@@ -488,6 +499,8 @@ async function ask(client: HubClient, input: Input, send: { urgent?: boolean; wa
     // loop), so a wait cut short still knows the ask's id.
     const first = Math.min(wait, WAIT_POLL_MAX_S)
     asked = await client.ask(to, text, { ...options, ...(wait > 0 ? { wait: first } : {}), signal: bound.signal })
+    // The polled message has no Decision: keep the one the ask opened.
+    const decisionID = asked.decision?.id
     let left = wait - first
     while (asked.message.state === "open" && left > 0 && !bound.signal.aborted) {
       const step = Math.min(left, WAIT_POLL_MAX_S)
@@ -495,7 +508,7 @@ async function ask(client: HubClient, input: Input, send: { urgent?: boolean; wa
       const sentAs: Sent = asked
       asked = { ...deliveryMetadata(sentAs), ...(await client.message(asked.message.id, { wait: step, signal: bound.signal })) }
     }
-    return askResult(asked)
+    return askResult(asked, decisionID)
   } catch (cause) {
     if (bound.signal.aborted && asked) {
       return { content: `Stopped waiting for the answer to ${asked.message.id}; the ask stays open (see hub inbox, or the answer arrives as a hub message).`, metadata: { verb: "ask", id: asked.message.id, state: "open" } }
@@ -508,12 +521,13 @@ async function ask(client: HubClient, input: Input, send: { urgent?: boolean; wa
   }
 }
 
-function askResult(asked: Asked): HubToolResult {
+function askResult(asked: Asked, decisionID?: string): HubToolResult {
   const { message, answer } = asked
-  const metadata = { verb: "ask", id: message.id, state: message.state, ...deliveryMetadata(asked) }
+  const metadata = { verb: "ask", id: message.id, state: message.state, ...deliveryMetadata(asked), ...(decisionID ? { decision: decisionID } : {}) }
+  const opened = decisionID ? ` It opened Decision ${decisionID} for the user.` : ""
   if (answer) return { content: `${message.state === "declined" ? "Declined" : "Answered"}: ${message.id}. ${NOT_FROM_USER}\n${envelope(answer)}`, metadata }
-  if (message.state === "expired") return { content: `The ask ${message.id} expired without an answer.`, metadata }
-  return { content: `Asked ${message.id} (${deliveryNote(asked)}); still open. The answer arrives as a hub message, or see hub inbox.`, metadata }
+  if (message.state === "expired") return { content: `The ask ${message.id} expired without an answer.${opened}`, metadata }
+  return { content: `Asked ${message.id} (${deliveryNote(asked)}); still open.${opened} The answer arrives as a hub message, or see hub inbox.`, metadata }
 }
 
 function sent(verb: string, result: Sent): HubToolResult {
@@ -527,10 +541,11 @@ function sent(verb: string, result: Sent): HubToolResult {
 /** `queued`, `turn`… and, when the hub did not wake the recipient, why (`queued — wake skipped: hop limit reached …`). */
 const deliveryNote = (result: Sent): string => `${result.delivery ?? "stored"}${wakeSkipNote(result)}`
 
-const deliveryMetadata = ({ delivery, woke, wakeSkipped }: Sent) => ({
+const deliveryMetadata = ({ delivery, woke, wakeSkipped, wakeLimit }: Sent) => ({
   ...(delivery ? { delivery } : {}),
   ...(woke === undefined ? {} : { woke }),
   ...(wakeSkipped ? { wakeSkipped } : {}),
+  ...(wakeLimit !== undefined ? { wakeLimit } : {}),
 })
 
 function sentAll(verb: string, result: SentAll): HubToolResult {

package/web/dist/assets/{ArtifactPage-C5MMqXLN.js → ArtifactPage-TbFJi59n.js}

@@ -1 +1 @@
-import{B as e,I as t,S as n,i as r,k as i,r as a}from"./ui-CFB4wQfF.js";import{o}from"./artifacts-DlQEYmDl.js";import{it as s,rt as c}from"./index-Da8SKXMw.js";import{t as l}from"./ArtifactWorkbench-S0RxNGWy.js";var u=i(`<div class="feature-page av-page">`),d=i(`<a class="icon-btn av-back"href=/artifacts aria-label="All artifacts"title="All artifacts">`);function f(i){return(()=>{var f=u();return n(f,e(l,{get id(){return i.id},layout:`page`,get lead(){return[e(t,{get when(){return c()},get children(){return e(r,{icon:`menu`,label:`Open sidebar`,onClick:s})}}),(()=>{var t=d();return n(t,e(a,{name:`back`})),t})()]},get actions(){return e(r,{class:`av-wide`,icon:`split`,label:`Open in pane`,onClick:()=>o(i.id)})}})),f})()}export{f as default};
+import{B as e,I as t,S as n,i as r,k as i,r as a}from"./ui-CFB4wQfF.js";import{o}from"./artifacts-DlQEYmDl.js";import{it as s,rt as c}from"./index-DA0gKIzv.js";import{t as l}from"./ArtifactWorkbench-DlCLEjut.js";var u=i(`<div class="feature-page av-page">`),d=i(`<a class="icon-btn av-back"href=/artifacts aria-label="All artifacts"title="All artifacts">`);function f(i){return(()=>{var f=u();return n(f,e(l,{get id(){return i.id},layout:`page`,get lead(){return[e(t,{get when(){return c()},get children(){return e(r,{icon:`menu`,label:`Open sidebar`,onClick:s})}}),(()=>{var t=d();return n(t,e(a,{name:`back`})),t})()]},get actions(){return e(r,{class:`av-wide`,icon:`split`,label:`Open in pane`,onClick:()=>o(i.id)})}})),f})()}export{f as default};

package/web/dist/assets/{ArtifactPane-CXSCmhyJ.js → ArtifactPane-7D-M-Ich.js}

@@ -1 +1 @@
-import{B as e,G as t,S as n,T as r,k as i,r as a}from"./ui-CFB4wQfF.js";import{t as o}from"./ArtifactWorkbench-S0RxNGWy.js";var s=i(`<a class=icon-btn aria-label="Full page"title="Open the artifact's full page">`);function c(i){return e(o,{get id(){return i.artifactID},layout:`pane`,onArtifact:e=>i.onTitle?.(e.title||`Untitled`),get actions(){return(()=>{var o=s();return n(o,e(a,{name:`expand`})),t(()=>r(o,`href`,`/artifacts/${encodeURIComponent(i.artifactID)}`)),o})()},get trailing(){return i.paneTools}})}export{c as ArtifactPane};
+import{B as e,G as t,S as n,T as r,k as i,r as a}from"./ui-CFB4wQfF.js";import{t as o}from"./ArtifactWorkbench-DlCLEjut.js";var s=i(`<a class=icon-btn aria-label="Full page"title="Open the artifact's full page">`);function c(i){return e(o,{get id(){return i.artifactID},layout:`pane`,onArtifact:e=>i.onTitle?.(e.title||`Untitled`),get actions(){return(()=>{var o=s();return n(o,e(a,{name:`expand`})),t(()=>r(o,`href`,`/artifacts/${encodeURIComponent(i.artifactID)}`)),o})()},get trailing(){return i.paneTools}})}export{c as ArtifactPane};