@huynle/hub 0.7.3 → 0.8.0

package/src/central/teams/intake.ts

@@ -0,0 +1,772 @@
+// Team intake (HWA-36; contract docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md, Teams and the
+// HWA-33/34/35/04/06/11 clarifications; record TeamIntake in packages/protocol/src/teams.ts).
+//
+// Work is given to a TEAM, never to a session: the user (console/MCP), an app token with `teams:submit` (automations
+// such as a Brain connector: docs/teams-intake.md) or a session submits {title, brief?, priority?, labels?, due?,
+// criteria?, ref?}. The hub
+//   1. stores a TeamIntake (`queued`) in collection `team-intake` (one aggregate per team, key: team ID: items,
+//      Idempotency-Keys) and the brief alone in `team-intake-brief` (key: intake ID) until it is delivered;
+//   2. routes it (drain) to a current seat of the team's entry role — an online one first (earliest staffed), else
+//      an offline one (Delivery keeps the message pending until its spoke reports the session): creates a
+//      WorkspaceAssignment (HWA-04) of that seat's member in the team's workspace (HWA-35, one per team) with
+//      `ref` = intake ID, then delivers the task as a hub `msg` and marks the intake `routed` (`progress: open`);
+//   3. while the entry role is vacant (no current seat), the team is paused, or its workspace is not linked yet, the
+//      intake stays `queued` (durable, capped at TEAM_LIMITS.openIntakePerTeam open items per team). onEvent drains a
+//      team on `team.staffed`, `team.updated`/`team.archived` (resume/restore), and `session.added` or
+//      `workspace.member.joined` of an entry seat (staffing emits team.staffed before the member joins); every
+//      submit and read drains too, so a trigger missed across a restart is picked up on the next touch.
+//
+// Sender (decided for HWA-36, Brain decision in project hub): the task is delivered from the fixed hub party
+// `app:team-intake` (like HWA-11's `app:workspace-coordinator`; no real token ID has this shape), never as the user
+// or the submitting app. Reasons: queued items are delivered later without the submitter's credential (an app token
+// may be revoked by then); a user-sent message would reset hop chains and pose as a human turn; and the party sits
+// in no team, so delivery policy admits it (r3vv4eon) while who submitted is named in the text. Consequence
+// (HWA-34): the entry seat's reply to this `msg` is a msg to an outsider and is denied without `externalContact`;
+// progress is reported explicitly through setStatus (POST /teams/:id/intake/:intakeID/status, MCP
+// team_intake_update, the OpenCode hub tool's intake_update verb), which the submitter reads (GET, `team.intake`
+// events). The text says so, with the exact verb and IDs (reportingLines).
+//
+// Status (explicit, never inferred from idleness/presence/departure; HWA-04/06): intake `queued` → `routed` →
+// `done` | `failed` | `cancelled` (queued may be cancelled). While routed, `progress` mirrors the assignment:
+// open | in_progress | blocked. Mapping to the assignment: done → done; failed and cancelled → cancelled (an
+// assignment has no failed). Closing the assignment through the workspace routes is reflected on the next read of
+// the intake (get / setStatus). Who: the user and apps with teams:manage — anything; a session holding a current
+// seat of the entry role — anything; the submitter (app or session) — cancel only.
+// Reads: users all; apps with teams:read or teams:manage all, with teams:submit their own submissions; sessions
+// holding a current seat in the team all, other sessions their own submissions. Another user's team: not_found.
+// Sessions submit under team policy: teamDeliveryVerdict for a `msg` from the session to the entry role (no-team
+// sessions: allowed; members need a path or externalContact) — intake is not a way around the drawn edges.
+//
+// Delivery is at-least-once: a routing claim (claimMs) keeps two drains from delivering the same item; a crash
+// after delivery and before the routed write re-delivers after the claim expires (the assignment is reused).
+// Events (`team.intake`, family manage) carry IDs, enums and revisions only: never title, brief, labels or criteria.
+import { createHash, randomBytes } from "node:crypto"
+import {
+  ID_PREFIXES,
+  IDEMPOTENCY_KEY,
+  IDEMPOTENCY_TTL_MS,
+  type IdKind,
+  isExpectedRevision,
+  isLabel,
+  isText,
+  LIST_LIMIT_DEFAULT,
+  LIST_LIMIT_MAX,
+  type Page,
+  tagsProblem,
+  TEAM_LIMITS,
+  type TeamIntake,
+  type TeamSeat,
+  teamDeliveryVerdict,
+} from "../../protocol"
+import type { AgentActor, AppActor } from "../agent/actor"
+import { sanitizeLabel } from "../agent/envelope"
+import { AgentError } from "../agent/errors"
+import type { AgentEvents, EventInput } from "../agent/events"
+import { canonicalBody } from "../agent/idempotency"
+import { updateVersioned } from "../agent/versioned"
+import type { Clock, StateStore } from "../backend/types"
+import { assignmentChangedEvent } from "../workspaces/events"
+import type { MembershipStore, SessionPresence, SessionPresenceLookup, StoredAssignment } from "../workspaces/members"
+import type { TeamSeatStore } from "./seats"
+import type { TeamStaffingService } from "./staffing"
+import type { Team, TeamStore } from "./store"
+
+/** One aggregate per team (key: team ID): intake items and their Idempotency-Keys. */
+export const TEAM_INTAKE = "team-intake"
+/** Briefs of undelivered intake (key: intake ID); removed once delivered or cancelled. */
+export const TEAM_INTAKE_BRIEFS = "team-intake-brief"
+/** The fixed party intake is delivered from (an app party no real token can be: those are 16 hex digits). */
+export const INTAKE_TOKEN = "team-intake"
+/** The party intake is delivered as (never the user or the submitter; it holds no scopes and no seats). */
+export const intakeActor = (userID: string): AppActor => ({ kind: "app", userID, tokenID: INTAKE_TOKEN, scopes: [], label: "team intake" })
+
+export const INTAKE_PRIORITIES = ["low", "normal", "high", "urgent"] as const
+export type IntakePriority = (typeof INTAKE_PRIORITIES)[number]
+export type IntakeProgress = "open" | "in_progress" | "blocked"
+export type IntakeStatus = TeamIntake["status"]
+/** What setStatus accepts: progress while routed, or a closing status. */
+export const INTAKE_STATUS_INPUTS = ["open", "in_progress", "blocked", "done", "failed", "cancelled"] as const
+export type IntakeStatusInput = (typeof INTAKE_STATUS_INPUTS)[number]
+
+export interface IntakeLimits {
+  /** Open (queued or routed) items per team. */
+  readonly openPerTeam: number
+  /** Submissions per team per rolling minute. */
+  readonly submitsPerMinute: number
+  /** Closed items kept per team (oldest closed dropped). */
+  readonly closedRetained: number
+  readonly briefMax: number
+  readonly refMax: number
+  readonly reasonMax: number
+  readonly criteriaPerIntake: number
+  readonly criterionMax: number
+  /** Live Idempotency-Keys kept per team. */
+  readonly keysPerTeam: number
+  /** How long a routing claim holds before another drain may retry the item. */
+  readonly claimMs: number
+}
+
+export const INTAKE_LIMITS: IntakeLimits = {
+  openPerTeam: TEAM_LIMITS.openIntakePerTeam,
+  submitsPerMinute: 60,
+  closedRetained: 200,
+  briefMax: 16_000,
+  refMax: 200,
+  reasonMax: 200,
+  criteriaPerIntake: 8,
+  criterionMax: 200,
+  keysPerTeam: 1_000,
+  claimMs: 60_000,
+}
+
+/** A TeamIntake as stored and read: the contract record plus additive fields (HWA-36). */
+export interface StoredIntake extends TeamIntake {
+  readonly priority: IntakePriority
+  readonly labels?: readonly string[]
+  /** Due time (epoch ms). */
+  readonly due?: number
+  readonly criteria?: readonly string[]
+  readonly workspaceID?: string
+  /** The entry seat's session it was delivered to. */
+  readonly sessionID?: string
+  readonly messageID?: string
+  /** While routed: the assignment's status. */
+  readonly progress?: IntakeProgress
+  /** Why it failed or was cancelled (bounded, never in events). */
+  readonly reason?: string
+  /** The last routing failure's error code (the item stays queued and is retried). */
+  readonly lastError?: string
+  readonly updatedAt: number
+  readonly routedAt?: number
+  readonly closedAt?: number
+}
+
+interface IntakeRow extends StoredIntake {
+  readonly claim?: { readonly owner: string; readonly at: number }
+}
+
+interface IntakeKey {
+  readonly intakeID: string
+  readonly digest: string
+  readonly at: number
+}
+
+interface IntakeDoc {
+  readonly v: 1
+  readonly teamID: string
+  readonly items: readonly IntakeRow[]
+  /** `<party>|<key>` → the intake it created. */
+  readonly keys: Readonly<Record<string, IntakeKey>>
+}
+
+/** Delivers one task text to a session (production: Delivery.send as intakeActor). */
+export type IntakeDeliver = (userID: string, sessionID: string, text: string) => Promise<{ readonly messageID: string }>
+
+export interface TeamIntakeDeps {
+  readonly state: StateStore
+  readonly teams: Pick<TeamStore, "get" | "require">
+  readonly seats: Pick<TeamSeatStore, "list" | "seatsOf" | "deliveryContext">
+  readonly staffing: Pick<TeamStaffingService, "workspaceOf">
+  readonly members: Pick<MembershipStore, "members" | "assign" | "assignment" | "setStatus" | "reassign">
+  readonly presence: SessionPresenceLookup
+  readonly deliver: IntakeDeliver
+  readonly events?: Pick<AgentEvents, "append">
+  readonly report?: (cause: unknown) => void
+  readonly now?: Clock
+  readonly newID?: (kind: IdKind) => string
+  readonly limits?: Partial<IntakeLimits>
+}
+
+export interface IntakeListQuery {
+  readonly status?: string
+  readonly limit?: number
+  readonly cursor?: string
+}
+
+/** Intake counts of one team (team status, HWA-37): by status, and routed items by progress. */
+export interface IntakeSummary {
+  readonly queued: number
+  readonly routed: number
+  readonly done: number
+  readonly cancelled: number
+  readonly failed: number
+  /** Routed items by progress. */
+  readonly open: number
+  readonly inProgress: number
+  readonly blocked: number
+  /** When the oldest still-queued item was submitted (epoch ms). */
+  readonly oldestQueuedAt?: number
+}
+
+const SUBMIT_FIELDS = new Set(["title", "brief", "priority", "labels", "due", "criteria", "ref"])
+const STATUS_FIELDS = new Set(["status", "expectedRevision", "reason"])
+const CLOSED: ReadonlySet<IntakeStatus> = new Set(["done", "cancelled", "failed"])
+const OPEN_ASSIGNMENT: ReadonlySet<string> = new Set(["open", "in_progress", "blocked"])
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const message = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause))
+const digestOf = (v: unknown) => createHash("sha256").update(canonicalBody(v)).digest("hex")
+
+function unknownField(input: Record<string, unknown>, allowed: ReadonlySet<string>): void {
+  const unknown = Object.keys(input).find((k) => !allowed.has(k))
+  if (unknown !== undefined) throw new AgentError("invalid", `unknown field ${/^[A-Za-z0-9_-]{1,40}$/.test(unknown) ? unknown : "(unprintable)"}`)
+}
+
+function readDoc(raw: unknown, teamID: string): IntakeDoc {
+  if (raw === undefined) return { v: 1, teamID, items: [], keys: {} }
+  if (isObj(raw) && typeof raw.v === "number" && raw.v > 1)
+    throw new AgentError("unsupported", `The intake of team ${teamID} was written by a newer hub`, { hint: "Upgrade this hub", extra: { feature: TEAM_INTAKE } })
+  if (!isObj(raw) || raw.v !== 1 || raw.teamID !== teamID || !Array.isArray(raw.items)) throw new AgentError("internal", `Stored intake of team ${teamID} is malformed`)
+  return { v: 1, teamID, items: raw.items as IntakeRow[], keys: isObj(raw.keys) ? (raw.keys as Record<string, IntakeKey>) : {} }
+}
+
+/** The source of a submission (the contract's TeamIntake.source). */
+function sourceOf(actor: AgentActor): TeamIntake["source"] {
+  switch (actor.kind) {
+    case "user":
+      return { kind: "user" }
+    case "app":
+      return { kind: "app", tokenID: actor.tokenID }
+    case "session":
+      return { kind: "session", sessionID: actor.sessionID }
+  }
+}
+
+const partyOf = (actor: AgentActor): string => (actor.kind === "user" ? "user" : actor.kind === "app" ? `app:${actor.tokenID}` : `ses:${actor.sessionID}`)
+
+const sameSource = (row: StoredIntake, actor: AgentActor): boolean =>
+  (actor.kind === "app" && row.source.kind === "app" && row.source.tokenID === actor.tokenID) ||
+  (actor.kind === "session" && row.source.kind === "session" && row.source.sessionID === actor.sessionID) ||
+  (actor.kind === "user" && row.source.kind === "user")
+
+/** The stored row as reads show it (no routing claim). */
+function view(row: IntakeRow): StoredIntake {
+  const { claim: _claim, ...rest } = row
+  return rest
+}
+
+const intakeEvent = (row: StoredIntake): EventInput => ({
+  type: "team.intake",
+  family: "manage",
+  subject: {
+    teamID: row.teamID,
+    intakeID: row.id,
+    ...(row.assignmentID !== undefined ? { assignmentID: row.assignmentID } : {}),
+    ...(row.workspaceID !== undefined ? { workspaceID: row.workspaceID } : {}),
+    ...(row.sessionID !== undefined ? { sessionID: row.sessionID } : {}),
+  },
+  data: { status: row.status, revision: row.revision, source: row.source.kind, priority: row.priority, ...(row.progress !== undefined ? { progress: row.progress } : {}) },
+})
+
+interface Body {
+  readonly title: string
+  readonly brief?: string
+  readonly priority: IntakePriority
+  readonly labels?: readonly string[]
+  readonly due?: number
+  readonly criteria?: readonly string[]
+  readonly ref?: string
+}
+
+interface Target {
+  readonly sessionID: string
+  readonly workspaceID: string
+  readonly memberID: string
+}
+
+export class TeamIntakeService {
+  private readonly state: StateStore
+  private readonly now: Clock
+  private readonly newID: (kind: IdKind) => string
+  private readonly report: (cause: unknown) => void
+  private readonly limits: IntakeLimits
+  private readonly owner = `intake-${process.pid}-${randomBytes(4).toString("hex")}`
+  /** Per user and team: the drain in progress (one at a time in this process). */
+  private readonly draining = new Map<string, Promise<number>>()
+
+  constructor(private readonly deps: TeamIntakeDeps) {
+    this.state = deps.state
+    this.now = deps.now ?? Date.now
+    this.newID = deps.newID ?? ((kind) => `${ID_PREFIXES[kind]}_${randomBytes(12).toString("hex")}`)
+    this.report = deps.report ?? ((cause) => console.error(`[hub] team intake: ${message(cause)}`))
+    this.limits = { ...INTAKE_LIMITS, ...deps.limits }
+  }
+
+  // ---------- submit ----------
+
+  /** Submits work to a team; routes it at once when an entry seat is staffed, else it waits queued. */
+  async submit(userID: string, actor: AgentActor, teamID: string, input: unknown, options: { readonly idempotencyKey?: string } = {}): Promise<{ intake: StoredIntake; created: boolean }> {
+    if (actor.kind === "app" && !actor.scopes.includes("teams:submit")) throw new AgentError("forbidden", "Submitting to a team needs scope teams:submit")
+    const body = this.body(input)
+    const key = options.idempotencyKey
+    if (key !== undefined && !IDEMPOTENCY_KEY.test(key)) throw new AgentError("invalid", "Idempotency-Key must be 1–200 of A-Z a-z 0-9 _ . : -")
+    const team = await this.deps.teams.require(userID, teamID)
+    if (team.state === "archived") throw new AgentError("invalid", `Team ${team.id} is archived`, { hint: "Restore it first" })
+    if (team.paused) throw new AgentError("invalid", `Team ${team.id} is paused: it takes no new work`, { hint: "Resume it first" })
+    if (actor.kind === "session") await this.checkPolicy(userID, team, actor.sessionID)
+
+    const digest = digestOf(body)
+    const slot = key === undefined ? undefined : `${partyOf(actor)}|${key}`
+    const id = this.newID("intake")
+    if (body.brief !== undefined) await this.state.put(userID, TEAM_INTAKE_BRIEFS, id, { v: 1, teamID, brief: body.brief })
+    let result: { row: IntakeRow; created: boolean } | undefined
+    try {
+      await this.writeDoc(userID, teamID, (doc) => {
+        const at = this.now()
+        const keys = this.liveKeys(doc, at)
+        const held = slot === undefined ? undefined : keys[slot]
+        if (held) {
+          if (held.digest !== digest) throw new AgentError("conflict", `Idempotency-Key ${key} was used for another submission`, { hint: "Use a new key for a different body, or resend the original body" })
+          const existing = doc.items.find((i) => i.id === held.intakeID)
+          if (existing) {
+            result = { row: existing, created: false }
+            return undefined
+          }
+        }
+        const recent = doc.items.filter((i) => at - i.createdAt < 60_000)
+        if (recent.length >= this.limits.submitsPerMinute) {
+          const oldest = Math.min(...recent.map((i) => i.createdAt))
+          throw new AgentError("rate_limited", `A team takes at most ${this.limits.submitsPerMinute} submissions a minute`, { extra: { retryAfter: Math.max(1, Math.ceil((oldest + 60_000 - at) / 1000)) } })
+        }
+        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 }
+        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) }
+      })
+    } catch (cause) {
+      if (body.brief !== undefined) await this.state.delete(userID, TEAM_INTAKE_BRIEFS, id).catch(this.report)
+      throw cause
+    }
+    if (!result!.created) {
+      if (body.brief !== undefined) await this.state.delete(userID, TEAM_INTAKE_BRIEFS, id).catch(this.report)
+      return { intake: view(await this.reconciled(userID, result!.row)), created: false }
+    }
+    await this.emit(userID, intakeEvent(result!.row))
+    await this.drainSafely(userID, teamID)
+    return { intake: view((await this.row(userID, teamID, id)) ?? result!.row), created: true }
+  }
+
+  // ---------- reads ----------
+
+  async get(userID: string, actor: AgentActor, teamID: string, intakeID: string): Promise<StoredIntake> {
+    const team = await this.deps.teams.require(userID, teamID)
+    const scope = await this.readScope(userID, actor, team)
+    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))
+  }
+
+  /** The team's intake the caller may see, oldest first, paged. */
+  async list(userID: string, actor: AgentActor, teamID: string, query: IntakeListQuery = {}): Promise<Page<StoredIntake>> {
+    const limit = query.limit ?? LIST_LIMIT_DEFAULT
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > LIST_LIMIT_MAX) throw new AgentError("invalid", `limit must be 1–${LIST_LIMIT_MAX}`)
+    if (query.status !== undefined && !["queued", "routed", "done", "cancelled", "failed"].includes(query.status))
+      throw new AgentError("invalid", "status must be one of queued, routed, done, cancelled, failed")
+    const after = query.cursor === undefined ? undefined : decodeCursor(query.cursor)
+    const team = await this.deps.teams.require(userID, teamID)
+    const scope = await this.readScope(userID, actor, team)
+    await this.drainSafely(userID, teamID)
+    const doc = readDoc((await this.state.get(userID, TEAM_INTAKE, teamID))?.value, teamID)
+    const all = doc.items
+      .filter((i) => scope === "all" || sameSource(i, actor))
+      .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)
+    return all.length > limit ? { items, cursor: encodeCursor(items.at(-1)!) } : { items }
+  }
+
+  /**
+   * Counts of the team's intake by status (and routed items by progress), for team status (HWA-37). The caller
+   * authorizes the read; counts carry no text.
+   */
+  async summary(userID: string, teamID: string): Promise<IntakeSummary> {
+    await this.deps.teams.require(userID, teamID)
+    const doc = readDoc((await this.state.get(userID, TEAM_INTAKE, teamID))?.value, teamID)
+    const out = { queued: 0, routed: 0, done: 0, cancelled: 0, failed: 0, open: 0, inProgress: 0, blocked: 0 }
+    let oldestQueuedAt: number | undefined
+    for (const item of doc.items) {
+      out[item.status]++
+      if (item.status === "queued") oldestQueuedAt = Math.min(oldestQueuedAt ?? item.createdAt, item.createdAt)
+      if (item.status === "routed") {
+        if (item.progress === "in_progress") out.inProgress++
+        else if (item.progress === "blocked") out.blocked++
+        else out.open++
+      }
+    }
+    return { ...out, ...(oldestQueuedAt !== undefined ? { oldestQueuedAt } : {}) }
+  }
+
+  // ---------- status ----------
+
+  /** Explicit progress or completion (see the header for who may do what). */
+  async setStatus(userID: string, actor: AgentActor, teamID: string, intakeID: string, input: unknown): Promise<{ intake: StoredIntake; assignment?: StoredAssignment }> {
+    if (!isObj(input)) throw new AgentError("invalid", "body must be an object")
+    unknownField(input, STATUS_FIELDS)
+    const { status, expectedRevision, reason } = input
+    if (!INTAKE_STATUS_INPUTS.includes(status as IntakeStatusInput)) throw new AgentError("invalid", `status must be one of ${INTAKE_STATUS_INPUTS.join(", ")}`)
+    if (!isExpectedRevision(expectedRevision)) throw new AgentError("invalid", "expectedRevision is required: the revision you read", { hint: "Read the intake and send its revision" })
+    if (reason !== undefined && !isLabel(reason, this.limits.reasonMax)) throw new AgentError("invalid", `reason must be 1–${this.limits.reasonMax} characters of text`)
+    const wanted = status as IntakeStatusInput
+    const team = await this.deps.teams.require(userID, teamID)
+    const scope = await this.readScope(userID, actor, team)
+    const stored = await this.row(userID, teamID, intakeID)
+    if (!stored || (scope === "own" && !sameSource(stored, actor))) throw new AgentError("not_found", `No intake ${intakeID} in team ${teamID}`)
+    if (!(await this.mayChange(userID, actor, team, stored, wanted)))
+      throw new AgentError("forbidden", wanted === "cancelled" ? "Only the user, the team's entry role or the submitter may cancel this" : "Only the user or a session in the team's entry role reports progress", {
+        hint: "The submitter may only cancel",
+      })
+    const row = await this.reconciled(userID, stored)
+    if (CLOSED.has(row.status)) {
+      if (row.status === wanted) return { intake: view(row) }
+      throw new AgentError("invalid", `Intake ${intakeID} is ${row.status}`, { hint: "Submit new work instead" })
+    }
+    if (row.revision !== expectedRevision)
+      throw new AgentError("conflict", `Intake ${intakeID} changed since you read it (revision ${row.revision} now)`, { hint: "Read it again and retry", extra: { currentRevision: row.revision } })
+    if (row.status === "queued" && wanted !== "cancelled") throw new AgentError("invalid", `Intake ${intakeID} is still queued for the entry role`, { hint: "Only cancelling is possible before it is routed" })
+
+    let assignment: StoredAssignment | undefined
+    if (row.status === "routed" && row.assignmentID !== undefined && row.workspaceID !== undefined) {
+      const target = wanted === "done" ? "done" : wanted === "failed" || wanted === "cancelled" ? "cancelled" : wanted
+      const before = await this.deps.members.assignment(userID, row.workspaceID, row.assignmentID).catch(() => undefined)
+      if (before) {
+        assignment = await this.deps.members.setStatus(userID, row.workspaceID, row.assignmentID, target)
+        if (assignment.revision !== before.revision) await this.emit(userID, assignmentChangedEvent(assignment, "status"))
+      }
+    }
+    const closing = wanted === "done" || wanted === "failed" || wanted === "cancelled"
+    const next = await this.mutate(userID, teamID, intakeID, (current) => {
+      if (current.revision !== expectedRevision)
+        throw new AgentError("conflict", `Intake ${intakeID} changed since you read it (revision ${current.revision} now)`, { extra: { currentRevision: current.revision } })
+      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 }
+    })
+    if (next.revision !== row.revision) await this.emit(userID, intakeEvent(next))
+    if (closing && row.status === "queued") await this.state.delete(userID, TEAM_INTAKE_BRIEFS, intakeID).catch(this.report)
+    return { intake: view(next), ...(assignment ? { assignment } : {}) }
+  }
+
+  // ---------- routing ----------
+
+  /** Routes the team's queued intake, oldest first, while an entry seat is reachable. Returns how many it routed. */
+  drain(userID: string, teamID: string): Promise<number> {
+    const key = `${userID}\u0000${teamID}`
+    const previous = this.draining.get(key) ?? Promise.resolve(0)
+    const run = previous.catch(() => 0).then(() => this.drainNow(userID, teamID))
+    this.draining.set(key, run)
+    void run.finally(() => {
+      if (this.draining.get(key) === run) this.draining.delete(key)
+    }).catch(() => undefined)
+    return run
+  }
+
+  /** A journal event appended (http.ts onAppend): drains the teams it may unblock. Never throws. */
+  async onEvent(userID: string, event: { readonly type: string; readonly subject?: Readonly<Record<string, string>> }): Promise<void> {
+    try {
+      const teamID = event.subject?.teamID
+      if ((event.type === "team.staffed" || event.type === "team.updated" || event.type === "team.archived") && teamID !== undefined) {
+        await this.drain(userID, teamID)
+      } else if ((event.type === "session.added" || event.type === "workspace.member.joined") && event.subject?.sessionID !== undefined) {
+        for (const seat of await this.deps.seats.seatsOf(userID, event.subject.sessionID)) {
+          const team = await this.deps.teams.get(userID, seat.teamID)
+          if (team && team.entryRole === seat.role) await this.drain(userID, seat.teamID)
+        }
+      }
+    } catch (cause) {
+      this.report(cause)
+    }
+  }
+
+  private async drainSafely(userID: string, teamID: string): Promise<void> {
+    await this.drain(userID, teamID).catch(this.report)
+  }
+
+  private async drainNow(userID: string, teamID: string): Promise<number> {
+    const team = await this.deps.teams.get(userID, teamID)
+    if (!team || team.state !== "active" || team.paused) return 0
+    const queued = readDoc((await this.state.get(userID, TEAM_INTAKE, teamID))?.value, teamID)
+      .items.filter((i) => i.status === "queued")
+      .sort(byCreation)
+    if (queued.length === 0) return 0
+    const target = await this.target(userID, team)
+    if (!target) return 0
+    let routed = 0
+    for (const item of queued) {
+      const outcome = await this.route(userID, team, item.id, target)
+      if (outcome === "failed") break
+      if (outcome === "routed") routed++
+    }
+    return routed
+  }
+
+  /** The entry seat to route to (online first, else offline; earliest staffed) and its workspace member. */
+  private async target(userID: string, team: Team): Promise<Target | undefined> {
+    const entry = (await this.deps.seats.list(userID, team.id, { current: true }))
+      .filter((s) => s.role === team.entryRole)
+      .sort((a, b) => a.since - b.since || (a.id < b.id ? -1 : 1))
+    if (entry.length === 0) return undefined
+    const presence = new Map<string, SessionPresence>()
+    for (const s of entry) if (!presence.has(s.sessionID)) presence.set(s.sessionID, await this.deps.presence(userID, s.sessionID))
+    const pick = entry.find((s) => presence.get(s.sessionID) === "online") ?? entry.find((s) => presence.get(s.sessionID) === "offline")
+    if (!pick) return undefined
+    const workspaceID = await this.deps.staffing.workspaceOf(userID, team.id)
+    if (workspaceID === undefined) return undefined
+    const member = (await this.deps.members.members(userID, workspaceID).catch(() => [])).find((m) => m.current && m.member.sessionID === pick.sessionID)
+    if (!member) return undefined
+    return { sessionID: pick.sessionID, workspaceID, memberID: member.member.id }
+  }
+
+  /** Claims, assigns, delivers and marks one queued item routed. */
+  private async route(userID: string, team: Team, intakeID: string, target: Target): Promise<"routed" | "skipped" | "failed"> {
+    const at = this.now()
+    let claimed: IntakeRow | undefined
+    await this.writeDoc(userID, team.id, (doc) => {
+      const row = doc.items.find((i) => i.id === intakeID)
+      if (!row || row.status !== "queued") return undefined
+      if (row.claim && row.claim.owner !== this.owner && at - row.claim.at < this.limits.claimMs) return undefined
+      claimed = { ...row, claim: { owner: this.owner, at } }
+      return { ...doc, items: doc.items.map((i) => (i.id === intakeID ? claimed! : i)) }
+    })
+    if (!claimed) return "skipped"
+    try {
+      const assignment = await this.assignmentFor(userID, claimed, target)
+      if (claimed.assignmentID !== assignment.id || claimed.workspaceID !== target.workspaceID)
+        await this.mutate(userID, team.id, intakeID, (row) => ({ ...row, assignmentID: assignment.id, workspaceID: target.workspaceID }), false)
+      const brief = (await this.state.get<{ brief?: unknown }>(userID, TEAM_INTAKE_BRIEFS, intakeID))?.value?.brief
+      const text = this.text(team, claimed, assignment.id, target, typeof brief === "string" ? brief : undefined)
+      const sent = await this.deps.deliver(userID, target.sessionID, text)
+      let cancelled = false
+      let routed: IntakeRow | undefined
+      await this.writeDoc(userID, team.id, (doc) => {
+        const row = doc.items.find((i) => i.id === intakeID)
+        if (!row) {
+          cancelled = true
+          return undefined
+        }
+        const { claim, lastError: _e, ...rest } = row
+        if (row.status !== "queued") {
+          cancelled = true
+          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 }
+        return { ...doc, items: doc.items.map((i) => (i.id === intakeID ? routed! : i)) }
+      })
+      if (cancelled) {
+        await this.deps.members.setStatus(userID, target.workspaceID, assignment.id, "cancelled").catch(this.report)
+        return "skipped"
+      }
+      await this.state.delete(userID, TEAM_INTAKE_BRIEFS, intakeID).catch(this.report)
+      await this.emit(userID, intakeEvent(routed!))
+      return "routed"
+    } catch (cause) {
+      const code = cause instanceof AgentError ? cause.code : "internal"
+      this.report(cause)
+      await this.mutate(userID, team.id, intakeID, (row) => {
+        const { claim: _c, ...rest } = row
+        return { ...rest, lastError: code }
+      }, false).catch(this.report)
+      return "failed"
+    }
+  }
+
+  /** The item's assignment for this target: reused (moved to the member when needed) or created idempotently. */
+  private async assignmentFor(userID: string, row: IntakeRow, target: Target): Promise<StoredAssignment> {
+    if (row.assignmentID !== undefined && row.workspaceID === target.workspaceID) {
+      const existing = await this.deps.members.assignment(userID, target.workspaceID, row.assignmentID).catch(() => undefined)
+      if (existing && OPEN_ASSIGNMENT.has(existing.status)) {
+        if (existing.memberID === target.memberID) return existing
+        const moved = await this.deps.members.reassign(userID, target.workspaceID, existing.id, target.memberID)
+        await this.emit(userID, assignmentChangedEvent(moved, "reassigned"))
+        return moved
+      }
+    }
+    const { assignment, created } = await this.deps.members.assign(
+      userID,
+      target.workspaceID,
+      { memberID: target.memberID, title: row.title, status: "open", ref: row.id, ...(row.criteria ? { criteria: [...row.criteria] } : {}) },
+      { idempotencyKey: `team-intake.${row.id}.${target.memberID}` },
+    )
+    if (created) await this.emit(userID, assignmentChangedEvent(assignment, "created"))
+    return assignment
+  }
+
+  /** The delivered task: team context first (a session may serve several teams), then the brief. */
+  private text(team: Team, row: IntakeRow, assignmentID: string, target: Target, brief: string | undefined): string {
+    const from = row.source.kind === "user" ? "the user" : row.source.kind === "app" ? `app ${row.source.tokenID}` : `session ${row.source.sessionID}`
+    const facts = [`intake ${row.id}`, `revision ${row.revision + 1}`, `assignment ${assignmentID}`, `workspace ${target.workspaceID}`, `priority ${row.priority}`]
+    if (row.due !== undefined) facts.push(`due ${new Date(row.due).toISOString()}`)
+    if (row.ref !== undefined) facts.push(`ref ${sanitizeLabel(row.ref, this.limits.refMax)}`)
+    const lines = [
+      `[hub] team intake for #${team.name} (team ${team.id}, entry role ${team.entryRole}), submitted by ${from}`,
+      `Title: ${sanitizeLabel(row.title)}`,
+      facts.join(" · "),
+    ]
+    if (row.labels?.length) lines.push(`Labels: ${row.labels.join(", ")}`)
+    if (row.criteria?.length) lines.push("Done means:", ...row.criteria.map((c) => `- ${sanitizeLabel(c, this.limits.criterionMax)}`))
+    lines.push("", brief !== undefined && brief.trim() ? brief : "(no brief)", "")
+    lines.push(...reportingLines(team.id, row.id))
+    return lines.join("\n")
+  }
+
+  // ---------- authority ----------
+
+  /** "all" or "own" (the caller's submissions); forbidden for apps without a teams scope. */
+  private async readScope(userID: string, actor: AgentActor, team: Team): Promise<"all" | "own"> {
+    if (actor.kind === "user") return "all"
+    if (actor.kind === "app") {
+      if (actor.scopes.includes("teams:read") || actor.scopes.includes("teams:manage")) return "all"
+      if (actor.scopes.includes("teams:submit")) return "own"
+      throw new AgentError("forbidden", "Team intake needs scope teams:submit (own submissions) or teams:read")
+    }
+    const seats = await this.deps.seats.list(userID, team.id, { current: true })
+    return seats.some((s) => s.sessionID === actor.sessionID) ? "all" : "own"
+  }
+
+  private async mayChange(userID: string, actor: AgentActor, team: Team, row: StoredIntake, wanted: IntakeStatusInput): Promise<boolean> {
+    if (actor.kind === "user") return true
+    if (actor.kind === "app" && actor.scopes.includes("teams:manage")) return true
+    if (actor.kind === "session") {
+      const seats = await this.deps.seats.list(userID, team.id, { current: true })
+      if (seats.some((s) => s.sessionID === actor.sessionID && s.role === team.entryRole)) return true
+    }
+    return wanted === "cancelled" && sameSource(row, actor)
+  }
+
+  /** A session submits only where it could `msg` the entry role (teamDeliveryVerdict, no team context). */
+  private async checkPolicy(userID: string, team: Team, sessionID: string): Promise<void> {
+    const context = await this.deps.seats.deliveryContext(userID, [sessionID])
+    const teams = new Map(context.teams)
+    teams.set(team.id, { mode: team.mode, edges: team.edges, roles: team.roles, state: team.state })
+    const recipient: TeamSeat[] = [{ teamID: team.id, role: team.entryRole }]
+    const verdict = teamDeliveryVerdict({ kind: "msg", toUser: false, replyToPermittedAsk: false, senderSeats: context.seats.get(sessionID) ?? [], recipientSeats: recipient, teams })
+    if (!verdict.allow) throw new AgentError("forbidden", "Team policy does not let this session give work to that team", { extra: { policy: verdict.reason } })
+  }
+
+  // ---------- internals ----------
+
+  private body(input: unknown): Body {
+    if (!isObj(input)) throw new AgentError("invalid", "body must be an object")
+    unknownField(input, SUBMIT_FIELDS)
+    const { title, brief, priority, labels, due, criteria, ref } = input
+    const l = this.limits
+    if (!isLabel(title)) throw new AgentError("invalid", "title must be 1–120 characters of text")
+    if (brief !== undefined && !isText(brief, l.briefMax)) throw new AgentError("invalid", `brief must be at most ${l.briefMax} characters of text`)
+    if (priority !== undefined && !INTAKE_PRIORITIES.includes(priority as IntakePriority)) throw new AgentError("invalid", `priority must be one of ${INTAKE_PRIORITIES.join(", ")}`)
+    const labelProblem = tagsProblem(labels)
+    if (labelProblem) throw new AgentError("invalid", labelProblem.replace(/^tags/, "labels").replace(/each tag/, "each label"))
+    if (due !== undefined && !(typeof due === "number" && Number.isSafeInteger(due) && due > 0)) throw new AgentError("invalid", "due must be a time in epoch milliseconds")
+    if (criteria !== undefined && (!Array.isArray(criteria) || criteria.length > l.criteriaPerIntake || !criteria.every((c) => isLabel(c, l.criterionMax))))
+      throw new AgentError("invalid", `criteria must be a list of at most ${l.criteriaPerIntake} lines of 1–${l.criterionMax} characters`)
+    if (ref !== undefined && !isLabel(ref, l.refMax)) throw new AgentError("invalid", `ref must be 1–${l.refMax} characters of text`)
+    return {
+      title: title as string,
+      ...(brief !== undefined ? { brief: brief as string } : {}),
+      priority: (priority as IntakePriority | undefined) ?? "normal",
+      ...(labels !== undefined ? { labels: [...(labels as string[])] } : {}),
+      ...(due !== undefined ? { due: due as number } : {}),
+      ...(criteria !== undefined ? { criteria: [...(criteria as string[])] } : {}),
+      ...(ref !== undefined ? { ref: ref as string } : {}),
+    }
+  }
+
+  /** Reflects an assignment changed through the workspace routes (closed, or another progress) on a routed item. */
+  private async reconciled(userID: string, row: IntakeRow): Promise<IntakeRow> {
+    if (row.status !== "routed" || row.assignmentID === undefined || row.workspaceID === undefined) return row
+    const assignment = await this.deps.members.assignment(userID, row.workspaceID, row.assignmentID).catch(() => undefined)
+    if (!assignment) return row
+    const closed = assignment.status === "done" || assignment.status === "cancelled"
+    if (!closed && assignment.status === row.progress) return row
+    const next = await this.mutate(userID, row.teamID, row.id, (current) => {
+      if (current.status !== "routed") return undefined
+      const { progress: _p, ...rest } = current
+      if (closed) return { ...rest, status: assignment.status as "done" | "cancelled", closedAt: this.now() }
+      return current.progress === assignment.status ? undefined : { ...current, progress: assignment.status as IntakeProgress }
+    })
+    if (next.revision !== row.revision) await this.emit(userID, intakeEvent(next))
+    return next
+  }
+
+  private async row(userID: string, teamID: string, intakeID: string): Promise<IntakeRow | undefined> {
+    return readDoc((await this.state.get(userID, TEAM_INTAKE, teamID))?.value, teamID).items.find((i) => i.id === intakeID)
+  }
+
+  /**
+   * Version-checked change of one item. `bump` (default) counts it as a visible change: revision + 1 and updatedAt.
+   * `change` returning undefined leaves it alone. Resolves with the item as stored.
+   */
+  private async mutate(userID: string, teamID: string, intakeID: string, change: (row: IntakeRow) => IntakeRow | undefined, bump = true): Promise<IntakeRow> {
+    let out: IntakeRow | undefined
+    await this.writeDoc(userID, teamID, (doc) => {
+      const row = doc.items.find((i) => i.id === intakeID)
+      if (!row) throw new AgentError("not_found", `No intake ${intakeID} in team ${teamID}`)
+      const next = change(row)
+      if (!next) {
+        out = row
+        return undefined
+      }
+      out = bump ? { ...next, revision: row.revision + 1, updatedAt: this.now() } : next
+      return { ...doc, items: this.retained(doc.items.map((i) => (i.id === intakeID ? out! : i))) }
+    })
+    return out!
+  }
+
+  private async writeDoc(userID: string, teamID: string, change: (doc: IntakeDoc) => IntakeDoc | undefined): Promise<void> {
+    await updateVersioned<IntakeDoc>(this.state, userID, TEAM_INTAKE, teamID, (raw) => change(readDoc(raw, teamID)))
+  }
+
+  /** Open items plus the newest closed ones. */
+  private retained(items: readonly IntakeRow[]): IntakeRow[] {
+    const closed = items.filter((i) => CLOSED.has(i.status)).sort((a, b) => (b.closedAt ?? b.updatedAt) - (a.closedAt ?? a.updatedAt))
+    const keep = new Set(closed.slice(0, this.limits.closedRetained).map((i) => i.id))
+    return items.filter((i) => !CLOSED.has(i.status) || keep.has(i.id))
+  }
+
+  private liveKeys(doc: IntakeDoc, at: number): Record<string, IntakeKey> {
+    const out: Record<string, IntakeKey> = {}
+    for (const [k, v] of Object.entries(doc.keys)) if (isObj(v) && typeof v.at === "number" && at - v.at < IDEMPOTENCY_TTL_MS) out[k] = v
+    return out
+  }
+
+  private boundedKeys(keys: Readonly<Record<string, IntakeKey>>): Record<string, IntakeKey> {
+    const entries = Object.entries(keys)
+    if (entries.length <= this.limits.keysPerTeam) return { ...keys }
+    return Object.fromEntries(entries.sort((a, b) => b[1].at - a[1].at).slice(0, this.limits.keysPerTeam))
+  }
+
+  private async emit(userID: string, ...events: EventInput[]): Promise<void> {
+    if (!this.deps.events) return
+    for (const event of events) await this.deps.events.append(userID, event).catch(this.report)
+  }
+}
+
+const byCreation = (a: StoredIntake, b: StoredIntake) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
+
+function encodeCursor(i: StoredIntake): string {
+  return Buffer.from(`${i.createdAt}:${i.id}`).toString("base64url")
+}
+
+function decodeCursor(cursor: string): [number, string] {
+  const match = /^([0-9]{1,15}):([A-Za-z0-9_]{1,64})$/.exec(Buffer.from(cursor, "base64url").toString())
+  if (!match) throw new AgentError("invalid", "cursor is not one this list gave", { hint: "Start again without a cursor" })
+  return [Number(match[1]), match[2]!]
+}
+
+/**
+ * How the entry seat reports and closes the item (RP-07 #9), the same in every harness: the OpenCode `hub` tool
+ * verb, the MCP tool (Claude Code, Codex) and the route. Nothing is inferred from idleness.
+ */
+export function reportingLines(teamID: string, intakeID: string): string[] {
+  return [
+    "Report progress and close this item explicitly — nothing is inferred from idleness or from replies (replies to this message do not reach the submitter):",
+    `- hub tool: {verb: "intake_update", team: "${teamID}", id: "${intakeID}", status: "in_progress"} (or "blocked"); when finished: status "done", or "failed" with reason: "<one line>"`,
+    `- MCP tool team_intake_update {team: "${teamID}", intake: "${intakeID}", status: in_progress|blocked|done|failed, reason?}`,
+    `- HTTP: POST /api/agent/teams/${teamID}/intake/${intakeID}/status {status, expectedRevision, reason?}`,
+  ]
+}