@huynle/hub 0.11.0 → 0.11.1

package/src/central/registry.ts

@@ -19,6 +19,7 @@ import { DoneWatch } from "./done"
 import { FrontRelays, RelayRefused } from "./front-relays"
 import { SentenceStream } from "./say-stream"
 import type { ActivityStep, NotificationKind } from "./push"
+import { classifyHealth, type SessionHealth } from "./health/classify"
 
 export { ACTIVITY_INTERVAL_MINUTES } from "./store"
 /** A tool call that took at least this long is named in activity updates (shorter ones are only counted). */
@@ -54,8 +55,12 @@ export interface MachineRef {
 }
 
 /** A status tree entry as the hub reports it: working sessions carry when their current run started. */
-/** `since`: a working entry's run start; `blockedSince`: when a blocked entry's oldest open blocker was first seen. */
-export type LiveStatus = SessionStatus & { readonly since?: number; readonly blockedSince?: number }
+/**
+ * `since`: a working entry's run start; `blockedSince`: when a blocked entry's oldest open blocker was first seen;
+ * (SS-1) `health`: why the session is not making progress (absent: ok). The state itself is unchanged (a retrying
+ * session stays "working").
+ */
+export type LiveStatus = SessionStatus & { readonly since?: number; readonly blockedSince?: number; readonly health?: SessionHealth }
 
 /** Timer functions (injectable for tests). */
 export interface Timers {
@@ -590,6 +595,9 @@ export class Registry {
   private readonly since = new Map<string, number>()
   /** (Session findability) Blocker ID → when this process first saw it (the "waiting 12m" of Needs you). */
   private readonly blockerSeen = new Map<string, number>()
+  /** (SS-1) When each session's current provider retry was first seen, and its health kind with when it began. */
+  private readonly retrySeen = new Map<string, number>()
+  private readonly healthSeen = new Map<string, { kind: SessionHealth["kind"]; since: number; detail?: string; resetAt?: number }>()
   /** Session → streamed text waiting for its send window. */
   private readonly streams = new Map<string, Stream>()
   /** Machine → its latest terminals frame and the connection that sent it. */
@@ -1645,10 +1653,33 @@ export class Registry {
           })
         : s.blockers
       const entry: LiveStatus = recommended ? { ...s, blockers } : s
-      return since === undefined && blockedSince === undefined ? entry : { ...entry, ...(since !== undefined ? { since } : {}), ...(blockedSince !== undefined ? { blockedSince } : {}) }
+      const health = this.health(s)
+      return since === undefined && blockedSince === undefined && health === undefined ? entry : { ...entry, ...(since !== undefined ? { since } : {}), ...(blockedSince !== undefined ? { blockedSince } : {}), ...(health ? { health } : {}) }
     })
   }
 
