@huynle/hub 0.7.4 → 0.8.0

package/src/central/teams/staffing.ts

@@ -0,0 +1,888 @@
+// Team staffing (HWA-35; contract docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md, Teams and the
+// HWA-33/34/05/15 clarifications). Binds live sessions to the roles of a team so the team outlives any one session:
+// attach an existing session (any machine) or launch a new member per role through the launch API.
+//
+// Seats (TeamSeatStore, `team-seats`) stay the single source of team policy rights (HWA-34 reads them fresh per
+// send). This service adds, in its own collection `team-staffing` (one aggregate per team, key: team ID):
+// - the team's workspace link (`workspaceID`) and which workspace members it joined (`managed`: session → member);
+// - staffing launch requests (`launching` → `staffed` | `failed`) and their Idempotency-Keys.
+//
+// Team ↔ workspace (decision recorded in Brain, project hub): ONE workspace per team, created at the team's first
+// staffing (title = team title, metadata `{team: <team ID>}`) and linked here. Every session holding a current
+// seat is one workspace member (role `worker`; one member per session even with several roles in the team). The
+// entry role supervises: each non-entry member without a live supervision link is attached under the earliest
+// staffed entry member (SupervisionStore, HWA-05). Existing links are never rewritten (a user's rearrangement
+// stands); a departing entry member's links move to its replacement (memberDeparted replacedBy) or are detached and
+// re-attached under another entry member. The workspace master is not set (HWA-12 owns explicit master
+// replacement). A team archived workspace is left alone: staffing still works, membership sync pauses until the user
+// restores it. Several teams → several workspaces, so a session's bindings in one team never move when it is staffed
+// in another. Native parentID/rootID are never read or written here.
+//
+// Generations: re-staffing the same (role, session) is its next generation (TeamSeatStore). An explicit replacement
+// ends the old seat and gives the new session the slot's next generation (old + 1) in ONE version-checked write on
+// the seats aggregate, so the old member loses its team policy rights at that instant. Replacing by launch ends the
+// old seat at once (the role is vacant while the launch runs) and the launched session takes the next generation.
+//
+// Presence: seats survive member restarts and disconnects; only deletion (sessionEnded, wired from
+// Registry.onSessionDeleted) or an explicit unstaff/replace ends them. The roster reports each seat's presence
+// (online/offline/archived/deleted/unknown), vacancy, understaffing (below minMembers), launching counts and the
+// role profile's assignment and ack status as stored (HWA-15) — never assumed applied.
+//
+// Authority: team definitions and seats grant nothing. Users staff their own teams. Agents (apps and sessions) need
+// the existing grants of their user, checked and spent in the acting order (kill switch → grants usable → actions
+// spent → kill switch): attach and unstaff need a `roles` grant covering the session's project; a launch needs
+// scope `sessions:launch` (apps), a `launch` and a `roles` grant covering the repo, and — when the role names a
+// profile — scope `profiles:assign` (apps; sessions never pin profiles), exactly as POST /launches. A missing grant
+// answers `needs_user` with `extra.missing` (verb + directory) and is audited (verb team.staff / team.unstaff); no
+// grant is ever issued and no Decision is opened by staffing (an agent may ask through a grant request).
+//
+// Launch correlation: the launch carries labels `hub.team` and `hub.team.request` and the request ID as its launch
+// key. A launch change staffs only when a stored `launching` request of that team has this launch (and launcher):
+// labels alone never grant a seat. roster()/settle() re-check pending launches, so a change missed across a hub
+// restart is picked up on the next read.
+import { randomBytes } from "node:crypto"
+import {
+  CONTRACT_VERSION,
+  ID_PREFIXES,
+  IDEMPOTENCY_KEY,
+  IDEMPOTENCY_TTL_MS,
+  type IdKind,
+  isExpectedRevision,
+  TEAM_LIMITS,
+  type ProfileAckStatus,
+  type ProfileAssignment,
+} from "../../protocol"
+import type { ActingSwitch } from "../agent/acting-switch"
+import { auditOf } from "../agent/acting"
+import type { AgentActor } from "../agent/actor"
+import type { AgentAudit, AuditTarget } from "../agent/audit"
+import { partyFromActor } from "../agent/envelope"
+import { AgentError } from "../agent/errors"
+import type { AgentEvents, EventInput } from "../agent/events"
+import type { Grant, Grants } from "../agent/grants"
+import { canonicalBody } from "../agent/idempotency"
+import type { LaunchEngine } from "../agent/launch-engine"
+import { launchedBy } from "../agent/launch-routes"
+import { validateLaunchSpec } from "../agent/launch-spec"
+import type { Launch } from "../agent/launch-store"
+import { updateVersioned } from "../agent/versioned"
+import type { Clock, StateStore } from "../backend/types"
+import { memberJoinedEvent, memberLeftEvent, supervisionDepartedEvent, supervisionSetEvent, workspaceCreatedEvent } from "../workspaces/events"
+import type { MembershipStore, SessionPresence, SessionPresenceLookup } from "../workspaces/members"
+import type { WorkspaceStore } from "../workspaces/store"
+import type { SupervisionStore } from "../workspaces/supervision"
+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 { TEAM_STORE_LIMITS, type TeamRoleSpec } from "./validation"
+
+/** One aggregate per team (key: team ID): workspace link, managed members, launch requests, Idempotency-Keys. */
+export const TEAM_STAFFING = "team-staffing"
+/** Launch labels naming the team and the staffing request (never trusted alone). */
+export const TEAM_LAUNCH_LABEL = "hub.team"
+export const TEAM_REQUEST_LABEL = "hub.team.request"
+/** Finished (staffed/failed) launch requests kept per team. */
+export const FINISHED_REQUESTS_RETAINED = 50
+/** Live launch Idempotency-Keys kept per team. */
+const KEYS_PER_TEAM = 500
+const LAUNCH_FIELDS = new Set(["role", "launch"])
+const REPLACE_FIELDS = new Set(["expectedRevision", "sessionID", "launch"])
+
+export type StaffingRequestState = "launching" | "staffed" | "failed"
+
+/** A staffing launch: one new member for one role, launched through the launch API. */
+export interface StaffingRequest {
+  readonly id: string
+  readonly teamID: string
+  readonly role: string
+  readonly state: StaffingRequestState
+  /** The launcher (`user`, `app:<token>`, `ses_…`), as the launch records it. */
+  readonly by: string
+  readonly launchID?: string
+  /** A replacement: the ended seat and its generation (the new seat gets the next one). */
+  readonly replaces?: { readonly staffingID: string; readonly generation: number }
+  readonly sessionID?: string
+  readonly machineID?: string
+  readonly staffingID?: string
+  readonly reason?: string
+  readonly createdAt: number
+  readonly updatedAt: number
+}
+
+interface RequestKey {
+  readonly requestID: string
+  readonly digest: string
+  readonly at: number
+}
+
+interface StaffingDoc {
+  readonly v: 1
+  readonly teamID: string
+  readonly workspaceID?: string
+  /** Workspace members this service joined, by session (only these are departed by it). */
+  readonly managed: Readonly<Record<string, string>>
+  readonly requests: readonly StaffingRequest[]
+  readonly keys: Readonly<Record<string, RequestKey>>
+}
+
+/** The team's workspace as staffing sees it. */
+export interface TeamWorkspaceLink {
+  readonly id: string
+  readonly state: "active" | "archived" | "missing"
+}
+
+export interface SeatProfileStatus {
+  readonly requested: { readonly profileID: string; readonly version?: number }
+  readonly assigned?: { readonly profileID: string; readonly version: number }
+  /** The stored ack status of the session's assignment; `unassigned` when it has none. */
+  readonly status: ProfileAckStatus | "unassigned"
+  /** The assignment is the requested profile (and version, when the role pins one). */
+  readonly matches: boolean
+}
+
+export interface RosterSeat {
+  readonly staffing: TeamSeatRecord
+  readonly presence: SessionPresence
+  readonly memberID?: string
+  readonly supervisorMemberID?: string
+  readonly profile?: SeatProfileStatus
+}
+
+export interface RosterRole {
+  readonly role: string
+  readonly entry: boolean
+  readonly minMembers: number
+  readonly maxMembers: number
+  readonly seats: readonly RosterSeat[]
+  /** Launches still on their way to a session. */
+  readonly launching: number
+  readonly online: number
+  /** Seats whose session is not online now (offline, archived, deleted or unknown). */
+  readonly offline: number
+  readonly vacant: boolean
+  readonly understaffed: boolean
+}
+
+export interface TeamRoster {
+  readonly teamID: string
+  readonly version: number
+  readonly state: Team["state"]
+  readonly paused: boolean
+  readonly workspace?: TeamWorkspaceLink
+  readonly roles: readonly RosterRole[]
+  readonly requests: readonly StaffingRequest[]
+}
+
+export interface StaffResult {
+  readonly staffing: TeamSeatRecord
+  readonly created: boolean
+  readonly workspace?: TeamWorkspaceLink
+}
+
+export interface LaunchResult {
+  readonly request: StaffingRequest
+  readonly launch: Launch
+  readonly created: boolean
+}
+
+export interface ReplaceResult {
+  readonly ended: TeamSeatRecord
+  /** The replacement seat (attach). */
+  readonly staffing?: TeamSeatRecord
+  /** The replacement launch (launch). */
+  readonly request?: StaffingRequest
+  readonly launch?: Launch
+}
+
+export interface StaffingProfiles {
+  assignment(userID: string, sessionID: string): Promise<ProfileAssignment | undefined>
+  get(userID: string, id: string): Promise<{ readonly latestVersion: number } | undefined>
+}
+
+export interface TeamStaffingDeps {
+  readonly state: StateStore
+  readonly teams: TeamStore
+  readonly seats: TeamSeatStore
+  readonly workspaces: WorkspaceStore
+  readonly members: MembershipStore
+  readonly supervision: SupervisionStore
+  readonly presence: SessionPresenceLookup
+  /** 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">
+  readonly grants: Pick<Grants, "usable" | "consume">
+  readonly acting: Pick<ActingSwitch, "ensureActing">
+  readonly audit?: Pick<AgentAudit, "record">
+  readonly profiles?: StaffingProfiles
+  readonly events?: Pick<AgentEvents, "append">
+  readonly report?: (cause: unknown) => void
+  readonly now?: Clock
+  readonly newID?: (kind: IdKind) => string
+}
+
+interface Need {
+  readonly verb: "launch" | "roles"
+  readonly directory: string
+}
+
+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))
+
+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): StaffingDoc {
+  if (raw === undefined) return { v: 1, teamID, managed: {}, requests: [], keys: {} }
+  if (isObj(raw) && typeof raw.v === "number" && raw.v > CONTRACT_VERSION)
+    throw new AgentError("unsupported", `The staffing of team ${teamID} was written by a newer hub`, { hint: "Upgrade this hub", extra: { feature: TEAM_STAFFING } })
+  if (!isObj(raw) || raw.v !== CONTRACT_VERSION || raw.teamID !== teamID || !Array.isArray(raw.requests)) throw new AgentError("internal", `Stored staffing of team ${teamID} is malformed`)
+  return {
+    v: 1,
+    teamID,
+    ...(typeof raw.workspaceID === "string" ? { workspaceID: raw.workspaceID } : {}),
+    managed: isObj(raw.managed) ? (raw.managed as Record<string, string>) : {},
+    requests: raw.requests as StaffingRequest[],
+    keys: isObj(raw.keys) ? (raw.keys as Record<string, RequestKey>) : {},
+  }
+}
+
+/** Current seats plus the newest retained ended ones (as TeamSeatStore keeps them). */
+function retainedSeats(seats: readonly TeamSeatRecord[]): TeamSeatRecord[] {
+  const ended = seats.filter((s) => s.until !== undefined).sort((a, b) => b.until! - a.until! || (a.id < b.id ? 1 : -1))
+  const keep = new Set(ended.slice(0, TEAM_STORE_LIMITS.endedSeatsRetained).map((s) => s.id))
+  return seats.filter((s) => s.until === undefined || keep.has(s.id))
+}
+
+/** Pending requests plus the newest finished ones. */
+function retainedRequests(requests: readonly StaffingRequest[]): StaffingRequest[] {
+  const finished = requests.filter((r) => r.state !== "launching").sort((a, b) => b.updatedAt - a.updatedAt)
+  const keep = new Set(finished.slice(0, FINISHED_REQUESTS_RETAINED).map((r) => r.id))
+  return requests.filter((r) => r.state === "launching" || keep.has(r.id))
+}
+
+function roleOf(team: Team, role: unknown): TeamRoleSpec {
+  if (typeof role !== "string") throw new AgentError("invalid", "role must be a role name of the team")
+  const spec = team.roles.find((r) => r.name === role)
+  if (!spec) throw new AgentError("invalid", `Team ${team.name} has no role ${role.slice(0, 40)}`)
+  return spec
+}
+
+/** New members need an active, unpaused team. */
+function staffable(team: Team): void {
+  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`, { hint: "Resume it first" })
+}
+
+const roleLimit = (role: TeamRoleSpec) => Math.min(role.maxMembers ?? TEAM_LIMITS.sessionsPerRole, TEAM_LIMITS.sessionsPerRole)
+
+export class TeamStaffingService {
+  private readonly state: StateStore
+  private readonly now: Clock
+  private readonly newID: (kind: IdKind) => string
+  private readonly report: (cause: unknown) => void
+
+  constructor(private readonly deps: TeamStaffingDeps) {
+    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 staffing: ${message(cause)}`))
+  }
+
+  // ---------- staffing ----------
+
+  /** Staffs an existing session (any machine) in a role. The same current (role, session) returns its seat. */
+  async attach(userID: string, actor: AgentActor, teamID: string, input: unknown, options: { readonly idempotencyKey?: string } = {}): Promise<StaffResult> {
+    if (!isObj(input)) throw new AgentError("invalid", "body must be an object")
+    const team = await this.deps.teams.require(userID, teamID)
+    staffable(team)
+    roleOf(team, input.role)
+    const sessionID = await this.knownSession(userID, input.sessionID)
+    const needs = actor.kind === "user" ? [] : [{ verb: "roles" as const, directory: this.directoryOf(userID, sessionID) }]
+    const result = await this.authorized(userID, actor, "team.staff", needs, { sessionID }, () => this.deps.seats.staff(userID, teamID, input, options))
+    if (result.created) await this.emit(userID, teamStaffedEvent(result.staffing))
+    const workspace = await this.sync(userID, teamID)
+    return { ...result, ...(workspace ? { workspace } : {}) }
+  }
+
+  /** Launches a new member for a role through the launch API; the running session is staffed. */
+  async launch(userID: string, actor: AgentActor, teamID: string, input: unknown, options: { readonly idempotencyKey?: string } = {}): Promise<LaunchResult> {
+    if (!isObj(input)) throw new AgentError("invalid", "body must be an object")
+    unknownField(input, LAUNCH_FIELDS)
+    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)
+    staffable(team)
+    const role = roleOf(team, input.role)
+    const by = launchedBy(actor)
+    const digest = canonicalBody({ role: role.name, launch: input.launch })
+    if (key !== undefined) {
+      const held = await this.byKey(userID, teamID, key, digest, by)
+      if (held) return held
+    }
+    return this.launchFor(userID, actor, team, role, input.launch, { ...(key !== undefined ? { key: { key, digest } } : {}) })
+  }
+
+  /**
+   * Explicit replacement of a current seat (under its expected revision) by an existing session (`sessionID`) or a
+   * launch (`launch`). The old seat ends at once; the new member gets the slot's next generation.
+   */
+  async replace(userID: string, actor: AgentActor, teamID: string, staffingID: string, input: unknown): Promise<ReplaceResult> {
+    if (!isObj(input)) throw new AgentError("invalid", "body must be an object")
+    unknownField(input, REPLACE_FIELDS)
+    const { expectedRevision } = input
+    if (!isExpectedRevision(expectedRevision)) throw new AgentError("invalid", "expectedRevision is required (the revision you read)")
+    if ((input.sessionID === undefined) === (input.launch === undefined)) throw new AgentError("invalid", "Name either sessionID (an existing session) or launch (a new one)")
+    const team = await this.deps.teams.require(userID, teamID)
+    staffable(team)
+    const old = (await this.deps.seats.list(userID, teamID)).find((s) => s.id === staffingID)
+    if (!old) throw new AgentError("not_found", `No staffing ${staffingID} in team ${teamID}`)
+    if (old.revision !== expectedRevision)
+      throw new AgentError("conflict", `Staffing ${staffingID} changed since you read it (revision ${old.revision} now)`, { hint: "Read it again and retry", extra: { currentRevision: old.revision } })
+    if (old.until !== undefined) throw new AgentError("invalid", `Staffing ${staffingID} already ended`, { hint: "Staff the role instead" })
+    const role = roleOf(team, old.role)
+
+    if (input.launch !== undefined) {
+      const out = await this.launchFor(userID, actor, team, role, input.launch, { replaces: { old, expectedRevision } })
+      return { ended: out.ended!, request: out.request, launch: out.launch }
+    }
+    const sessionID = await this.knownSession(userID, input.sessionID)
+    if (sessionID === old.sessionID) throw new AgentError("invalid", `Session ${sessionID} already holds this seat`)
+    const needs = actor.kind === "user" ? [] : [{ verb: "roles" as const, directory: this.directoryOf(userID, sessionID) }]
+    const { ended, staffing } = await this.authorized(userID, actor, "team.staff", needs, { sessionID }, () =>
+      this.writeSeat(userID, team, role, sessionID, { end: { staffingID, expectedRevision } }),
+    )
+    await this.emit(userID, teamUnstaffedEvent(ended!), teamStaffedEvent(staffing))
+    await this.sync(userID, teamID, new Map([[old.sessionID, sessionID]]))
+    return { ended: ended!, staffing }
+  }
+
+  /** Ends a seat under its expected revision (an ended seat: no-op). */
+  async unstaff(userID: string, actor: AgentActor, teamID: string, staffingID: string, expectedRevision: number): Promise<TeamSeatRecord> {
+    const seat = (await this.deps.seats.list(userID, teamID)).find((s) => s.id === staffingID)
+    if (!seat) throw new AgentError("not_found", `No staffing ${staffingID} in team ${teamID}`)
+    const needs = actor.kind === "user" ? [] : [{ verb: "roles" as const, directory: this.directoryOf(userID, seat.sessionID) }]
+    const ended = await this.authorized(userID, actor, "team.unstaff", needs, { sessionID: seat.sessionID }, () => this.deps.seats.unstaff(userID, teamID, staffingID, expectedRevision))
+    if (seat.until === undefined && ended.until !== undefined) await this.emit(userID, teamUnstaffedEvent(ended))
+    await this.sync(userID, teamID)
+    return ended
+  }
+
+  /** The session was deleted: its seats end in every team; workspaces and supervision follow. */
+  async sessionEnded(userID: string, sessionID: string): Promise<TeamSeatRecord[]> {
+    const ended = await this.deps.seats.sessionEnded(userID, sessionID)
+    await this.emit(userID, ...ended.map(teamUnstaffedEvent))
+    for (const teamID of new Set(ended.map((s) => s.teamID))) {
+      try {
+        await this.sync(userID, teamID)
+      } catch (cause) {
+        this.report(cause)
+      }
+    }
+    return ended
+  }
+
+  // ---------- launches ----------
+
+  /** A launch changed (LaunchFeed): staffs the running session of a matching request, or fails an ended one. */
+  async launchChanged(userID: string, launch: Launch): Promise<void> {
+    const teamID = launch.spec.labels?.[TEAM_LAUNCH_LABEL]
+    const requestID = launch.spec.labels?.[TEAM_REQUEST_LABEL]
+    if (teamID === undefined || requestID === undefined || launch.owner !== userID) return
+    const raw = (await this.state.get(userID, TEAM_STAFFING, teamID))?.value
+    if (raw === undefined) return
+    const request = readDoc(raw, teamID).requests.find((r) => r.id === requestID)
+    if (!request || request.state !== "launching") return
+    const ours = (request.launchID ?? launch.id) === launch.id && launch.spec.key === request.id && (launch.by ?? "user") === request.by
+    if (!ours) return
+    if (launch.state === "running" && launch.sessionID !== undefined) {
+      await this.staffLaunched(userID, request, launch)
+    } else if (launch.state === "ended") {
+      await this.finish(userID, teamID, request.id, { state: "failed", reason: launch.reason || "The launch ended before its session was staffed" })
+    }
+  }
+
+  /** Re-checks the team's pending launches (a change missed across a restart is picked up here). */
+  async settle(userID: string, teamID: string): Promise<void> {
+    const doc = readDoc((await this.state.get(userID, TEAM_STAFFING, teamID))?.value, teamID)
+    for (const request of doc.requests.filter((r) => r.state === "launching" && r.launchID !== undefined)) {
+      const launch = await this.deps.launches.view(userID, request.launchID!)
+      if (launch) await this.launchChanged(userID, launch)
+      else await this.finish(userID, teamID, request.id, { state: "failed", reason: "The launch is no longer known" })
+    }
+  }
+
+  // ---------- reads ----------
+
+  /** The team's workspace ID (undefined before its first staffing). */
+  async workspaceOf(userID: string, teamID: string): Promise<string | undefined> {
+    return readDoc((await this.state.get(userID, TEAM_STAFFING, teamID))?.value, teamID).workspaceID
+  }
+
+  /** Roles with their seats, presence, vacancy, launches and profile status; settles pending launches first. */
+  async roster(userID: string, teamID: string): Promise<TeamRoster> {
+    const team = await this.deps.teams.require(userID, teamID)
+    await this.settle(userID, teamID)
+    const doc = readDoc((await this.state.get(userID, TEAM_STAFFING, teamID))?.value, teamID)
+    const current = await this.deps.seats.list(userID, teamID, { current: true })
+    const workspace = await this.link(userID, doc.workspaceID)
+    const memberOf = new Map<string, string>()
+    const supervisorOf = new Map<string, string>()
+    if (workspace?.state === "active" || workspace?.state === "archived") {
+      for (const { member } of await this.deps.members.members(userID, workspace.id)) memberOf.set(member.sessionID, member.id)
+      for (const { link, member, supervisor } of (await this.deps.supervision.graph(userID, workspace.id)).links)
+        if (member === "current" && supervisor === "current") supervisorOf.set(link.memberID, link.supervisorMemberID)
+    }
+    const presence = new Map<string, SessionPresence>()
+    for (const sessionID of new Set(current.map((s) => s.sessionID))) presence.set(sessionID, await this.deps.presence(userID, sessionID))
+    const roles: RosterRole[] = []
+    for (const role of team.roles) {
+      const seats: RosterSeat[] = []
+      for (const staffing of current.filter((s) => s.role === role.name)) {
+        const memberID = memberOf.get(staffing.sessionID)
+        const supervisorMemberID = memberID !== undefined ? supervisorOf.get(memberID) : undefined
+        const profile = role.profile ? await this.profileStatus(userID, staffing.sessionID, role.profile) : undefined
+        seats.push({
+          staffing,
+          presence: presence.get(staffing.sessionID)!,
+          ...(memberID !== undefined ? { memberID } : {}),
+          ...(supervisorMemberID !== undefined ? { supervisorMemberID } : {}),
+          ...(profile ? { profile } : {}),
+        })
+      }
+      const online = seats.filter((s) => s.presence === "online").length
+      const minMembers = role.minMembers ?? 0
+      roles.push({
+        role: role.name,
+        entry: role.name === team.entryRole,
+        minMembers,
+        maxMembers: roleLimit(role),
+        seats,
+        launching: doc.requests.filter((r) => r.role === role.name && r.state === "launching").length,
+        online,
+        offline: seats.length - online,
+        vacant: seats.length === 0,
+        understaffed: seats.length < minMembers,
+      })
+    }
+    return {
+      teamID,
+      version: team.version,
+      state: team.state,
+      paused: team.paused === true,
+      ...(workspace ? { workspace } : {}),
+      roles,
+      requests: [...doc.requests].sort((a, b) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : 1)),
+    }
+  }
+
+  // ---------- internals: launches ----------
+
+  private async launchFor(
+    userID: string,
+    actor: AgentActor,
+    team: Team,
+    role: TeamRoleSpec,
+    base: unknown,
+    options: { readonly key?: { readonly key: string; readonly digest: string }; readonly replaces?: { readonly old: TeamSeatRecord; readonly expectedRevision: number } },
+  ): Promise<LaunchResult & { ended?: TeamSeatRecord }> {
+    if (actor.kind === "app" && !actor.scopes.includes("sessions:launch")) throw new AgentError("forbidden", "Staffing by launch needs scope sessions:launch")
+    const requestID = `tsr_${randomBytes(12).toString("hex")}`
+    const spec = await this.launchSpec(userID, team, role, base, requestID)
+    if (spec.agentProfile !== undefined && actor.kind !== "user" && !(actor.kind === "app" && actor.scopes.includes("profiles:assign")))
+      throw new AgentError("forbidden", "A launch's agentProfile needs scope profiles:assign; sessions cannot pin profiles", { hint: "Ask the user to staff this role" })
+    const repo = (spec.workspace as { repo: string }).repo
+    if (!options.replaces) await this.checkRoom(userID, team, role)
+    const by = launchedBy(actor)
+    const needs: Need[] = actor.kind === "user" ? [] : [{ verb: "launch", directory: repo }, { verb: "roles", directory: repo }]
+    return this.authorized(userID, actor, "team.staff", needs, {}, async () => {
+      let ended: TeamSeatRecord | undefined
+      if (options.replaces) {
+        ended = await this.deps.seats.unstaff(userID, team.id, options.replaces.old.id, options.replaces.expectedRevision)
+        await this.emit(userID, teamUnstaffedEvent(ended))
+        await this.sync(userID, team.id)
+      }
+      const at = this.now()
+      const request: StaffingRequest = {
+        id: requestID,
+        teamID: team.id,
+        role: role.name,
+        state: "launching",
+        by,
+        ...(options.replaces ? { replaces: { staffingID: options.replaces.old.id, generation: options.replaces.old.generation } } : {}),
+        createdAt: at,
+        updatedAt: at,
+      }
+      await this.writeDoc(userID, team.id, (doc) => {
+        if (!options.replaces && doc.requests.filter((r) => r.role === role.name && r.state === "launching").length >= roleLimit(role))
+          throw new AgentError("rate_limited", `Role ${role.name} of team ${team.name} holds at most ${roleLimit(role)} sessions`, { extra: { limit: roleLimit(role) } })
+        const live = this.liveKeys(doc)
+        if (options.key && live[options.key.key])
+          throw new AgentError("rate_limited", `The staffing for Idempotency-Key ${options.key.key} is still being launched`, { extra: { retryAfter: 1 } })
+        const keys = options.key ? { ...live, [options.key.key]: { requestID, digest: options.key.digest, at } } : doc.keys
+        return { ...doc, requests: retainedRequests([...doc.requests, request]), keys: this.boundedKeys(keys) }
+      })
+      let accepted: { launch: Launch; created: boolean }
+      try {
+        accepted = await this.deps.launches.accept(userID, spec, { by })
+      } catch (cause) {
+        await this.finish(userID, team.id, requestID, { state: "failed", reason: message(cause) })
+        throw cause
+      }
+      const stored = await this.finish(userID, team.id, requestID, { launchID: accepted.launch.id })
+      if (accepted.launch.state === "running" || accepted.launch.state === "ended") await this.launchChanged(userID, accepted.launch)
+      return { request: stored ?? { ...request, launchID: accepted.launch.id }, launch: accepted.launch, created: true, ...(ended ? { ended } : {}) }
+    })
+  }
+
+  /** The launch body: the caller's, with the role's placement/harness/model/profile defaults and team labels. */
+  private async launchSpec(userID: string, team: Team, role: TeamRoleSpec, base: unknown, requestID: string): Promise<Record<string, unknown>> {
+    if (!isObj(base)) throw new AgentError("invalid", "launch must be a launch body (workspace, prompt, …)")
+    if (base.key !== undefined) throw new AgentError("invalid", "launch.key is set by staffing", { hint: "Send an Idempotency-Key header instead" })
+    const labels = isObj(base.labels) ? base.labels : base.labels === undefined ? {} : undefined
+    if (!labels) throw new AgentError("invalid", "launch.labels must be an object")
+    if (TEAM_LAUNCH_LABEL in labels || TEAM_REQUEST_LABEL in labels) throw new AgentError("invalid", `launch.labels ${TEAM_LAUNCH_LABEL} and ${TEAM_REQUEST_LABEL} are set by staffing`)
+    const prefs = role.prefs ?? {}
+    const placement = isObj(base.placement) ? base.placement : base.placement === undefined ? {} : undefined
+    if (!placement) throw new AgentError("invalid", "launch.placement must be an object")
+    const machine = placement.machine ?? prefs.machineID
+    const harness = base.harness ?? prefs.harness
+    const model = base.model ?? prefs.model
+    const agentProfile = base.agentProfile ?? (role.profile ? await this.profileRef(userID, role.profile) : undefined)
+    const spec: Record<string, unknown> = {
+      ...base,
+      key: requestID,
+      ...(harness !== undefined ? { harness } : {}),
+      ...(model !== undefined ? { model } : {}),
+      ...(machine !== undefined || base.placement !== undefined ? { placement: { ...placement, ...(machine !== undefined ? { machine } : {}) } } : {}),
+      ...(agentProfile !== undefined ? { agentProfile } : {}),
+      labels: { ...labels, [TEAM_LAUNCH_LABEL]: team.id, [TEAM_REQUEST_LABEL]: requestID },
+    }
+    validateLaunchSpec(spec)
+    return spec
+  }
+
+  /** The role's profile as a launch pins it: its version, or the profile's latest. */
+  private async profileRef(userID: string, profile: NonNullable<TeamRoleSpec["profile"]>): Promise<{ profileID: string; version: number }> {
+    if (profile.version !== undefined) return { profileID: profile.profileID, version: profile.version }
+    const found = await this.deps.profiles?.get(userID, profile.profileID)
+    if (!found) throw new AgentError("invalid", `The role's profile ${profile.profileID} is not available`, { hint: "Fix the team's role profile, or name launch.agentProfile" })
+    return { profileID: profile.profileID, version: found.latestVersion }
+  }
+
+  /** 429 when the role's current seats and pending launches reach its maxMembers. */
+  private async checkRoom(userID: string, team: Team, role: TeamRoleSpec): Promise<void> {
+    const seats = (await this.deps.seats.list(userID, team.id, { current: true })).filter((s) => s.role === role.name).length
+    const doc = readDoc((await this.state.get(userID, TEAM_STAFFING, team.id))?.value, team.id)
+    const launching = doc.requests.filter((r) => r.role === role.name && r.state === "launching").length
+    if (seats + launching >= roleLimit(role))
+      throw new AgentError("rate_limited", `Role ${role.name} of team ${team.name} holds at most ${roleLimit(role)} sessions (staffed and launching)`, {
+        hint: "Unstaff or replace a member instead",
+        extra: { limit: roleLimit(role) },
+      })
+  }
+
+  /** The request a live Idempotency-Key names (same launcher and body), with its launch. */
+  private async byKey(userID: string, teamID: string, key: string, digest: string, by: string): Promise<LaunchResult | undefined> {
+    const doc = readDoc((await this.state.get(userID, TEAM_STAFFING, teamID))?.value, teamID)
+    const held = this.liveKeys(doc)[key]
+    if (!held) return undefined
+    const request = doc.requests.find((r) => r.id === held.requestID)
+    if (!request) return undefined
+    if (request.by !== by) throw new AgentError("invalid", "This key was used by another launcher", { hint: "Use a key of your own" })
+    if (held.digest !== digest) throw new AgentError("conflict", `Idempotency-Key ${key} was used for another staffing`, { hint: "Use a new key for a different body" })
+    const launch = request.launchID !== undefined ? await this.deps.launches.view(userID, request.launchID) : undefined
+    if (!launch) throw new AgentError("rate_limited", `The staffing for Idempotency-Key ${key} is still being launched`, { extra: { retryAfter: 1 } })
+    return { request, launch, created: false }
+  }
+
+  private async staffLaunched(userID: string, request: StaffingRequest, launch: Launch): Promise<void> {
+    const sessionID = launch.sessionID!
+    const where = { sessionID, ...(launch.machineID !== undefined ? { machineID: launch.machineID } : {}) }
+    let staffing: TeamSeatRecord
+    let created: boolean
+    try {
+      const team = await this.deps.teams.require(userID, request.teamID)
+      if (request.replaces) {
+        staffable(team)
+        const out = await this.writeSeat(userID, team, roleOf(team, request.role), sessionID, { minGeneration: request.replaces.generation + 1 })
+        staffing = out.staffing
+        created = out.created
+      } else {
+        const out = await this.deps.seats.staff(userID, request.teamID, { role: request.role, sessionID })
+        staffing = out.staffing
+        created = out.created
+      }
+    } catch (cause) {
+      if (!(cause instanceof AgentError)) throw cause
+      await this.finish(userID, request.teamID, request.id, { state: "failed", reason: `The launched session was not staffed: ${cause.message}`, ...where })
+      return
+    }
+    const finished = await this.finish(userID, request.teamID, request.id, { state: "staffed", staffingID: staffing.id, ...where })
+    if (created && finished) await this.emit(userID, teamStaffedEvent(staffing))
+    await this.sync(userID, request.teamID)
+  }
+
+  /** Moves a launching request on (state, launch, session); undefined when it is no longer launching. */
+  private async finish(userID: string, teamID: string, requestID: string, change: Partial<StaffingRequest>): Promise<StaffingRequest | undefined> {
+    let out: StaffingRequest | undefined
+    await this.writeDoc(userID, teamID, (doc) => {
+      const request = doc.requests.find((r) => r.id === requestID)
+      if (!request || request.state !== "launching") return undefined
+      out = { ...request, ...change, updatedAt: this.now() }
+      return { ...doc, requests: retainedRequests(doc.requests.map((r) => (r.id === requestID ? out! : r))) }
+    })
+    return out
+  }
+
+  // ---------- internals: seats ----------
+
+  /**
+   * One version-checked write on the team's seats: optionally ends a seat (replacement) and staffs the session with
+   * at least `minGeneration` (and above its own earlier generations in the role). An existing current seat of the
+   * (role, session) is returned as is.
+   */
+  private async writeSeat(
+    userID: string,
+    team: Team,
+    role: TeamRoleSpec,
+    sessionID: string,
+    options: { readonly end?: { readonly staffingID: string; readonly expectedRevision: number }; readonly minGeneration?: number },
+  ): Promise<{ staffing: TeamSeatRecord; created: boolean; ended?: TeamSeatRecord }> {
+    let result: { staffing: TeamSeatRecord; created: boolean; ended?: TeamSeatRecord } | undefined
+    await updateVersioned<SeatsDoc>(this.state, userID, TEAM_SEATS, team.id, (raw) => {
+      const doc = readSeatsDoc(raw, team.id)
+      let seats = [...((doc?.seats ?? []) as TeamSeatRecord[])]
+      const at = this.now()
+      let ended: TeamSeatRecord | undefined
+      let floor = options.minGeneration ?? 1
+      if (options.end) {
+        const old = seats.find((s) => s.id === options.end!.staffingID)
+        if (!old) throw new AgentError("not_found", `No staffing ${options.end.staffingID} in team ${team.id}`)
+        if (old.revision !== options.end.expectedRevision)
+          throw new AgentError("conflict", `Staffing ${old.id} changed since you read it (revision ${old.revision} now)`, { hint: "Read it again and retry", extra: { currentRevision: old.revision } })
+        if (old.until !== undefined) throw new AgentError("invalid", `Staffing ${old.id} already ended`, { hint: "Staff the role instead" })
+        ended = { ...old, until: at, revision: old.revision + 1 }
+        seats = seats.map((s) => (s.id === old.id ? ended! : s))
+        floor = Math.max(floor, old.generation + 1)
+      }
+      const current = seats.filter((s) => s.until === undefined)
+      const same = current.find((s) => s.role === role.name && s.sessionID === sessionID)
+      if (same) {
+        if (ended) throw new AgentError("invalid", `Session ${sessionID} already holds role ${role.name}`, { hint: "Unstaff the other seat instead" })
+        result = { staffing: same, created: false }
+        return undefined
+      }
+      if (current.filter((s) => s.role === role.name).length >= roleLimit(role))
+        throw new AgentError("rate_limited", `Role ${role.name} of team ${team.name} holds at most ${roleLimit(role)} sessions`, { extra: { limit: roleLimit(role) } })
+      const generation = Math.max(floor, 1 + Math.max(0, ...seats.filter((s) => s.role === role.name && s.sessionID === sessionID).map((s) => s.generation)))
+      const staffing: TeamSeatRecord = { v: 1, id: this.newID("staffing"), teamID: team.id, role: role.name, sessionID, generation, since: at, revision: 1, teamVersion: team.version }
+      result = { staffing, created: true, ...(ended ? { ended } : {}) }
+      return { v: 1, teamID: team.id, seats: retainedSeats([...seats, staffing]), keys: doc?.keys ?? {} }
+    })
+    return result!
+  }
+
+  // ---------- internals: workspace and supervision ----------
+
+  /**
+   * Brings the team's workspace in line with its current seats: creates/links it on first staffing, joins seated
+   * sessions, departs sessions this service joined that hold no seat any more (links move to `replacements`), and
+   * attaches unsupervised non-entry members under the earliest entry member. Archived workspace: left alone.
+   */
+  private async sync(userID: string, teamID: string, replacements: ReadonlyMap<string, string> = new Map()): Promise<TeamWorkspaceLink | undefined> {
+    const team = await this.deps.teams.get(userID, teamID)
+    if (!team) return undefined
+    const current = await this.deps.seats.list(userID, teamID, { current: true })
+    const doc = readDoc((await this.state.get(userID, TEAM_STAFFING, teamID))?.value, teamID)
+    let link = await this.link(userID, doc.workspaceID)
+    if (!link || link.state === "missing") {
+      if (current.length === 0) return link
+      link = await this.createWorkspace(userID, team)
+    }
+    if (link.state !== "active") return link
+    const workspaceID = link.id
+    const seated = [...new Set(current.map((s) => s.sessionID))]
+    const entries = [...new Set(current.filter((s) => s.role === team.entryRole).map((s) => s.sessionID))]
+    const memberOf = new Map((await this.deps.members.members(userID, workspaceID)).map((m) => [m.member.sessionID, m.member.id]))
+    const added: Record<string, string> = {}
+    const removed = new Set<string>()
+    for (const sessionID of seated) {
+      if (memberOf.has(sessionID)) continue
+      try {
+        const { member, created } = await this.deps.members.join(userID, workspaceID, { sessionID, role: "worker" })
+        memberOf.set(sessionID, member.id)
+        if (created) {
+          added[sessionID] = member.id
+          await this.emit(userID, memberJoinedEvent(member))
+        }
+      } catch (cause) {
+        this.report(cause)
+      }
+    }
+    const seatedSet = new Set(seated)
+    for (const [sessionID, memberID] of Object.entries(doc.managed)) {
+      if (seatedSet.has(sessionID)) continue
+      removed.add(sessionID)
+      try {
+        const before = await this.deps.members.member(userID, workspaceID, memberID).catch(() => undefined)
+        const left = before ? await this.deps.members.leave(userID, workspaceID, memberID, { reason: "removed" }) : undefined
+        const next = replacements.get(sessionID)
+        const replacedBy = next !== undefined ? memberOf.get(next) : undefined
+        const departed = await this.deps.supervision.memberDeparted(userID, workspaceID, memberID, replacedBy !== undefined ? { replacedBy } : {})
+        if (left && before && left.revision !== before.revision) await this.emit(userID, memberLeftEvent(left))
+        if (departed.detached + departed.transferred + departed.pruned > 0) await this.emit(userID, supervisionDepartedEvent(memberID, departed))
+        memberOf.delete(sessionID)
+      } catch (cause) {
+        this.report(cause)
+      }
+    }
+    const supervisor = entries.map((s) => memberOf.get(s)).find((m) => m !== undefined)
+    if (supervisor !== undefined) {
+      const graph = await this.deps.supervision.graph(userID, workspaceID)
+      const supervised = new Set(graph.links.filter((l) => l.member === "current" && l.supervisor === "current").map((l) => l.link.memberID))
+      const entrySet = new Set(entries)
+      for (const sessionID of seated) {
+        const memberID = memberOf.get(sessionID)
+        if (entrySet.has(sessionID) || memberID === undefined || supervised.has(memberID)) continue
+        try {
+          const result = await this.deps.supervision.set(userID, workspaceID, { memberID, supervisorMemberID: supervisor })
+          if (result.change !== "unchanged") await this.emit(userID, supervisionSetEvent(memberID, result, result.link))
+        } catch (cause) {
+          this.report(cause)
+        }
+      }
+    }
+    if (Object.keys(added).length > 0 || removed.size > 0) {
+      await this.writeDoc(userID, teamID, (d) => {
+        const managed = { ...d.managed, ...added }
+        for (const sessionID of removed) delete managed[sessionID]
+        return { ...d, managed }
+      })
+    }
+    return link
+  }
+
+  private async createWorkspace(userID: string, team: Team): Promise<TeamWorkspaceLink> {
+    const body = { title: team.title, metadata: { team: team.id } }
+    let created: Awaited<ReturnType<WorkspaceStore["create"]>>
+    try {
+      created = await this.deps.workspaces.create(userID, body, { idempotencyKey: `team-workspace:${team.id}` })
+    } catch (cause) {
+      // The key was used with an older title (a crash before the link was written): create without it.
+      if (!(cause instanceof AgentError) || cause.code !== "conflict") throw cause
+      created = await this.deps.workspaces.create(userID, body)
+    }
+    let linked = created.workspace.id
+    await this.writeDoc(userID, team.id, (doc) => {
+      if (doc.workspaceID !== undefined && doc.workspaceID !== created.workspace.id) {
+        linked = doc.workspaceID
+        return undefined
+      }
+      return doc.workspaceID === created.workspace.id ? undefined : { ...doc, workspaceID: created.workspace.id }
+    })
+    if (linked === created.workspace.id && created.created) await this.emit(userID, workspaceCreatedEvent(created.workspace))
+    return (await this.link(userID, linked)) ?? { id: linked, state: "missing" }
+  }
+
+  private async link(userID: string, workspaceID: string | undefined): Promise<TeamWorkspaceLink | undefined> {
+    if (workspaceID === undefined) return undefined
+    const workspace = await this.deps.workspaces.get(userID, workspaceID)
+    return { id: workspaceID, state: workspace ? workspace.state : "missing" }
+  }
+
+  // ---------- internals: authority, profiles, storage ----------
+
+  /** A session the user's directory knows (unknown/deleted: not_found); returns its ID. */
+  private async knownSession(userID: string, sessionID: unknown): Promise<string> {
+    if (typeof sessionID !== "string" || sessionID.length === 0 || sessionID.length > 200) throw new AgentError("invalid", "sessionID must be a session ID")
+    const presence = await this.deps.presence(userID, sessionID)
+    if (presence === "unknown" || presence === "deleted") throw new AgentError("not_found", `No session ${sessionID}`)
+    return sessionID
+  }
+
+  /** The session's project for a grant check; offline when no spoke reports it (as role writes answer). */
+  private directoryOf(userID: string, sessionID: string): string {
+    const directory = this.deps.sessionDirectory(userID, sessionID)
+    if (directory === undefined) throw new AgentError("offline", "No spoke reports this session now, so its project cannot be checked against a grant")
+    return directory
+  }
+
+  /**
+   * Runs `run` for the caller. Agents: kill switch → every needed grant usable (else needs_user listing the missing
+   * ones; nothing issued, nothing escalated) → one action spent per grant → kill switch again. Audited.
+   */
+  private async authorized<T>(userID: string, actor: AgentActor, verb: string, needs: readonly Need[], target: AuditTarget, run: () => Promise<T>): Promise<T> {
+    const used: Grant[] = []
+    const record = async (decision: ReturnType<typeof auditOf>[0], outcome: ReturnType<typeof auditOf>[1], reason?: string) => {
+      await this.deps.audit
+        ?.record(userID, { actor: partyFromActor(actor), verb, target, ...(used[0] ? { grant: used[0].id } : {}), decision, ...(reason ? { reason } : {}), outcome })
+        .catch(this.report)
+    }
+    try {
+      if (actor.kind !== "user") {
+        this.deps.acting.ensureActing(userID)
+        const missing: Need[] = []
+        const found: Grant[] = []
+        for (const need of needs) {
+          const usable = await this.deps.grants.usable(actor, need.verb, { directory: need.directory })
+          if (usable.length === 0) missing.push(need)
+          else found.push(usable[0]!)
+        }
+        if (missing.length > 0)
+          throw new AgentError("needs_user", `Needs the user: no grant lets this ${actor.kind} ${missing.map((m) => `${m.verb} in ${m.directory}`).join(" or ")}`, {
+            hint: "The user staffs this role, or grants the missing verbs (an agent may ask with a grant request); staffing never issues grants",
+            extra: { missing },
+          })
+        for (const grant of found) {
+          await this.deps.grants.consume(grant)
+          used.push(grant)
+        }
+        this.deps.acting.ensureActing(userID)
+      }
+      const result = await run()
+      await record("allow", "ok")
+      return result
+    } catch (cause) {
+      const [decision, outcome] = auditOf(cause)
+      await record(decision, outcome, message(cause))
+      throw cause
+    }
+  }
+
+  private async profileStatus(userID: string, sessionID: string, requested: NonNullable<TeamRoleSpec["profile"]>): Promise<SeatProfileStatus> {
+    const want = { profileID: requested.profileID, ...(requested.version !== undefined ? { version: requested.version } : {}) }
+    const assigned = await this.deps.profiles?.assignment(userID, sessionID)
+    if (!assigned) return { requested: want, status: "unassigned", matches: false }
+    return {
+      requested: want,
+      assigned: { profileID: assigned.profileID, version: assigned.version },
+      status: assigned.ack?.status ?? "pending",
+      matches: assigned.profileID === requested.profileID && (requested.version === undefined || requested.version === assigned.version),
+    }
+  }
+
+  private async writeDoc(userID: string, teamID: string, change: (doc: StaffingDoc) => StaffingDoc | undefined): Promise<void> {
+    await updateVersioned<StaffingDoc>(this.state, userID, TEAM_STAFFING, teamID, (raw) => change(readDoc(raw, teamID)))
+  }
+
+  private liveKeys(doc: StaffingDoc): Record<string, RequestKey> {
+    const now = this.now()
+    const out: Record<string, RequestKey> = {}
+    for (const [k, v] of Object.entries(doc.keys)) if (isObj(v) && typeof v.at === "number" && now - v.at < IDEMPOTENCY_TTL_MS) out[k] = v
+    return out
+  }
+
+  private boundedKeys(keys: Readonly<Record<string, RequestKey>>): Record<string, RequestKey> {
+    const entries = Object.entries(keys)
+    if (entries.length <= KEYS_PER_TEAM) return { ...keys }
+    return Object.fromEntries(entries.sort((a, b) => b[1].at - a[1].at).slice(0, KEYS_PER_TEAM))
+  }
+
+  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)
+  }
+}