@agent-compose/sdk 0.8.1 → 0.8.2

package/src/sandbox/sizes.ts

@@ -1,27 +1,68 @@
 /**
- * Sandbox machine sizes + the E2B template aliases derived from them.
+ * Sandbox machine sizes — THE single source of the size vocabulary.
  *
- * A coarse hardware knob that maps to provider machine specs at create time:
- * Vercel honours it natively via `resources.vcpus`; E2B sizing is baked into
- * the template, so on E2B a size resolves to a pre-built per-size template.
+ * Everything that names a size (the server's `SANDBOX_DEFAULT_SIZE` env enum,
+ * the register/invoke zod schemas, the run + session row types, the CLI's
+ * `--size` flag, the dashboard pickers via `GET /v1/sandbox-sizes`) derives
+ * from `SANDBOX_SIZES` / `SandboxSize` here. Adding a size is a ONE-LINE edit
+ * to `SANDBOX_MACHINES`: the type, the enums, the E2B build matrix and the
+ * pickers all follow. Do NOT re-declare the union inline anywhere.
+ *
+ * A size is a coarse hardware knob that maps to provider machine specs:
+ * Vercel honours it natively via `resources.vcpus`; E2B sizing is BAKED INTO
+ * THE TEMPLATE (e2b 2.30.5 has no create-time cpu/mem knob — `NewSandbox`
+ * carries only `templateID`), so on E2B a size resolves to a pre-built
+ * per-size template.
  */
 
-/** Sandbox hardware SKU. Named for the actual machine spec (vCPU + RAM) rather
- *  than abstract t-shirt sizes. Memory is always 2048 MB per vCPU:
- *    2vcpu-4gb   =  2 vCPU /  4 GiB  (Vercel's own default machine)
- *    4vcpu-8gb   =  4 vCPU /  8 GiB
- *    8vcpu-16gb  =  8 vCPU / 16 GiB  (per-sandbox ceiling on STANDARD accounts —
- *                                     probed live: 16 & 32 vCPU 400 on dev)
- *    32vcpu-64gb = 32 vCPU / 64 GiB  (ENTERPRISE ONLY — standard accounts reject >8 vCPU) */
-export type SandboxSize = "2vcpu-4gb" | "4vcpu-8gb" | "8vcpu-16gb" | "32vcpu-64gb";
-
-/** SKU → Vercel vCPU count (RAM follows at 2048 MB/vCPU). */
-export const SANDBOX_VCPUS: Record<SandboxSize, number> = {
-  "2vcpu-4gb":    2,
-  "4vcpu-8gb":    4,
-  "8vcpu-16gb":   8,
-  "32vcpu-64gb": 32,
-};
+/** Every sandbox hardware SKU, with its real machine spec. Named for the
+ *  machine (vCPU + RAM) rather than abstract t-shirt sizes, so a size can
+ *  never quietly mean something different than it says.
+ *
+ *  RAM is 2048 MB/vCPU everywhere EXCEPT `8vcpu-8gb`, which exists because
+ *  E2B caps a sandbox at 8 vCPU / 8192 MB (e2b.dev/docs/billing: Hobby and
+ *  Pro both "8 vCPU / 8 GB", raised only by arrangement): 8 vCPU at the 2 GB
+ *  rule would need 16 GiB and cannot be built. `8vcpu-8gb` is the CPU ceiling
+ *  at the memory ceiling — the only way to get 8 cores on E2B today, and a
+ *  spec already proven bakeable by the devbox (`E2B_DEVBOX_SPEC`).
+ *
+ *  Adding an entry here automatically: widens `SandboxSize`, widens every
+ *  derived enum, and — if it fits under the E2B caps — adds it to
+ *  `E2B_TEMPLATE_SIZES`, which is what `infra/e2b-template/build.ts` and the
+ *  `sandbox-images` CI job loop over. Two templates get baked per size, so
+ *  the matrix is not free; see that workflow's header. */
+export const SANDBOX_MACHINES = {
+  /** 1 vCPU / 2 GiB — the cheap floor. Plenty for a terminal session or a
+   *  shell-shaped agent; tight for a big `bun install` or a browser. */
+  "1vcpu-2gb":   { vcpus: 1,  memoryMB: 2048 },
+  /** 2 vCPU / 4 GiB — the default (Vercel's own default machine too). */
+  "2vcpu-4gb":   { vcpus: 2,  memoryMB: 4096 },
+  /** 4 vCPU / 8 GiB — comfortable for builds and multi-tool agent turns. */
+  "4vcpu-8gb":   { vcpus: 4,  memoryMB: 8192 },
+  /** 8 vCPU / 8 GiB — E2B's per-sandbox CEILING (cores maxed at the memory
+   *  cap). NOT expressible on Vercel, whose RAM follows vCPUs at 2 GB each. */
+  "8vcpu-8gb":   { vcpus: 8,  memoryMB: 8192 },
+  /** 8 vCPU / 16 GiB — Vercel only; exceeds E2B's 8 GiB memory cap. */
+  "8vcpu-16gb":  { vcpus: 8,  memoryMB: 16384 },
+  /** 32 vCPU / 64 GiB — Vercel Enterprise only; far past every E2B cap. */
+  "32vcpu-64gb": { vcpus: 32, memoryMB: 65536 },
+} as const satisfies Record<string, { vcpus: number; memoryMB: number }>;
+
+/** Sandbox hardware SKU. Derived from `SANDBOX_MACHINES` — never re-spelled
+ *  as an inline union. */
+export type SandboxSize = keyof typeof SANDBOX_MACHINES;
+
+/** The vocabulary as an ordered, smallest-first array — the shape zod
+ *  (`z.enum`), the CLI's `--size` validation, and the wire catalogue want.
+ *  Ordering is the pickers' display order, so keep it ascending. */
+export const SANDBOX_SIZES = Object.keys(SANDBOX_MACHINES) as readonly SandboxSize[] as
+  readonly [SandboxSize, ...SandboxSize[]];
+
+/** SKU → Vercel vCPU count (Vercel's RAM follows automatically at 2048
+ *  MB/vCPU — which is why `isVercelSupportedSize` exists). */
+export const SANDBOX_VCPUS: Record<SandboxSize, number> = Object.fromEntries(
+  SANDBOX_SIZES.map((s) => [s, SANDBOX_MACHINES[s].vcpus]),
+) as Record<SandboxSize, number>;
 
 /** SDK fallback size when neither the caller nor the deployment specifies one.
  *  Deliberately conservative — the OPERATIONAL default is the server's
@@ -29,37 +70,79 @@ export const SANDBOX_VCPUS: Record<SandboxSize, number> = {
  *  small matters because Vercel rate-limits creation by vCPUs-per-window
  *  (`api-sandboxes-vcpus-creation`); a large default 429s bursty/simultaneous
  *  creates. Workloads that need more RAM/CPU declare `resources.size` on the
- *  workflow rather than inflating the default for everyone. */
+ *  workflow rather than inflating the default for everyone.
+ *
+ *  NOT `1vcpu-2gb`: the floor is an opt-IN for cheap sessions, not a quiet
+ *  downgrade of every existing run's machine. */
 export const DEFAULT_SANDBOX_SIZE: SandboxSize = "2vcpu-4gb";
 
