@huynle/hub 0.10.1 → 0.11.1

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/policy.ts

@@ -109,6 +109,16 @@ const sessionParty = (entry: DirectoryEntry): Party => ({ kind: "session", sessi
 export class TeamPolicy {
   constructor(private readonly deps: TeamPolicyDeps) {}
 
+  /** Shared active seat(s) only; cross-team and non-team sends use the global limit. */
+  async hopContext(userID: string, from: Party, to: Party, explicitTeamID?: string): Promise<{ teamID: string; limit?: number } | undefined> {
+    if (from.kind !== "session" || to.kind !== "session") return undefined
+    const ctx = await this.context(userID, [from.sessionID, to.sessionID])
+    const shared = seatsIn(ctx, from.sessionID).map((s) => s.teamID).filter((id) => (explicitTeamID === undefined || explicitTeamID === id) && seatsIn(ctx, to.sessionID).some((s) => s.teamID === id) && ctx.teams.get(id)?.state === "active").sort()
+    const teamID = shared[0]
+    if (!teamID) return undefined
+    return { teamID, ...(ctx.teams.get(teamID)?.hopLimit !== undefined ? { limit: ctx.teams.get(teamID)!.hopLimit } : {}) }
+  }
+
   /** Starts a send from `from` to `addr` (see the header). */
   async prepare(userID: string, from: Party, addr: string): Promise<TeamSend> {
     const resolved = await this.resolve(userID, from, addr)

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,6 +249,7 @@ export function teamRoutes(deps: TeamRoutesDeps): AgentRoute[] {
       allow: MANAGE,
       async handle(context) {
         const body = await bodyOf(context.request)
+        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))
@@ -292,6 +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 || 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/seats.ts

@@ -47,7 +47,7 @@ export interface TeamSeatRecord extends TeamStaffing {
   readonly teamVersion: number
 }
 
-export type DeliveryTeams = ReadonlyMap<string, Pick<TeamDefinition, "mode" | "edges" | "roles" | "state">>
+export type DeliveryTeams = ReadonlyMap<string, Pick<TeamDefinition, "mode" | "edges" | "roles" | "state" | "hopLimit">>
 
 export interface DeliveryContext {
   /** Each asked session's current seats (empty when it holds none). */
@@ -199,11 +199,11 @@ export class TeamSeatStore {
   /** Seats of several sessions and the teams they are in: teamDeliveryVerdict's inputs (HWA-34). */
   async deliveryContext(userID: string, sessionIDs: readonly string[]): Promise<DeliveryContext> {
     const seats = await this.seatsBySession(userID, sessionIDs)
-    const teams = new Map<string, Pick<TeamDefinition, "mode" | "edges" | "roles" | "state">>()
+    const teams = new Map<string, Pick<TeamDefinition, "mode" | "edges" | "roles" | "state" | "hopLimit">>()
     for (const teamID of new Set([...seats.values()].flat().map((s) => s.teamID))) {
       try {
         const team = await this.teams.get(userID, teamID)
-        if (team) teams.set(teamID, { mode: team.mode, edges: team.edges, roles: team.roles, state: team.state })
+        if (team) teams.set(teamID, { mode: team.mode, edges: team.edges, roles: team.roles, state: team.state, ...(team.hopLimit !== undefined ? { hopLimit: team.hopLimit } : {}) })
       } catch {
         // A team this build cannot read takes no part in delivery (its seats are then ignored by the verdict).
       }

package/src/central/teams/staffing.ts

@@ -75,6 +75,7 @@ import { readSeatsDoc, type SeatsDoc, TEAM_SEATS } from "./collections"
 import { teamStaffedEvent, teamUnstaffedEvent } from "./events"
 import type { TeamSeatRecord, TeamSeatStore } from "./seats"
 import type { Team, TeamStore } from "./store"
+import type { TeamHopStalls } from "./hop-stalls"
 import { TEAM_STORE_LIMITS, type TeamRoleSpec } from "./validation"
 
 /** One aggregate per team (key: team ID): workspace link, managed members, launch requests, Idempotency-Keys. */
@@ -144,6 +145,8 @@ export interface SeatProfileStatus {
 export interface RosterSeat {
   readonly staffing: TeamSeatRecord
   readonly presence: SessionPresence
+  /** An agent-only message to this seat hit the team's hop limit; only the user may renew. */
+  readonly stalled?: "hop cap"
   readonly memberID?: string
   readonly supervisorMemberID?: string
   readonly profile?: SeatProfileStatus
@@ -208,6 +211,7 @@ export interface TeamStaffingDeps {
   readonly members: MembershipStore
   readonly supervision: SupervisionStore
   readonly presence: SessionPresenceLookup
+  readonly hopStalls?: Pick<TeamHopStalls, "stalled">
   /** The session's project directory now (grant scope); undefined when no spoke reports it. */
   readonly sessionDirectory: (userID: string, sessionID: string) => string | undefined
   readonly launches: Pick<LaunchEngine, "accept" | "view">
@@ -454,6 +458,7 @@ export class TeamStaffingService {
         seats.push({
           staffing,
           presence: presence.get(staffing.sessionID)!,
+          ...(await this.deps.hopStalls?.stalled(userID, teamID, staffing.sessionID) ? { stalled: "hop cap" as const } : {}),
           ...(memberID !== undefined ? { memberID } : {}),
           ...(supervisorMemberID !== undefined ? { supervisorMemberID } : {}),
           ...(profile ? { profile } : {}),

package/src/central/teams/store.ts

@@ -136,6 +136,11 @@ export interface TeamStoreDeps {
   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 {
@@ -256,12 +261,14 @@ export class TeamStore {
   private readonly now: Clock
   private readonly newID: (kind: IdKind) => string
   private readonly pinned?: PinnedVersions
+  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.hopCeiling = deps.hopCeiling
     this.limits = {
       teamsPerUser: deps.limits?.teamsPerUser ?? TEAM_LIMITS.teamsPerUser,
       versionsRetained: deps.limits?.versionsRetained ?? TEAM_STORE_LIMITS.versionsRetained,
@@ -278,6 +285,7 @@ export class TeamStore {
    */
   async create(userID: string, input: unknown, options: { readonly idempotencyKey?: string } = {}): Promise<{ team: Team; created: boolean }> {
     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 _ . : -")
@@ -360,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)
+      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,
@@ -63,6 +64,9 @@ export interface TeamSpec {
   readonly title: string
   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[]
@@ -82,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", "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"] 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 => {
@@ -164,6 +168,11 @@ export function teamSpecOf(input: unknown): TeamSpec {
   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)
+  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)
@@ -193,6 +202,9 @@ export function teamSpecOf(input: unknown): TeamSpec {
     title: input.title as string,
     ...(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,
@@ -202,6 +214,8 @@ export function teamSpecOf(input: unknown): 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.

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-CsPjam8D.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-But87Jfo.js";import{it as s,rt as c}from"./index-bX8B6NLo.js";import{t as l}from"./ArtifactWorkbench-DzKhMs3l.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-B9weO8L6.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-DzKhMs3l.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};