@huynle/hub 0.7.4 → 0.8.0

package/src/central/workspaces/master.ts

@@ -0,0 +1,490 @@
+// Explicit master replacement and lifetime recovery (HWA-12; contract: Workspaces `POST /workspaces/:id/master
+// {sessionID, expectedRevision}` in docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md and its
+// clarifications from HWA-04, HWA-05, HWA-06 and HWA-11).
+//
+// What a replacement does, in this order:
+//   1. Checks the workspace record's `expectedRevision` (stale: 409 conflict with currentRevision) and takes the
+//      workspace's replacement fence: one record per workspace in the StateStore collection `workspace-master`,
+//      claimed by a version-checked write. Of two concurrent replacements exactly one holds the fence; the other is
+//      a 409 conflict. After the claim the workspace revision is checked again, so a replacement that finished
+//      between the first read and the claim fences the late one out as well.
+//   2. MembershipStore.join(…, {allowMaster, replaces}): ONE write of the members aggregate departs the old master
+//      as `replaced` and adds the new master member with the old generation + 1 (no current master: one more than
+//      any earlier master of the workspace, so the master slot's generation never goes back).
+//   3. WorkspaceStore.setMaster(new member) under the expected revision: the commit point. Steps 2 and 3 are two
+//      records (the StateStore has no cross-record transactions), so the fence records the new member before step
+//      3. A crash or a lost race (an unrelated PATCH moved the revision) rolls FORWARD: the master record is set to
+//      the already joined member under a fresh read, as long as it still names the old master or nobody. Nothing
+//      is undone, because the old membership is already departed.
+//   4. SupervisionStore.memberDeparted(old, {replacedBy: new}) AFTER masterMemberID names the new member, so the
+//      old master's supervised members move to the new one and the new master never ends up with a supervisor.
+//   5. Releases the fence, flushes the StateStore; the route appends compact events: `workspace.member.left`
+//      (replaced), `workspace.member.joined`, `workspace.master.replaced` (IDs, generations, revisions, counts).
+// A fence whose holder crashed is finished (rolled forward or released) by the next replacement or read once it is
+// older than MASTER_FENCE_MS; until then a replacement is a 409 conflict with a retry hint.
+//
+// Fencing an old master: member IDs are minted per generation, so everything keyed by the old master member (its
+// checkpoints, its digest ledger, its supervision links) stops applying the moment it departs: checkpoint acks
+// naming it are refused (it left), the coordinator revokes its ledger on its next pass, and assertMaster() refuses
+// anything that names a master member or generation that is no longer current (409 conflict with the current one).
+//
+// Board and checkpoint continuity: the board is derived from live records, so it simply shows the new master.
+// Checkpoints stay per supervisor member and generation: the new master does NOT inherit the old master's
+// checkpoint cursor. A cursor acknowledges what one session processed; the new session has not seen those events,
+// so the coordinator starts it with a fresh snapshot (members, presence, unresolved assignments, revisions). The old
+// master's checkpoints are kept (GET …/checkpoints?supervisorMemberID=<old>) and the replacement answer carries the
+// old master's latest one (`checkpoints.previousCheckpoint`, without the internal journal position).
+//
+// Grants: none move. Grants held by or given to the old master's session stay exactly as they are; the new master's
+// session needs its own explicit grants (the answer says so in `grants`). Membership and the master role grant
+// nothing. Native parentID/rootID are never touched.
+//
+// Sessions and harness restarts: the new master may be any session the user's directory knows, online or offline
+// (presence is reported, never hidden); an unknown session is not_found and a deleted one invalid. The old
+// master's presence never blocks a replacement (an offline or vanished master can always be replaced by the user).
+// A harness that resumes the same session (same session ID) keeps its membership: nothing to replace. A restart that
+// makes a new session (Claude Code and Codex cannot resume a lost process as the same session) cannot own the
+// workspace's lifetime: when the old session is deleted the hub departs it (`ended`) and the workspace stays,
+// without a master, until the user replaces it. `launchID` instead of `sessionID` names the session of one of the
+// user's running launches (the existing launch API starts it under its own authority; nothing is launched here).
+//
+// Rollback: older hubs never read `workspace-master`; workspace and member records keep their shapes.
+import { randomBytes } from "node:crypto"
+import { CONTRACT_VERSION, type HubWorkspace, isExpectedRevision, WORKSPACE_SCOPES, type WorkspaceMember } from "../../protocol"
+import type { AgentContext, AgentRoute } from "../agent/routes"
+import type { AgentEvents, EventInput } from "../agent/events"
+import { AgentError } from "../agent/errors"
+import { idempotencyKeyOf, RouteIdempotency } from "../agent/idempotency"
+import type { Clock, StateStore } from "../backend/types"
+import type { CheckpointStore, StoredCheckpoint } from "./checkpoints"
+import { memberJoinedEvent, memberLeftEvent, supervisionDepartedEvent } from "./events"
+import { type MembershipStore, SESSION_ID, type SessionPresence } from "./members"
+import { WORKSPACE_ROUTE_IDEMPOTENCY } from "./routes"
+import type { WorkspaceStore } from "./store"
+import type { DepartureResult, SupervisionStore } from "./supervision"
+import { AGENT_JSON_BODY_MAX, boundedText } from "../agent/body"
+
+export const WORKSPACE_MASTER = "workspace-master"
+/** A replacement fence older than this belongs to a crashed holder and is finished by the next caller. */
+export const MASTER_FENCE_MS = 60_000
+/** Earlier masters listed by GET /workspaces/:id/master. */
+export const PREVIOUS_MASTERS_MAX = 10
+const ATTEMPTS = 16
+const LAUNCH_ID = /^[A-Za-z0-9_-]{1,128}$/
+
+export const GRANTS_NOTE = "Grants are not transferred: grants held by or given to the previous master stay as they are; the new master's session needs its own explicit grants."
+
+/** The launch API's read (LaunchEngine.view). */
+export interface MasterLaunches {
+  view(userID: string, id: string): Promise<{ readonly state: string; readonly sessionID?: string } | undefined>
+}
+
+export interface MasterStoreDeps {
+  readonly state: StateStore
+  readonly workspaces: WorkspaceStore
+  readonly members: MembershipStore
+  readonly supervision: SupervisionStore
+  readonly checkpoints?: Pick<CheckpointStore, "latest">
+  readonly launches?: MasterLaunches
+  readonly now?: Clock
+  readonly newOpID?: () => string
+}
+
+/** The replacement fence of one workspace. `phase: "done"` is a released fence (kept so versions only grow). */
+interface Fence {
+  readonly v: 1
+  readonly workspaceID: string
+  readonly opID: string
+  readonly phase: "claimed" | "joined" | "done"
+  readonly at: number
+  readonly sessionID: string
+  readonly previousMemberID?: string
+  readonly newMemberID?: string
+}
+type HeldFence = Fence & { readonly version: number }
+
+export type PublicCheckpoint = Omit<StoredCheckpoint, "position">
+
+export interface MasterReplacement {
+  readonly workspace: HubWorkspace
+  readonly master: WorkspaceMember
+  readonly presence: SessionPresence
+  readonly previous?: WorkspaceMember
+  readonly previousPresence?: SessionPresence
+  /** False when the session already was the current master (nothing changed). */
+  readonly changed: boolean
+  /** The old master's links, moved to the new master or detached. */
+  readonly supervision?: DepartureResult
+  /** The new master starts from a fresh snapshot; the old master's latest checkpoint for reference. */
+  readonly checkpoints: { readonly inherited: false; readonly previousCheckpoint?: PublicCheckpoint }
+  readonly grants: { readonly transferred: false; readonly note: string }
+}
+
+export interface MasterView {
+  readonly workspaceID: string
+  readonly revision: number
+  readonly master?: { readonly member: WorkspaceMember; readonly presence: SessionPresence }
+  /** Earlier masters, newest first (bounded). */
+  readonly previous: readonly { readonly member: WorkspaceMember; readonly presence: SessionPresence }[]
+  /** A replacement in flight (or one a crashed holder left behind: `stale`). */
+  readonly pending?: { readonly phase: "claimed" | "joined"; readonly at: number; readonly stale: boolean }
+}
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+const conflict = (message: string, extra: Record<string, unknown>, hint = "Read the workspace again and retry with its current revision") =>
+  new AgentError("conflict", message, { hint, extra })
+
+const revisionConflict = (workspace: HubWorkspace) =>
+  conflict(`Workspace ${workspace.id} changed since you read it (revision ${workspace.revision} now)`, { currentRevision: workspace.revision })
+
+const publicCheckpoint = ({ position: _position, ...rest }: StoredCheckpoint): PublicCheckpoint => rest
+
+const isConflict = (error: unknown) => error instanceof AgentError && error.code === "conflict"
+
+function readFence(raw: unknown, workspaceID: string): Fence | undefined {
+  if (raw === undefined) return undefined
+  if (isObj(raw) && typeof raw.v === "number" && raw.v > CONTRACT_VERSION)
+    throw new AgentError("unsupported", `Workspace ${workspaceID} master state was written by a newer hub`, { hint: "Upgrade this hub", extra: { feature: WORKSPACE_MASTER } })
+  if (!isObj(raw) || raw.v !== CONTRACT_VERSION || raw.workspaceID !== workspaceID || typeof raw.opID !== "string") throw new AgentError("internal", "Stored workspace master state is malformed")
+  return raw as unknown as Fence
+}
+
+export class MasterStore {
+  private readonly now: Clock
+  private readonly newOpID: () => string
+
+  constructor(private readonly deps: MasterStoreDeps) {
+    this.now = deps.now ?? Date.now
+    this.newOpID = deps.newOpID ?? (() => `mop_${randomBytes(10).toString("hex")}`)
+  }
+
+  /**
+   * Replaces (or first sets) the workspace's master: `{sessionID | launchID, expectedRevision}` where
+   * expectedRevision is the workspace record's revision. See the header for the steps and their guarantees.
+   */
+  async replace(userID: string, workspaceID: string, input: unknown): Promise<MasterReplacement> {
+    if (!isObj(input)) throw new AgentError("invalid", "body must be an object")
+    for (const key of Object.keys(input))
+      if (!["sessionID", "launchID", "expectedRevision"].includes(key)) throw new AgentError("invalid", `unknown field ${/^[A-Za-z0-9_-]{1,40}$/.test(key) ? key : "(unprintable)"}`)
+    const { expectedRevision } = input
+    if (expectedRevision === undefined) throw new AgentError("invalid", "expectedRevision is required: the workspace revision you read", { hint: "Read the workspace and send its revision" })
+    if (!isExpectedRevision(expectedRevision)) throw new AgentError("invalid", "expectedRevision must be the revision you read")
+    const sessionID = await this.targetSession(userID, input)
+
+    await this.recover(userID, workspaceID)
+    const workspace = await this.deps.workspaces.require(userID, workspaceID)
+    if (workspace.state === "archived") throw new AgentError("invalid", `Workspace ${workspaceID} is archived`, { hint: "Restore it first" })
+    if (workspace.revision !== expectedRevision) throw revisionConflict(workspace)
+
+    const all = await this.deps.members.members(userID, workspaceID, { includeLeft: true })
+    const previousView = workspace.masterMemberID === undefined ? undefined : all.find((v) => v.current && v.member.id === workspace.masterMemberID)
+    if (previousView && previousView.member.sessionID === sessionID)
+      return { workspace, master: previousView.member, presence: previousView.presence, changed: false, checkpoints: { inherited: false }, grants: { transferred: false, note: GRANTS_NOTE } }
+    const other = all.find((v) => v.current && v.member.sessionID === sessionID)
+    if (other)
+      throw new AgentError("invalid", `Session ${sessionID} is already a ${other.member.role} member of this workspace`, {
+        hint: "Remove that membership first; a master is always a new membership",
+        extra: { memberID: other.member.id },
+      })
+    const previous = previousView?.member
+    const minGeneration = 1 + Math.max(0, ...all.filter((v) => v.member.role === "master").map((v) => v.member.generation))
+
+    // 1. the fence, then the revision again under it
+    const fence = await this.claim(userID, workspaceID, sessionID, previous?.id)
+    let master: WorkspaceMember
+    try {
+      const fenced = await this.deps.workspaces.require(userID, workspaceID)
+      if (fenced.revision !== expectedRevision) throw revisionConflict(fenced)
+      // 2. one members write: the old master replaced, the new one at generation + 1
+      const options = { allowMaster: true, minGeneration, ...(previous ? { replaces: previous.id } : {}) }
+      master = (await this.deps.members.join(userID, workspaceID, { sessionID, role: "master" }, options)).member
+    } catch (error) {
+      await this.release(userID, workspaceID, fence)
+      throw error
+    }
+    const joined = await this.advance(userID, workspaceID, fence, { phase: "joined", newMemberID: master.id })
+    // 3. the commit point (rolled forward on a lost race), 4. supervision follows the new master
+    const committed = await this.commit(userID, workspaceID, joined, expectedRevision)
+    const supervision = previous ? await this.deps.supervision.memberDeparted(userID, workspaceID, previous.id, { replacedBy: master.id }) : undefined
+    await this.release(userID, workspaceID, joined)
+    await this.deps.state.flush?.()
+
+    const departed = previous ? await this.deps.members.member(userID, workspaceID, previous.id) : undefined
+    const latest = previous ? await this.deps.checkpoints?.latest(userID, workspaceID, previous.id) : undefined
+    const presence = (await this.deps.members.members(userID, workspaceID)).find((v) => v.member.id === master.id)?.presence ?? "unknown"
+    return {
+      workspace: committed,
+      master,
+      presence,
+      ...(departed && previousView ? { previous: departed, previousPresence: previousView.presence } : {}),
+      changed: true,
+      ...(supervision ? { supervision } : {}),
+      checkpoints: { inherited: false, ...(latest ? { previousCheckpoint: publicCheckpoint(latest) } : {}) },
+      grants: { transferred: false, note: GRANTS_NOTE },
+    }
+  }
+
+  /** The current master with presence, earlier masters and any replacement in flight. */
+  async view(userID: string, workspaceID: string): Promise<MasterView> {
+    await this.recover(userID, workspaceID)
+    const workspace = await this.deps.workspaces.require(userID, workspaceID)
+    const all = await this.deps.members.members(userID, workspaceID, { includeLeft: true })
+    const current = all.find((v) => v.current && v.member.id === workspace.masterMemberID)
+    const previous = all
+      .filter((v) => v.member.role === "master" && v !== current)
+      .sort((a, b) => (b.member.leftAt ?? b.member.joinedAt) - (a.member.leftAt ?? a.member.joinedAt))
+      .slice(0, PREVIOUS_MASTERS_MAX)
+      .map(({ member, presence }) => ({ member, presence }))
+    const fence = readFence((await this.deps.state.get(userID, WORKSPACE_MASTER, workspaceID))?.value, workspaceID)
+    const pending = fence && fence.phase !== "done" ? { phase: fence.phase, at: fence.at, stale: this.now() - fence.at >= MASTER_FENCE_MS } : undefined
+    return {
+      workspaceID,
+      revision: workspace.revision,
+      ...(current ? { master: { member: current.member, presence: current.presence } } : {}),
+      previous,
+      ...(pending ? { pending } : {}),
+    }
+  }
+
+  /**
+   * Refuses a stale master: `memberID` (and `generation`, when given) must be the workspace's current master.
+   * 409 conflict naming the current master member and generation otherwise. For master-only operations.
+   */
+  async assertMaster(userID: string, workspaceID: string, memberID: string, generation?: number): Promise<WorkspaceMember> {
+    const workspace = await this.deps.workspaces.require(userID, workspaceID)
+    const named = workspace.masterMemberID === undefined ? undefined : await this.deps.members.member(userID, workspaceID, workspace.masterMemberID).catch(() => undefined)
+    const live = named && named.leftAt === undefined ? named : undefined
+    if (!live || live.id !== memberID || (generation !== undefined && live.generation !== generation))
+      throw conflict(
+        `Member ${memberID} is not the current master of workspace ${workspaceID}`,
+        { ...(live ? { currentMasterMemberID: live.id, currentGeneration: live.generation } : {}), currentRevision: workspace.revision },
+        "The master was replaced: act as the current master or replace it explicitly",
+      )
+    return live
+  }
+
+  /**
+   * Finishes a replacement whose holder crashed (fence older than MASTER_FENCE_MS): rolls a joined member forward
+   * to master, or releases a fence that never joined. Fresh fences are left alone (`busy`).
+   */
+  async recover(userID: string, workspaceID: string): Promise<"none" | "busy" | "rolled_forward" | "released"> {
+    const fence = readFence((await this.deps.state.get(userID, WORKSPACE_MASTER, workspaceID))?.value, workspaceID)
+    if (!fence || fence.phase === "done") return "none"
+    if (this.now() - fence.at < MASTER_FENCE_MS) return "busy"
+    let newMemberID = fence.newMemberID
+    if (newMemberID === undefined) {
+      // The join may have landed before the crash without the fence recording it.
+      const views = await this.deps.members.members(userID, workspaceID)
+      newMemberID = views.find((v) => v.member.role === "master" && v.member.sessionID === fence.sessionID && v.member.joinedAt >= fence.at)?.member.id
+    }
+    let outcome: "rolled_forward" | "released" = "released"
+    if (newMemberID !== undefined) {
+      const joined = await this.deps.members.member(userID, workspaceID, newMemberID).catch(() => undefined)
+      if (joined && joined.leftAt === undefined) {
+        await this.commit(userID, workspaceID, { ...fence, newMemberID }, undefined)
+        if (fence.previousMemberID) await this.deps.supervision.memberDeparted(userID, workspaceID, fence.previousMemberID, { replacedBy: newMemberID })
+        outcome = "rolled_forward"
+      }
+    }
+    await this.release(userID, workspaceID, fence)
+    await this.deps.state.flush?.()
+    return outcome
+  }
+
+  // ---------- internals ----------
+
+  private async targetSession(userID: string, input: Record<string, unknown>): Promise<string> {
+    const { sessionID, launchID } = input
+    if ((sessionID === undefined) === (launchID === undefined)) throw new AgentError("invalid", "Send exactly one of sessionID or launchID")
+    if (sessionID !== undefined) {
+      if (typeof sessionID !== "string" || !SESSION_ID.test(sessionID)) throw new AgentError("invalid", "sessionID must be a session ID (ses_…)")
+      return sessionID
+    }
+    if (typeof launchID !== "string" || !LAUNCH_ID.test(launchID)) throw new AgentError("invalid", "launchID must be a launch ID")
+    if (!this.deps.launches) throw new AgentError("unsupported", "This hub does not serve launches", { extra: { feature: "launches" } })
+    const launch = await this.deps.launches.view(userID, launchID)
+    if (!launch) throw new AgentError("not_found", `No launch ${launchID}`)
+    if (launch.state !== "running" || launch.sessionID === undefined)
+      throw new AgentError("invalid", `Launch ${launchID} is ${launch.state}, not running`, {
+        hint: launch.state === "ended" ? "Launch a new session" : "Wait until it is running",
+        extra: { launchState: launch.state },
+      })
+    return launch.sessionID
+  }
+
+  /** Takes the workspace's fence (409 conflict while another replacement holds a fresh one). */
+  private async claim(userID: string, workspaceID: string, sessionID: string, previousMemberID: string | undefined): Promise<HeldFence> {
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const stored = await this.deps.state.get(userID, WORKSPACE_MASTER, workspaceID)
+      const held = readFence(stored?.value, workspaceID)
+      if (held && held.phase !== "done") {
+        if (this.now() - held.at < MASTER_FENCE_MS)
+          throw conflict(
+            `Another master replacement of workspace ${workspaceID} is in progress`,
+            { retryAfter: Math.max(1, Math.ceil((held.at + MASTER_FENCE_MS - this.now()) / 1000)) },
+            "Read the workspace again shortly",
+          )
+        await this.recover(userID, workspaceID)
+        continue
+      }
+      const fence: Fence = { v: 1, workspaceID, opID: this.newOpID(), phase: "claimed", at: this.now(), sessionID, ...(previousMemberID ? { previousMemberID } : {}) }
+      const put = await this.deps.state.put(userID, WORKSPACE_MASTER, workspaceID, fence, { ifVersion: stored?.version ?? 0 })
+      if (put.ok) return { ...fence, version: put.version }
+      // Another writer got there first: the next round reads its fence.
+    }
+    throw new Error(`state update of ${WORKSPACE_MASTER}/${workspaceID} kept conflicting`)
+  }
+
+  /** Records progress under the fence; a fence taken over meanwhile (only after MASTER_FENCE_MS) is a conflict. */
+  private async advance(userID: string, workspaceID: string, fence: HeldFence, change: Partial<Fence>): Promise<HeldFence> {
+    const { version, ...rest } = fence
+    const next: Fence = { ...rest, ...change }
+    const put = await this.deps.state.put(userID, WORKSPACE_MASTER, workspaceID, next, { ifVersion: version })
+    if (!put.ok) throw conflict(`The master replacement of workspace ${workspaceID} was taken over`, {}, "Read the workspace again")
+    return { ...next, version: put.version }
+  }
+
+  /** Releases the fence (phase done) if it is still this operation's. */
+  private async release(userID: string, workspaceID: string, fence: Fence): Promise<void> {
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const stored = await this.deps.state.get(userID, WORKSPACE_MASTER, workspaceID)
+      const current = readFence(stored?.value, workspaceID)
+      if (!stored || !current || current.opID !== fence.opID || current.phase === "done") return
+      const done: Fence = { ...current, phase: "done", at: this.now() }
+      if ((await this.deps.state.put(userID, WORKSPACE_MASTER, workspaceID, done, { ifVersion: stored.version })).ok) return
+    }
+  }
+
+  /**
+   * Points masterMemberID at the joined member: under the caller's expected revision first, then (rolled forward)
+   * under fresh reads while the record still names the old master or nobody. Another master there means someone
+   * else committed: a conflict.
+   */
+  private async commit(userID: string, workspaceID: string, fence: Fence, expectedRevision: number | undefined): Promise<HubWorkspace> {
+    const target = fence.newMemberID!
+    if (expectedRevision !== undefined) {
+      try {
+        return await this.deps.workspaces.setMaster(userID, workspaceID, target, expectedRevision)
+      } catch (error) {
+        if (!isConflict(error)) throw error
+      }
+    }
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const current = await this.deps.workspaces.require(userID, workspaceID)
+      if (current.masterMemberID === target) return current
+      if (current.masterMemberID !== undefined && current.masterMemberID !== fence.previousMemberID)
+        throw conflict(`Workspace ${workspaceID} has another master now`, { currentRevision: current.revision, currentMasterMemberID: current.masterMemberID })
+      try {
+        return await this.deps.workspaces.setMaster(userID, workspaceID, target, current.revision)
+      } catch (error) {
+        if (!isConflict(error)) throw error
+      }
+    }
+    throw new Error(`workspace ${workspaceID} master kept conflicting`)
+  }
+}
+
+// ---------- events ----------
+
+/** The master changed: IDs, generations, revisions and counts only. */
+export function masterReplacedEvent(result: MasterReplacement): EventInput {
+  return {
+    type: "workspace.master.replaced",
+    family: "manage",
+    subject: { workspaceID: result.workspace.id, memberID: result.master.id, sessionID: result.master.sessionID, ...(result.previous ? { previousMemberID: result.previous.id } : {}) },
+    data: {
+      generation: result.master.generation,
+      revision: result.workspace.revision,
+      ...(result.previous ? { previousGeneration: result.previous.generation } : {}),
+      transferred: result.supervision?.transferred ?? 0,
+      detached: result.supervision?.detached ?? 0,
+    },
+  }
+}
+
+/** The journal events of a replacement, in order (none when nothing changed). */
+export function masterEvents(result: MasterReplacement): EventInput[] {
+  if (!result.changed) return []
+  const links = result.supervision
+  return [
+    ...(result.previous ? [memberLeftEvent(result.previous)] : []),
+    memberJoinedEvent(result.master),
+    masterReplacedEvent(result),
+    ...(result.previous && links && links.detached + links.transferred + links.pruned > 0 ? [supervisionDepartedEvent(result.previous.id, links)] : []),
+  ]
+}
+
+// ---------- routes ----------
+
+const PREFIX = "/api/agent/workspaces"
+const NO_STORE = { "cache-control": "no-store" }
+const [READ_SCOPE, MANAGE_SCOPE] = WORKSPACE_SCOPES
+
+export interface MasterRoutesDeps extends Omit<MasterStoreDeps, "state"> {
+  /** Default: the workspaces' StateStore. */
+  readonly state?: StateStore
+  readonly events?: Pick<AgentEvents, "append">
+  readonly audit?: { audit(entry: { actor: string; action: string; target: string; detail?: string }): unknown }
+  readonly idempotency?: RouteIdempotency
+  readonly report?: (cause: unknown) => void
+}
+
+function sessionsVisible(context: AgentContext): void {
+  const { actor } = context
+  if (actor.kind === "app" && !actor.scopes.includes("sessions:read")) throw new AgentError("forbidden", "Master routes also need scope sessions:read")
+}
+
+async function bodyOf(request: Request): Promise<Record<string, unknown>> {
+  const text = await boundedText(request, AGENT_JSON_BODY_MAX)
+  let raw: unknown
+  try {
+    raw = JSON.parse(text === "" ? "{}" : text)
+  } catch {
+    throw new AgentError("invalid", "Body must be JSON")
+  }
+  if (!isObj(raw)) throw new AgentError("invalid", "Body must be a JSON object")
+  return raw
+}
+
+/**
+ *   GET  /api/agent/workspaces/:id/master                                            workspaces:read + sessions:read
+ *   POST /api/agent/workspaces/:id/master {sessionID | launchID, expectedRevision}   workspaces:manage + sessions:read
+ *        (Idempotency-Key: the answer is replayed)
+ * Users and app tokens by scope; session tokens are refused (membership grants nothing).
+ */
+export function masterRoutes(deps: MasterRoutesDeps): AgentRoute[] {
+  const state = deps.state ?? deps.workspaces.state
+  const store = new MasterStore({ ...deps, state })
+  const idempotency = deps.idempotency ?? new RouteIdempotency({ state, collection: WORKSPACE_ROUTE_IDEMPOTENCY, ...(deps.now ? { now: deps.now } : {}) })
+  const report = deps.report ?? ((cause: unknown) => console.error(`[hub] workspace event failed: ${cause instanceof Error ? cause.message : String(cause)}`))
+  return [
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/master`,
+      allow: { scope: READ_SCOPE },
+      async handle(context) {
+        sessionsVisible(context)
+        return Response.json(await store.view(context.user.id, context.params.id!), { headers: NO_STORE })
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/:id/master`,
+      allow: { scope: MANAGE_SCOPE },
+      async handle(context) {
+        sessionsVisible(context)
+        const body = await bodyOf(context.request)
+        const userID = context.user.id
+        return idempotency.run(userID, `POST ${context.url.pathname}`, idempotencyKeyOf(context.request) ?? null, body, async () => {
+          const result = await store.replace(userID, context.params.id!, body)
+          if (result.changed) {
+            await deps.audit?.audit({ actor: userID, action: "workspace.master.replace", target: result.master.id, detail: context.actor.kind })
+            for (const event of masterEvents(result)) await deps.events?.append(userID, event).catch(report)
+          }
+          return { status: 200, body: result }
+        })
+      },
+    },
+  ]
+}