-/** The E2B sizes we pre-build a template for. E2B sizing is template-baked
- *  (no per-create cpu/mem knob), so honouring `resources.size` on E2B means
- *  ONE pre-built template per size. `32vcpu-64gb` is absent (E2B has no
- *  >8-vCPU equivalent). `8vcpu-16gb` is also absent: it needs 16 GiB RAM, but
- *  the E2B account caps memory at 8 GiB (`Template.build` 400s with
- *  "Memory can't be higher than 8192 MiB"). Add it back here (and rebuild the
- *  templates) only once the account's memory limit is raised. The register/
- *  invoke guards reject an unsupported E2B size before it can reach here. */
-export const E2B_TEMPLATE_SIZES: readonly SandboxSize[] = [
-  "2vcpu-4gb",
-  "4vcpu-8gb",
-];
-
-/** Is `size` one E2B can be built/booted at? `32vcpu-64gb` (no >8-vCPU E2B
- *  equivalent) and `8vcpu-16gb` (exceeds the account's 8 GiB memory cap) are
- *  not — the guards lean on this so the "no E2B equivalent" decision lives in
- *  exactly one place. */
+/** SESSION default — deliberately one size up from the run default
+ *  (2026-08-13): a session's sandbox carries the full desktop toolbelt
+ *  (VS Code + Chromium + dockerd) plus the KasmVNC encoder at the 60fps
+ *  cap, and that stack swap-thrashes on 4 GiB while the encoder starves on
+ *  2 shared vCPUs. Workflow runs keep DEFAULT_SANDBOX_SIZE — no desktop,
+ *  no toolbelt weight. Sessions bill active time only (parked = storage),
+ *  so the delta applies to active hours, not the fleet. */
+export const SESSION_DEFAULT_SANDBOX_SIZE: SandboxSize = "4vcpu-8gb";
+
+/** E2B's per-sandbox ceiling on the plans we run (e2b.dev/docs/billing —
+ *  Hobby: "8 vCPU / 8 GB"; Pro: the same, "8+" only by arrangement with
+ *  support). Recorded live too: `Template.build` 400s with "Memory can't be
+ *  higher than 8192 MiB" past the memory cap.
+ *
+ *  These two numbers are the ONLY knob for which sizes get an E2B template —
+ *  raise them after E2B raises the account limit and the build matrix (and
+ *  therefore the session picker) widens on its own. */
+export const E2B_MAX_VCPUS = 8;
+export const E2B_MAX_MEMORY_MB = 8192;
+
+/** The E2B sizes we pre-build a template for — DERIVED from the caps, not
+ *  hand-listed, so a new `SANDBOX_MACHINES` entry can never be offered
+ *  without a template or omitted despite fitting. E2B sizing is
+ *  template-baked (no per-create cpu/mem knob), so honouring `resources.size`
+ *  on E2B means ONE pre-built template per size; `infra/e2b-template/build.ts`
+ *  loops exactly this list. The register / invoke / session-spawn / resize
+ *  guards all reject an unsupported E2B size before it can reach a create. */
+export const E2B_TEMPLATE_SIZES: readonly SandboxSize[] = SANDBOX_SIZES.filter(
+  (s) => SANDBOX_MACHINES[s].vcpus <= E2B_MAX_VCPUS
+    && SANDBOX_MACHINES[s].memoryMB <= E2B_MAX_MEMORY_MB,
+);
+
+/** Is `size` one E2B can be built/booted at? False for the sizes past E2B's
+ *  8 vCPU / 8 GiB ceiling (`8vcpu-16gb`, `32vcpu-64gb`) — those run on Vercel.
+ *  The "no E2B equivalent" decision lives in exactly one place: the caps. */
 export function isE2bSupportedSize(size: SandboxSize): boolean {
   return E2B_TEMPLATE_SIZES.includes(size);
 }
 
