@opengeni/contracts 0.2.0 → 0.4.0

package/src/index.ts

@@ -10,9 +10,398 @@ export const SessionStatus = z.enum([
 ]);
 export type SessionStatus = z.infer<typeof SessionStatus>;
 
-export const SandboxBackend = z.enum(["docker", "modal", "local", "none"]);
+// 11 backends; 3-way enum parity (contracts / sdk / deployment) is pinned by
+// `packages/sdk/test/contract-parity.test.ts`. Every member is ADDITIVE AT THE
+// END (the parity test pins positions): the original four, then the six cloud
+// backends, then `selfhosted` (bring-your-own-compute — a user's own machine
+// enrolled as a first-class sandbox).
+export const SandboxBackend = z.enum([
+  "docker",
+  "modal",
+  "local",
+  "none",
+  "daytona",
+  "runloop",
+  "e2b",
+  "blaxel",
+  "cloudflare",
+  "vercel",
+  "selfhosted",
+]);
 export type SandboxBackend = z.infer<typeof SandboxBackend>;
 
+// OS axis. Only "linux" is reachable in v1; macos/windows are seam placeholders.
+export const SandboxOs = z.enum(["linux", "macos", "windows"]);
+export type SandboxOs = z.infer<typeof SandboxOs>;
+
+// The five surfaceable sandbox capabilities (PascalCase, the canonical names).
+export const SandboxCapabilityName = z.enum([
+  "FileSystem", // Channel A: list/read/write/search (Pierre tree)
+  "Terminal", // Channel A: command-output firehose (+ future pty-ws)
+  "Git", // Channel A: status/diff/log/show (Pierre diff)
+  "DesktopStream", // Channel B: noVNC pixels over a scoped tunnel URL
+  "Recording", // ffmpeg x11grab -> object storage
+]);
+export type SandboxCapabilityName = z.infer<typeof SandboxCapabilityName>;
+
+// How a backend exposes a network port to the data plane.
+export type PortExposureKind = "provider-tunnel" | "preview-url" | "local-port" | "none";
+
+// Static per-backend metadata — pure data, no runtime state. This table lives
+// in CONTRACTS (not runtime) so config can read it without an import cycle
+// through runtime (ledger CR8). Everything downstream (config boot-validation,
+// OS image selection, capability negotiation, env/mount branch) reads this
+// data, never a hard-coded backend name.
+export type CapabilityDescriptor = {
+  backend: SandboxBackend;
+  backendId: string; // asserted === SDK client.backendId at registry build (deferred to P0.3)
+  tier: "desktop" | "headless" | "dev" | "none";
+  os: { supported: SandboxOs[]; default: SandboxOs };
+  capabilities: {
+    FileSystem: { available: boolean; readOnly: boolean };
+    Terminal: { available: boolean; transport: "sse-events" | "pty-ws" | null; pty: boolean };
+    Git: { available: boolean };
+    DesktopStream: { available: boolean; transport: "vnc-ws" | "rdp-ws" | "webrtc" | null };
+    // Feasibility only (== DesktopStream.available && os==linux); NOT a request.
+    Recording: { available: boolean };
+  };
+  lifetime: {
+    hardLifetimeMs?: number; // modal 24h, vercel 5h
+    requiresSnapshotRollover: boolean;
+    hasIdleKiller: boolean;
+    supportsSuspendResume: boolean; // runloop/e2b/vercel/modal true
+    resumeIsLockFree: boolean; // modal true (fromId, no lock)
+    idleKillDisableHint?: string;
+  };
+  snapshot: {
+    kind: "native-fs" | "native-dir" | "native-snapshot-id" | "tar-only" | "none";
+    hasTarFallback: boolean;
+  };
+  portExposure: { kind: PortExposureKind; supportsOnDemandPorts: boolean }; // runloop=false; blaxel only true
+  workspaceRoot: string; // os-overridable; per-backend default (providers owns; os defers)
+  nativeBucketMount: boolean; // modal true -> mount/signed-download branch
+  persistable: boolean;
+  supportsRunAs: boolean;
+};
+
+// The websockify/noVNC desktop port that is merged into `exposedPorts` for
+// every desktop-capable (backend, os). Asserted present by boot-validation.
+export const DESKTOP_STREAM_PORT = 6080;
+
+// The ttyd PTY-over-websocket port that is exposed over the SAME Modal raw-TLS
+// tunnel as the desktop, for the REAL interactive terminal (Channel-B-symmetric).
+// ttyd's default; the box bakes ttyd and launches it on this port. The pty-ws
+// Terminal cell's `url` is the tunnel address resolved against this port.
+export const TERMINAL_STREAM_PORT = 7681;
+
+// The Part-D matrix (master-spine PART D + module 03-providers). One row per
+// backend (10 rows). v1 reachable cells are all Linux; macos/windows are seam
+// placeholders (no enum members shipped). Reading rule: a capability cell is
+// `available:false` + a reason in the negotiated doc, never absent.
+export const CAPABILITY_DESCRIPTORS: Record<SandboxBackend, CapabilityDescriptor> = {
+  modal: {
+    backend: "modal",
+    backendId: "modal",
+    tier: "desktop",
+    os: { supported: ["linux"], default: "linux" },
+    capabilities: {
+      FileSystem: { available: true, readOnly: false },
+      Terminal: { available: true, transport: "sse-events", pty: true },
+      Git: { available: true },
+      DesktopStream: { available: true, transport: "vnc-ws" },
+      Recording: { available: true },
+    },
+    lifetime: {
+      hardLifetimeMs: 24 * 60 * 60 * 1000,
+      requiresSnapshotRollover: true,
+      hasIdleKiller: true,
+      supportsSuspendResume: true,
+      resumeIsLockFree: true,
+    },
+    snapshot: { kind: "native-fs", hasTarFallback: true },
+    portExposure: { kind: "provider-tunnel", supportsOnDemandPorts: false }, // pre-declare 6080
+    workspaceRoot: "/workspace",
+    nativeBucketMount: true,
+    persistable: true,
+    supportsRunAs: true,
+  },
+  daytona: {
+    backend: "daytona",
+    backendId: "daytona",
+    tier: "desktop",
+    os: { supported: ["linux"], default: "linux" },
+    capabilities: {
+      FileSystem: { available: true, readOnly: false },
+      Terminal: { available: true, transport: "sse-events", pty: true },
+      Git: { available: true },
+      DesktopStream: { available: true, transport: "vnc-ws" },
+      Recording: { available: true },
+    },
+    lifetime: {
+      requiresSnapshotRollover: false,
+      hasIdleKiller: true,
+      supportsSuspendResume: true,
+      resumeIsLockFree: false,
+    },
+    snapshot: { kind: "native-snapshot-id", hasTarFallback: true },
+    portExposure: { kind: "preview-url", supportsOnDemandPorts: false },
+    workspaceRoot: "/workspace",
+    nativeBucketMount: false,
+    persistable: true,
+    supportsRunAs: true,
+  },
+  runloop: {
+    backend: "runloop",
+    backendId: "runloop",
+    tier: "desktop",
+    os: { supported: ["linux"], default: "linux" },
+    capabilities: {
+      FileSystem: { available: true, readOnly: false },
+      Terminal: { available: true, transport: "sse-events", pty: false },
+      Git: { available: true },
+      DesktopStream: { available: true, transport: "vnc-ws" },
+      Recording: { available: true },
+    },
+    lifetime: {
+      requiresSnapshotRollover: false,
+      hasIdleKiller: true,
+      supportsSuspendResume: true,
+      resumeIsLockFree: false,
+    },
+    snapshot: { kind: "native-snapshot-id", hasTarFallback: true },
+    portExposure: { kind: "provider-tunnel", supportsOnDemandPorts: false }, // CR9: pre-declare 6080
+    workspaceRoot: "/workspace",
+    nativeBucketMount: false,
+    persistable: true,
+    supportsRunAs: false,
+  },
+  e2b: {
+    backend: "e2b",
+    backendId: "e2b",
+    tier: "desktop",
+    os: { supported: ["linux"], default: "linux" },
+    capabilities: {
+      FileSystem: { available: true, readOnly: false },
+      Terminal: { available: true, transport: "sse-events", pty: false }, // pty-until-proven=no
+      Git: { available: true },
+      DesktopStream: { available: true, transport: "vnc-ws" },
+      Recording: { available: true },
+    },
+    lifetime: {
+      requiresSnapshotRollover: false,
+      hasIdleKiller: true,
+      supportsSuspendResume: true,
+      resumeIsLockFree: false,
+    },
+    snapshot: { kind: "native-snapshot-id", hasTarFallback: true },
+    portExposure: { kind: "preview-url", supportsOnDemandPorts: false },
+    workspaceRoot: "/home/user",
+    nativeBucketMount: false,
+    persistable: true,
+    supportsRunAs: false,
+  },
+  blaxel: {
+    backend: "blaxel",
+    backendId: "blaxel",
+    tier: "desktop",
+    os: { supported: ["linux"], default: "linux" },
+    capabilities: {
+      FileSystem: { available: true, readOnly: false },
+      Terminal: { available: true, transport: "sse-events", pty: false }, // pty-until-proven=no
+      Git: { available: true },
+      DesktopStream: { available: true, transport: "vnc-ws" },
+      Recording: { available: true },
+    },
+    lifetime: {
+      requiresSnapshotRollover: false,
+      hasIdleKiller: true,
+      supportsSuspendResume: false,
+      resumeIsLockFree: false,
+    },
+    snapshot: { kind: "tar-only", hasTarFallback: true },
+    portExposure: { kind: "provider-tunnel", supportsOnDemandPorts: true }, // only on-demand backend
+    workspaceRoot: "/workspace",
+    nativeBucketMount: false,
+    persistable: true,
+    supportsRunAs: false,
+  },
+  cloudflare: {
+    backend: "cloudflare",
+    backendId: "cloudflare",
+    tier: "headless",
+    os: { supported: ["linux"], default: "linux" },
+    capabilities: {
+      FileSystem: { available: true, readOnly: false },
+      Terminal: { available: true, transport: "sse-events", pty: true },
+      Git: { available: true },
+      DesktopStream: { available: false, transport: null },
+      Recording: { available: false },
+    },
+    lifetime: {
+      requiresSnapshotRollover: false,
+      hasIdleKiller: true,
+      supportsSuspendResume: false,
+      resumeIsLockFree: false,
+    },
+    snapshot: { kind: "tar-only", hasTarFallback: true },
+    portExposure: { kind: "provider-tunnel", supportsOnDemandPorts: false },
+    workspaceRoot: "/workspace",
+    nativeBucketMount: false,
+    persistable: true,
+    supportsRunAs: true,
+  },
+  vercel: {
+    backend: "vercel",
+    backendId: "vercel",
+    tier: "headless",
+    os: { supported: ["linux"], default: "linux" },
+    capabilities: {
+      FileSystem: { available: true, readOnly: false },
+      Terminal: { available: true, transport: "sse-events", pty: false },
+      Git: { available: true },
+      DesktopStream: { available: false, transport: null },
+      Recording: { available: false },
+    },
+    lifetime: {
+      hardLifetimeMs: 5 * 60 * 60 * 1000,
+      requiresSnapshotRollover: true,
+      hasIdleKiller: true,
+      supportsSuspendResume: true,
+      resumeIsLockFree: false,
+    },
+    snapshot: { kind: "tar-only", hasTarFallback: true },
+    portExposure: { kind: "preview-url", supportsOnDemandPorts: false },
+    workspaceRoot: "/vercel/sandbox",
+    nativeBucketMount: false,
+    persistable: true,
+    supportsRunAs: false,
+  },
+  docker: {
+    backend: "docker",
+    backendId: "docker",
+    tier: "dev",
+    os: { supported: ["linux"], default: "linux" },
+    capabilities: {
+      FileSystem: { available: true, readOnly: false },
+      Terminal: { available: true, transport: "sse-events", pty: true },
+      Git: { available: true },
+      DesktopStream: { available: false, transport: null }, // local
+      Recording: { available: false },
+    },
+    lifetime: {
+      requiresSnapshotRollover: false,
+      hasIdleKiller: false,
+      supportsSuspendResume: false,
+      resumeIsLockFree: true,
+    },
+    snapshot: { kind: "native-dir", hasTarFallback: true },
+    portExposure: { kind: "local-port", supportsOnDemandPorts: false },
+    workspaceRoot: "/workspace",
+    nativeBucketMount: false,
+    persistable: true,
+    supportsRunAs: true,
+  },
+  local: {
+    backend: "local",
+    // The SDK's UnixLocalSandboxClient reports backendId "unix_local" — this MUST
+    // match it (it is the resume-fence field compared against client.backendId).
+    backendId: "unix_local",
+    tier: "dev",
+    os: { supported: ["linux"], default: "linux" },
+    capabilities: {
+      FileSystem: { available: true, readOnly: false },
+      Terminal: { available: true, transport: "sse-events", pty: true },
+      Git: { available: true },
+      DesktopStream: { available: false, transport: null },
+      Recording: { available: false },
+    },
+    lifetime: {
+      requiresSnapshotRollover: false,
+      hasIdleKiller: false,
+      supportsSuspendResume: false,
+      resumeIsLockFree: true,
+    },
+    snapshot: { kind: "native-dir", hasTarFallback: true },
+    portExposure: { kind: "local-port", supportsOnDemandPorts: false },
+    workspaceRoot: "/workspace",
+    nativeBucketMount: false,
+    persistable: false,
+    supportsRunAs: false,
+  },
+  none: {
+    backend: "none",
+    backendId: "none",
+    tier: "none",
+    os: { supported: ["linux"], default: "linux" },
+    capabilities: {
+      FileSystem: { available: false, readOnly: true },
+      Terminal: { available: false, transport: null, pty: false },
+      Git: { available: false },
+      DesktopStream: { available: false, transport: null },
+      Recording: { available: false },
+    },
+    lifetime: {
+      requiresSnapshotRollover: false,
+      hasIdleKiller: false,
+      supportsSuspendResume: false,
+      resumeIsLockFree: true,
+    },
+    snapshot: { kind: "none", hasTarFallback: false },
+    portExposure: { kind: "none", supportsOnDemandPorts: false },
+    workspaceRoot: "/workspace",
+    nativeBucketMount: false,
+    persistable: false,
+    supportsRunAs: false,
+  },
+  // Bring-your-own-compute: the user's OWN machine, enrolled via a Rust agent,
+  // becomes ONE shared whole-machine sandbox (the agent IS the box). It is the
+  // first backend to make macOS/Windows reachable (default linux). Desktop is
+  // capability-PROCLAIMED ("vnc-ws") — the agent serves a native display stack
+  // (Linux X11/Xvfb, macOS CGEvent/ScreenCaptureKit) consent-gated at enroll;
+  // the online/offline/consent/display negotiation lives in select.ts (M3), this
+  // row is the static feasibility ceiling. Always-on (process-lifetime, never
+  // idle-reaped) and NOT persistable — OpenGeni cannot snapshot the user's disk,
+  // so resume = "is the agent's subject live?", never a cold re-create. Ports
+  // surface on-demand through the stateless relay edge, which lands behind the
+  // `resolveExposedPort` swap-seam later; until then it reuses the existing
+  // `provider-tunnel` exposure kind (the relay IS the provider tunnel for the
+  // agent) so no new PortExposureKind literal — and no new switch arms — are
+  // introduced. supportsOnDemandPorts:true: the agent opens a stream channel for
+  // a port on request rather than pre-declaring 6080/7681 at construction.
+  selfhosted: {
+    backend: "selfhosted",
+    backendId: "selfhosted",
+    tier: "desktop",
+    os: { supported: ["linux", "macos", "windows"], default: "linux" },
+    capabilities: {
+      FileSystem: { available: true, readOnly: false },
+      Terminal: { available: true, transport: "pty-ws", pty: true }, // real PTY over the relay
+      Git: { available: true },
+      DesktopStream: { available: true, transport: "vnc-ws" }, // proclaimed; consent-gated at enroll
+      Recording: { available: true }, // boot invariant: == DesktopStream.available
+    },
+    lifetime: {
+      // Whole-machine, always-there: online while the agent process runs, offline
+      // when it stops. The lease is NEVER idle-killed (it's the user's machine,
+      // not a reapable cloud box) and there is nothing to suspend/resume — the
+      // machine simply is or isn't reachable.
+      requiresSnapshotRollover: false,
+      hasIdleKiller: false,
+      supportsSuspendResume: false,
+      resumeIsLockFree: true, // resume = address the live NATS subject; no provider lock
+    },
+    // persistable:false forces snapshot.kind:"none" (the descriptor invariant
+    // `persistable ⇒ snapshot.kind!=="none"`): OpenGeni cannot snapshot the
+    // user's disk — the machine itself is the persistence.
+    snapshot: { kind: "none", hasTarFallback: false },
+    portExposure: { kind: "provider-tunnel", supportsOnDemandPorts: true },
+    workspaceRoot: "/", // agent-reported machine root (the whole machine is the sandbox)
+    nativeBucketMount: false,
+    persistable: false,
+    supportsRunAs: false,
+  },
+};
+
 export const ReasoningEffort = z.enum(["none", "minimal", "low", "medium", "high", "xhigh"]);
 export type ReasoningEffort = z.infer<typeof ReasoningEffort>;
 