+  /** (SS-1) The entry's health with the time its kind began; undefined while ok (the history is then forgotten). */
+  private health(s: SessionStatus): SessionHealth | undefined {
+    const now = this.now()
+    if (s.retry && s.state === "working") {
+      if (!this.retrySeen.has(s.id)) remember(this.retrySeen, s.id, now, BLOCKERS_SEEN)
+    } else this.retrySeen.delete(s.id)
+    const health = classifyHealth(s, { now, ...(this.retrySeen.has(s.id) ? { retrySince: this.retrySeen.get(s.id)! } : {}) })
+    if (health.kind === "ok") {
+      this.healthSeen.delete(s.id)
+      return undefined
+    }
+    let seen = this.healthSeen.get(s.id)
+    if (seen?.kind !== health.kind) remember(this.healthSeen, s.id, (seen = { kind: health.kind, since: now }), BLOCKERS_SEEN)
+    // A relative hint ("reset after 118h") is anchored when its message is first seen: re-parsing it at every read
+    // would move resetAt forward each time (and journal a change for every status update).
+    if (health.resetAt !== undefined) {
+      if (seen!.detail !== health.detail || seen!.resetAt === undefined) Object.assign(seen!, { detail: health.detail, resetAt: health.resetAt })
+      return { ...health, resetAt: seen!.resetAt, since: seen!.since }
+    }
+    return { ...health, since: seen!.since }
+  }
+
   catalog(): CatalogMachine[] {
     const machines = new Map<string, { id: string; name: string; processes: CatalogProcess[] }>()
     for (const conn of this.all().sort((a, b) => a.seq - b.seq)) {

package/src/central/teams/budgets.ts

@@ -0,0 +1,144 @@
+// Per-team intake wake usage. An item pauses alone when its wakes or running hours are exhausted.
+import type { StateStore } from "../backend/types"
+
+const COLLECTION = "team-item-budget"
+const CONTEXT = "team-item-context"
+const EXHAUSTION = "team-item-exhaustion"
+const DAY_MS = 24 * 60 * 60_000
+
+export interface ItemBudgetLimits { readonly wakes: number; readonly hours: number }
+export interface ItemBudgetUsage { readonly wakes: number; readonly hours: number; readonly budget: ItemBudgetLimits; readonly generation: number }
+type Usage = { readonly wakes: readonly number[]; readonly generation?: number; readonly startedAt?: number; readonly extendedBy?: readonly string[]; readonly charged?: Readonly<Record<string, number>> }
+/** Sessions charged a wake per item (TA2-8 resets only these); oldest dropped beyond this. */
+const CHARGED_MAX = 32
+type ChildUsage = { readonly wakes: number; readonly chargedTo: string | "pool"; readonly at: number }
+
+export class ItemBudgets {
+  constructor(private readonly deps: {
+    readonly state: StateStore
+    readonly limits: (userID: string, teamID: string) => Promise<ItemBudgetLimits> | ItemBudgetLimits
+    readonly now?: () => number
+    readonly exhausted?: (userID: string, teamID: string, itemID: string | undefined, reason: "wakes" | "hours", limit: number, usage: ItemBudgetUsage) => Promise<void>
+  }) {}
+
+  private now(): number { return (this.deps.now ?? Date.now)() }
+  private key(teamID: string, itemID: string | undefined): string { return `${teamID}:${itemID ?? "unattributed"}` }
+  private active(row: Usage | undefined, now: number): number[] { return (row?.wakes ?? []).filter((at) => at > now - DAY_MS) }
+
+  private static charge(previous: Usage["charged"], sessions: readonly string[], now: number): Record<string, number> | undefined {
+    if (!sessions.length) return previous ? { ...previous } : undefined
+    const next: Record<string, number> = { ...previous }
+    for (const sessionID of sessions) { delete next[sessionID]; next[sessionID] = now }
+    const kept = Object.entries(next).sort((a, b) => b[1] - a[1]).slice(0, CHARGED_MAX)
+    return Object.fromEntries(kept)
+  }
+
+  /** Sessions charged a wake for this item within the last `windowMs` (newest first). */
+  async charged(userID: string, teamID: string, itemID: string, windowMs: number): Promise<string[]> {
+    const row = (await this.deps.state.get<Usage>(userID, COLLECTION, this.key(teamID, itemID)))?.value
+    const since = this.now() - windowMs
+    return Object.entries(row?.charged ?? {}).filter(([, at]) => at >= since).sort((a, b) => b[1] - a[1]).map(([sessionID]) => sessionID)
+  }
+
+  private async report(userID: string, teamID: string, itemID: string | undefined, reason: "wakes" | "hours", limit: number, usage: ItemBudgetUsage, now: number): Promise<void> {
+    const key = `${this.key(teamID, itemID)}:${reason}:${itemID ? usage.generation : "pool"}`
+    const previous = await this.deps.state.get<{ at: number }>(userID, EXHAUSTION, key)
+    if (!itemID && previous && now - previous.value.at >= DAY_MS) await this.deps.state.delete(userID, EXHAUSTION, key, { ifVersion: previous.version })
+    const claimed = await this.deps.state.put(userID, EXHAUSTION, key, { at: now }, { ifVersion: 0 })
+    if (claimed.ok) try { await this.deps.exhausted?.(userID, teamID, itemID, reason, limit, usage) }
+    catch (cause) { console.error("[hub] item budget exhaustion notice failed:", cause) }
+  }
+
+  /** Last item assigned or received in this team; validity is rechecked before using it. */
+  async current(userID: string, teamID: string, sessionID: string): Promise<string | undefined> {
+    return (await this.deps.state.get<Record<string, { item: string; at: number }>>(userID, CONTEXT, sessionID))?.value[teamID]?.item
+  }
+
+  /** One row per session, not a scan of every team/session context. Eligibility is rechecked before inheritance. */
+  async currents(userID: string, sessionID: string): Promise<readonly { teamID: string; item: string }[]> {
+    const row = (await this.deps.state.get<Record<string, { item: string; at: number }>>(userID, CONTEXT, sessionID))?.value ?? {}
+    return Object.entries(row)
+      .sort(([teamA, a], [teamB, b]) => b.at - a.at || teamA.localeCompare(teamB))
+      .map(([teamID, value]) => ({ teamID, item: value.item }))
+  }
+
+  async setCurrent(userID: string, teamID: string, sessionID: string, item: string): Promise<void> {
+    for (let attempt = 0; attempt < 64; attempt++) {
+      const current = await this.deps.state.get<Record<string, { item: string; at: number }>>(userID, CONTEXT, sessionID)
+      const result = await this.deps.state.put(userID, CONTEXT, sessionID, { ...current?.value, [teamID]: { item, at: this.now() } }, { ifVersion: current?.version ?? 0 })
+      if (result.ok) return
+      await new Promise<void>((resolve) => setTimeout(resolve, 1 + Math.floor(Math.random() * 10)))
+    }
+    throw new Error("Item context write contention")
+  }
+
+  async chargeChild(userID: string, teamID: string, itemID: string, chargedTo: string | "pool"): Promise<void> {
+    const key = `${teamID}:${itemID}`
+    for (let i = 0; i < 64; i++) {
+      const current = await this.deps.state.get<ChildUsage>(userID, "team-item-child-usage", key)
+      const next = await this.deps.state.put(userID, "team-item-child-usage", key, { wakes: (current?.value.wakes ?? 0) + 1, chargedTo, at: this.now() }, { ifVersion: current?.version ?? 0 })
+      if (next.ok) return
+      await new Promise<void>((resolve) => setTimeout(resolve, 1 + Math.floor(Math.random() * 10)))
+    }
+    console.error("[hub] item child usage contention; count may lag")
+  }
+
+  async usage(userID: string, teamID: string, itemID: string, startedAt?: number, parentItem?: string): Promise<ItemBudgetUsage & { readonly chargedTo?: string }> {
+    const now = this.now()
+    const limits = await this.deps.limits(userID, teamID)
+    const row = (await this.deps.state.get<Usage>(userID, COLLECTION, this.key(teamID, itemID)))?.value
+    const child = parentItem ? (await this.deps.state.get<ChildUsage>(userID, "team-item-child-usage", `${teamID}:${itemID}`))?.value : undefined
+    const generation = row?.generation ?? 1
+    return { wakes: parentItem ? child?.wakes ?? 0 : row?.wakes.length ?? 0, hours: (row?.startedAt ?? startedAt) === undefined ? 0 : Math.max(0, (now - (row?.startedAt ?? startedAt)!) / 3_600_000), budget: { wakes: limits.wakes * generation, hours: limits.hours * generation }, generation, ...(parentItem ? { chargedTo: child?.chargedTo ?? parentItem } : {}) }
+  }
+
+  /** Extend is cumulative: the allowance grows, but the prior wake/hour usage remains true. */
+  async extend(userID: string, teamID: string, itemID: string, ref: string): Promise<ItemBudgetLimits> {
+    const key = this.key(teamID, itemID)
+    for (let i = 0; i < 32; i++) {
+      const current = await this.deps.state.get<Usage>(userID, COLLECTION, key)
+      const prior = current?.value
+      if (prior?.extendedBy?.includes(ref)) {
+        const base = await this.deps.limits(userID, teamID)
+        const generation = prior.generation ?? 1
+        return { wakes: base.wakes * generation, hours: base.hours * generation }
+      }
+      const generation = (prior?.generation ?? 1) + 1
+      const result = await this.deps.state.put(userID, COLLECTION, key, { wakes: prior?.wakes ?? [], generation, extendedBy: [...(prior?.extendedBy ?? []), ref], ...(prior?.startedAt !== undefined ? { startedAt: prior.startedAt } : {}), ...(prior?.charged ? { charged: prior.charged } : {}) }, { ifVersion: current?.version ?? 0 })
+      if (result.ok) { const base = await this.deps.limits(userID, teamID); return { wakes: base.wakes * generation, hours: base.hours * generation } }
+    }
+    throw new Error("Item budget extend contention")
+  }
+
+  /** Reserve a wake under CAS; false means this item (or its team's unattributed pool) is exhausted. */
+  /** `sessions`: the sender and recipient this wake is charged for (recorded on the item, never the pool). */
+  async wake(userID: string, teamID: string, itemID?: string, startedAt?: number, sessions: readonly string[] = []): Promise<{ allowed: boolean; limit: number; reason?: "wakes" | "hours" }> {
+    const limits = await this.deps.limits(userID, teamID)
+    const poolLimit = Math.floor(limits.wakes / 5)
+    const now = this.now()
+    const key = this.key(teamID, itemID)
+    for (let i = 0; i < 64; i++) {
+      const current = await this.deps.state.get<Usage>(userID, COLLECTION, key)
+      const generation = itemID ? (current?.value.generation ?? 1) : 1
+      const limit = itemID ? limits.wakes * generation : poolLimit
+      const active = itemID ? [...(current?.value.wakes ?? [])] : this.active(current?.value, now)
+      const start = current?.value.startedAt ?? startedAt ?? (itemID ? now : undefined)
+      if (itemID && start !== undefined && now - start >= limits.hours * generation * 3_600_000) {
+        const usage: ItemBudgetUsage = { wakes: active.length, hours: (now - start) / 3_600_000, budget: { wakes: limit, hours: limits.hours * generation }, generation }
+        await this.report(userID, teamID, itemID, "hours", usage.budget.hours, usage, now)
+        return { allowed: false, limit: usage.budget.hours, reason: "hours" }
+      }
+      if (active.length >= limit) {
+        await this.report(userID, teamID, itemID, "wakes", limit, { wakes: active.length, hours: start === undefined ? 0 : Math.max(0, (now - start) / 3_600_000), budget: { wakes: limit, hours: limits.hours * generation }, generation }, now)
+        return { allowed: false, limit, reason: "wakes" }
+      }
+      const result = await this.deps.state.put(userID, COLLECTION, key, { wakes: [...active, now], generation, ...(current?.value.extendedBy ? { extendedBy: current.value.extendedBy } : {}), ...(start !== undefined ? { startedAt: start } : {}), ...(itemID && (sessions.length || current?.value.charged) ? { charged: ItemBudgets.charge(current?.value.charged, sessions, now) } : {}) }, { ifVersion: current?.version ?? 0 })
+      if (result.ok) return { allowed: true, limit }
+      // Avoid a lockstep CAS stampede between sessions on the same item.
+      await new Promise<void>((resolve) => setTimeout(resolve, Math.min(20, 1 + Math.floor(Math.random() * (i + 1)))))
+    }
+    // A message may already be stored: fail closed (no wake), never turn contention into a send error.
+    console.error("[hub] item budget contention; skipping wake")
+    return { allowed: false, limit: itemID ? limits.wakes : poolLimit, reason: "wakes" }
+  }
+}

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

@@ -17,11 +17,9 @@ interface Stall {
 export class TeamHopStalls {
   constructor(private readonly deps: {
     readonly state: StateStore
-    readonly seats: (userID: string, teamID: string) => Promise<readonly string[]>
     readonly open: (userID: string, teamID: string, sender: string, recipient: string, limit: number) => Promise<string>
     readonly notice?: (userID: string, teamID: string, decisionID: string) => Promise<void>
-    readonly close?: (userID: string, decisionID: string) => Promise<void>
-    readonly reset: (userID: string, sessionID: string) => Promise<void>
+    readonly close?: (userID: string, decisionID: string, reason?: string) => Promise<void>
     readonly now?: () => number
   }) {}
 
@@ -55,11 +53,21 @@ export class TeamHopStalls {
     return stall as Stall & { readonly decisionID: string }
   }
 
-  async renew(userID: string, teamID: string, decisionID: string): Promise<void> {
+  async matches(userID: string, teamID: string, decisionID: string): Promise<void> {
     const entry = await this.deps.state.get<Stall>(userID, TEAM_HOP_STALLS, teamID)
     if (!entry || entry.value.decisionID !== decisionID) throw new Error("No matching team hop-cap Decision")
-    for (const sessionID of new Set(await this.deps.seats(userID, teamID))) await this.deps.reset(userID, sessionID)
-    await this.deps.state.delete(userID, TEAM_HOP_STALLS, teamID, { ifVersion: entry.version })
+  }
+
+  /** A user has taken part in this team again: clear its stall and close the pending Renew Decision. */
+  /** Whether the team has an open hop-cap Decision. */
+  async open(userID: string, teamID: string): Promise<boolean> {
+    return (await this.deps.state.get<Stall>(userID, TEAM_HOP_STALLS, teamID))?.value.decisionID !== undefined
+  }
+
+  async clearTeam(userID: string, teamID: string, reason = "The user is involved again"): Promise<void> {
+    const entry = await this.deps.state.get<Stall>(userID, TEAM_HOP_STALLS, teamID)
+    if (!entry || !(await this.deps.state.delete(userID, TEAM_HOP_STALLS, teamID, { ifVersion: entry.version })).ok) return
+    if (entry.value.decisionID) await this.deps.close?.(userID, entry.value.decisionID, reason)
   }
 
   async clearForHuman(userID: string, sessionID: string): Promise<void> {

package/src/central/teams/intake.ts

@@ -83,6 +83,7 @@ import type { Clock, StateStore, Timers } from "../backend/types"
 import { assignmentChangedEvent } from "../workspaces/events"
 import type { MembershipStore, SessionPresence, SessionPresenceLookup, StoredAssignment } from "../workspaces/members"
 import type { TeamSeatStore } from "./seats"
+import type { ItemBudgets, ItemBudgetUsage } from "./budgets"
 import type { TeamStaffingService } from "./staffing"
 import type { Team, TeamStore } from "./store"
 
@@ -139,6 +140,9 @@ export const INTAKE_LIMITS: IntakeLimits = {
 
 /** A TeamIntake as stored and read: the contract record plus additive fields (HWA-36). */
 export interface StoredIntake extends TeamIntake {
+  /** Session-submitted child: its root item, when eligible at submit time. Old rows omit it. */
+  readonly parentItem?: string
+  readonly usage?: ItemBudgetUsage
   readonly priority: IntakePriority
   readonly labels?: readonly string[]
   /** Due time (epoch ms). */
@@ -158,6 +162,8 @@ export interface StoredIntake extends TeamIntake {
   readonly lastError?: string
   readonly updatedAt: number
   readonly routedAt?: number
+  /** First active work (routed or in_progress); pauses and blocked time continue counting. */
+  readonly startedAt?: number
   readonly closedAt?: number
 }
 
@@ -206,6 +212,15 @@ export interface TeamIntakeDeps {
   readonly deliver: IntakeDeliver
   /** A session submitter's hop chain (absent: deliveries start their own chain). */
   readonly hopOf?: IntakeHopOf
+  /** Called only for a new, persisted intake submitted by the authenticated user. */
+  readonly submittedByUser?: (userID: string, teamID: string, intakeID: string, actor: Extract<AgentActor, { kind: "user" }>) => Promise<void>
+  readonly budgets?: Pick<ItemBudgets, "usage">
+  /** The entry seat received an item after routing; remember its current work context. */
+  readonly routed?: (userID: string, teamID: string, intakeID: string, sessionID: string) => Promise<void>
+  /** Resolve a session submitter's eligible current root item; undefined charges its child to the team pool. */
+  readonly parentOf?: (userID: string, teamID: string, sessionID: string) => Promise<string | undefined>
+  /** A real status/revision change of a routed item; attribution uses the assigned seat, not the reporter's words. */
+  readonly progressChanged?: (input: { readonly userID: string; readonly teamID: string; readonly item: string; readonly sessionID?: string; readonly revision: number; readonly status: string; readonly actor: AgentActor }) => void | Promise<void>
   readonly events?: Pick<AgentEvents, "append">
   readonly report?: (cause: unknown) => void
   readonly now?: Clock
@@ -335,6 +350,12 @@ interface Target {
 }
 
 export class TeamIntakeService {
+  private async withUsage(userID: string, row: IntakeRow): Promise<StoredIntake> {
+    const item = view(row)
+    if (!this.deps.budgets) return item
+    try { return { ...item, usage: await this.deps.budgets.usage(userID, row.teamID, row.id, row.startedAt, row.source.kind === "session" ? row.parentItem ?? "pool" : undefined) } }
+    catch (cause) { this.report(cause); return item }
+  }
   private readonly state: StateStore
   private readonly now: Clock
   private readonly newID: (kind: IdKind) => string
@@ -376,6 +397,7 @@ export class TeamIntakeService {
     const slot = key === undefined ? undefined : `${partyOf(actor)}|${key}`
     const id = this.newID("intake")
     const hop = actor.kind === "session" && this.deps.hopOf ? await this.deps.hopOf(userID, actor.sessionID) : undefined
+    const parentItem = actor.kind === "session" ? await this.deps.parentOf?.(userID, teamID, actor.sessionID) : undefined
     if (body.brief !== undefined && !expired) await this.state.put(userID, TEAM_INTAKE_BRIEFS, id, { v: 1, teamID, brief: body.brief })
     let result: { row: IntakeRow; created: boolean } | undefined
     try {
@@ -401,7 +423,7 @@ export class TeamIntakeService {
         if (doc.items.filter((i) => !CLOSED.has(i.status)).length >= this.limits.openPerTeam)
           throw new AgentError("rate_limited", `A team holds at most ${this.limits.openPerTeam} open submissions`, { hint: "Close or cancel some first", extra: { limit: this.limits.openPerTeam } })
         const { brief: _brief, ...fields } = body
-        const row: IntakeRow = { v: 1, id, teamID, ...fields, source: sourceOf(actor), status: "queued", revision: 1, createdAt: at, updatedAt: at, ...(hop === undefined ? {} : { hop }) }
+        const row: IntakeRow = { v: 1, id, teamID, ...fields, source: sourceOf(actor), status: "queued", revision: 1, createdAt: at, updatedAt: at, ...(hop === undefined ? {} : { hop }), ...(parentItem ? { parentItem } : {}) }
         result = { row, created: true }
         const nextKeys = slot === undefined ? keys : { ...keys, [slot]: { intakeID: id, digest, at } }
         return { ...doc, items: this.retained([...doc.items, row]), keys: this.boundedKeys(nextKeys) }
@@ -416,6 +438,10 @@ export class TeamIntakeService {
       return { intake: view(await this.reconciled(userID, (await this.row(userID, teamID, result!.row.id)) ?? result!.row)), created: false }
     }
     await this.emit(userID, intakeEvent(result!.row))
+    if (actor.kind === "user") {
+      try { await this.deps.submittedByUser?.(userID, teamID, id, actor) }
+      catch (cause) { this.report(cause) }
+    }
     if (result!.row.notAfter !== undefined) this.arm(result!.row.notAfter)
     await this.drainSafely(userID, teamID)
     return { intake: view((await this.row(userID, teamID, id)) ?? result!.row), created: true }
@@ -429,7 +455,8 @@ export class TeamIntakeService {
     await this.drainSafely(userID, teamID)
     const row = await this.row(userID, teamID, intakeID)
     if (!row || (scope === "own" && !sameSource(row, actor))) throw new AgentError("not_found", `No intake ${intakeID} in team ${teamID}`)
-    return view(await this.reconciled(userID, row))
+    const current = await this.reconciled(userID, row)
+    return this.withUsage(userID, current)
   }
 
   /** The team's intake the caller may see, oldest first, paged. */
@@ -448,7 +475,7 @@ export class TeamIntakeService {
       .filter((i) => query.status === undefined || i.status === query.status)
       .filter((i) => !after || i.createdAt > after[0] || (i.createdAt === after[0] && i.id > after[1]))
       .sort(byCreation)
-    const items = all.slice(0, limit).map(view)
+    const items = await Promise.all(all.slice(0, limit).map((row) => this.withUsage(userID, row)))
     return all.length > limit ? { items, cursor: encodeCursor(items.at(-1)!) } : { items }
   }
 
@@ -517,9 +544,13 @@ export class TeamIntakeService {
       const { progress: _p, claim: _c, ...rest } = current
       if (closing) return { ...rest, status: wanted, ...(reason !== undefined ? { reason: reason as string } : {}), closedAt: this.now() }
       if (current.progress === wanted) return undefined
-      return { ...rest, ...(current.claim ? { claim: current.claim } : {}), progress: wanted as IntakeProgress }
+      return { ...rest, ...(current.claim ? { claim: current.claim } : {}), progress: wanted as IntakeProgress, ...(wanted === "in_progress" ? { startedAt: current.startedAt ?? this.now() } : {}) }
     })
-    if (next.revision !== row.revision) await this.emit(userID, intakeEvent(next))
+    if (next.revision !== row.revision) {
+      await this.emit(userID, intakeEvent(next))
+      try { await this.deps.progressChanged?.({ userID, teamID, item: intakeID, ...(next.sessionID ? { sessionID: next.sessionID } : {}), revision: next.revision, status: next.progress ?? next.status, actor }) }
+      catch (cause) { this.report(cause) }
+    }
     if (closing && row.status === "queued") await this.state.delete(userID, TEAM_INTAKE_BRIEFS, intakeID).catch(this.report)
     return { intake: view(next), ...(assignment ? { assignment } : {}) }
   }
@@ -738,7 +769,7 @@ export class TeamIntakeService {
           return claim ? { ...doc, items: doc.items.map((i) => (i.id === intakeID ? rest : i)) } : undefined
         }
         const t = this.now()
-        routed = { ...rest, status: "routed", progress: "open", assignmentID: assignment.id, workspaceID: target.workspaceID, sessionID: target.sessionID, messageID: sent.messageID, routedAt: t, revision: row.revision + 1, updatedAt: t }
+        routed = { ...rest, status: "routed", progress: "open", assignmentID: assignment.id, workspaceID: target.workspaceID, sessionID: target.sessionID, messageID: sent.messageID, routedAt: t, startedAt: row.startedAt ?? t, revision: row.revision + 1, updatedAt: t }
         return { ...doc, items: doc.items.map((i) => (i.id === intakeID ? routed! : i)) }
       })
       if (cancelled) {
@@ -747,6 +778,7 @@ export class TeamIntakeService {
       }
       await this.state.delete(userID, TEAM_INTAKE_BRIEFS, intakeID).catch(this.report)
       await this.emit(userID, intakeEvent(routed!))
+      try { await this.deps.routed?.(userID, team.id, routed!.id, target.sessionID) } catch (cause) { this.report(cause) }
       return "routed"
     } catch (cause) {
       const code = cause instanceof AgentError ? cause.code : "internal"

package/src/central/teams/involvement.ts

@@ -0,0 +1,95 @@
+// A user act toward one team (or a current seat of several teams) resets the team's agent-only hop chain.
+import type { TeamHopStalls } from "./hop-stalls"
+
+export type InvolvementAct = {
+  readonly kind: "decision" | "intake" | "permission" | "form" | "prompt" | "renew" | "manual" | "budget" | "progress"
+  readonly teamIDs?: readonly string[]
+  readonly sessionID?: string
+  readonly ref: string
+  readonly actor?: { readonly deviceID?: string; readonly via?: string }
+}
+
+export interface TeamResetRecord {
+  readonly userID: string
+  readonly teamID: string
+  readonly kind: InvolvementAct["kind"]
+  readonly ref: string
+  readonly seats: readonly string[]
+  readonly failed: readonly string[]
+  readonly actor?: InvolvementAct["actor"]
+}
+
+export interface TeamInvolvementDeps {
+  /** Current seats only: a departed member must never be reset. */
+  readonly seats: (userID: string, teamID: string) => Promise<readonly string[]>
+  readonly seatsOf: (userID: string, sessionID: string) => Promise<readonly { readonly teamID: string }[]>
+  readonly reset: (userID: string, sessionID: string) => Promise<void>
+  readonly stalls: Pick<TeamHopStalls, "clearTeam" | "matches">
+  readonly audit: (entry: TeamResetRecord) => Promise<void>
+  readonly event: (entry: TeamResetRecord) => Promise<void>
+}
+
+export class TeamInvolvement {
+  constructor(private readonly deps: TeamInvolvementDeps) {}
+
+  /** Renew must fail if lookup or reset fails, leaving its Decision open for a retry. */
+  async renew(userID: string, teamID: string, decisionID: string, actor?: InvolvementAct["actor"]): Promise<void> {
+    await this.deps.stalls.matches(userID, teamID, decisionID)
+    await this.resetTeam(userID, teamID, { kind: "renew", teamIDs: [teamID], ref: decisionID, ...(actor ? { actor } : {}) }, true)
+  }
+
+  /** The user's Renew button in the console: strict like renew, but needs no stall (a failure → the caller's 500, retryable). */
+  async renewManual(userID: string, teamID: string, actor: NonNullable<InvolvementAct["actor"]>): Promise<void> {
+    await this.resetTeam(userID, teamID, { kind: "manual", teamIDs: [teamID], ref: "console", actor }, true)
+  }
+
+  /** Best effort: never make the user's original action fail because one reset/audit/event did. */
+  async involved(userID: string, act: InvolvementAct): Promise<void> {
+    try {
+      const teams = new Set(act.teamIDs ?? [])
+      if (act.sessionID) for (const seat of await this.deps.seatsOf(userID, act.sessionID)) teams.add(seat.teamID)
+      for (const teamID of teams) {
+        try { await this.resetTeam(userID, teamID, act, false) }
+        catch (cause) { console.error(`[hub] team involvement for ${teamID} failed:`, cause) }
+      }
+    } catch (cause) { console.error("[hub] team involvement lookup failed:", cause) }
+  }
+
+  /** A qualifying hub-observed progress signal (TA2-5) resets only seats charged to this item; never all team seats. */
+  async progress(userID: string, teamID: string, item: string, charged: readonly string[]): Promise<void> {
+    const seats = [...new Set(charged)]
+    if (seats.length === 0) return
+    const failed: string[] = []
+    for (const sessionID of seats) {
+      try { await this.deps.reset(userID, sessionID) }
+      catch (cause) { failed.push(sessionID); console.error(`[hub] item progress hop reset failed: ${cause instanceof Error ? cause.message : String(cause)}`) }
+    }
+    // Keep the team-level Renew stall and all seats outside the item's charged set unchanged.
+    const record: TeamResetRecord = { userID, teamID, kind: "progress", ref: item, seats, failed, actor: { via: "hub" } }
+    try { await this.deps.audit(record) }
+    catch (cause) { console.error(`[hub] item progress audit failed: ${cause instanceof Error ? cause.message : String(cause)}`) }
+    try { await this.deps.event(record) }
+    catch (cause) { console.error(`[hub] item progress event failed: ${cause instanceof Error ? cause.message : String(cause)}`) }
+  }
+
+  private async resetTeam(userID: string, teamID: string, act: InvolvementAct, strict: boolean): Promise<void> {
+    const seats = [...new Set(await this.deps.seats(userID, teamID))]
+    const failed: string[] = []
+    for (const sessionID of seats) {
+      try { await this.deps.reset(userID, sessionID) }
+      catch (cause) {
+        failed.push(sessionID)
+        console.error(`[hub] team hop reset for ${sessionID} failed:`, cause)
+        if (strict) throw cause
+      }
+    }
+    try { await this.deps.stalls.clearTeam(userID, teamID, act.kind === "manual" ? "The user renewed the team from the console" : undefined) }
+    catch (cause) { console.error(`[hub] team hop stall clear failed:`, cause); if (strict) throw cause }
+    const record: TeamResetRecord = { userID, teamID, kind: act.kind, ref: act.ref, seats, failed, ...(act.actor ? { actor: act.actor } : {}) }
+    // Renewal has already cleared its stall: audit/event failure must not reopen a Decision that cannot match.
+    try { await this.deps.audit(record) }
+    catch (cause) { console.error(`[hub] team hop reset audit failed:`, cause) }
+    try { await this.deps.event(record) }
+    catch (cause) { console.error(`[hub] team hop reset event failed:`, cause) }
+  }
+}

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

@@ -0,0 +1,60 @@
+// Pure ports for a tap-only item stall Decision. The hub wires these to budgets, loops, intake and involvement.
+/** The value returned by ItemBudgets.extend once TA2-4 is in the parent branch. */
+type ItemBudgetLimits = { readonly wakes: number; readonly hours: number }
+
+export interface ItemDecisionStall {
+  readonly userID: string
+  readonly teamID: string
+  readonly item?: string
+  readonly title: string
+  readonly reason: "budget" | "loop"
+  readonly decisionID: string
+  readonly pair?: readonly [string, string]
+  readonly usage: { readonly wakes: number; readonly hours: number }
+  readonly limit: ItemBudgetLimits
+}
+
+export interface ItemDecisionActor { readonly kind: string; readonly userID: string; readonly deviceID?: string; readonly via?: string }
+
+export function itemDecisionQuestion(stall: ItemDecisionStall): string | undefined {
+  if (!stall.item) return undefined // The team's unattributed pool receives a quiet notice, never a Decision.
+  const pair = stall.pair ? ` between ${stall.pair[0]} and ${stall.pair[1]}` : ""
+  const title = stall.title.replace(/[\x00-\x1f\x7f\p{Cf}]/gu, " ").replace(/\s+/g, " ").trim().slice(0, 120).replace(/\\/g, "\\\\").replace(/"/g, '\\"')
+  const hours = (value: number) => (Math.round(value * 10) / 10).toFixed(1)
+  return `Item ${stall.item} ("${title}") ${stall.reason === "budget" ? "spent its budget" : `is looping${pair}`}. ${stall.usage.wakes}/${stall.limit.wakes} wakes, ${hours(stall.usage.hours)}/${hours(stall.limit.hours)} hours. Extend or Stop?`
+}
+
+export class ItemDecisions {
+  constructor(private readonly deps: {
+    readonly matches: (userID: string, teamID: string, itemID: string, decisionID: string) => Promise<boolean>
+    readonly clearStall: (userID: string, itemID: string, decisionID: string) => Promise<void>
+    readonly extend: (userID: string, teamID: string, itemID: string, decisionID: string) => Promise<ItemBudgetLimits>
+    readonly clearLoop: (userID: string, itemID: string, pair: readonly [string, string]) => Promise<void>
+    readonly involved: (userID: string, act: { kind: "budget"; teamIDs: string[]; ref: string; actor: { deviceID: string; via: "cookie" } }) => Promise<void>
+    readonly stop: (userID: string, teamID: string, itemID: string, reason: "budget" | "loop") => Promise<void>
+    readonly audit: (entry: { userID: string; actor: { kind: "user" }; deviceID: string; verb: "team.item.extend" | "team.item.stop"; target: {}; reason: string; decision: "allow"; outcome: "ok" }) => Promise<void>
+  }) {}
+
+  async answer(stall: ItemDecisionStall, option: string | undefined, by: ItemDecisionActor): Promise<"gone" | "done" | { outcome: "done"; note: string }> {
+    const { userID, teamID, item, decisionID, reason, pair } = stall
+    if (!item || (option !== "extend" && option !== "stop") || by.kind !== "user" || by.userID !== userID || by.via !== "cookie" || !by.deviceID) return "gone"
+    if (!(await this.deps.matches(userID, teamID, item, decisionID))) return "gone"
+    let note: string | undefined
+    if (option === "extend") {
+      if (reason === "budget") {
+        const limits = await this.deps.extend(userID, teamID, item, decisionID)
+        note = `Budget extended to ${limits.wakes} wakes / ${limits.hours} hours`
+      } else {
+        if (!pair) return "gone"
+        await this.deps.clearLoop(userID, item, pair)
+      }
+      try { await this.deps.involved(userID, { kind: "budget", teamIDs: [teamID], ref: decisionID, actor: { deviceID: by.deviceID, via: "cookie" } }) }
+      catch (cause) { console.error("[hub] item Decision involvement failed:", cause) }
+    } else await this.deps.stop(userID, teamID, item, reason)
+    try { await this.deps.audit({ userID, actor: { kind: "user" }, deviceID: by.deviceID, verb: option === "extend" ? "team.item.extend" : "team.item.stop", target: {}, reason: `${item} ${reason}${pair ? ` ${pair.join(" → ")}` : ""}: limit ${stall.limit.wakes}/${stall.limit.hours}`, decision: "allow", outcome: "ok" }) }
+    catch (cause) { console.error("[hub] item Decision audit failed:", cause) }
+    try { await this.deps.clearStall(userID, item, decisionID) }
+    catch (cause) { console.error("[hub] item Decision stall clear failed:", cause) }
+    return note ? { outcome: "done", note } : "done"
+  }
+}

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

@@ -0,0 +1,35 @@
+// One owner-side item check for explicit attribution and future inherited message context.
+import type { TeamSeatStore } from "./seats"
+import type { TeamStore } from "./store"
+import type { TeamIntakeService } from "./intake"
+
+export type ItemEligibility = { readonly ok: true; readonly teamID: string; readonly startedAt?: number; readonly parentItem?: string; readonly child?: boolean } | { readonly ok: false; readonly reason: "closed" | "archived" | "unseated"; readonly sessionID?: string; readonly team?: string }
+
+export function itemEligibility(deps: {
+  readonly seats: Pick<TeamSeatStore, "seatsOf">
+  readonly teams: Pick<TeamStore, "get">
+  readonly intake: Pick<TeamIntakeService, "get">
+}): { eligible(userID: string, item: string, sessionIDs: readonly string[]): Promise<ItemEligibility> } {
+  return {
+    async eligible(userID, itemID, sessionIDs) {
+      if (!sessionIDs.length) return { ok: false, reason: "unseated" }
+      const seats = await Promise.all(sessionIDs.map((id) => deps.seats.seatsOf(userID, id)))
+      for (const seat of seats[0] ?? []) {
+        const team = await deps.teams.get(userID, seat.teamID)
+        if (!team) continue
+        let item
+        try {
+          item = await deps.intake.get(userID, { kind: "user", userID, deviceID: "hub", via: "cookie" }, team.id, itemID)
+        } catch (cause) {
+          if (typeof cause === "object" && cause !== null && "code" in cause && cause.code === "not_found") continue
+          throw cause
+        }
+        if (team.state === "archived") return { ok: false, reason: "archived", team: team.name }
+        if (item.status === "done" || item.status === "failed" || item.status === "cancelled") return { ok: false, reason: "closed" }
+        for (let i = 1; i < sessionIDs.length; i++) if (!seats[i]?.some((s) => s.teamID === team.id)) return { ok: false, reason: "unseated", sessionID: sessionIDs[i] }
+        return { ok: true, teamID: team.id, ...(item.startedAt !== undefined ? { startedAt: item.startedAt } : {}), ...(item.parentItem ? { parentItem: item.parentItem } : {}), ...(item.source.kind === "session" ? { child: true } : {}) }
+      }
+      return { ok: false, reason: "unseated", sessionID: sessionIDs[0] }
+    },
+  }
+}