-/** Machine spec for a SandboxSize, in the shape `Template.build` wants. RAM is
- *  always 2048 MB/vCPU, matching the size name + Vercel parity
- *  (`SANDBOX_VCPUS` × 2048). Used by `infra/e2b-template/build.ts` to stamp the
- *  per-size base + agent-env templates. */
+/** Vercel's fixed memory-per-vCPU ratio. Vercel takes `resources.vcpus` and
+ *  allocates RAM itself at this rate — there is no independent memory knob. */
+export const VERCEL_MEMORY_MB_PER_VCPU = 2048;
+
+/** Is `size` expressible on Vercel? Only when its RAM matches what Vercel
+ *  would allocate for that vCPU count — otherwise asking for it would hand
+ *  the caller a machine that does not match the name (`8vcpu-8gb` would come
+ *  back with 16 GiB). Vercel's own ceiling (32 vCPU, Enterprise) is a plan
+ *  matter, not a shape matter, so it is not encoded here. */
+export function isVercelSupportedSize(size: SandboxSize): boolean {
+  const m = SANDBOX_MACHINES[size];
+  return m.memoryMB === m.vcpus * VERCEL_MEMORY_MB_PER_VCPU;
+}
+
+/** Machine spec for a SandboxSize, in the shape `Template.build` wants. Used
+ *  by `infra/e2b-template/build.ts` to stamp the per-size base + agent-env
+ *  templates. Reads the explicit table rather than deriving RAM from vCPUs —
+ *  `8vcpu-8gb` is deliberately off the 2048 MB/vCPU line. */
 export function e2bMachineSpec(size: SandboxSize): { cpuCount: number; memoryMB: number } {
-  const cpuCount = SANDBOX_VCPUS[size];
-  return { cpuCount, memoryMB: cpuCount * 2048 };
+  const m = SANDBOX_MACHINES[size];
+  return { cpuCount: m.vcpus, memoryMB: m.memoryMB };
+}
+
+/** Human label for a size — "2 vCPU · 4 GB". The wire catalogue carries it so
+ *  the dashboard never has to parse the id back into numbers. */
+export function sandboxSizeLabel(size: SandboxSize): string {
+  const m = SANDBOX_MACHINES[size];
+  return `${m.vcpus} vCPU · ${Math.round(m.memoryMB / 1024)} GB`;
 }
 
 /** Stable E2B template ALIAS for the platform base at a given size

package/src/sandbox.ts

@@ -23,10 +23,18 @@ export { DOT_SEGMENT_PATH_RE2, toVercelNetworkPolicy, toE2bNetwork } from "./san
 
 export type { SandboxSize } from "./sandbox/sizes.js";
 export {
+  SANDBOX_SIZES,
+  SANDBOX_MACHINES,
   SANDBOX_VCPUS,
   DEFAULT_SANDBOX_SIZE,
+  SESSION_DEFAULT_SANDBOX_SIZE,
   E2B_TEMPLATE_SIZES,
+  E2B_MAX_VCPUS,
+  E2B_MAX_MEMORY_MB,
+  VERCEL_MEMORY_MB_PER_VCPU,
   isE2bSupportedSize,
+  isVercelSupportedSize,
+  sandboxSizeLabel,
   e2bMachineSpec,
   e2bBaseTemplate,
   e2bAgentEnvTemplate,

package/src/types/api-conversations.ts

@@ -104,6 +104,9 @@ export interface ConversationMessageRow {
   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 }>;
@@ -167,6 +170,12 @@ export interface ConversationDetail {
    *  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
@@ -251,6 +260,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 +345,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 +391,121 @@ export interface SessionChangeSet {
   truncated: boolean;
   /** Open `factory_file_conflicts` rows from this session's prior merges. */
   openConflicts: number;