@@ -66,8 +455,28 @@ export const Permission = z.enum([
   "sessions:create",
   "sessions:read",
   "sessions:control",
+  // Sandbox-surfacing (master-spine §C.3 / crosscut PART 1.2). stream:view is a
+  // REAL, distinct permission — strictly BROADER than sessions:read — because the
+  // pixel plane (Channel B) is UN-REDACTED: a viewer of raw pixels can see cloud
+  // creds the agent cat's into a terminal, which the redacted Channel-A event log
+  // never exposes. sessions:read is NOT permission to watch raw pixels.
+  "stream:view",
+  // SEPARATE from stream:view: raw input to the desktop (bypasses approvalQueue /
+  // interrupt). NEVER granted by default in v1 (the input plane is OFF —
+  // streamControlEnabled=false); the permission exists so later hardening is a
+  // flag flip, not a redesign.
+  "stream:control",
+  // Accept the pixel-plane secret-leak acknowledgment (consent gate before the
+  // un-redacted desktop URL is handed out).
+  "stream:acknowledge",
   "files:upload",
   "files:read",
+  // Channel-A structured write surface (FS writes / apply-patch); distinct from
+  // files:read so a read-only viewer can't mutate the box filesystem.
+  "files:write",
+  // Attach to an interactive PTY (terminal-as-pty, Channel A); distinct from
+  // sessions:read which only reads the command-output firehose.
+  "terminal:attach",
   "documents:manage",
   "documents:search",
   "scheduled_tasks:manage",
@@ -78,6 +487,13 @@ export const Permission = z.enum([
   "environments:manage",
   "environments:use",
   "goals:manage",
+  // Bring-your-own-compute (M5). enrollments:read lists a workspace's machines;
+  // enrollments:manage approves a device-flow enrollment (the LOUD whole-machine
+  // consent) + revokes a machine. Distinct from sessions/stream perms because an
+  // enrollment grants WHOLE-MACHINE access to a user's own hardware — a high-trust,
+  // admin-shaped action. workspace:admin is the super-wildcard over both.
+  "enrollments:read",
+  "enrollments:manage",
 ]);
 export type Permission = z.infer<typeof Permission>;
 
@@ -196,6 +612,280 @@ export async function verifyDelegatedAccessToken(secret: string, token: string,
   return payload.data;
 }
 
+// --- Enrollment bearer credential (bring-your-own-compute M5, dossier §10.2) ---
+//
+// The signed bearer the agent presents to the control plane after enrollment (the
+// EnrollmentCredentials.bearer the poll returns). REUSES the SAME HMAC envelope as
+// the delegated/stream tokens (base64Url payload + hmacSha256Base64Url) with a
+// distinct `oge_` prefix so it can never be confused with an `ogd_` access token or
+// an `ogs_` stream token. It binds (workspaceId, agentId, enrollmentId) so the
+// control plane can verify the agent owns the subject `agent.<ws>.<id>` it
+// subscribes to. Signed with resolveEnrollmentSigningSecret; the secret value is
+// NEVER logged. The real per-workspace NATS Account creds binding is infra-deferred
+// (M4/relay) — this bearer is the application-tier identity proof.
+export const EnrollmentBearerPayload = z.object({
+  workspaceId: z.string().uuid(),
+  agentId: z.string().uuid(),
+  enrollmentId: z.string().uuid(),
+  // The Account-scoped control-plane subject prefix the agent subscribes to.
+  subjectPrefix: z.string().min(1),
+  exp: z.number().int().positive(),
+});
+export type EnrollmentBearerPayload = z.infer<typeof EnrollmentBearerPayload>;
+
+export async function signEnrollmentBearer(secret: string, payload: EnrollmentBearerPayload): Promise<string> {
+  const encodedPayload = base64UrlEncode(JSON.stringify(EnrollmentBearerPayload.parse(payload)));
+  const signature = await hmacSha256Base64Url(secret, encodedPayload);
+  return `oge_${encodedPayload}.${signature}`;
+}
+
+export async function verifyEnrollmentBearer(secret: string, token: string, nowSeconds = Math.floor(Date.now() / 1000)): Promise<EnrollmentBearerPayload | null> {
+  if (!token.startsWith("oge_")) {
+    return null;
+  }
+  const withoutPrefix = token.slice("oge_".length);
+  const dot = withoutPrefix.lastIndexOf(".");
+  if (dot <= 0) {
+    return null;
+  }
+  const encodedPayload = withoutPrefix.slice(0, dot);
+  const signature = withoutPrefix.slice(dot + 1);
+  const expected = await hmacSha256Base64Url(secret, encodedPayload);
+  if (!constantTimeEqual(signature, expected)) {
+    return null;
+  }
+  const payload = EnrollmentBearerPayload.safeParse(JSON.parse(base64UrlDecode(encodedPayload)));
+  if (!payload.success || payload.data.exp < nowSeconds) {
+    return null;
+  }
+  return payload.data;
+}
+
+// --- Non-interactive enroll token (self-hosted enrollment UX §A2.1) ----------
+//
+// The SHORT-TTL, secret, workspace-scoped token the headless/fleet enroll path
+// presents to /v1/enrollments/token/exchange. The token IS the grant — there is
+// no human approve step — so it is stateless-signed (no DB row): the holder of an
+// unexpired token can enroll ONE machine identity into ONE workspace.
+//
+// It REUSES the SAME HMAC envelope as signEnrollmentBearer (base64Url payload +
+// hmacSha256Base64Url) with a DISTINCT `oget_` prefix and a `typ: "enroll"` claim.
+// DOMAIN SEPARATION: even though it shares the signing secret with the `oge_`
+// bearer, the prefix + typ claim make an enroll token unusable as an `oge_`
+// bearer (verifyEnrollmentBearer's `oge_` prefix check rejects it) and vice-versa
+// (verifyEnrollToken's `oget_` prefix + typ check rejects an `oge_` bearer). The
+// secret value is NEVER logged.
+export const EnrollTokenPayload = z.object({
+  // Domain-separation claim — fixed "enroll" so an `oge_`/`ogd_`/`ogs_` payload (no
+  // typ, or a different typ) can never satisfy verifyEnrollToken even past the prefix.
+  typ: z.literal("enroll"),
+  workspaceId: z.string().uuid(),
+  accountId: z.string().uuid(),
+  // The screen-control consent baked into the token at mint (the minting user's
+  // decision); the exchange records it as consentedScreenControl on the enrollment.
+  allowScreenControl: z.boolean(),
+  iat: z.number().int().nonnegative(),
+  exp: z.number().int().positive(),
+});
+export type EnrollTokenPayload = z.infer<typeof EnrollTokenPayload>;
+
+export async function signEnrollToken(secret: string, payload: EnrollTokenPayload): Promise<string> {
+  const encodedPayload = base64UrlEncode(JSON.stringify(EnrollTokenPayload.parse(payload)));
+  const signature = await hmacSha256Base64Url(secret, encodedPayload);
+  return `oget_${encodedPayload}.${signature}`;
+}
+
+/**
+ * Verify an enroll token: rejects (returns null) on a bad prefix (NOT `oget_`),
+ * a malformed envelope, a bad HMAC signature (constant-time), schema-invalid
+ * claims (which includes `typ !== "enroll"` — the `z.literal` rejects it), or an
+ * expired token (`exp < now`). Mirrors verifyEnrollmentBearer exactly. An `oge_`
+ * bearer fails the prefix gate; a same-secret token that lacks the typ claim fails
+ * the schema gate — both halves of the domain separation are enforced here.
+ */
+export async function verifyEnrollToken(secret: string, token: string, nowSeconds = Math.floor(Date.now() / 1000)): Promise<EnrollTokenPayload | null> {
+  if (!token.startsWith("oget_")) {
+    return null;
+  }
+  const withoutPrefix = token.slice("oget_".length);
+  const dot = withoutPrefix.lastIndexOf(".");
+  if (dot <= 0) {
+    return null;
+  }
+  const encodedPayload = withoutPrefix.slice(0, dot);
+  const signature = withoutPrefix.slice(dot + 1);
+  const expected = await hmacSha256Base64Url(secret, encodedPayload);
+  if (!constantTimeEqual(signature, expected)) {
+    return null;
+  }
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(base64UrlDecode(encodedPayload));
+  } catch {
+    return null;
+  }
+  const payload = EnrollTokenPayload.safeParse(decoded);
+  if (!payload.success || payload.data.exp < nowSeconds) {
+    return null;
+  }
+  return payload.data;
+}
+
+// --- Scoped data-plane stream token (master-spine §C.3 / crosscut PART 1.3) ---
+//
+// REUSES the existing HMAC envelope (sign/verifyDelegatedAccessToken's
+// base64Url + hmacSha256Base64Url) — NOT a second crypto — but with a distinct
+// `ogs_` prefix and a HARD-NARROW claim set. The token is a CLAIM the OpenGeni
+// control plane mints; it is NOT the provider's tunnel secret. The browser
+// receives { providerUrl, streamToken }; the provider tunnel URL is the
+// transport, the streamToken is what the in-box edge validates (websockify
+// TokenFile is later-hardening; in v1 the URL's short TTL + the acknowledged
+// stream:view gate are the real boundary). The token is minted + recorded
+// against the holder from day one. It is NEVER appended to the URL as a query
+// param (the provider's own scoped token already lives in the URL).
+//
+// `leaseEpoch` is the fence: when the box is re-elected (warming→warm bumps the
+// epoch) the URL is re-minted with epoch+1 and the old tunnel is torn down, so a
+// stale token points at a dead tunnel. Epoch mismatch is enforced at USE (by the
+// caller comparing the claim against the live lease), not inside verify.
+export const StreamTokenPayload = z.object({
+  workspaceId: z.string().uuid(),
+  sessionId: z.string().uuid(),
+  // Identifies the sandbox_lease_holders row (the viewer holder).
+  viewerId: z.string().uuid(),
+  // Fence: the token logically dies when the box is re-elected (epoch++).
+  leaseEpoch: z.number().int().nonnegative(),
+  // v1 is always "view"; "control" is the never-granted raw-input plane.
+  mode: z.enum(["view", "control"]),
+  // 6080 (noVNC); pins the token to ONE exposed port.
+  port: z.number().int().positive(),
+  // Short TTL (120s default); rotation is event-driven under the epoch fence,
+  // not on a keepalive clock.
+  exp: z.number().int().positive(),
+});
+export type StreamTokenPayload = z.infer<typeof StreamTokenPayload>;
+
+export async function signStreamToken(secret: string, payload: StreamTokenPayload): Promise<string> {
+  const encodedPayload = base64UrlEncode(JSON.stringify(StreamTokenPayload.parse(payload)));
+  const signature = await hmacSha256Base64Url(secret, encodedPayload);
+  return `ogs_${encodedPayload}.${signature}`;
+}
+
+/**
+ * Verify a stream token: rejects (returns null) on a bad prefix, malformed
+ * envelope, bad HMAC signature (constant-time), schema-invalid claims, or an
+ * expired token (`exp < now`). Mirrors verifyDelegatedAccessToken exactly.
+ *
+ * The epoch fence (claim.leaseEpoch vs the LIVE lease epoch) and the
+ * workspace/session scope are checked by the CALLER at use against the live
+ * lease + route params — verify proves the token is authentic + unexpired, the
+ * caller proves it is for THIS box's current epoch and THIS workspace+session.
+ */
+export async function verifyStreamToken(secret: string, token: string, nowSeconds = Math.floor(Date.now() / 1000)): Promise<StreamTokenPayload | null> {
+  if (!token.startsWith("ogs_")) {
+    return null;
+  }
+  const withoutPrefix = token.slice("ogs_".length);
+  const dot = withoutPrefix.lastIndexOf(".");
+  if (dot <= 0) {
+    return null;
+  }
+  const encodedPayload = withoutPrefix.slice(0, dot);
+  const signature = withoutPrefix.slice(dot + 1);
+  const expected = await hmacSha256Base64Url(secret, encodedPayload);
+  if (!constantTimeEqual(signature, expected)) {
+    return null;
+  }
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(base64UrlDecode(encodedPayload));
+  } catch {
+    return null;
+  }
+  const payload = StreamTokenPayload.safeParse(decoded);
+  if (!payload.success || payload.data.exp < nowSeconds) {
+    return null;
+  }
+  return payload.data;
+}
+
+// --- Relay PRODUCER token (bring-your-own-compute M8b, dossier §10.5) ---
+//
+// The token the AGENT presents to the relay edge when it registers a pty/desktop
+// stream channel (role=AGENT) — distinct from the viewer's `ogs_` token. It is
+// minted by the control plane at enrollment and threaded into EnrollmentCredentials
+// (proto field `relay_token`); the relay verifies it on its own merits, then pairs
+// the producer with the consumer by the shared channel key.
+//
+// REUSES the EXACT SAME HMAC envelope as the `ogs_`/`ogd_`/`oge_` tokens
+// (base64Url JSON payload + hmacSha256Base64Url) — NOT a second crypto — with a
+// distinct `ogr_` prefix so it can never be confused with the others. The claim
+// set binds (workspaceId, agentId): the relay reads the channel-key's ws+agent
+// from the StreamOpen and asserts the producer token claims the SAME pair, so a
+// producer token for workspace A can never register a channel for workspace B.
+// Signed with resolveRelayTokenSecret (the relay-token HMAC secret); the value is
+// NEVER logged. Long-lived by design (it is enrollment-scoped, not per-stream —
+// the agent presents it on every channel registration for the life of the
+// enrollment); the relay additionally validates the channel key + (for the
+// viewer's `ogs_`) the lease/active-epoch fence.
+//
+// The Rust relay re-implements this verify (the same base64url(JSON) + HMAC-SHA256
+// + prefix split) so TS-mint and Rust-verify provably agree — see the cross-stack
+// fixture in agent/crates/opengeni-relay/tests and the relay's `token` module doc.
+export const RelayTokenPayload = z.object({
+  // The workspace the agent (and its channels) belong to — the relay asserts this
+  // equals the channel-key's ws so a producer can only register its own channels.
+  workspaceId: z.string().uuid(),
+  // The agent (machine) id — the relay asserts this equals the channel-key's agent.
+  agentId: z.string().uuid(),
+  // Expiry (unix seconds). Enrollment-scoped horizon (re-minted on re-enroll).
+  exp: z.number().int().positive(),
+});
+export type RelayTokenPayload = z.infer<typeof RelayTokenPayload>;
+
+export async function signRelayToken(secret: string, payload: RelayTokenPayload): Promise<string> {
+  const encodedPayload = base64UrlEncode(JSON.stringify(RelayTokenPayload.parse(payload)));
+  const signature = await hmacSha256Base64Url(secret, encodedPayload);
+  return `ogr_${encodedPayload}.${signature}`;
+}
+
+/**
+ * Verify a relay producer token: rejects (returns null) on a bad prefix, malformed
+ * envelope, bad HMAC signature (constant-time), schema-invalid claims, or expiry.
+ * Mirrors verifyStreamToken exactly. The relay (Rust) re-implements this verify;
+ * the TS verify here proves the format for the cross-stack fixture + any TS caller.
+ *
+ * The channel-key scope (claim.workspaceId/agentId vs the StreamOpen channel key)
+ * is enforced by the relay at USE — verify proves authenticity + freshness only.
+ */
+export async function verifyRelayToken(secret: string, token: string, nowSeconds = Math.floor(Date.now() / 1000)): Promise<RelayTokenPayload | null> {
+  if (!token.startsWith("ogr_")) {
+    return null;
+  }
+  const withoutPrefix = token.slice("ogr_".length);
+  const dot = withoutPrefix.lastIndexOf(".");
+  if (dot <= 0) {
+    return null;
+  }
+  const encodedPayload = withoutPrefix.slice(0, dot);
+  const signature = withoutPrefix.slice(dot + 1);
+  const expected = await hmacSha256Base64Url(secret, encodedPayload);
+  if (!constantTimeEqual(signature, expected)) {
+    return null;
+  }
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(base64UrlDecode(encodedPayload));
+  } catch {
+    return null;
+  }
+  const payload = RelayTokenPayload.safeParse(decoded);
+  if (!payload.success || payload.data.exp < nowSeconds) {
+    return null;
+  }
+  return payload.data;
+}
+
 export const CreateWorkspaceRequest = z.object({
   accountId: z.string().uuid().optional(),
   name: z.string().min(1),
@@ -246,6 +936,38 @@ export const CreateApiKeyResponse = z.object({
 });
 export type CreateApiKeyResponse = z.infer<typeof CreateApiKeyResponse>;
 
+// A person (or API key) with access to a workspace: one workspace_memberships
+// row. `subjectId` is `user:<betterAuthUserId>` or `api_key:<id>`; the People
+// surface lists the `user:` subjects (api_key subjects belong to API keys).
+export const WorkspaceMember = z.object({
+  subjectId: z.string().min(1),
+  subjectLabel: z.string().nullable(),
+  role: z.string(),
+  permissions: z.array(Permission),
+  createdAt: z.string(),
+});
+export type WorkspaceMember = z.infer<typeof WorkspaceMember>;
+
+export const ListWorkspaceMembersResponse = z.object({
+  members: z.array(WorkspaceMember),
+});
+export type ListWorkspaceMembersResponse = z.infer<typeof ListWorkspaceMembersResponse>;
+
+export const AddWorkspaceMemberRequest = z.object({
+  // Resolved against the managed (Better Auth) users; email invites for
+  // not-yet-registered users are deferred, so an unknown email returns 404.
+  email: z.string().email(),
+  role: z.string().min(1).optional(),
+  permissions: z.array(Permission),
+});
+export type AddWorkspaceMemberRequest = z.infer<typeof AddWorkspaceMemberRequest>;
+
+export const UpdateWorkspaceMemberRequest = z.object({
+  role: z.string().min(1).optional(),
+  permissions: z.array(Permission),
+});
+export type UpdateWorkspaceMemberRequest = z.infer<typeof UpdateWorkspaceMemberRequest>;
+
 export const UsageEventType = z.enum([
   "agent_run.created",
   "agent_run.completed",
@@ -256,6 +978,15 @@ export const UsageEventType = z.enum([
   "document.indexed",
   "scheduled_task.fired",
   "api_key.request",
+  // --- sandbox warm-time metering (P2.1) ---
+  // Wall-clock seconds a box was warm — the billable warm-time meter. Accrued on
+  // the two stateless ticks (turn heartbeat + reaper sweep), idempotent on
+  // (sandbox_group_id, lease_epoch, tick) so a shared box (N sessions) is metered
+  // EXACTLY ONCE per tick (N sessions != N x bill). Orthogonal to model.tokens /
+  // model.cost (model API cost vs provider compute cost — both real, no overlap).
+  "sandbox.warm_seconds",
+  // usd_micros: warm-seconds x the per-provider per-second warm rate.
+  "sandbox.warm_cost",
 ]);
 export type UsageEventType = z.infer<typeof UsageEventType>;
 
@@ -312,6 +1043,155 @@ export const LimitDecision = z.discriminatedUnion("allowed", [
 ]);
 export type LimitDecision = z.infer<typeof LimitDecision>;
 
+// ============ P3 — Entitlements port (§7.5) ============
+//
+// The host-providable admission seam over OpenGeni's TWO existing admission
+// sites: the API edge (`checkLimit`/`requireLimit`, billing/limits.ts) AND the
+// worker edge (`ensureRunAllowed`, agent-turn.ts — both turn-entry and the
+// mid-stream budget valve). A host that owns its OWN ledger/meter binds this to
+// keep OpenGeni from re-deriving admission from its local ledger.
+//
+// CRITICAL CONTRACT: `admitRun` returns a transport-neutral allow/deny decision
+// (+ optional structured reason + the echoed quantity it admitted) and NEVER
+// exposes `getBillingBalance` or any ledger internals — the host's balance math
+// stays on the host side of the boundary. This is what lets the same port serve
+// both PUSH (host funds OpenGeni's ledger; admission is a LOCAL read of that
+// funded ledger) and PULL (a network callback to the host's own meter).
+//
+// `action` is a free `string` (NOT the internal `LimitAction` enum) so a host
+// meter can key on actions OpenGeni does not model. `quantity` is the units the
+// caller is about to consume (tokens, bytes, 1 run, …); the decision MAY echo
+// the admitted quantity so a PULL host can grant a partial allowance.
+export const EntitlementDecision = z.discriminatedUnion("allowed", [
+  z.object({ allowed: z.literal(true), quantity: z.number().optional() }),
+  z.object({ allowed: z.literal(false), reason: z.string(), code: z.string().optional(), quantity: z.number().optional() }),
+]);
+export type EntitlementDecision = z.infer<typeof EntitlementDecision>;
+
+export type AdmitRunInput = {
+  accountId: string;
+  workspaceId: string;
+  action: string;
+  quantity: number;
+};
+
+export type EntitlementsPort = {
+  admitRun(input: AdmitRunInput): Promise<EntitlementDecision>;
+};
+
+// ============ P4a — Connection-credential provider (§7.6) ============
+//
+// The host-providable per-run credential-mint seam over OpenGeni's TWO
+// run-scoped credential sites in the worker:
+//   - GIT credentials: the GitHub App installation token minted in
+//     `sandboxEnvironmentForRun` (today `createGitHubAppInstallationToken`
+//     from `settings`) and injected as `GH_TOKEN`/`GITHUB_TOKEN`/the git
+//     extraheader.
+//   - SANDBOX secrets: the decrypted workspace environment values loaded in
+//     `loadWorkspaceEnvironmentForRun` (today decrypted with
+//     `environmentsEncryptionKeyBytes(settings)`).
+//
+// In embedded/separate topologies the HOST owns these external connections
+// (its GitHub App, its secret vault + encryption key). When a host binds this
+// port, OpenGeni asks the host to mint/decrypt per-run instead of self-minting
+// from `settings`. Unset (standalone default) → byte-for-byte today's
+// self-mint.
+//
+// FORK-7 CROSS-CHECK (the host-mapping safety guardrail): a credential
+// provider returns the `workspaceId` it scoped the credential to, and the
+// activity ASSERTS it agrees with the run's workspace BEFORE injecting
+// `GH_TOKEN` (or applying the decrypted values). A host mapping bug that
+// returns tenant B's creds while the run is tenant A is thereby caught at the
+// seam, never silently injected into tenant A's sandbox.
+
+export type GitCredentialsRequest = {
+  accountId: string;
+  workspaceId: string;
+  // The GitHub App installation the run's repository resources resolved to,
+  // and the specific repositories the token must be scoped to. Mirrors the
+  // shape `createGitHubAppInstallationToken` consumes today.
+  installationId: number;
+  repositoryIds: number[];
+};
+
+export type GitCredentials = {
+  // The minted installation token the activity injects as GH_TOKEN/GITHUB_TOKEN
+  // and into the git http extraheader (identical downstream handling to the
+  // self-mint path).
+  token: string;
+  // FORK-7 echo: the workspace the provider scoped this token to. The activity
+  // asserts `workspaceId === request.workspaceId` before injecting.
+  workspaceId: string;
+  // Optional git identity override. When omitted the activity falls back to
+  // today's `githubAppBotIdentity(settings)`.
+  identity?: { name: string; email: string } | null;
+};
+
+export type SandboxSecretsRequest = {
+  accountId: string;
+  workspaceId: string;
+  // The workspace environment the run's session declares (null = unattached;
+  // the provider, like the self-mint path, returns null values for it).
+  environmentId: string;
+};
+
+export type SandboxSecrets = {
+  // The decrypted environment values the run injects, replacing the local
+  // `environmentsEncryptionKeyBytes` decrypt. Same shape the self-mint path
+  // produces (plaintext name→value).
+  values: Record<string, string>;
+  // FORK-7 echo: the workspace the provider scoped these secrets to.
+  workspaceId: string;
+  // Optional environment metadata; when omitted the activity uses the
+  // environmentId as both id and name (the local decrypt carries the row's
+  // id/name/description, but only `id` is load-bearing downstream).
+  id?: string;
+  name?: string;
+  description?: string | null;
+};
+
+export type ConnectionCredentialsPort = {
+  // Both legs are optional: a host may drive ONLY git creds (BYO-GitHub-App)
+  // and leave sandbox secrets to OpenGeni's local decrypt, or vice-versa. An
+  // unset leg falls through to today's self-mint for THAT leg only.
+  gitCredentials?: (input: GitCredentialsRequest) => Promise<GitCredentials>;
+  sandboxSecrets?: (input: SandboxSecretsRequest) => Promise<SandboxSecrets>;
+};
+
+// ============ P4a — GitHub App API port (BYO-App, §7.6 / SPIKE-2 remainder) ===
+//
+// The host-driven GitHub-API credential leg. SPIKE-2 closed the establishment +
+// gate (storage) axis; this closes the credential leg by making the two live
+// GitHub-API calls host-PROVIDABLE so a BYO-GitHub-App host drives its OWN App
+// credentials (its own JWT-signing key, its own OAuth client) instead of
+// OpenGeni self-minting from `settings`:
+//   - verifyInstallationAccessForUser: the OAuth code→token + installation
+//     lookup that PROVES the install is real (today
+//     `verifyGitHubInstallationAccessForUser(settings, …)`).
+//   - listRepositories: the installation-scoped repo listing behind
+//     `GET /v1/workspaces/:id/github/repositories` (today
+//     `listGitHubAppRepositories(settings, …)`).
+//
+// Unset (standalone default) → today's `settings`-based self-mint runs
+// byte-for-byte (the live GitHub-API verify/list against OpenGeni's own App).
+
+export type GitHubInstallationSummary = {
+  installationId: number;
+  accountLogin: string | null;
+  accountType: string | null;
+  suspended: boolean;
+};
+
+export type GitHubAppApiPort = {
+  verifyInstallationAccessForUser?: (input: {
+    code: string;
+    installationId: number;
+  }) => Promise<GitHubInstallationSummary>;
+  listRepositories?: (input: {
+    installationIds?: number[];
+  }) => Promise<GitHubRepository[]>;
+};
+
 export const BillingBalance = z.object({
   accountId: z.string().uuid(),
   balanceMicros: z.number().int(),
@@ -471,6 +1351,16 @@ export type DocumentSearchRequest = z.infer<typeof DocumentSearchRequest>;
 export const ToolRef = z.object({
   kind: z.literal("mcp"),
   id: z.string().min(1),
+  // Non-fatal-on-connect marker for an AUTO-ATTACHED (workspace-default)
+  // capability MCP server: when true, a connect / tools-list failure (e.g. an
+  // expired capability credential returning 401) must SKIP that server with a
+  // logged warning and let the turn proceed, rather than failing the whole
+  // turn before the model runs. Absent/false ⇒ STRICT: an unavailable server
+  // fails the turn (the contract for EXPLICITLY-requested tools). This flag is
+  // set server-side only, at the default-capability auto-attach seam; it is
+  // stripped from client-supplied tool refs so an explicit request always
+  // stays strict.
+  optional: z.boolean().optional(),
 });
 export type ToolRef = z.infer<typeof ToolRef>;
 
@@ -482,17 +1372,26 @@ export class ResourceRefConflictError extends Error {
 }
 
 export function mergeToolRefs(existing: ToolRef[], additions: ToolRef[]): ToolRef[] {
-  const seen = new Set<string>();
-  const out: ToolRef[] = [];
+  const byKey = new Map<string, ToolRef>();
+  const order: string[] = [];
   for (const tool of [...existing, ...additions]) {
     const key = `${tool.kind}:${tool.id}`;
-    if (seen.has(key)) {
+    const prior = byKey.get(key);
+    if (!prior) {
+      byKey.set(key, tool);
+      order.push(key);
       continue;
     }
-    seen.add(key);
-    out.push(tool);
+    // Strict wins: if the same server appears both auto-attached (optional) and
+    // explicitly requested (non-optional), the explicit occurrence upgrades the
+    // merged ref to strict — a later explicit request of an already-defaulted
+    // capability MCP must still fail the turn when the server is unavailable.
+    if (prior.optional === true && tool.optional !== true) {
+      const { optional: _dropped, ...strict } = prior;
+      byKey.set(key, strict);
+    }
   }
-  return out;
+  return order.map((key) => byKey.get(key)!);
 }
 
 export function mergeResourceRefs(
@@ -616,6 +1515,11 @@ export const UpdateSessionGoalRequest = z.object({
 });
 export type UpdateSessionGoalRequest = z.infer<typeof UpdateSessionGoalRequest>;
 
+export const UpdateSessionRequest = z.object({
+  title: z.string().min(1).max(200),
+});
+export type UpdateSessionRequest = z.infer<typeof UpdateSessionRequest>;
+
 // Operator context controls (slash-command palette: /clear, /compact). These
 // are session/operator actions, NOT a structured way to talk to the agent —
 // the human↔agent channel stays plain chat. Both require `sessions:control`.
@@ -694,6 +1598,8 @@ export const SessionTurn = z.object({
   model: z.string().min(1),
   reasoningEffort: ReasoningEffort,
   sandboxBackend: SandboxBackend,
+  // Per-turn OS override. NULL = inherit the session's sandboxOs.
+  sandboxOs: SandboxOs.nullable(),
   metadata: z.record(z.string(), z.unknown()),
   startedAt: z.string().nullable(),
   finishedAt: z.string().nullable(),
@@ -1237,11 +2143,26 @@ export const Session = z.object({
   accountId: z.string().uuid(),
   status: SessionStatus,
   initialMessage: z.string(),
+  title: z.string().nullable(),
+  titleSource: z.enum(["user", "agent"]).nullable(),
   resources: z.array(ResourceRef),
   tools: z.array(ToolRef),
   metadata: z.record(z.string(), z.unknown()),
   model: z.string(),
   sandboxBackend: SandboxBackend,
+  // The OS the session's box runs. Defaults to 'linux' (today's only OS).
+  sandboxOs: SandboxOs,
+  // The shared-sandbox group the session's box belongs to. Equals the session's
+  // own id for a singleton group (today's 1:1 default); equals the parent's
+  // group when spawned shared (both sessions run in ONE box).
+  sandboxGroupId: z.string().uuid(),
+  // The first-class swappable-sandbox POINTER (bring-your-own-compute M2). NULL
+  // resolves to the session's own group sandbox (the backward-compat default);
+  // a swap sets it to the target sandbox row. active_epoch is the second epoch
+  // ABOVE the lease epoch, bumped on every swap so the routing proxy can fence a
+  // stale in-flight op and retry against the new active sandbox.
+  activeSandboxId: z.string().uuid().nullable(),
+  activeEpoch: z.number().int().nonnegative(),
   environmentId: z.string().uuid().nullable(),
   // Non-default first-party MCP token permissions (manager-style sessions);
   // null means the fixed worker default set.
@@ -1262,6 +2183,12 @@ export const Session = z.object({
   // signal. Null until a turn with usage has completed.
   lastInputTokens: z.number().int().nonnegative().nullable(),
   lastSequence: z.number().int().nonnegative(),
+  // Multi-account Codex (P1). codexPinnedCredentialId: the account this session is
+  // manually PINNED to (null ⇒ follow the workspace active pointer).
+  // codexLastCredentialId: the account the most recent turn actually ran on (the
+  // "Running on:" indicator's source). Both are credential-row ids, null until set.
+  codexPinnedCredentialId: z.string().uuid().nullable(),
+  codexLastCredentialId: z.string().uuid().nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -1300,9 +2227,502 @@ export const SessionEventType = z.enum([
   "goal.paused",
   "goal.resumed",
   "goal.continuation",
+  // Channel-B desktop pixel-plane signals (07-channel-b §1.2). The pixel socket
+  // carries opaque RFB and cannot carry a control message the client can act on,
+  // so these ride the durable, sequenced, gap-filled Channel-A SSE spine.
+  "stream.url.rotated", // re-minted {url,token,expiresAt} on box rollover (event-driven)
+  "stream.opened", // a viewer attached (audit + refcount visibility)
+  "stream.closed", // a viewer detached / was reaped
+  "stream.revoked", // a grant was revoked → connected clients MUST disconnect now
+  // Channel-B recording signals (P4.3 / module 05 §3.4). The "agent films itself
+  // proving the fix" loop: ffmpeg x11grab of the SAME :0 humans watch → artifact
+  // → storage. The artifact ref rides the AVAILABLE event (storageKey, NOT a
+  // long-lived URL — clients mint a short-TTL signed GET via the route).
+  "recording.started", // ffmpeg launched on :0 (mode/codec/dimensions)
+  "recording.available", // finalized: bytes PUT to storage, replayable
+  "recording.failed", // ffmpeg/box-death/rollover/upload error — no artifact
+  // Channel-A structured-service notifications (P4.4 / modules/08-channel-a.md
+  // §2.2). The A2 reads (fs/git/terminal exec) are SYNCHRONOUS API-direct point
+  // queries (their result is the HTTP response, NEVER an event). What rides A1
+  // here are the side-effect NOTIFICATIONS — a path changed, git state changed,
+  // a pty opened/printed/exited — durable, sequenced, gap-filled like every
+  // other session event, so any viewer's Pierre tree / diff / terminal stays
+  // live. fs.changed/git.changed are cache-invalidation signals; the pty.*
+  // events carry the interactive terminal byte stream.
+  "fs.changed", // a path was created/modified/deleted (write or agent mutation)
+  "git.changed", // working-tree/index/HEAD changed (debounced re-probe)
+  "terminal.pty.started", // an interactive PTY session opened (carries ptyId)
+  "terminal.pty.output.delta", // PTY stdout/stderr bytes (separate from command.output)
+  "terminal.pty.exited", // PTY session ended (exitCode/reason)
+  "session.title_set",
+  // Multi-account Codex (P1): the account a session's turn runs on changed
+  // (manual switch in P1; failover/rotation in P3 reuse the same event). Drives
+  // the in-session "Running on:" indicator's live flip.
+  "codex.account.switched",
 ]);
 export type SessionEventType = z.infer<typeof SessionEventType>;
 
+// Channel-B stream-event payloads (07-channel-b §1.2). SessionEvent.payload is
+// z.unknown() (NOT a discriminated union) — these are standalone schemas parsed
+// explicitly at the producer (the API-direct handshake/rotation) and the SDK/
+// React consumer. The rotation payload carries the freshly-minted data-plane URL
+// + the scoped stream token so a connected client hot-swaps its noVNC socket.
+export const StreamUrlRotatedPayload = z.object({
+  url: z.string().url(),
+  token: z.string().nullable(),
+  expiresAt: z.string().datetime().nullable(),
+  // The epoch the new URL was minted under (the box-rollover fence the client
+  // reconciles against). A client must drop a rotation event whose epoch it has
+  // already advanced past.
+  leaseEpoch: z.number().int().nonnegative(),
+  transport: z.literal("vnc-ws"),
+  // The viewer holder this URL is for (so a client filters out other viewers').
+  viewerId: z.string().uuid().nullable().default(null),
+});
+export type StreamUrlRotatedPayload = z.infer<typeof StreamUrlRotatedPayload>;
+
+export const StreamOpenedPayload = z.object({
+  viewerId: z.string().uuid(),
+  shared: z.boolean().default(false),
+  viewerCount: z.number().int().nonnegative(),
+});
+export type StreamOpenedPayload = z.infer<typeof StreamOpenedPayload>;
+
+export const StreamClosedPayload = z.object({
+  viewerId: z.string().uuid(),
+  reason: z.enum(["client-disconnect", "reaped", "revoked", "box-rollover"]),
+  viewerCount: z.number().int().nonnegative(),
+});
+export type StreamClosedPayload = z.infer<typeof StreamClosedPayload>;
+
+export const StreamRevokedPayload = z.object({
+  viewerId: z.string().uuid().nullable().default(null),
+  reason: z.enum(["grant-revoked", "session-failed", "admin"]),
+});
+export type StreamRevokedPayload = z.infer<typeof StreamRevokedPayload>;
+
+// ── Recording payloads (P4.3 / module 05 §3.4) ──────────────────────────────
+// SessionEvent.payload is z.unknown() (NOT a discriminated union) — these are
+// standalone schemas parsed explicitly at the producer (the recording activity)
+// and the SDK/React consumer. The codec/contentType pair stays consistent
+// (h264-mp4↔video/mp4, vp9-webm↔video/webm).
+export const RecordingMode = z.enum(["manual", "on-turn", "on-verify"]);
+export type RecordingMode = z.infer<typeof RecordingMode>;
+export const RecordingCodec = z.enum(["h264-mp4", "vp9-webm"]);
+export type RecordingCodec = z.infer<typeof RecordingCodec>;
+export const RecordingContentType = z.enum(["video/mp4", "video/webm"]);
+export type RecordingContentType = z.infer<typeof RecordingContentType>;
+
+export const RecordingStartedPayload = z.object({
+  recordingId: z.string().uuid(),
+  turnId: z.string().uuid().nullable(),
+  mode: RecordingMode,
+  codec: RecordingCodec,
+  dimensions: z.tuple([z.number().int().positive(), z.number().int().positive()]),
+  framerate: z.number().int().positive(),
+  startedAt: z.string(), // ISO
+  // The verification rationale ("agent-verification: tf apply succeeded"). Agent-
+  // authored free text — the producer caps + scrubs it before emit.
+  reason: z.string().nullable().optional(),
+});
+export type RecordingStartedPayload = z.infer<typeof RecordingStartedPayload>;
+
+export const RecordingAvailablePayload = z.object({
+  recordingId: z.string().uuid(),
+  turnId: z.string().uuid().nullable(),
+  codec: RecordingCodec,
+  contentType: RecordingContentType,
+  // The @opengeni/storage object key. NO long-lived URL in the event — clients
+  // mint a short-TTL signed GET via GET …/recordings/:id/url.
+  storageKey: z.string(),
+  durationSeconds: z.number().nonnegative().nullable(),
+  sizeBytes: z.number().int().nonnegative(),
+  dimensions: z.tuple([z.number().int().positive(), z.number().int().positive()]),
+});
+export type RecordingAvailablePayload = z.infer<typeof RecordingAvailablePayload>;
+
+// `max-bytes-exceeded` is distinct from `timeout` (the -t ceiling hitting is a
+// SUCCESSFUL finalize, never a failure) — the adversarial-review F7 fix.
+export const RecordingFailedReason = z.enum([
+  "ffmpeg-error",
+  "box-death",
+  "box-rollover",
+  "upload-failed",
+  "max-bytes-exceeded",
+  "display-unavailable",
+]);
+export type RecordingFailedReason = z.infer<typeof RecordingFailedReason>;
+
+export const RecordingFailedPayload = z.object({
+  recordingId: z.string().uuid(),
+  turnId: z.string().uuid().nullable(),
+  reason: RecordingFailedReason,
+  // ffmpeg-stderr tail / error detail — agent/ffmpeg-controlled, so the producer
+  // caps + scrubs it before emit (it rides redact() like every payload).
+  detail: z.string().nullable().optional(),
+});
+export type RecordingFailedPayload = z.infer<typeof RecordingFailedPayload>;
+
+// ── Channel-A structured services (P4.4 / modules/08-channel-a.md) ───────────
+// Two transports on one spine: the A2 request/response shapes (FsNode tree,
+// GitDiff hunks, terminal exec) are returned INLINE on synchronous API-direct
+// routes (never the bus); the A1 notification payloads below ride the durable
+// SSE event log so every viewer's Pierre tree / diff / terminal stays live.
+
+// --- A1 event payloads -------------------------------------------------------
+
+// The agent's command-output firehose, enriched. Backward-compatible widening
+// of the existing sandbox.command.output.delta (consumers read `chunk`); the
+// producer may now also stamp stream/commandId/seq for finer terminal rendering.
+export const SandboxCommandOutputDeltaPayload = z.object({
+  stream: z.enum(["stdout", "stderr"]).default("stdout"),
+  chunk: z.string(), // raw bytes, utf-8 (lossy) — terminal is opaque-ish
+  commandId: z.string().optional(), // groups deltas to one agent command
+  seq: z.number().int().nonnegative().optional(), // intra-command ordering hint
+});
+export type SandboxCommandOutputDeltaPayload = z.infer<typeof SandboxCommandOutputDeltaPayload>;
+
+export const FsChangeKind = z.enum(["created", "modified", "deleted", "renamed"]);
+export type FsChangeKind = z.infer<typeof FsChangeKind>;
+export const FsChangedPayload = z.object({
+  changes: z.array(z.object({
+    path: z.string(), // workspace-relative POSIX path
+    kind: FsChangeKind,
+    isDir: z.boolean().default(false),
+    sizeBytes: z.number().int().nonnegative().nullable().default(null),
+    oldPath: z.string().optional(), // for "renamed"
+  })).min(1),
+  source: z.enum(["write", "watch", "agent"]).default("write"),
+  // Monotonic FS revision (per-lease, paired with leaseEpoch for staleness).
+  revision: z.number().int().nonnegative(),
+  // The lease epoch the revision was minted under: a client invalidates on a
+  // (leaseEpoch, revision) tuple change, never a bare revision compare (H3 —
+  // revision resets to 0 on box re-key, so a bare monotonic compare goes stale).
+  leaseEpoch: z.number().int().nonnegative().default(0),
+});
+export type FsChangedPayload = z.infer<typeof FsChangedPayload>;
+
+export const GitChangedPayload = z.object({
+  head: z.string().nullable(), // current branch or detached SHA
+  dirty: z.boolean(), // working tree has uncommitted changes
+  ahead: z.number().int().nonnegative().default(0),
+  behind: z.number().int().nonnegative().default(0),
+  changedFileCount: z.number().int().nonnegative(),
+  reason: z.enum(["commit", "checkout", "stage", "worktree", "fetch", "unknown"]).default("unknown"),
+  revision: z.number().int().nonnegative().default(0),
+  leaseEpoch: z.number().int().nonnegative().default(0),
+});
+export type GitChangedPayload = z.infer<typeof GitChangedPayload>;
+
+export const TerminalPtyStartedPayload = z.object({
+  ptyId: z.string().uuid(),
+  cols: z.number().int().positive(),
+  rows: z.number().int().positive(),
+  shell: z.string(), // resolved shell, e.g. "/bin/bash"
+  cwd: z.string(),
+});
+export type TerminalPtyStartedPayload = z.infer<typeof TerminalPtyStartedPayload>;
+
+export const TerminalPtyOutputDeltaPayload = z.object({
+  ptyId: z.string().uuid(),
+  stream: z.enum(["stdout", "stderr"]).default("stdout"),
+  chunk: z.string(), // raw terminal bytes (incl. ANSI), utf-8 lossy
+  seq: z.number().int().nonnegative(), // strict per-pty ordering (owner-assigned)
+});
+export type TerminalPtyOutputDeltaPayload = z.infer<typeof TerminalPtyOutputDeltaPayload>;
+
+export const TerminalPtyExitedPayload = z.object({
+  ptyId: z.string().uuid(),
+  exitCode: z.number().int().nullable(),
+  reason: z.enum(["exit", "killed", "owner_gone", "timeout"]),
+});
+export type TerminalPtyExitedPayload = z.infer<typeof TerminalPtyExitedPayload>;
+
+// --- A2 FileSystem request/response (NOT events; returned inline) ------------
+export const FsNodeType = z.enum(["file", "dir", "symlink", "other"]);
+export type FsNodeType = z.infer<typeof FsNodeType>;
+// The Pierre-tree node. `children` is present only when the dir was listed with
+// depth>0; the tree lazy-expands via repeated depth-1 lists at deeper paths.
+export interface FsTreeNode {
+  name: string;
+  path: string; // workspace-relative POSIX, no leading slash
+  type: z.infer<typeof FsNodeType>;
+  sizeBytes: number | null; // null for dirs
+  mtimeMs: number | null;
+  mode: number | null; // unix mode bits, for Pierre tree icons/perms
+  children?: FsTreeNode[] | undefined;
+  truncated: boolean; // dir had more entries than the cap
+}
+export const FsTreeNode: z.ZodType<FsTreeNode> = z.lazy(() => z.object({
+  name: z.string(),
+  path: z.string(),
+  type: FsNodeType,
+  sizeBytes: z.number().int().nonnegative().nullable(),
+  mtimeMs: z.number().int().nonnegative().nullable(),
+  mode: z.number().int().nullable(),
+  children: z.array(FsTreeNode).optional(),
+  truncated: z.boolean().default(false),
+})) as z.ZodType<FsTreeNode>;
+
+export const FsListRequest = z.object({
+  path: z.string().default(""), // "" = workspace root
+  depth: z.number().int().min(0).max(8).default(1),
+  maxEntries: z.number().int().positive().max(20_000).default(2_000),
+  includeHidden: z.boolean().default(true),
+});
+export type FsListRequest = z.infer<typeof FsListRequest>;
+export const FsListResponse = z.object({
+  root: FsTreeNode,
+  revision: z.number().int().nonnegative(),
+  truncated: z.boolean(), // global cap hit
+});
+export type FsListResponse = z.infer<typeof FsListResponse>;
+
+export const FsEncoding = z.enum(["utf8", "base64"]);
+export type FsEncoding = z.infer<typeof FsEncoding>;
+export const FsReadRequest = z.object({
+  path: z.string(),
+  encoding: FsEncoding.default("utf8"),
+  maxBytes: z.number().int().positive().max(25 * 1024 * 1024).default(5 * 1024 * 1024),
+});
+export type FsReadRequest = z.infer<typeof FsReadRequest>;
+export const FsReadResponse = z.object({
+  path: z.string(),
+  encoding: FsEncoding,
+  content: z.string(), // text or base64 per encoding
+  sizeBytes: z.number().int().nonnegative(), // bytes returned (== content size)
+  truncated: z.boolean(), // sizeBytes hit maxBytes; content is the prefix
+  isBinary: z.boolean(), // sniffed NUL byte in first 8KB
+  revision: z.number().int().nonnegative(),
+});
+export type FsReadResponse = z.infer<typeof FsReadResponse>;
+
+export const FsWriteRequest = z.object({
+  path: z.string(),
+  encoding: FsEncoding.default("utf8"),
+  content: z.string(),
+  overwrite: z.boolean().default(true), // false + existing path => 409
+  createParents: z.boolean().default(true),
+});
+export type FsWriteRequest = z.infer<typeof FsWriteRequest>;
+export const FsWriteResponse = z.object({
+  path: z.string(),
+  sizeBytes: z.number().int().nonnegative(),
+  revision: z.number().int().nonnegative(), // == the fs.changed revision
+});
+export type FsWriteResponse = z.infer<typeof FsWriteResponse>;
+
+export const FsDeleteRequest = z.object({
+  path: z.string(),
+  recursive: z.boolean().default(false), // required true to delete a non-empty dir
+});
+export type FsDeleteRequest = z.infer<typeof FsDeleteRequest>;
+export const FsDeleteResponse = z.object({ revision: z.number().int().nonnegative() });
+export type FsDeleteResponse = z.infer<typeof FsDeleteResponse>;
+
+export const FsMoveRequest = z.object({
+  path: z.string(),
+  newPath: z.string(),
+  overwrite: z.boolean().default(false), // false + existing destination => 409
+  createParents: z.boolean().default(true),
+});
+export type FsMoveRequest = z.infer<typeof FsMoveRequest>;
+export const FsMoveResponse = z.object({
+  path: z.string(),
+  newPath: z.string(),
+  revision: z.number().int().nonnegative(), // == the fs.changed revision
+});
+export type FsMoveResponse = z.infer<typeof FsMoveResponse>;
+
+export const FsMkdirRequest = z.object({
+  path: z.string(),
+  recursive: z.boolean().default(true), // false + existing path => 400
+});
+export type FsMkdirRequest = z.infer<typeof FsMkdirRequest>;
+export const FsMkdirResponse = z.object({
+  path: z.string(),
+  revision: z.number().int().nonnegative(), // == the fs.changed revision
+});
+export type FsMkdirResponse = z.infer<typeof FsMkdirResponse>;
+
+// --- A2 Git request/response (read-only; feeds Pierre diff/tree) -------------
+export const GitFileStatusCode = z.enum([
+  "added", "modified", "deleted", "renamed", "copied", "untracked", "ignored", "conflicted", "typechange",
+]);
+export type GitFileStatusCode = z.infer<typeof GitFileStatusCode>;
+export const GitFileStatus = z.object({
+  path: z.string(),
+  oldPath: z.string().nullable(), // for renamed/copied
+  index: GitFileStatusCode.nullable(), // staged change (X in porcelain XY)
+  worktree: GitFileStatusCode.nullable(), // unstaged change (Y in porcelain XY)
+  isConflicted: z.boolean().default(false),
+});
+export type GitFileStatus = z.infer<typeof GitFileStatus>;
+export const GitStatusRequest = z.object({
+  path: z.string().default(""), // repo root within workspace (multi-repo support)
+});
+export type GitStatusRequest = z.infer<typeof GitStatusRequest>;
+export const GitStatusResponse = z.object({
+  isRepo: z.boolean(),
+  head: z.string().nullable(), // branch name
+  detached: z.boolean().default(false),
+  upstream: z.string().nullable(),
+  ahead: z.number().int().nonnegative().default(0),
+  behind: z.number().int().nonnegative().default(0),
+  files: z.array(GitFileStatus),
+  revision: z.number().int().nonnegative(),
+});
+export type GitStatusResponse = z.infer<typeof GitStatusResponse>;
+
+// The structured hunk shape that feeds Pierre diff — the whole point of Git.
+export const GitDiffLineType = z.enum(["context", "add", "del", "meta"]);
+export type GitDiffLineType = z.infer<typeof GitDiffLineType>;
+export const GitDiffLine = z.object({
+  type: GitDiffLineType,
+  // null on the side that doesn't have the line (add => oldNo null; del => newNo null)
+  oldNo: z.number().int().positive().nullable(),
+  newNo: z.number().int().positive().nullable(),
+  text: z.string(), // line WITHOUT leading +/-/space marker
+});
+export type GitDiffLine = z.infer<typeof GitDiffLine>;
+export const GitDiffHunk = z.object({
+  oldStart: z.number().int().nonnegative(),
+  oldLines: z.number().int().nonnegative(),
+  newStart: z.number().int().nonnegative(),
+  newLines: z.number().int().nonnegative(),
+  header: z.string(), // the @@ ... @@ section heading
+  lines: z.array(GitDiffLine),
+});
+export type GitDiffHunk = z.infer<typeof GitDiffHunk>;
+export const GitFileDiff = z.object({
+  path: z.string(),
+  oldPath: z.string().nullable(),
+  status: GitFileStatusCode,
+  isBinary: z.boolean().default(false),
+  isImage: z.boolean().default(false),
+  additions: z.number().int().nonnegative(),
+  deletions: z.number().int().nonnegative(),
+  hunks: z.array(GitDiffHunk), // empty if binary or truncated
+  truncated: z.boolean().default(false), // diff exceeded maxBytes; hunks omitted
+});
+export type GitFileDiff = z.infer<typeof GitFileDiff>;
+export const GitDiffRequest = z.object({
+  path: z.string().default(""), // repo root
+  // diff selectors, mutually exclusive precedence: refs > staged > worktree
+  staged: z.boolean().default(false), // --cached (index vs HEAD)
+  fromRef: z.string().optional(),
+  toRef: z.string().optional(),
+  pathspec: z.array(z.string()).default([]),
+  contextLines: z.number().int().min(0).max(10).default(3),
+  maxBytesPerFile: z.number().int().positive().max(2 * 1024 * 1024).default(512 * 1024),
+});
+export type GitDiffRequest = z.infer<typeof GitDiffRequest>;
+export const GitDiffResponse = z.object({
+  files: z.array(GitFileDiff),
+  revision: z.number().int().nonnegative(),
+});
+export type GitDiffResponse = z.infer<typeof GitDiffResponse>;
+
+export const GitLogRequest = z.object({
+  path: z.string().default(""),
+  ref: z.string().default("HEAD"),
+  maxCount: z.number().int().positive().max(1_000).default(100),
+  skip: z.number().int().nonnegative().default(0),
+  pathspec: z.array(z.string()).default([]),
+});
+export type GitLogRequest = z.infer<typeof GitLogRequest>;
+export const GitCommit = z.object({
+  sha: z.string(),
+  shortSha: z.string(),
+  parents: z.array(z.string()),
+  author: z.object({ name: z.string(), email: z.string(), timestamp: z.number().int() }),
+  committer: z.object({ name: z.string(), email: z.string(), timestamp: z.number().int() }),
+  subject: z.string(),
+  body: z.string(),
+  refs: z.array(z.string()).default([]), // decorations: branch/tag pointers
+});
+export type GitCommit = z.infer<typeof GitCommit>;
+export const GitLogResponse = z.object({ commits: z.array(GitCommit), hasMore: z.boolean() });
+export type GitLogResponse = z.infer<typeof GitLogResponse>;
+
+export const GitShowRequest = z.object({
+  path: z.string().default(""),
+  ref: z.string(), // a commit/tag/tree-ish
+  filePath: z.string().optional(), // ref + filePath => raw blob ("open file at commit")
+  encoding: FsEncoding.default("utf8"),
+  maxBytesPerFile: z.number().int().positive().max(2 * 1024 * 1024).default(512 * 1024),
+});
+export type GitShowRequest = z.infer<typeof GitShowRequest>;
+export const GitShowResponse = z.object({
+  commit: GitCommit.nullable(), // null when fetching a raw blob
+  files: z.array(GitFileDiff), // commit diff vs first parent
+  blob: z.object({ content: z.string(), encoding: FsEncoding, sizeBytes: z.number().int(), truncated: z.boolean() }).nullable(),
+  revision: z.number().int().nonnegative(),
+});
+export type GitShowResponse = z.infer<typeof GitShowResponse>;
+
+// --- A2 Terminal exec (run a command in-box, stream stdout/stderr) -----------
+// The command-output FIREHOSE rides A1 (sandbox.command.output.delta). This is
+// the SYNCHRONOUS exec: run a bounded command and return its stdout/stderr +
+// exit code inline (the result IS the HTTP response). Full interactive PTY
+// (open/write/resize) layers on top via the pty.* events; exec ships now.
+export const TerminalExecRequest = z.object({
+  command: z.string().min(1),
+  cwd: z.string().default(""), // workspace-relative
+  // Soft per-call wall-clock bound (the box yields output back when reached).
+  timeoutMs: z.number().int().positive().max(120_000).default(30_000),
+  // Stream the deltas onto A1 as the agent firehose (so other viewers see it),
+  // in addition to returning the buffered result inline.
+  emitStream: z.boolean().default(true),
+});
+export type TerminalExecRequest = z.infer<typeof TerminalExecRequest>;
+export const TerminalExecResponse = z.object({
+  stdout: z.string(),
+  stderr: z.string(),
+  exitCode: z.number().int().nullable(),
+  // True when the process was still running when the call yielded (a long
+  // command); the remaining output drains onto A1 if emitStream was set.
+  running: z.boolean(),
+  wallTimeSeconds: z.number().nonnegative(),
+});
+export type TerminalExecResponse = z.infer<typeof TerminalExecResponse>;
+
+// --- A2 Terminal PTY control (output rides A1) -------------------------------
+export const PtyOpenRequest = z.object({
+  cols: z.number().int().positive().max(500).default(80),
+  rows: z.number().int().positive().max(300).default(24),
+  cwd: z.string().default(""), // workspace-relative
+  shell: z.string().optional(), // default: resolved login shell
+});
+export type PtyOpenRequest = z.infer<typeof PtyOpenRequest>;
+export const PtyOpenResponse = z.object({
+  ptyId: z.string().uuid(),
+  // output streams as terminal.pty.output.delta on the SSE channel the client holds
+  streamVia: z.literal("sse-events"),
+  supportsInput: z.boolean(), // false on backends without writeStdin
+});
+export type PtyOpenResponse = z.infer<typeof PtyOpenResponse>;
+export const PtyWriteRequest = z.object({ ptyId: z.string().uuid(), data: z.string() }); // utf-8 stdin
+export type PtyWriteRequest = z.infer<typeof PtyWriteRequest>;
+export const PtyResizeRequest = z.object({ ptyId: z.string().uuid(), cols: z.number().int().positive(), rows: z.number().int().positive() });
+export type PtyResizeRequest = z.infer<typeof PtyResizeRequest>;
+export const PtyCloseRequest = z.object({ ptyId: z.string().uuid() });
+export type PtyCloseRequest = z.infer<typeof PtyCloseRequest>;
+
+// Per-session structured-service capabilities (the Channel-A slice of the
+// negotiation). The full SessionCapabilities doc already carries FileSystem /
+// Terminal / Git blocks (P0.1); this is the compact projection the SDK mirrors.
+export const SessionStructuredCapabilities = z.object({
+  FileSystem: z.object({ available: z.boolean(), readOnly: z.boolean(), root: z.string() }),
+  Terminal: z.object({
+    events: z.boolean(), // command.output firehose (always on if a box exists)
+    exec: z.boolean(), // synchronous terminal exec
+    pty: z.object({ available: z.boolean() }), // interactive stdin (writeStdin)
+  }),
+  Git: z.object({ available: z.boolean(), repos: z.array(z.string()) }),
+});
+export type SessionStructuredCapabilities = z.infer<typeof SessionStructuredCapabilities>;
+
 export const SessionEvent = z.object({
   id: z.string().uuid(),
   workspaceId: z.string().uuid(),
@@ -1324,6 +2744,17 @@ export const CreateSessionRequest = z.object({
   model: z.string().min(1).optional(),
   reasoningEffort: ReasoningEffort.optional(),
   sandboxBackend: SandboxBackend.optional(),
+  // The enrolled machine (a sandbox id) to run this session on; seeds the
+  // active-sandbox pointer at creation so the FIRST turn routes to the chosen
+  // machine (race-free: the pointer is committed before the worker turn
+  // workflow can read it). An invalid/unowned/offline target fails the create.
+  targetSandboxId: z.string().uuid().optional(),
+  // The working directory the targeted machine runs the session under — the
+  // path/cwd base for its agent exec, terminal, and file dock. Free-form pass-
+  // through: a launch-workspace_root-relative subdir or an absolute machine path
+  // (the agent's resolve_cwd handles both). Only valid WITH targetSandboxId
+  // (workingDir alone is a 422); omitted ⇒ the machine's default workspace_root.
+  workingDir: z.string().min(1).optional(),
   // Workspace environment attachment is fixed at session creation; follow-up
   // user.message events cannot switch or add one.
   environmentId: z.string().uuid().optional(),
@@ -1341,6 +2772,28 @@ export const CreateSessionRequest = z.object({
   // the orchestration/environment/github tools. Capped at creation: every
   // requested permission must be held by the creating grant (no escalation).
   firstPartyMcpPermissions: z.array(Permission).optional(),
+  // Shared-sandbox placement (addendum 05 §D.1). Three-way union; OMITTED ⇒
+  // today's behavior (a context-dependent default resolved server-side: from
+  // inside a session → "shared" with the creator's box, top-level → "new").
+  //   - "shared":  join the CREATOR's box. Requires a parent session (inferred
+  //                from the worker-signed sessionId claim, never caller-supplied);
+  //                top-level "shared" is a 422.
+  //   - "new":     mint a fresh singleton box (group ≡ the new session's id).
+  //   - {groupId}: join a SPECIFIC sibling group in THIS workspace (manager
+  //                fan-out). Validated workspace-scoped (cross-workspace → 404).
+  // A shared spawn inherits the box's (backend, os) — it is literally the same
+  // box; the child cannot pick its own backend. Cross-workspace sharing is
+  // forbidden by construction (the parent/group reads are RLS-workspace-scoped).
+  // ENV-AWARE: the box's environment is fixed at creation, so a share requires
+  // the SAME environmentId as the creator's box. On a mismatch the inherited
+  // default silently falls back to an own box; an explicit "shared"/{groupId}
+  // request 422s at create (instead of the first turn dying on the SDK's
+  // manifest-env guard).
+  sandbox: z.union([
+    z.literal("shared"),
+    z.literal("new"),
+    z.object({ groupId: z.string().uuid() }),
+  ]).optional(),
 });
 export type CreateSessionRequest = z.infer<typeof CreateSessionRequest>;
 
@@ -1422,10 +2875,569 @@ export const ClientAuthConfig = z.discriminatedUnion("mode", [
 ]);
 export type ClientAuthConfig = z.infer<typeof ClientAuthConfig>;
 
+// The negotiated capability handshake document (master-spine C.3). ONE shape;
+// collapses the parallel per-module definitions. A capability cell is always
+// present with `available`/`transport` + a `reason` when unavailable — never
+// absent.
+export const CapabilityUnavailableReason = z.enum([
+  "backend_unsupported",
+  "os_unsupported",
+  "not_provisioned",
+  "disabled_by_policy",
+  "lease_cold",
+  "tier_headless",
+  // Selfhosted (bring-your-own-compute) negotiation states (M1 additive; the
+  // selfhosted negotiation in select.ts wires them in M3):
+  "agent_offline", // the enrolled agent process is not running / unreachable
+  "agent_reconnecting", // a transient blip — the agent is reconnecting (warmable)
+  "consent_required", // whole-machine / screen-control consent not yet acknowledged
+  "display_unavailable", // headless machine with no display stack (no DesktopStream)
+]);
+export type CapabilityUnavailableReason = z.infer<typeof CapabilityUnavailableReason>;
+
+export const SessionCapabilities = z.object({
+  sessionId: z.string().uuid(),
+  backend: SandboxBackend,
+  os: SandboxOs,
+  liveness: z.enum(["cold", "warming", "warm", "draining"]),
+  // Echoed on viewer heartbeats (the split-brain fence).
+  leaseEpoch: z.number().int().nonnegative(),
+  viewerHeartbeatIntervalMs: z.number().int().positive().default(30_000),
+  FileSystem: z.object({
+    available: z.boolean(),
+    readOnly: z.boolean(),
+    root: z.string(),
+    pathSep: z.enum(["/", "\\"]),
+    treeMode: z.enum(["lazy", "snapshot"]),
+    reason: CapabilityUnavailableReason.nullable(),
+  }),
+  Terminal: z.object({
+    transport: z.enum(["sse-events", "pty-ws"]).nullable(),
+    ptyCapable: z.boolean(),
+    shell: z.string(),
+    // The direct-to-provider ttyd PTY-over-websocket URL (pty-ws) resolved on the
+    // SAME tunnel as the desktop; null on a cold lease / read-only sse-events
+    // firehose / degraded terminal. The scoped stream token is recorded against
+    // the holder (NEVER a URL query param), symmetric with DesktopStream.
+    url: z.string().url().nullable(),
+    token: z.string().nullable(),
+    // ISO absolute expiry of the minted stream token (symmetric with
+    // DesktopStream.expiresAt). Null when no live URL/token is minted.
+    expiresAt: z.string().nullable(),
+    reason: CapabilityUnavailableReason.nullable(),
+  }),
+  Git: z.object({
+    available: z.boolean(),
+    repos: z.array(z.string()),
+    reason: CapabilityUnavailableReason.nullable(),
+  }),
+  DesktopStream: z.object({
+    // "relay-frames" is the selfhosted framebuffer stream: PNG-per-frame protobuf
+    // datagrams spliced over the relay (NOT RFB). The viewer renders it with the
+    // "frames" client (a canvas painter), distinct from Modal's "vnc-ws"/"novnc".
+    transport: z.enum(["vnc-ws", "rdp-ws", "webrtc", "relay-frames"]).nullable(),
+    client: z.enum(["novnc", "web-rdp", "frames"]).nullable(),
+    mode: z.enum(["read-only", "interactive"]).default("read-only"),
+    url: z.string().url().nullable(),
+    token: z.string().nullable(),
+    expiresAt: z.string().nullable(),
+    resolution: z
+      .tuple([z.number().int().positive(), z.number().int().positive()])
+      .default([1024, 768]),
+    // REQUIRED, no default (the server must assert un-redacted pixels).
+    unredacted: z.boolean(),
+    requiresAcknowledgment: z.boolean(),
+    acknowledged: z.boolean(),
+    // SHARED-EXPOSURE disclosure (addendum E.1). `shared` is true when the box's
+    // group has >1 session: watching this desktop ALSO shows the sibling
+    // sessions' agents on the one :0 framebuffer (the pixels cannot be redacted).
+    // `sharedSessionIds` lists the OTHER sessions whose agents may appear — IDS
+    // ONLY, never their goal/metadata/conversation (a viewer of A must not be
+    // able to use "I can see B's id" to subscribe to B's events; stress g). When
+    // shared, the consent gate requires the shared-exposure acknowledgment (409
+    // shared_acknowledgment_required) before the desktop path is handed out.
+    shared: z.boolean().default(false),
+    sharedSessionIds: z.array(z.string().uuid()).default([]),
+    reason: CapabilityUnavailableReason.nullable(),
+  }),
+  Recording: z.object({
+    available: z.boolean(),
+    modes: z.array(z.enum(["manual", "on-turn", "on-verify"])),
+    codecs: z.array(z.enum(["h264-mp4", "vp9-webm"])),
+    reason: CapabilityUnavailableReason.nullable(),
+  }),
+  // The AGENT drives the SAME :0 (xdotool/XTEST + scrot) the human watches; the
+  // human viewer plane is read-only by default (§6). `available` == desktop-
+  // capable backend && computerUseEnabled; `readOnly` reports whether the agent
+  // driver itself is gated to no-op input (v1 default false — the agent clicks).
+  ComputerUse: z.object({
+    available: z.boolean(),
+    readOnly: z.boolean(),
+    reason: CapabilityUnavailableReason.nullable(),
+  }),
+  negotiatedAt: z.string(),
+});
+export type SessionCapabilities = z.infer<typeof SessionCapabilities>;
+
+// ── API-direct viewer attach (P1.4) ─────────────────────────────────────────
+// A viewer holds the GROUP lease (keeping the box warm while watched). These
+// shape the in-process attach/heartbeat/detach handlers. The scoped stream
+// token + the un-redacted-pixel acknowledgment are P3/P4 — here it is the
+// viewer-HOLDER lifecycle only.
+
+// POST .../viewers — acquire a viewer holder. An omitted viewerId mints a fresh
+// one (returned in the response, to carry through heartbeats + detach).
+//
+// `desktop` declares intent to attach the UN-REDACTED pixel plane (noVNC). ONLY
+// that plane carries the consent gate (the un-redacted/shared acknowledgment). A
+// terminal-only warm attach (`desktop:false`, the default) needs NO consent — a
+// shell is interactive by nature and the gate is the scoped tunnel URL + stream
+// token — so it warms the box and mints the pty-ws terminal cell WITHOUT a 409.
+// Omitted defaults to `false` so a terminal-only client never trips the gate.
+export const AttachViewerRequest = z.object({
+  viewerId: z.string().uuid().optional(),
+  desktop: z.boolean().optional(),
+});
+export type AttachViewerRequest = z.infer<typeof AttachViewerRequest>;
+
+export const ViewerHolder = z.object({
+  viewerId: z.string().uuid(),
+  sandboxGroupId: z.string().uuid(),
+  liveness: z.enum(["cold", "warming", "warm", "draining"]),
+  // The epoch the viewer is fenced on; echoed back on heartbeats.
+  leaseEpoch: z.number().int().nonnegative(),
+  viewerHeartbeatIntervalMs: z.number().int().positive(),
+  // The desktop pixel tunnel URL the viewer connects to directly; null until
+  // P4 mints it (gated until then).
+  dataPlaneUrl: z.string().nullable(),
+});
+export type ViewerHolder = z.infer<typeof ViewerHolder>;
+
+// POST .../stream-capabilities/acknowledge — record the calling principal's
+// acknowledgment of the un-redacted pixel plane (P3.2; modules/07-channel-b.md
+// §6 + addendum E.1). Reuses the acknowledgment machinery — no new endpoint
+// shape beyond this body, no new permission beyond stream:acknowledge.
+//
+// `acknowledgeShared` MUST be true when the box is shared (the group has >1
+// session): the un-redacted desktop path returns 409 shared_acknowledgment_required
+// until a shared box is acknowledged WITH the shared-exposure consent. For a
+// solo box `acknowledgeShared` is irrelevant (the un-redacted ack alone gates).
+export const AcknowledgeStreamRequest = z.object({
+  // The principal accepts that the desktop pixel plane is un-redacted (can show
+  // cloud creds the agent cat's into a terminal). Always true to record consent;
+  // present for self-documentation + a future explicit withdraw.
+  acknowledgeUnredacted: z.boolean().default(true),
+  // The principal accepts the shared-exposure disclosure: watching this desktop
+  // also shows sibling sessions' agents on the one framebuffer.
+  acknowledgeShared: z.boolean().default(false),
+});
+export type AcknowledgeStreamRequest = z.infer<typeof AcknowledgeStreamRequest>;
+
+export const AcknowledgeStreamResponse = z.object({
+  acknowledged: z.boolean(),
+  acknowledgedShared: z.boolean(),
+});
+export type AcknowledgeStreamResponse = z.infer<typeof AcknowledgeStreamResponse>;
+
+// POST .../viewers/:viewerId/heartbeat — refresh the holder TTL. Epoch-fenced:
+// a stale-epoch beat (a box re-established under a newer epoch) is rejected.
+export const ViewerHeartbeatRequest = z.object({
+  leaseEpoch: z.number().int().nonnegative(),
+});
+export type ViewerHeartbeatRequest = z.infer<typeof ViewerHeartbeatRequest>;
+
+export const ViewerHeartbeatResponse = z.object({
+  // false ⇒ the holder was reaped or the epoch is stale; the client re-attaches.
+  alive: z.boolean(),
+});
+export type ViewerHeartbeatResponse = z.infer<typeof ViewerHeartbeatResponse>;
+
+// =============================================================================
+// Bring-your-own-compute (M5) — enrollment device-flow HTTP contract.
+//
+// The HTTP shapes mirror the @opengeni/agent-proto device-flow messages
+// (DeviceAuthStart*, DeviceAuthPoll*, EnrollmentCredentials) so the Rust agent's
+// `enroll` command (which runs the flow over HTTP before it has NATS creds)
+// decodes the SAME field names (the proto's ts-proto JSON is camelCase). The
+// request bodies additionally carry the consent-relevant fields the dossier brief
+// mandates (the agent ed25519 pubkey + can-offer-display + requests-screen-control).
+// =============================================================================
+
+export const EnrollmentOs = z.enum(["linux", "macos", "windows"]);
+export type EnrollmentOs = z.infer<typeof EnrollmentOs>;
+export const EnrollmentArch = z.enum(["x86_64", "aarch64"]);
+export type EnrollmentArch = z.infer<typeof EnrollmentArch>;
+
+// POST /enrollments/device/start (agent-side, unauthenticated-at-the-user-level,
+// rate-limited). The agent presents its ed25519 public key + os/arch + the
+// requested whole-machine exposure + whether it can offer a display + whether it
+// requests screen control.
+export const DeviceEnrollmentStartRequest = z.object({
+  // The agent's ed25519 public key (the machine identity the enrollment binds to).
+  publicKey: z.string().min(1).max(1024),
+  os: EnrollmentOs.default("linux"),
+  arch: EnrollmentArch.default("x86_64"),
+  // Human-friendly machine name (hostname by default).
+  machineName: z.string().min(1).max(256).optional(),
+  // v1 only supports whole-machine; kept explicit so the consent is recorded.
+  exposure: z.literal("whole-machine").default("whole-machine"),
+  // The agent can offer a display (a real screen / Xvfb is available).
+  canOfferDisplay: z.boolean().default(false),
+  // The agent requests screen control (computer-use); the user's allow_screen_control
+  // at approve is the AUTHORITATIVE consent.
+  requestsScreenControl: z.boolean().default(false),
+  // The workspace this machine is enrolling into. The agent is told this at install
+  // (the user picks the workspace, or the install/enroll token carries it). The user
+  // who approves must hold a grant in THIS workspace — that binding is what makes
+  // the (user-unauthenticated) start safe: it cannot grant access to a workspace no
+  // authorized user later approves in.
+  workspaceId: z.string().uuid(),
+});
+export type DeviceEnrollmentStartRequest = z.infer<typeof DeviceEnrollmentStartRequest>;
+
+// The DeviceAuthStart response (field names match the proto's JSON).
+export const DeviceEnrollmentStartResponse = z.object({
+  deviceCode: z.string(),
+  userCode: z.string(),
+  verificationUri: z.string(),
+  verificationUriComplete: z.string(),
+  intervalSeconds: z.number().int().positive(),
+  expiresInSeconds: z.number().int().positive(),
+});
+export type DeviceEnrollmentStartResponse = z.infer<typeof DeviceEnrollmentStartResponse>;
+
+// POST /enrollments/device/approve (USER-authenticated, workspace-gated). The
+// LOUD CONSENT step. whole-machine is mandatory (implicit); screen-control is
+// opt-in per allow_screen_control.
+export const DeviceEnrollmentApproveRequest = z.object({
+  userCode: z.string().min(1).max(64),
+  allowScreenControl: z.boolean().default(false),
+});
+export type DeviceEnrollmentApproveRequest = z.infer<typeof DeviceEnrollmentApproveRequest>;
+
+export const DeviceEnrollmentApproveResponse = z.object({
+  approved: z.boolean(),
+  enrollmentId: z.string().uuid(),
+  sandboxId: z.string().uuid(),
+  allowScreenControl: z.boolean(),
+});
+export type DeviceEnrollmentApproveResponse = z.infer<typeof DeviceEnrollmentApproveResponse>;
+
+// POST /enrollments/device/poll (agent-side). The poll state machine.
+export const DeviceEnrollmentPollRequest = z.object({
+  deviceCode: z.string().min(1).max(256),
+});
+export type DeviceEnrollmentPollRequest = z.infer<typeof DeviceEnrollmentPollRequest>;
+
+export const DeviceEnrollmentState = z.enum(["pending", "authorized", "denied", "expired", "disabled"]);
+export type DeviceEnrollmentState = z.infer<typeof DeviceEnrollmentState>;
+
+// The EnrollmentCredentials (field names match the proto's JSON). natsAccountCreds
+// is a PLACEHOLDER — the real per-workspace NATS Account creds binding is
+// infra-deferred (M4/relay); the bearer + subjectPrefix are the application-tier
+// identity the agent presents today.
+export const EnrollmentCredentialsResponse = z.object({
+  agentId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  // The signed bearer the agent presents to the control plane (the `oge_` token).
+  bearer: z.string(),
+  // The Account-scoped control-plane subject prefix the agent subscribes to:
+  // agent.<workspaceId>.<agentId>.
+  subjectPrefix: z.string(),
+  // Connect info for the control plane + stream relay (may be empty when not yet
+  // configured for this deployment — the agent surfaces "control plane unconfigured").
+  natsUrls: z.array(z.string()),
+  relayUrl: z.string(),
+  // The agent's PRODUCER token for the relay edge (the `ogr_` token; M8b). Presented
+  // as StreamOpen.token when the agent registers a pty/desktop channel; the relay
+  // verifies it then pairs the producer with the viewer (whose `ogs_` token the
+  // relay also verifies). Empty when the relay-token plane is unconfigured for this
+  // deployment (graceful degrade — the agent then presents an empty token the relay
+  // rejects, surfacing the gap loudly rather than silently producing a dead stream).
+  relayToken: z.string(),
+  // VESTIGIAL (M-AUTH): there is no per-machine NATS Account creds file. The agent
+  // presents the `bearer` above as the NATS connect AUTH-TOKEN; the server's
+  // auth-callout responder validates it and mints a workspace-scoped user JWT. This
+  // field echoes the bearer so a consumer reading it as the connect credential still
+  // works; new consumers should read `bearer` directly.
+  natsAccountCreds: z.string(),
+  // The minisign public key the agent pins for self-update verification.
+  updatePublicKey: z.string(),
+  consentedWholeMachine: z.boolean(),
+  consentedScreenControl: z.boolean(),
+});
+export type EnrollmentCredentialsResponse = z.infer<typeof EnrollmentCredentialsResponse>;
+
+export const DeviceEnrollmentPollResponse = z.object({
+  state: DeviceEnrollmentState,
+  // Present only when state === "authorized".
+  credentials: EnrollmentCredentialsResponse.optional(),
+});
+export type DeviceEnrollmentPollResponse = z.infer<typeof DeviceEnrollmentPollResponse>;
+
+// GET /enrollments — a workspace's machines (the Machines dashboard surface).
+export const EnrollmentSummary = z.object({
+  id: z.string().uuid(),
+  pubkey: z.string(),
+  exposure: z.literal("whole-machine"),
+  hasDisplay: z.boolean(),
+  allowScreenControl: z.boolean(),
+  status: z.enum(["active", "revoked"]),
+  os: EnrollmentOs,
+  arch: z.string(),
+  lastSeenAt: z.string().nullable(),
+  createdAt: z.string(),
+  revokedAt: z.string().nullable(),
+});
+export type EnrollmentSummary = z.infer<typeof EnrollmentSummary>;
+
+export const ListEnrollmentsResponse = z.object({
+  enrollments: z.array(EnrollmentSummary),
+});
+export type ListEnrollmentsResponse = z.infer<typeof ListEnrollmentsResponse>;
+
+export const RevokeEnrollmentResponse = z.object({
+  revoked: z.boolean(),
+});
+export type RevokeEnrollmentResponse = z.infer<typeof RevokeEnrollmentResponse>;
+
+// =============================================================================
+// Enrollment UX (self-hosted enrollment UX, design 11): the click-Grant approve
+// page lookup/deny + the headless enroll-token mint/exchange. These sit beside the
+// device-flow contracts above and REUSE EnrollmentCredentialsResponse for the
+// exchange's credential payload (identical shape to the poll authorized branch).
+// =============================================================================
+
+// POST /v1/enrollments/device/lookup (USER-authenticated, NO workspace in the
+// path). The approve page (EnrollmentConsent) needs the machine details for a
+// user_code WITHOUT consuming the request. The user_code is globally unique among
+// pending rows; the route resolves its workspace, authorizes (enrollments:read),
+// and returns the machine details — or 404 (never revealing cross-workspace
+// existence) when the grant check fails or no live pending row matches.
+export const DeviceEnrollmentLookupRequest = z.object({
+  userCode: z.string().min(1).max(64),
+});
+export type DeviceEnrollmentLookupRequest = z.infer<typeof DeviceEnrollmentLookupRequest>;
+
+// The presentational machine details the consent screen renders (a subset of the
+// pending request — NO secrets, NO device_code).
+export const DeviceEnrollmentLookupMachine = z.object({
+  machineName: z.string().nullable(),
+  os: EnrollmentOs,
+  arch: z.string(),
+  canOfferDisplay: z.boolean(),
+  requestsScreenControl: z.boolean(),
+});
+export type DeviceEnrollmentLookupMachine = z.infer<typeof DeviceEnrollmentLookupMachine>;
+
+export const DeviceEnrollmentLookupResponse = z.object({
+  workspaceId: z.string().uuid(),
+  userCode: z.string(),
+  machine: DeviceEnrollmentLookupMachine,
+  expiresAt: z.string(),
+});
+export type DeviceEnrollmentLookupResponse = z.infer<typeof DeviceEnrollmentLookupResponse>;
+
+// POST /v1/workspaces/:workspaceId/enrollments/device/deny (USER-authenticated,
+// enrollments:manage). The explicit "no" at the approve page — mirrors approve.
+export const DeviceEnrollmentDenyRequest = z.object({
+  userCode: z.string().min(1).max(64),
+});
+export type DeviceEnrollmentDenyRequest = z.infer<typeof DeviceEnrollmentDenyRequest>;
+
+export const DeviceEnrollmentDenyResponse = z.object({
+  denied: z.boolean(),
+});
+export type DeviceEnrollmentDenyResponse = z.infer<typeof DeviceEnrollmentDenyResponse>;
+
+// POST /v1/workspaces/:workspaceId/enrollments/token (USER-authenticated,
+// enrollments:manage). Mints the short-TTL headless enroll token (the `oget_`
+// token). allowScreenControl bakes the screen-control consent into the token.
+export const MintEnrollTokenRequest = z.object({
+  allowScreenControl: z.boolean().default(false),
+});
+export type MintEnrollTokenRequest = z.infer<typeof MintEnrollTokenRequest>;
+
+export const MintEnrollTokenResponse = z.object({
+  // The `oget_` token. SECRET — the UI shows it once with a copy-now warning.
+  token: z.string(),
+  expiresAt: z.string(),
+  expiresInSeconds: z.number().int().positive(),
+});
+export type MintEnrollTokenResponse = z.infer<typeof MintEnrollTokenResponse>;
+
+// POST /v1/enrollments/token/exchange (UNAUTHENTICATED — the token IS the auth).
+// The agent presents the same identity fields it sends to device/start plus the
+// enroll token. On a valid token the control plane performs the SAME finalize as
+// approve and returns the IDENTICAL EnrollmentCredentialsResponse shape (so the
+// agent's existing credential parsing is reused).
+export const EnrollTokenExchangeRequest = z.object({
+  // The `oget_` enroll token (the auth + the workspace/account/consent grant).
+  token: z.string().min(1),
+  // The agent's ed25519 public key (the machine identity the enrollment binds to).
+  publicKey: z.string().min(1).max(1024),
+  os: EnrollmentOs.default("linux"),
+  arch: EnrollmentArch.default("x86_64"),
+  machineName: z.string().min(1).max(256).optional(),
+  // v1 only supports whole-machine; kept explicit so the consent is recorded.
+  exposure: z.literal("whole-machine").default("whole-machine"),
+  canOfferDisplay: z.boolean().default(false),
+  // The agent's REQUEST; the token's allowScreenControl is the AUTHORITATIVE consent.
+  requestsScreenControl: z.boolean().default(false),
+});
+export type EnrollTokenExchangeRequest = z.infer<typeof EnrollTokenExchangeRequest>;
+
+// The exchange wraps the EXISTING EnrollmentCredentialsResponse — IDENTICAL to the
+// poll authorized branch's `credentials` (NOT a redefined credential shape).
+export const EnrollTokenExchangeResponse = z.object({
+  credentials: EnrollmentCredentialsResponse,
+});
+export type EnrollTokenExchangeResponse = z.infer<typeof EnrollTokenExchangeResponse>;
+
+// ── Machines dashboard + per-machine metrics (M10, dossier §10.7) ────────────
+//
+// The SHARED data contract M10 (backend) implements + M9 (UI) renders. THE
+// orchestrator owns this shape; M9 imports these types so the dashboard never
+// drifts from the API. The fields mirror the agent's MetricsSample wire shape
+// (`@opengeni/agent-proto`) projected to the dashboard's JSON, plus the derived
+// machine state matrix (the M3 liveness + the consent/display reasons).
+
+/**
+ * A point-in-time machine metrics sample as the dashboard reads it. `cpuPct` and
+ * the load averages are 0..N doubles; the byte figures are integers; `gpuUtilPct`
+ * / `gpuMemBytes` are null when no GPU was present at sample time (the wire
+ * contract: absence == not-reported, NEVER a real zero). `runQueue` is the
+ * runnable-count contention signal. `sampledAt` is an ISO-8601 instant.
+ */
+export const MetricSample = z.object({
+  cpuPct: z.number(),
+  load1: z.number(),
+  load5: z.number(),
+  load15: z.number(),
+  memUsedBytes: z.number().int(),
+  memTotalBytes: z.number().int(),
+  diskUsedBytes: z.number().int(),
+  diskTotalBytes: z.number().int(),
+  gpuUtilPct: z.number().nullable(),
+  gpuMemBytes: z.number().int().nullable(),
+  runQueue: z.number(),
+  sampledAt: z.string(),
+});
+export type MetricSample = z.infer<typeof MetricSample>;
+
+/** The derived dashboard state of a machine. The M3 liveness
+ *  (online/reconnecting/offline) plus the enrollment-derived consent/display
+ *  reasons (consent_required / display_unavailable) and the in-flight device-flow
+ *  (enrolling). */
+export const MachineState = z.enum([
+  "online",
+  "reconnecting",
+  "offline",
+  "consent_required",
+  "display_unavailable",
+  "enrolling",
+]);
+export type MachineState = z.infer<typeof MachineState>;
+
+export const MachineKind = z.enum(["modal", "selfhosted"]);
+export type MachineKind = z.infer<typeof MachineKind>;
+
+/**
+ * A machine as the Machines dashboard renders it. The workspace's enrolled
+ * selfhosted machines PLUS the session's synthetic Modal group box
+ * (`isSessionGroup: true`). `active` marks the session's currently-active
+ * routing target. `sharedSessionCount` is the lease refcount (how many sessions
+ * share this whole machine). `metrics` is the latest sample, or null when none
+ * has landed yet (just enrolled / offline before a first heartbeat).
+ */
+export const MachineView = z.object({
+  sandboxId: z.string(),
+  enrollmentId: z.string().nullable(),
+  name: z.string(),
+  kind: MachineKind,
+  state: MachineState,
+  active: z.boolean(),
+  isSessionGroup: z.boolean(),
+  os: z.string(),
+  arch: z.string(),
+  hasDisplay: z.boolean(),
+  allowScreenControl: z.boolean(),
+  sharedSessionCount: z.number().int(),
+  lastSeenAt: z.string().nullable(),
+  metrics: MetricSample.nullable(),
+});
+export type MachineView = z.infer<typeof MachineView>;
+
+/**
+ * GET /v1/workspaces/:ws/machines — the dashboard list. `activeSandboxId` /
+ * `activeEpoch` echo the session's epoch-fenced active-sandbox pointer (null
+ * activeSandboxId == the session's own group box is active).
+ */
+export const MachinesResponse = z.object({
+  activeSandboxId: z.string().nullable(),
+  activeEpoch: z.number().int(),
+  machines: z.array(MachineView),
+});
+export type MachinesResponse = z.infer<typeof MachinesResponse>;
+
+/**
+ * POST /v1/workspaces/:ws/sessions/:sessionId/active-sandbox — the user-
+ * authenticated swap of a session's active sandbox (the same epoch-fenced
+ * mechanic the M7 `sandbox_swap` MCP tool exposes to the agent). `target` is a
+ * `MachinesResponse` machine's `sandboxId`, or "session"/"default" to swap back
+ * to the session's own group box.
+ */
+export const SwapActiveSandboxRequest = z.object({
+  target: z.string().min(1),
+});
+export type SwapActiveSandboxRequest = z.infer<typeof SwapActiveSandboxRequest>;
+
+/**
+ * The swap outcome (mirrors the server `FleetSwapResult`). `swapped` is true on a
+ * successful repoint OR a no-op (already pointed there); `reason` carries the
+ * failure detail (unowned/offline target, or a lost epoch fence) when false.
+ */
+export const SwapActiveSandboxResponse = z.object({
+  swapped: z.boolean(),
+  activeSandboxId: z.string().nullable(),
+  activeEpoch: z.number().int(),
+  reason: z.string().optional(),
+});
+export type SwapActiveSandboxResponse = z.infer<typeof SwapActiveSandboxResponse>;
+
+/**
+ * GET /v1/workspaces/:ws/machines/:enrollmentId/metrics/series?window=1h — the
+ * downsampled (~1/min) history the dashboard time-range reads.
+ */
+export const MachineMetricsSeriesResponse = z.object({
+  samples: z.array(MetricSample),
+});
+export type MachineMetricsSeriesResponse = z.infer<typeof MachineMetricsSeriesResponse>;
+
+/**
+ * A single host-exposed model + the provider that serves it, as surfaced to
+ * clients (SDK + React composer) by GET /v1/config/client. The wire `api`
+ * ("responses" | "chat") lets a client reason about provider capabilities; the
+ * provider id/label drive the picker's grouping. This mirrors the runtime's
+ * ConfiguredModel (packages/config) projected to the client-safe fields.
+ */
+export const ClientModel = z.object({
+  id: z.string(),
+  label: z.string(),
+  provider: z.string(),        // provider id
+  providerLabel: z.string(),
+  api: z.enum(["responses", "chat"]),
+  contextWindowTokens: z.number().int().positive().optional(),
+});
+export type ClientModel = z.infer<typeof ClientModel>;
+
 export const ClientConfig = z.object({
   deploymentRevision: z.string(),
   defaultModel: z.string(),
   allowedModels: z.array(z.string()).min(1),
+  // Richer model list (provider-grouped) for the picker. Defaults to [] for
+  // back-compat: callers that only read allowedModels are unaffected.
+  models: z.array(ClientModel).default([]),
   defaultReasoningEffort: ReasoningEffort,
   allowedReasoningEfforts: z.array(ReasoningEffort).min(1),
   mcpServers: z.array(z.object({
@@ -1438,6 +3450,15 @@ export const ClientConfig = z.object({
   }),
   productAccessMode: ProductAccessMode,
   auth: ClientAuthConfig.default({ mode: "none" }),
+  // Server-wide hint: does this deployment support Channel-A structured services
+  // at all (P4.4). Per-session availability is negotiated on /stream-capabilities
+  // (it depends on the session's pinned backend); this is the coarse on/off the
+  // client uses to decide whether to even attempt the fs/git/terminal panels.
+  structuredServices: z.object({
+    fileSystem: z.boolean(),
+    git: z.boolean(),
+    terminalEvents: z.boolean(),
+  }).default({ fileSystem: false, git: false, terminalEvents: false }),
 });
 export type ClientConfig = z.infer<typeof ClientConfig>;