@agent-compose/sdk 0.8.1 → 0.8.3

package/src/types/api-conversations.ts

@@ -95,15 +95,44 @@ export interface ConversationRow {
   unreadCount?: number;
 }
 
+/** Agent-author identity decoration (mirrors the server's `agentAuthor`
+ *  on message rows and stream payloads): rows authored by a user's agent
+ *  that is not the conversation's resident agent — the assistant's
+ *  delegated sends, review briefs, and PEER-SESSION messages
+ *  (`sourceChannel: 'session'`). The persona `name` is the author label;
+ *  `avatarSeed` is the agent's own generated orb; the owner names WHOSE
+ *  agent it is. */
+export interface ConversationAgentAuthor {
+  agentId: string;
+  name: string;
+  avatarSeed: string;
+  ownerUserId: string | null;
+  ownerName: string | null;
+}
+
 export interface ConversationMessageRow {
   id: string;
   authorKind: string;
   authorId: string | null;
+  /** The author's display name, resolved server-side — a HUMAN author's
+   *  display name, or an attributable AGENT author's persona name (see
+   *  `agentAuthor`). Null for resident-agent/system rows; absent on older
+   *  servers. */
+  authorLabel?: string | null;
+  /** Sender identity for foreign-agent and peer-session rows — render the
+   *  persona name + its avatarSeed FIRST, before any session/runtime
+   *  fallback (the one resolution order; streamed and settled renders are
+   *  identical). Null/absent on resident-agent, session channel-post, and
+   *  older-server rows. */
+  agentAuthor?: ConversationAgentAuthor | null;
   parts: ConversationMessagePart[];
   threadRootId: string | null;
   reactions: Record<string, string[]>;
   replyCount: number;
   lastReplyAt: string | null;
+  /** When the author last edited the content; null/absent = never edited
+   *  (absent on older servers). */
+  editedAt?: string | null;
   createdAt: string;
   /** Thread-root facepile (≤3) — present only on roots with replies. */
   replyAuthors?: Array<{ kind: string; id: string | null }>;
@@ -112,6 +141,12 @@ export interface ConversationMessageRow {
    *  rows to the session (title + runtime mark), never a resident agent.
    *  Null once the session is deleted; absent on older servers. */
   sourceSessionId?: string | null;
+  /** THE ORIGIN SURFACE (ADR-0073 §6.5): the ingress the row arrived over —
+   *  'sms' / 'phone' / 'voice' on inbound user rows, 'assistant' on
+   *  delegated sends, 'session' on peer session→session messages (whose
+   *  author identity rides `agentAuthor`). Null/absent = an ordinary
+   *  in-app send or an older server. */
+  sourceChannel?: "sms" | "phone" | "voice" | "assistant" | "session" | null;
   /** Set on a session-transcript row RELAYED from a channel mention
    *  (ADR-0057 Seam 3) — the channel it arrived from. Null once the
    *  channel is deleted; absent on older servers. */
@@ -130,9 +165,44 @@ export interface ConversationsPage {
 /** Sessions page — each row additionally carries its resident
  *  executor substrate (ADR-0037 §8): `"cloud"` = persistent server-side
  *  sandbox (pickers render the ☁ marker), `"local"` = bridge daemon,
- *  null = no durable session record yet. */
+ *  null = no durable session record yet — and, on diff-review spawns,
+ *  `reviewOf`: the session this row was born to REVIEW (id + its current
+ *  alias/title; a deleted reviewed conversation degrades to a bare id
+ *  ref). Null/absent for ordinary sessions and older servers. */
 export interface SessionsPage {
-  conversations: Array<ConversationRow & { sessionExecutor: "local" | "cloud" | null }>;
+  conversations: Array<ConversationRow & {
+    sessionExecutor: "local" | "cloud" | null;
+    reviewOf?: { conversationId: string; alias: string | null; title: string | null; head?: string | null } | null;
+  }>;
+  next_cursor: string | null;
+}
+
+/** One 15-minute sandbox perf rollup bucket from
+ *  GET /conversations/:id/perf-history (session_perf_rollups). Null
+ *  utilization fields = the guest never reported that resource in the
+ *  bucket — never zero-filled. */
+export interface SessionPerfBucket {
+  /** Start of the bucket, ISO 8601. */
+  bucket_start: string;
+  /** Guest samples folded into the bucket (turn + sweep lanes). */
+  samples: number;
+  cpu_busy_p50: number | null;
+  cpu_busy_p95: number | null;
+  mem_used_p50: number | null;
+  mem_used_p95: number | null;
+  disk_used_p95: number | null;
+  load1_max: number | null;
+  /** Seconds within the bucket any resource sat ≥90% (capped at 900). */
+  saturated_seconds: number;
+  vcpu: number | null;
+  provider: string;
+}
+
+/** Newest-first, keyset-paginated (house list envelope). */
+export interface SessionPerfHistoryPage {
+  object: "list";
+  data: SessionPerfBucket[];
+  has_more: boolean;
   next_cursor: string | null;
 }
 
@@ -162,16 +232,31 @@ export interface ConversationDetail {
    *  with a drive branch and a resolvable factory; null/absent = main
    *  only (read loosely — older servers omit it). */
   sessionDrive?: { factorySlug: string; branch: string } | null;
+  /** THE REVIEWER MARKER (diff-review spawns): non-null ⇒ this session was
+   *  born to review that conversation's diff. Null for ordinary sessions;
+   *  absent on older servers (read loosely). */
+  sessionReviewOf?: string | null;
   viewerLastReadAt: string | null;
   /** The caller's role in this conversation (ADR-0045) — drives client
    *  affordances only; the server remains the authority on every action.
    *  Public channels report implicit `write` for non-member teammates. */
   viewerRole: ConversationMemberRole;
+  /** Provenance when `viewerRole` is DERIVED rather than held: the project
+   *  (ADR-0045 read floor) or attached channel (ADR-0057) the viewer
+   *  follows this conversation through. Null/absent for real members —
+   *  clients use it to explain read-only honestly ("You follow this
+   *  session through <project>…"). Absent on older servers. */
+  viewerRoleVia?: { kind: "project" | "channel"; id: string; name: string | null } | null;
   /** SSE replay watermark: the conversation's highest durable stream-event
    *  id at hydrate time — everything at or below it is already folded into
    *  `messages`. Seed the stream's first `Last-Event-ID` from it instead of
    *  0 (0 replays the entire history). Absent on older servers. */
   streamCursor?: number;
+  /** Windowed hydrate (2026-08-17): `messages` is the NEWEST window
+   *  (default 50; `limit` caps at 200). Non-null = older transcript
+   *  exists — page it with `GET /conversations/:id/messages?before=` +
+   *  this opaque cursor. Absent on older servers. */
+  olderCursor?: string | null;
   messages: ConversationMessageRow[];
 }
 
@@ -251,6 +336,15 @@ export interface CreateCloudSessionInput {
    *  seeds re-applied on every fresh acquire. Paths under .claude/ only;
    *  strict base64; 256KB decoded total (server-capped). */
   seedFiles?: Array<{ path: string; contentB64: string; mode: "write" | "append" }>;
+  /** DIFF REVIEW spawn: the conversation whose proposed changes this
+   *  session is born to review. Server-resolved: on a graph-plane drive
+   *  the new session's branch is minted as a FORK of the reviewed branch
+   *  (its working dir IS the proposal, `.review/` comparison materials
+   *  included); on the legacy plane the spawn degrades to an ordinary
+   *  session. Requires a human caller and a chat session on the reviewed
+   *  session's factory; 409 `review_of_review` when the target is itself
+   *  a review session. */
+  reviewOfConversationId?: string;
 }
 
 export interface CloudSessionCreated {
@@ -327,6 +421,15 @@ export interface SessionForked {
   conversationId: string;
 }
 
+/** Result of holding a session's background-work busy lease
+ *  (`POST /conversations/:id/background-work`). While the lease is live the
+ *  between-turns park/suspend leaves the session's VM running; it lapses on
+ *  its own — re-hold to extend. */
+export interface BackgroundWorkHeld {
+  /** ISO timestamp the lease now runs to. */
+  leaseUntil: string;
+}
+
 // ── Session branch proposals (ADR-0053) ─────────────────────────────────────
 // Every cloud session works on its own factory-drive branch; the whole branch
 // is the unit of review, like a PR. Wire shapes mirror
@@ -364,6 +467,217 @@ export interface SessionChangeSet {
   truncated: boolean;
   /** Open `factory_file_conflicts` rows from this session's prior merges. */
   openConflicts: number;
+  /** Graph plane only (additive — absent elsewhere): the opaque cursor for
+   *  the NEXT page of `changes` — pass it back as `after` on
+   *  `getSessionChanges`. Null = last page. */
+  nextAfter?: string | null;
+  /** The serving plane (additive): `"graph"` when the change set is served
+   *  from the commit graph (paginated, head-anchored); absent = legacy. */
+  plane?: "graph";
+  /** MERGE GATE (merge-gate spec, additive — absent on older servers):
+   *  null = ungated. Present: whether THIS caller's merge lands directly
+   *  (`canMerge` — an owner or named approver) or stages a kind='merge'
+   *  approval instead (`mergeSessionChanges` answers 202
+   *  `SessionMergeGated`), plus the resolved approver set. */
+  mergeGate?: {
+    enabled: true;
+    canMerge: boolean;
+    approvers: Array<{ userId: string; label: string | null }>;
+  } | null;
+  /** The OPEN kind='merge' approval already waiting on this session's
+   *  branch, if any (additive — absent on older servers). */
+  pendingApprovalId?: string | null;
+  /** DIFF REVIEW (additive — absent on older servers): notes written back
+   *  by a spawned review session, whether they predate the served diff
+   *  (`reviewStale` — the changed-file signature no longer matches), the
+   *  bound review session's conversation + whether it is still live, and
+   *  whether the deployment offers reviews at all (`reviewEnabled`; false
+   *  hides the affordance). Reviews are USER-TRIGGERED only — binding
+   *  rides `POST /conversations/:id/changes/review`, and notes arrive
+   *  through the review session's own gated write-back. */
+  reviewNotes?: string | null;
+  reviewStale?: boolean;
+  reviewEnabled?: boolean;
+  reviewSessionConversationId?: string | null;
+  reviewSessionActive?: boolean;
+  /** BOUND (additive): the bound review session — the FOLLOW-UP LOOP's
+   *  driver — exists and is not ended (a parked reviewer between turns is
+   *  bound but not active). Not publish rights: every reviewer of the
+   *  diff owns its own document; concurrent reviewers are first-class,
+   *  bounded at spawn (`reviewer_cap`). */
+  reviewSessionBound?: boolean;
+  /** The AUTOMATIC follow-up loop (additive): armed (default true) + how
+   *  many automatic rounds ran since the last human-triggered review
+   *  (hard cap 2; a manual re-review resets it). */
+  reviewAutoFollowup?: boolean;
+  reviewAutoRounds?: number;
+  /** The OPT-IN main-advance auto-rebase reflex (additive — absent on
+   *  older servers; default OFF): armed ⇒ when main moves and a preflight
+   *  proves the fold clean, the platform rebases this session's branch
+   *  from main headlessly. Toggled via `setSessionAutoRebase`. */
+  autoRebaseFromMain?: boolean;
+  /** STRUCTURED review suggestions beside the notes (additive — absent on
+   *  older servers): individually actionable {id, path, title, rationale,
+   *  patch} entries the review session wrote back, status-stamped
+   *  `"proposed"` by the server (`"accepted"`/`"rejected"` are reserved for
+   *  the human decision pass). */
+  reviewSuggestions?: ReviewSuggestion[];
+  /** THE REVIEWER MARKER (additive — absent on older servers): non-null ⇒
+   *  THIS session was born to review that conversation's diff. Its own
+   *  branch is a fork of the reviewed branch and can never merge
+   *  (`mergeable` false, merge 409s `fork_branch_unmergeable`), and it is
+   *  refused as a review target (409 `review_of_review`). */
+  reviewOfConversationId?: string | null;
+  /** PER-REVIEWER review documents (additive — absent on older servers;
+   *  owner ask 2026-08-22): EVERY reviewer's published document for this
+   *  diff, newest publish first — parallel reviewers each own one. The
+   *  flat `reviewNotes`/`reviewSuggestions` above are derived aggregates
+   *  (the primary document's notes; the reviewer-stamped union); this is
+   *  the grouped truth the review panel renders. Page 1 only — cursor
+   *  pages serve an empty array. */
+  reviewDocuments?: SessionReviewDocument[];
+}
+
+/** One reviewer's published review document
+ *  (`SessionChangeSet.reviewDocuments`). `stale` compares the head this
+ *  document was published against with the served diff. */
+export interface SessionReviewDocument {
+  reviewerConversationId: string;
+  /** The reviewer session's @alias / title, when its conversation still
+   *  exists (a deleted reviewer degrades to the bare id). */
+  reviewerAlias: string | null;
+  reviewerTitle: string | null;
+  notes: string;
+  suggestions: ReviewSuggestion[];
+  /** ISO timestamp of this document's last publish. */
+  publishedAt: string;
+  /** The diff head published against (null = pre-stamp reviewer). */
+  signature: string | null;
+  /** Display form of `signature` ("head cd741f27"). */
+  headShort: string | null;
+  stale: boolean;
+}
+
+/** One STRUCTURED, individually actionable suggestion a review session
+ *  wrote back beside its notes (`SessionChangeSet.reviewSuggestions`). */
+export interface ReviewSuggestion {
+  /** Reviewer-minted stable id — survives full-replace re-posts. */
+  id: string;
+  /** The changed file the suggestion targets (always in the change set —
+   *  the writeback refuses paths outside it). */
+  path: string;
+  title: string;
+  rationale: string;
+  /** Unified-diff hunk targeting the PROPOSED side of `path`. */
+  patch: string;
+  /** Server-stamped `"proposed"` at writeback; the HUMAN decision routes
+   *  (`POST …/changes/suggestions/:suggestionId/decide` / `…/decide-all`)
+   *  are the only writers of the rest — `"accepted"` (the patch landed on
+   *  the session branch), `"rejected"`, or `"stale"` (an accept found the
+   *  file drifted since review; nothing was written). */
+  status: "proposed" | "accepted" | "rejected" | "stale";
+  /** REVIEWER IDENTITY (additive — present on the flat
+   *  `SessionChangeSet.reviewSuggestions` union; owner ask 2026-08-22):
+   *  which reviewer's document this entry came from. Ids are unique only
+   *  PER REVIEWER — the decide-one route takes `reviewerConversationId`
+   *  when two reviewers reused an id (409 `ambiguous_suggestion`
+   *  otherwise). */
+  reviewerConversationId?: string;
+  reviewerAlias?: string | null;
+}
+
+/** One suggestion in the review write-back (`publishReviewNotes` /
+ *  `agentc review publish`): `ReviewSuggestion` minus `status` — the server
+ *  stamps every stored entry `"proposed"`, so a reviewer can never claim
+ *  acceptance. `path` must name a file in the change set (refused
+ *  otherwise). */
+export interface ReviewSuggestionInput {
+  id: string;
+  path: string;
+  title: string;
+  rationale: string;
+  patch: string;
+}
+
+/** `POST /conversations/:id/review-notes` — the review session publishing
+ *  its whole review document (full replace: notes AND suggestions
+ *  together). Gated to the bound review session's own toolbelt key. */
+export interface ReviewNotesPublished {
+  ok: true;
+}
+
+/** `POST /conversations/:id/review-git-credential` — one fresh short-lived
+ *  credential for the review git remote, minted per git operation by the
+ *  sandbox's credential helper (`agentc review git-credential`). Gated to
+ *  the review session's own toolbelt key; never stored, never reused. */
+export interface ReviewGitCredential {
+  /** The stable, credential-free remote URL (`https://host/git/<disk>`). */
+  url: string;
+  username: string;
+  password: string;
+  /** ISO timestamp the credential expires — informational (the helper
+   *  mints anew per operation). */
+  expiresAt: string;
+}
+
+/** `POST /conversations/:id/changes/suggestions/:suggestionId/decide` —
+ *  the post-call truth for that suggestion (an accept that found drift
+ *  answers `"stale"`; repeats on a settled row are no-ops). */
+export interface ReviewSuggestionDecision {
+  object: "review_suggestion_decision";
+  conversationId: string;
+  id: string;
+  status: ReviewSuggestion["status"];
+  /** PER-REVIEWER documents (additive): whose document the decided
+   *  suggestion lives in — null on older servers / legacy ids. */
+  reviewerConversationId?: string | null;
+}
+
+/** `POST /conversations/:id/changes/suggestions/decide-all` — every stored
+ *  suggestion's post-call status (only `"proposed"` rows flip). */
+export interface ReviewSuggestionDecisions {
+  object: "review_suggestion_decisions";
+  conversationId: string;
+  results: Array<{ id: string; status: ReviewSuggestion["status"]; reviewerConversationId?: string | null }>;
+}
+
+/** `GET /conversations/:id/changes/stats` — the changes chip's aggregate
+ *  +added/−removed line counts, cached server-side per (base, theirsHead).
+ *  `unavailable` = no cheap head anchors (legacy plane, unbranched) — the
+ *  chip degrades to its file count, never fake zeros. */
+export type SessionChangeStats =
+  | { object: "session_change_stats"; conversationId: string; state: "unavailable" }
+  | {
+      object: "session_change_stats"; conversationId: string; state: "ok";
+      additions: number; deletions: number; files: number;
+      /** True when the count is partial (list truncated / file cap). */
+      truncated: boolean;
+      base: string; theirsHead: string;
+    };
+
+/** `POST /conversations/:id/changes/review` — binds a just-spawned review
+ *  session to the reviewed session and stamps the diff signature the
+ *  review covers. */
+export interface SessionDiffReviewBound {
+  object: "session_diff_review";
+  conversationId: string;
+  reviewSessionConversationId: string;
+  reviewDiffSignature: string;
+}
+
+/** 202 from `POST /conversations/:id/changes/merge` on a merge-GATED
+ *  session when the caller is not an approver: nothing merged — the ask
+ *  froze into (`approval_required`) or converged on (`approval_pending`) a
+ *  kind='merge' approval routed to the approvers. */
+export interface SessionMergeGated {
+  object: "session_merge_gated";
+  conversationId: string;
+  code: "approval_required" | "approval_pending";
+  approvalId: string;
+  branch?: string;
+  changeCount?: number;
+  openConflicts?: number;
+  approvers: Array<{ userId: string; label: string | null }>;
 }
 
 /** Per-file accounting of one session branch merge — the merge core's
@@ -412,6 +726,81 @@ export interface SessionDiscardReport {
   discarded: true;
 }
 
+/** One row of the conflict preflight (`GET /conversations/:id/changes/preflight`)
+ *  — the branch-side change decorated with the REAL merge's own per-file
+ *  disposition, computed report-only: `fastForward` lands as-is (main
+ *  untouched at the path), `skip` is already-equal on both sides,
+ *  `conflict` would 409 the merge today. `autoMerge` is the legacy plane's
+ *  clean-diff3 class — never emitted on the graph plane. */
+export interface SessionPreflightFileRow {
+  path: string;
+  kind: "add" | "modify" | "delete";
+  disposition: "fastForward" | "autoMerge" | "conflict" | "skip";
+  /** Set on `conflict` rows only. */
+  conflictReason: "same_region" | "binary" | "delete_vs_edit" | null;
+}
+
+/** `GET /conversations/:id/changes/preflight` — see conflicts AHEAD of the
+ *  merge: report-only, no writes, no locks. `unavailable` = no cheap head
+ *  anchors (legacy plane, unbranched) or the classification faulted — the
+ *  caller degrades honestly, never fake zeros. `pending` = a cold compute
+ *  outlived the first-response deadline; poll again to collect it. */
+export type SessionChangePreflight =
+  | { object: "session_change_preflight"; conversationId: string; state: "unavailable" }
+  | {
+      object: "session_change_preflight"; conversationId: string; state: "pending";
+      base: string; oursHead: string; theirsHead: string;
+    }
+  | {
+      object: "session_change_preflight"; conversationId: string; state: "ok";
+      branch: string;
+      base: string;
+      /** main's head — the exact commit the dispositions were computed against. */
+      oursHead: string;
+      /** the session branch's head. */
+      theirsHead: string;
+      files: SessionPreflightFileRow[];
+      conflictCount: number;
+      /** Page caps hit — dispositions cover a floor, honestly. */
+      truncated: boolean;
+    };
+
+/** Result of `POST /conversations/:id/changes/rebase` — current main
+ *  folded INTO the session branch (the reverse merge; main untouched).
+ *  `rebased` advanced the branch by one merge commit (`rebaseCommit`)
+ *  and future diffs/merges use the new base. `rebased_with_conflicts`
+ *  folded the clean remainder (`foldCommit`, null when nothing folded) and
+ *  KEPT the branch's version for `conflictPaths` — each is recorded as a
+ *  conflict row and the session was told in-conversation to reconcile. */
+export interface SessionRebaseReport {
+  object: "session_rebase_report";
+  conversationId: string;
+  branch: string;
+  outcome: "noop" | "rebased" | "rebased_with_conflicts";
+  /** main's head at rebase — the branch's new effective base on a clean
+   *  rebase. */
+  mainHead: string;
+  rebaseCommit?: string;
+  foldCommit?: string | null;
+  folded?: { added: number; modified: number; deleted: number; skipped: number };
+  baselineAdvanced?: boolean;
+  /** Capped at 100 on the wire; `conflictCount` is the true total. */
+  conflictPaths?: string[];
+  conflictCount?: number;
+  conflictsTruncated?: boolean;
+  /** True when the gateway truncated its conflict list — the fold was
+   *  skipped whole (an unlisted conflicted path must never be overwritten). */
+  foldSkipped?: boolean;
+}
+
+/** Result of `POST /conversations/:id/changes/autorebase` — the opt-in
+ *  main-advance auto-rebase reflex's new state. */
+export interface SessionAutoRebaseState {
+  object: "session_autorebase";
+  conversationId: string;
+  autoRebaseFromMain: boolean;
+}
+
 /** The sender's page stamp (HUD bar sends) — persisted server-side, never
  *  echoed back on the wire. Mirrors the server's `PageContext` schema. */
 export interface ConversationPageContext {
@@ -435,6 +824,15 @@ export interface SendConversationMessageInput {
  *  work and a coalesced follow-up turn will answer it. NOT an error. */
 export type ConversationTurnState = "none" | "started" | "queued";
 
+/** One @-mentioned user the server DROPPED as a non-member — the mention
+ *  ping went to nobody, and the response says so instead of staying
+ *  silent. `name` is the label the sender's own text carried for the
+ *  mention (picked in the typeahead — no new information). */
+export interface UnnotifiedMention {
+  userId: string;
+  name: string;
+}
+
 export interface SendConversationMessageResult {
   /** The persisted user message's id. */
   messageId: string;
@@ -447,6 +845,10 @@ export interface SendConversationMessageResult {
    *  each runs its own turn in its own conversation. Absent on older
    *  servers and non-channel sends. */
   relayedSessionIds?: string[];
+  /** Mentioned users whose ping was dropped by the member filter (a
+   *  private channel pings members only; a DM pings only the pair) —
+   *  present only when non-empty. Absent on older servers. */
+  unnotifiedMentions?: UnnotifiedMention[];
 }
 
 /** Response of the presence heartbeat (ADR-0037 §6): a fresh agent-liveness
@@ -517,6 +919,63 @@ export interface SessionChannelMessagePosted {
   threadRootId?: string | null;
 }
 
+/** Result of `POST /session-messages` — one session's agent messaging
+ *  ANOTHER session's conversation (`agentc session message @alias`). Unlike
+ *  a channel post, this DOES wake the target's turn machinery: `turn` is
+ *  the server's verdict ('started' | 'queued' | 'parked' — the agent-to-
+ *  agent exchange damper landed the message without waking anyone). */
+export interface SessionDirectMessageSent {
+  object: "session_message";
+  messageId: string;
+  target: { conversationId: string; alias: string | null; title: string | null };
+  turn: "started" | "queued" | "parked";
+  /** Honest posture line — delivery is not completion. */
+  note: string;
+}
+
+/** One branch claim, as the claim/release routes serialize it. */
+export interface BranchClaimInfo {
+  id: string;
+  branch: string;
+  targetConversationId: string;
+  holderConversationId: string;
+  targetLabel: string;
+  holderLabel: string;
+  reason: string | null;
+  claimedAt: string;
+}
+
+/** Result of `POST /session-branch-claims` — write authority over the
+ *  target session's drive branch transferred to the calling session, plus
+ *  the mount material the CLI uses to FUSE-mount the branch in-guest. */
+export interface BranchClaimGranted {
+  object: "branch_claim";
+  claim: BranchClaimInfo;
+  /** True = the caller already held this claim (re-mint / re-mount path). */
+  reclaimedOwn: boolean;
+  branch: string;
+  token: string;
+  gatewayWsUrl: string;
+  expiresAtS: number;
+  diskId: string;
+}
+
+/** Result of `POST /session-branch-claims/release` (and the human reclaim
+ *  door) — the claims this call closed. */
+export interface BranchClaimsReleased {
+  object: "branch_claim.release";
+  released: BranchClaimInfo[];
+}
+
+/** `GET /conversations/:id/branch-claim` — one session's claim state: the
+ *  live claim ON its branch (null = writable there), and the claims it
+ *  HOLDS on other sessions' branches. */
+export interface BranchClaimState {
+  object: "branch_claim.state";
+  claimedBy: BranchClaimInfo | null;
+  holds: BranchClaimInfo[];
+}
+
 /** One agent on the team, as listed by `GET /api/v1/agents`. Bridge-runtime
  *  rows additionally carry live presence (`online`, from the daemon's
  *  heartbeat within the server's TTL) and the hosting machine's label. */