+  /** 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;
+  /** 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;
+}
+
+/** 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";
+}
+
+/** `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"];
+}
+
+/** `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"] }>;
+}
+
+/** `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
@@ -435,6 +577,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 +598,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

package/src/types/api-factory.ts

@@ -313,6 +313,27 @@ export interface ApiKey {
  *  shown once at creation, never retrievable again. */
 export interface ApiKeyCreated extends ApiKey { key: string }
 
+/** Options for `GET /api-keys` — the list is bounded and keyset-paginated
+ *  (every run step / session boot mints a key row, so "all keys ever" is
+ *  unbounded by construction). */
+export interface ListApiKeysOptions {
+  /** Page size, 1–200 (server default 100). */
+  limit?:  number;
+  /** `active` = unrevoked + unexpired only; `all` (default) includes
+   *  revoked/expired history. */
+  status?: "active" | "all";
+  /** Opaque cursor from a previous page's `nextCursor`. */
+  cursor?: string;
+}
+
+/** One page of `GET /api-keys`. */
+export interface ApiKeyPage {
+  data:       ApiKey[];
+  hasMore:    boolean;
+  /** Pass as `cursor` to fetch the next page; null on the last page. */
+  nextCursor: string | null;
+}
+
 /** Single rollup row from `GET /api/v1/usage`. */
 export interface UsageRollupRow {
   eventType: string;
@@ -333,7 +354,10 @@ export interface UsageResponse {
 // ── GitHub-linked drive directories (ADR-0030 P1) ───────────────────────────
 
 /** One drive-directory ⇄ GitHub-repo link (`/factories/:slug/repo-links`).
- *  The webhook secret ref is operator plumbing and never on the wire. */
+ *  Multi-branch model: ONE link row per (repo, branch); sibling branches
+ *  of a repo occupy sibling `base@<branch>` placements. The webhook secret
+ *  ref is operator plumbing and never on the wire — `webhookConfigured` /
+ *  `webhookVerifiedAt` carry the honest connect status instead. */
 export interface DriveRepoLink {
   id:            string;
   factoryId:     string;
@@ -343,26 +367,52 @@ export interface DriveRepoLink {
   provider:      string;
   /** "org/repo". */
   repoFullName:  string;
-  /** The GitHub branch drive `main` syncs with. */
+  /** The GitHub branch this link's placement syncs with. */
   trackedBranch: string;
   connectorGrantId: string | null;
   /** v1 links are always 'write' (the round trip is the feature). */
   access:        "read" | "write";
+  /** A webhook secret exists for this link (registration done). NOT proof
+   *  of delivery — that is `webhookVerifiedAt`. */
+  webhookConfigured: boolean;
+  /** When a signed GitHub delivery last PROVED the webhook delivers; null
+   *  = unproven (the link syncs by poll). */
+  webhookVerifiedAt: string | null;
+  /** Two-way sync: drive edits under the prefix push back to the tracked
+   *  branch. ON by default for new links. */
+  pushOutEnabled: boolean;
+  /** Follow-all mode (stamped identically on every sibling link of one
+   *  repo): pushes to NEW branches auto-link them; GitHub branch deletes
+   *  auto-unlink. False = explicit selection. */
+  followAllBranches: boolean;
+  /** Branches follow-all could NOT link (with the reason) — stamped on
+   *  the repo's PRIMARY link row only; empty everywhere else. */
+  autoLinkSkips: Array<{ branch: string; reason: string; at: string }>;
   lastSyncedGitSha:    string | null;
   lastSyncedAcgCommit: string | null;
-  syncState:     "idle" | "syncing" | "diverged" | "reauth_required";
-  visibility:    "team" | "restricted";
+  syncState:     "idle" | "syncing" | "pushing" | "error" | "conflict" | "diverged" | "reauth_required";
+  /** Human-readable detail when syncState is 'error' or 'conflict'. */
+  syncError:     string | null;
   createdBy:     string | null;
   lastSyncedAt:  string | null;
   createdAt:     string;
 }
 
 /** Input for `POST /factories/:slug/repo-links`. Requires the drive to be
- *  graph-authoritative (ADR-0058 Phase 4 promoted) — 409 otherwise. */
+ *  graph-authoritative (ADR-0058 Phase 4 promoted) — 409 otherwise.
+ *  Exactly ONE of `followAllBranches` / `trackedBranches`:
+ *  `followAllBranches: true` (the default connect mode) links EVERY
+ *  branch — default branch primary at the plain `dirPrefix` — and keeps
+ *  following live (new branches auto-link on push, deleted branches
+ *  auto-unlink; capped at 100 branches). Explicit `trackedBranches`:
+ *  index 0 is the PRIMARY and keeps the plain placement; every additional
+ *  branch lands at the sibling `dirPrefix@<sanitized-branch>` placement. */
 export interface CreateDriveRepoLinkInput {
   dirPrefix:     string;
   repoFullName:  string;
-  trackedBranch: string;
+  trackedBranches?: string[];
+  followAllBranches?: boolean;
   connectorGrantId: string;
-  visibility?:   "team" | "restricted";
+  /** Two-way sync ("push-out") — defaults to TRUE for new links. */
+  pushOut?:      boolean;
 }

package/src/types/api-runs.ts

@@ -303,7 +303,8 @@ export interface ListRunsOptions {
   factorySlug?: string;
   /** Substring match on the registered workflow name (`metadata._workflow`). */
   workflow?: string;
-  /** Substring match across title / task title / branch / run id. */
+  /** Substring match across title / task title / branch — or an exact run
+   *  id (full UUID). */
   search?: string;
   outcome?: string;
   sort?: "newest" | "oldest" | "fastest" | "slowest";

package/src/types/workflow-metadata.ts

@@ -154,11 +154,12 @@ export interface InvokePolicy {
  *  today; kept as its own object so finer controls (disk, gpu, …) can be
  *  added later without reshaping `WorkflowMetadata`. */
 export interface SandboxResources {
-  /** Machine hardware SKU — one of the `SandboxSize` vCPU strings
-   *  (`2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`). Maps to
-   *  provider specs at create time (Vercel: 2 / 4 / 8 / 32 vCPU, 2048 MB RAM
-   *  per vCPU). Omit → the smallest SKU. E2B sizing is template-defined and
-   *  ignores this. */
+  /** Machine hardware SKU. The vocabulary is `SANDBOX_SIZES` in
+   *  `sandbox/sizes.ts` — the single source; do not restate it here or
+   *  anywhere else. Maps to provider specs at create time: Vercel takes the
+   *  vCPU count and allocates RAM at 2048 MB/vCPU; E2B has no create-time
+   *  cpu/mem knob at all, so the size selects a PRE-BUILT per-size template
+   *  (`E2B_TEMPLATE_SIZES`). Omit → `DEFAULT_SANDBOX_SIZE`. */
   size?: SandboxSize;
   /** Sandbox provider this workflow's runs execute on — `"vercel"` or
    *  `"e2b"`. Optional and additive: omit and the run resolves to the