@opengeni/contracts 0.10.0 → 0.15.0

package/src/index.ts

@@ -1,4 +1,26 @@
 import { z } from "zod";
+import {
+  boundSessionEventPayload,
+  measureSessionEventJson,
+  sessionEventJsonBytes,
+  type SessionEventBoundarySurface,
+} from "./event-preview";
+
+export {
+  SESSION_EVENT_PAYLOAD_MAX_BYTES,
+  approximateSessionEventTokens,
+  boundSessionEventPayload,
+  measureSessionEventJson,
+  sessionEventJsonBytes,
+  sessionEventMediaPreview,
+  sessionEventMediaPreviewFromDataUrl,
+  sessionEventPayloadTruncation,
+  type BoundSessionEventPayloadOptions,
+  type SessionEventBoundarySurface,
+  type SessionEventMediaPreview,
+  type SessionEventJsonMeasurement,
+  type SessionEventPayloadTruncation,
+} from "./event-preview";
 
 export const SessionStatus = z.enum([
   "queued",
@@ -7,7 +29,6 @@ export const SessionStatus = z.enum([
   "requires_action",
   "recovering",
   "waiting_capacity",
-  "paused",
   "failed",
   "cancelled",
 ]);
@@ -62,9 +83,16 @@ export type CapabilityDescriptor = {
   os: { supported: SandboxOs[]; default: SandboxOs };
   capabilities: {
     FileSystem: { available: boolean; readOnly: boolean };
-    Terminal: { available: boolean; transport: "sse-events" | "pty-ws" | null; pty: 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 };
+    DesktopStream: {
+      available: boolean;
+      transport: "vnc-ws" | "rdp-ws" | "webrtc" | null;
+    };
     // Feasibility only (== DesktopStream.available && os==linux); NOT a request.
     Recording: { available: boolean };
   };
@@ -97,7 +125,7 @@ export const DESKTOP_STREAM_PORT = 6080;
 // 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
+// The provider capability matrix (sandbox contract 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.
@@ -444,7 +472,7 @@ 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
+  // sandbox workspace (sandbox contract §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
@@ -553,11 +581,13 @@ export const Workspace = z.object({
   // validated by WorkspaceSettingsSchema; unknown keys are preserved across
   // PATCH merges so newer settings survive an older server.
   settings: z.record(z.string(), z.unknown()),
-  inferenceState: z.enum(["active", "paused"]),
-  inferenceGeneration: z.number().int().nonnegative(),
-  inferenceReason: z.string().nullable(),
-  inferenceChangedBy: z.string().nullable(),
-  inferenceChangedAt: z.string().nullable(),
+  inferenceControl: z.object({
+    state: z.enum(["active", "paused"]),
+    revision: z.number().int().nonnegative(),
+    reason: z.string().nullable(),
+    changedBy: z.string().nullable(),
+    changedAt: z.string().nullable(),
+  }),
   // Workspace default rig used by session/scheduled-task create fallback.
   defaultRigId: z.string().uuid().nullable(),
   createdAt: z.string(),
@@ -565,12 +595,297 @@ export const Workspace = z.object({
 });
 export type Workspace = z.infer<typeof Workspace>;
 
+export const WorkspaceTranscriptionTarget = z
+  .object({
+    provider: z.string().trim().min(1).max(128),
+    model: z.string().trim().min(1).max(256).nullable(),
+    credentialMode: z.enum(["managed", "byok"]),
+    // A workspace-scoped connection reference, never credential material.
+    credentialConnectionId: z.string().uuid().nullable(),
+    region: z.string().trim().min(1).max(128).nullable(),
+  })
+  .strict()
+  .superRefine((target, context) => {
+    if (target.provider === "azure-speech" && target.credentialMode !== "byok") {
+      context.addIssue({
+        code: "custom",
+        path: ["credentialMode"],
+        message: "Azure Speech is supported only through workspace BYOK",
+      });
+    }
+    if (target.credentialMode === "byok" && target.credentialConnectionId === null) {
+      context.addIssue({
+        code: "custom",
+        path: ["credentialConnectionId"],
+        message: "BYOK transcription targets require a workspace connection reference",
+      });
+    }
+    if (target.credentialMode === "managed" && target.credentialConnectionId !== null) {
+      context.addIssue({
+        code: "custom",
+        path: ["credentialConnectionId"],
+        message: "managed transcription targets cannot name a BYOK connection",
+      });
+    }
+  });
+export type WorkspaceTranscriptionTarget = z.infer<typeof WorkspaceTranscriptionTarget>;
+
+export const TranscriptionErrorCode = z.enum([
+  "permission_denied",
+  "not_supported",
+  "network",
+  "provider",
+  "policy_blocked",
+  "timeout",
+  "cancelled",
+  "unknown",
+]);
+export type TranscriptionErrorCode = z.infer<typeof TranscriptionErrorCode>;
+
+export const TranscriptionTimeSpan = z
+  .object({
+    startMilliseconds: z.number().finite().nonnegative(),
+    endMilliseconds: z.number().finite().nonnegative(),
+  })
+  .strict()
+  .superRefine((span, context) => {
+    if (span.endMilliseconds < span.startMilliseconds) {
+      context.addIssue({
+        code: "custom",
+        path: ["endMilliseconds"],
+        message: "transcription spans must not end before they start",
+      });
+    }
+  });
+export type TranscriptionTimeSpan = z.infer<typeof TranscriptionTimeSpan>;
+
+export const TranscriptionSpeaker = z
+  .object({
+    id: z.string().trim().min(1).max(128),
+    label: z.string().trim().min(1).max(128).optional(),
+  })
+  .strict();
+export type TranscriptionSpeaker = z.infer<typeof TranscriptionSpeaker>;
+
+export const TranscriptionWord = z
+  .object({
+    text: z.string().min(1).max(4096),
+    span: TranscriptionTimeSpan,
+    confidence: z.number().finite().min(0).max(1).optional(),
+    speaker: TranscriptionSpeaker.optional(),
+  })
+  .strict();
+export type TranscriptionWord = z.infer<typeof TranscriptionWord>;
+
+export const TranscriptionResultMetadata = z
+  .object({
+    detectedLanguage: z.string().trim().min(1).max(64).optional(),
+    span: TranscriptionTimeSpan.optional(),
+    confidence: z.number().finite().min(0).max(1).optional(),
+    speaker: TranscriptionSpeaker.optional(),
+    words: z.array(TranscriptionWord).max(10_000).optional(),
+  })
+  .strict()
+  .superRefine((metadata, context) => {
+    let previousStart = -1;
+    for (const [index, word] of (metadata.words ?? []).entries()) {
+      if (word.span.startMilliseconds < previousStart) {
+        context.addIssue({
+          code: "custom",
+          path: ["words", index, "span", "startMilliseconds"],
+          message: "transcription words must be ordered by start time",
+        });
+      }
+      previousStart = word.span.startMilliseconds;
+      if (
+        metadata.span &&
+        (word.span.startMilliseconds < metadata.span.startMilliseconds ||
+          word.span.endMilliseconds > metadata.span.endMilliseconds)
+      ) {
+        context.addIssue({
+          code: "custom",
+          path: ["words", index, "span"],
+          message: "transcription word spans must fall within the result span",
+        });
+      }
+    }
+  });
+export type TranscriptionResultMetadata = z.infer<typeof TranscriptionResultMetadata>;
+
+const TranscriptionEventBase = z
+  .object({
+    localSessionId: z.string().min(1).max(256),
+    sequence: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    occurredAt: z.string().datetime({ offset: true }),
+  })
+  .strict();
+
+/** Strict provider-neutral event surface; provider payload bags are rejected. */
+export const TranscriptionEvent = z.discriminatedUnion("type", [
+  TranscriptionEventBase.extend({ type: z.literal("permission.requested") }),
+  TranscriptionEventBase.extend({
+    type: z.literal("session.opened"),
+    providerSessionId: z.string().min(1).max(512),
+  }),
+  TranscriptionEventBase.extend({
+    type: z.literal("transcript.partial"),
+    segmentId: z.string().min(1).max(512),
+    text: z.string().max(1_000_000),
+    metadata: TranscriptionResultMetadata.optional(),
+  }),
+  TranscriptionEventBase.extend({
+    type: z.literal("transcript.final"),
+    segmentId: z.string().min(1).max(512),
+    text: z.string().max(1_000_000),
+    providerAcceptanceId: z.string().min(1).max(512),
+    metadata: TranscriptionResultMetadata.optional(),
+  }),
+  TranscriptionEventBase.extend({
+    type: z.literal("usage"),
+    audioMilliseconds: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    costUsd: z.number().finite().nonnegative().max(1_000_000_000).nullable(),
+  }),
+  TranscriptionEventBase.extend({
+    type: z.literal("session.reconnecting"),
+    attempt: z.number().int().nonnegative().max(10_000),
+    reason: z.string().min(1).max(256),
+  }),
+  TranscriptionEventBase.extend({
+    type: z.literal("session.error"),
+    code: TranscriptionErrorCode,
+    recoverable: z.boolean(),
+  }),
+  TranscriptionEventBase.extend({
+    type: z.literal("session.closed"),
+    reason: z.enum(["completed", "cancelled", "error", "replaced"]),
+  }),
+]);
+export type TranscriptionEvent = z.infer<typeof TranscriptionEvent>;
+
+/**
+ * Workspace-only policy for the distinct speech-to-text capability. It never
+ * authorizes a turn model/provider and contains connection references rather
+ * than secrets. `acceptanceId` changes whenever an admin accepts a new target
+ * set, so clients can bind a microphone session to one exact policy revision.
+ */
+export const WorkspaceTranscriptionPolicy = z
+  .object({
+    enabled: z.boolean(),
+    acceptanceId: z.string().uuid().nullable(),
+    primary: WorkspaceTranscriptionTarget.nullable(),
+    language: z.string().trim().min(1).max(64).nullable(),
+    autoDetectLanguage: z.boolean(),
+    diarization: z
+      .object({
+        enabled: z.boolean(),
+        maxSpeakers: z.number().int().min(2).max(100).nullable(),
+      })
+      .strict(),
+    retention: z
+      .object({
+        mode: z.enum(["none", "provider-policy"]),
+        maxDays: z.number().int().nonnegative().max(3650).nullable(),
+      })
+      .strict(),
+    privacy: z
+      .object({
+        allowProviderLogging: z.boolean(),
+        allowProviderTraining: z.boolean(),
+      })
+      .strict(),
+    fallback: z
+      .object({
+        mode: z.enum(["disabled", "explicit"]),
+        targets: z.array(WorkspaceTranscriptionTarget).max(8),
+      })
+      .strict(),
+    cost: z
+      .object({
+        currency: z.literal("USD"),
+        maxPerHour: z.number().finite().nonnegative().max(10_000).nullable(),
+        maxPerMonth: z.number().finite().nonnegative().max(1_000_000).nullable(),
+      })
+      .strict(),
+  })
+  .strict()
+  .superRefine((policy, context) => {
+    if (policy.enabled && policy.acceptanceId === null) {
+      context.addIssue({
+        code: "custom",
+        path: ["acceptanceId"],
+        message: "enabled transcription requires an accepted policy identity",
+      });
+    }
+    if (policy.enabled && policy.primary === null) {
+      context.addIssue({
+        code: "custom",
+        path: ["primary"],
+        message: "enabled transcription requires a primary target",
+      });
+    }
+    if (policy.enabled && !policy.autoDetectLanguage && policy.language === null) {
+      context.addIssue({
+        code: "custom",
+        path: ["language"],
+        message: "enabled transcription requires a language or accepted automatic detection",
+      });
+    }
+    if (policy.autoDetectLanguage && policy.language !== null) {
+      context.addIssue({
+        code: "custom",
+        path: ["language"],
+        message: "automatic language detection and a fixed language are mutually exclusive",
+      });
+    }
+    if (!policy.diarization.enabled && policy.diarization.maxSpeakers !== null) {
+      context.addIssue({
+        code: "custom",
+        path: ["diarization", "maxSpeakers"],
+        message: "disabled diarization cannot retain a speaker limit",
+      });
+    }
+    if (policy.fallback.mode === "disabled" && policy.fallback.targets.length > 0) {
+      context.addIssue({
+        code: "custom",
+        path: ["fallback", "targets"],
+        message: "disabled fallback cannot retain accepted targets",
+      });
+    }
+    if (policy.fallback.mode === "explicit" && policy.fallback.targets.length === 0) {
+      context.addIssue({
+        code: "custom",
+        path: ["fallback", "targets"],
+        message: "explicit fallback requires at least one accepted target",
+      });
+    }
+    const targetKeys = [policy.primary, ...policy.fallback.targets]
+      .filter((target): target is WorkspaceTranscriptionTarget => target !== null)
+      .map((target) =>
+        [
+          target.provider,
+          target.model ?? "",
+          target.credentialMode,
+          target.credentialConnectionId ?? "",
+          target.region ?? "",
+        ].join("\u0000"),
+      );
+    if (new Set(targetKeys).size !== targetKeys.length) {
+      context.addIssue({
+        code: "custom",
+        path: ["fallback", "targets"],
+        message: "transcription targets must be unique",
+      });
+    }
+  });
+export type WorkspaceTranscriptionPolicy = z.infer<typeof WorkspaceTranscriptionPolicy>;
+
 // Validates the KNOWN keys of workspaces.settings; passthrough keeps unknown
-// (future) keys rather than stripping them. memoryEnabled gates Workspace Memory
-// V1 agent surfaces (turn injection + first-party memory tools); default false.
+// (future) keys rather than stripping them. memoryEnabled and transcription are
+// both default-off capabilities.
 export const WorkspaceSettingsSchema = z
   .object({
     memoryEnabled: z.boolean().optional(),
+    transcription: WorkspaceTranscriptionPolicy.optional(),
   })
   .passthrough();
 export type WorkspaceSettings = z.infer<typeof WorkspaceSettingsSchema>;
@@ -581,12 +896,13 @@ export function resolveWorkspaceMemoryEnabled(settings: unknown): boolean {
   return parsed.success ? parsed.data.memoryEnabled === true : false;
 }
 
-// PATCH body for workspace settings: a partial patch that deep-merges into the
-// stored bag. memoryEnabled is the only typed key today; passthrough carries
-// forward-compatible unknown keys through validation.
+// PATCH body for workspace settings: a partial top-level patch that merges into
+// the stored bag. Nested transcription policy updates are therefore full
+// replacements; passthrough carries forward-compatible unknown keys.
 export const UpdateWorkspaceSettingsRequest = z
   .object({
     memoryEnabled: z.boolean().optional(),
+    transcription: WorkspaceTranscriptionPolicy.optional(),
   })
   .passthrough();
 export type UpdateWorkspaceSettingsRequest = z.infer<typeof UpdateWorkspaceSettingsRequest>;
@@ -606,6 +922,78 @@ export const UpdateWorkspaceModelPolicyRequest = z.object({
 });
 export type UpdateWorkspaceModelPolicyRequest = z.infer<typeof UpdateWorkspaceModelPolicyRequest>;
 
+const turnInitiatorIdentityFields = {
+  subjectId: z.string().min(1),
+  /** Immutable display snapshot; never an authorization input. */
+  label: z.string().min(1).optional(),
+} as const;
+
+/** Reserved creator/initiator id used only by legacy-row migration defaults. */
+export const UNATTRIBUTED_LEGACY_INITIATOR_SUBJECT_ID = "unattributed-legacy" as const;
+
+/**
+ * A named machine/service principal asserted by a trusted embedding host. This
+ * deliberately excludes `kind: "subject"`: a delegated service assertion may
+ * describe causal machine work, but it is not a generic human-impersonation
+ * mechanism. The authenticated grant remains the authorization boundary.
+ */
+export const ServiceTurnInitiator = z.object({
+  kind: z.literal("service"),
+  subjectId: z
+    .string()
+    .min(1)
+    .max(1024)
+    .refine((value) => value !== UNATTRIBUTED_LEGACY_INITIATOR_SUBJECT_ID, {
+      message: "unattributed-legacy is reserved for migrated rows",
+    }),
+  /** Immutable display snapshot; never an authorization input. */
+  label: z.string().min(1).max(256).optional(),
+});
+export type ServiceTurnInitiator = z.infer<typeof ServiceTurnInitiator>;
+
+/**
+ * Immutable, non-secret provenance captured with an initiator. This is audit
+ * context (for example an external occurrence id), not a second identity or
+ * authorization surface.
+ */
+export const TurnInitiatorContext = z.record(z.string(), z.unknown());
+export type TurnInitiatorContext = z.infer<typeof TurnInitiatorContext>;
+
+const reservedServiceTurnInitiatorContextKeys = new Set([
+  "backfill",
+  "label",
+  "provenanceError",
+  "via",
+  "viaTruncated",
+]);
+
+/** Bounded host provenance that cannot forge OpenGeni-owned lineage fields. */
+export const ServiceTurnInitiatorContext = TurnInitiatorContext.superRefine((value, ctx) => {
+  for (const key of reservedServiceTurnInitiatorContextKeys) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: [key],
+        message: `${key} is reserved OpenGeni initiator context`,
+      });
+    }
+  }
+  try {
+    if (new TextEncoder().encode(JSON.stringify(value)).byteLength > 4096) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "service initiator context exceeds 4096 UTF-8 bytes",
+      });
+    }
+  } catch {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "service initiator context must be JSON-serializable",
+    });
+  }
+});
+export type ServiceTurnInitiatorContext = z.infer<typeof ServiceTurnInitiatorContext>;
+
 export const AccountGrant = z.object({
   accountId: z.string().uuid(),
   subjectId: z.string().min(1),
@@ -623,6 +1011,10 @@ export const AccessGrant = z.object({
   subjectLabel: z.string().optional(),
   permissions: z.array(Permission),
   metadata: z.record(z.string(), z.unknown()).optional(),
+  // Optional trusted causal principal for a command submitted by an embedding
+  // host. Authorization still uses subjectId + permissions above.
+  serviceInitiator: ServiceTurnInitiator.optional(),
+  serviceInitiatorContext: ServiceTurnInitiatorContext.optional(),
 });
 export type AccessGrant = z.infer<typeof AccessGrant>;
 
@@ -637,34 +1029,76 @@ export const AccessContext = z.object({
 });
 export type AccessContext = z.infer<typeof AccessContext>;
 
-export const DelegatedAccessTokenPayload = z.object({
-  accountId: z.string().uuid(),
-  workspaceId: z.string().uuid(),
-  subjectId: z.string().min(1),
-  subjectLabel: z.string().optional(),
-  permissions: z.array(Permission).min(1),
-  // Worker-asserted session scope for first-party MCP calls (HMAC-signed, not
-  // agent-controlled); enables session-scoped tools such as goal management.
-  sessionId: z.string().uuid().optional(),
-  // The turn making the call (the caller's identity), HMAC-signed by the worker
-  // at turn setup. Lets a tool classify WHO is calling from the token itself,
-  // instead of racily re-reading the session's live active_turn_id — e.g. the
-  // sacred-pause guard must know if the CALLER is a machine child-notification
-  // turn, and the active pointer can flip to another turn mid-check.
-  turnId: z.string().uuid().optional(),
-  exp: z.number().int().positive(),
-});
+export const DelegatedAccessTokenPayload = z
+  .object({
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    subjectId: z.string().min(1),
+    subjectLabel: z.string().optional(),
+    permissions: z.array(Permission).min(1),
+    // Trusted embedding hosts can sign a causal service principal separately
+    // from the grant subject that authorizes the request. The claim is consumed
+    // only when a command creates a new session/turn.
+    serviceInitiator: ServiceTurnInitiator.optional(),
+    serviceInitiatorContext: ServiceTurnInitiatorContext.optional(),
+    // Worker-asserted session scope for first-party MCP calls (HMAC-signed, not
+    // agent-controlled); enables session-scoped tools such as goal management.
+    sessionId: z.string().uuid().optional(),
+    // The turn making the call (the caller's identity), HMAC-signed by the worker
+    // at turn setup. Lets a tool classify WHO is calling from the token itself,
+    // instead of racily re-reading the session's live active_turn_id — e.g. the
+    // sacred-pause guard must know if the CALLER is a machine child-notification
+    // turn, and the active pointer can flip to another turn mid-check.
+    turnId: z.string().uuid().optional(),
+    // Exact execution owner. Agent control commands are accepted only while this
+    // attempt still owns the signed turn.
+    attemptId: z.string().uuid().optional(),
+    executionGeneration: z.number().int().positive().optional(),
+    exp: z.number().int().positive(),
+  })
+  .superRefine((payload, ctx) => {
+    if (payload.serviceInitiatorContext && !payload.serviceInitiator) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["serviceInitiatorContext"],
+        message: "serviceInitiatorContext requires serviceInitiator",
+      });
+    }
+    if (
+      payload.serviceInitiator &&
+      (payload.turnId !== undefined ||
+        payload.attemptId !== undefined ||
+        payload.executionGeneration !== undefined)
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["serviceInitiator"],
+        message: "serviceInitiator cannot replace an exact agent-attempt initiator",
+      });
+    }
+  });
 export type DelegatedAccessTokenPayload = z.infer<typeof DelegatedAccessTokenPayload>;
 
+const delegatedAccessTokenPrefix = "ogd_";
+const delegatedServiceAccessTokenPrefix = "ogd2_";
+
 export async function signDelegatedAccessToken(
   secret: string,
   payload: DelegatedAccessTokenPayload,
 ): Promise<string> {
-  const encodedPayload = base64UrlEncode(
-    JSON.stringify(DelegatedAccessTokenPayload.parse(payload)),
+  const parsed = DelegatedAccessTokenPayload.parse(payload);
+  const prefix = parsed.serviceInitiator
+    ? delegatedServiceAccessTokenPrefix
+    : delegatedAccessTokenPrefix;
+  const encodedPayload = base64UrlEncode(JSON.stringify(parsed));
+  // The service-capable envelope binds its prefix into the signature. An old
+  // verifier accepts only ogd_ and therefore fails closed during a rolling
+  // deploy; changing ogd2_ to ogd_ cannot turn provenance loss into success.
+  const signature = await hmacSha256Base64Url(
+    secret,
+    prefix === delegatedServiceAccessTokenPrefix ? `${prefix}${encodedPayload}` : encodedPayload,
   );
-  const signature = await hmacSha256Base64Url(secret, encodedPayload);
-  return `ogd_${encodedPayload}.${signature}`;
+  return `${prefix}${encodedPayload}.${signature}`;
 }
 
 export async function verifyDelegatedAccessToken(
@@ -672,30 +1106,48 @@ export async function verifyDelegatedAccessToken(
   token: string,
   nowSeconds = Math.floor(Date.now() / 1000),
 ): Promise<DelegatedAccessTokenPayload | null> {
-  if (!token.startsWith("ogd_")) {
+  const prefix = token.startsWith(delegatedServiceAccessTokenPrefix)
+    ? delegatedServiceAccessTokenPrefix
+    : token.startsWith(delegatedAccessTokenPrefix)
+      ? delegatedAccessTokenPrefix
+      : null;
+  if (!prefix) {
     return null;
   }
-  const withoutPrefix = token.slice("ogd_".length);
+  const withoutPrefix = token.slice(prefix.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);
+  const expected = await hmacSha256Base64Url(
+    secret,
+    prefix === delegatedServiceAccessTokenPrefix ? `${prefix}${encodedPayload}` : encodedPayload,
+  );
   if (!constantTimeEqual(signature, expected)) {
     return null;
   }
-  const payload = DelegatedAccessTokenPayload.safeParse(
-    JSON.parse(base64UrlDecode(encodedPayload)),
-  );
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(base64UrlDecode(encodedPayload));
+  } catch {
+    return null;
+  }
+  const payload = DelegatedAccessTokenPayload.safeParse(decoded);
   if (!payload.success || payload.data.exp < nowSeconds) {
     return null;
   }
+  if (
+    (prefix === delegatedServiceAccessTokenPrefix) !==
+    (payload.data.serviceInitiator !== undefined)
+  ) {
+    return null;
+  }
   return payload.data;
 }
 
-// --- Enrollment bearer credential (bring-your-own-compute M5, dossier §10.2) ---
+// --- Enrollment bearer credential (bring-your-own-compute M5) ---
 //
 // The signed bearer the agent presents to the control plane after enrollment (the
 // EnrollmentCredentials.bearer the poll returns). REUSES the SAME HMAC envelope as
@@ -828,7 +1280,7 @@ export async function verifyEnrollToken(
   return payload.data;
 }
 
-// --- Scoped data-plane stream token (master-spine §C.3 / crosscut PART 1.3) ---
+// --- Scoped data-plane stream token (sandbox contract §C.3 / crosscut PART 1.3) ---
 //
 // REUSES the existing HMAC envelope (sign/verifyDelegatedAccessToken's
 // base64Url + hmacSha256Base64Url) — NOT a second crypto — but with a distinct
@@ -913,7 +1365,7 @@ export async function verifyStreamToken(
   return payload.data;
 }
 
-// --- Relay PRODUCER token (bring-your-own-compute M8b, dossier §10.5) ---
+// --- Relay PRODUCER token (bring-your-own-compute M8b) ---
 //
 // 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
@@ -1147,7 +1599,11 @@ export type Entitlements = z.infer<typeof Entitlements>;
 
 export const LimitDecision = z.discriminatedUnion("allowed", [
   z.object({ allowed: z.literal(true) }),
-  z.object({ allowed: z.literal(false), code: z.string(), message: z.string() }),
+  z.object({
+    allowed: z.literal(false),
+    code: z.string(),
+    message: z.string(),
+  }),
 ]);
 export type LimitDecision = z.infer<typeof LimitDecision>;
 
@@ -1195,10 +1651,21 @@ export type EntitlementsPort = {
 export const GitCredentialProvider = z.enum(["github", "gitlab", "azure_devops"]);
 export type GitCredentialProvider = z.infer<typeof GitCredentialProvider>;
 
+// Host-opaque identity for one independently mintable Git credential. It is
+// deliberately NOT constrained to a filesystem-safe alphabet: runtimes hash it
+// before using it in paths, command text, or environment variable names.
+export const GitCredentialBindingId = z.string().min(1).max(256);
+export type GitCredentialBindingId = z.infer<typeof GitCredentialBindingId>;
+
+export const GitRepositoryAccess = z.enum(["read", "write"]);
+export type GitRepositoryAccess = z.infer<typeof GitRepositoryAccess>;
+
 const GitProviderRepositoryId = z.union([z.number().int().positive(), z.string().min(1)]);
 
 export const GitCredentialRepositoryRef = z.object({
   provider: GitCredentialProvider.optional(),
+  credentialBindingId: GitCredentialBindingId.optional(),
+  access: GitRepositoryAccess.optional(),
   uri: z.string().min(1),
   ref: z.string().min(1),
   repositoryId: GitProviderRepositoryId.optional(),
@@ -1208,10 +1675,10 @@ export const GitCredentialRepositoryRef = z.object({
 });
 export type GitCredentialRepositoryRef = z.infer<typeof GitCredentialRepositoryRef>;
 
-// ============ P4a — Connection-credential provider (§7.6) ============
+// ============ connection-credential provider — Connection-credential provider (§7.6) ============
 //
-// The host-providable per-run credential-mint seam over OpenGeni's TWO
-// run-scoped credential sites in the worker:
+// The host-providable credential seam over OpenGeni's run-scoped credential
+// sites in the worker and API:
 //   - GIT credentials: run-scoped provider tokens minted in
 //     `sandboxEnvironmentForRun` (standalone self-mints GitHub App tokens from
 //     `settings`; embedded hosts can broker GitHub, GitLab, and Azure DevOps)
@@ -1219,6 +1686,8 @@ export type GitCredentialRepositoryRef = z.infer<typeof GitCredentialRepositoryR
 //   - SANDBOX secrets: the decrypted variable set values loaded in
 //     `loadVariableSetForRun` (today decrypted with
 //     `environmentsEncryptionKeyBytes(settings)`).
+//   - MCP credentials: request-time transport headers for connection-backed
+//     servers, shared by normal model tools and Toolspace/Code Mode.
 //
 // In embedded/separate topologies the HOST owns these external connections
 // (its GitHub App, its secret vault + encryption key). When a host binds this
@@ -1226,7 +1695,7 @@ export type GitCredentialRepositoryRef = z.infer<typeof GitCredentialRepositoryR
 // from `settings`. Unset (standalone default) → byte-for-byte today's
 // self-mint.
 //
-// FORK-7 CROSS-CHECK (the host-mapping safety guardrail): a credential
+// Workspace-scope 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
 // any git provider token seed (or applying decrypted environment values). A host mapping bug that
@@ -1236,10 +1705,26 @@ export type GitCredentialRepositoryRef = z.infer<typeof GitCredentialRepositoryR
 export type GitCredentialsRequest = {
   accountId: string;
   workspaceId: string;
+  /** Immutable authority admitted with the turn requesting this credential. */
+  sessionId: string;
+  rootSessionId: string;
+  turnId: string;
+  attemptId: string;
+  executionGeneration: number;
+  initiator: TurnInitiator;
+  initiatorContext: TurnInitiatorContext;
   // Provider defaults to "github" for the legacy request shape. GitHub-only
   // hosts can keep reading installationId/repositoryIds exactly as before;
   // provider-aware hosts should branch on this and repositoryRefs.
   provider?: GitCredentialProvider;
+  // Present when the host supplied an explicit binding or when more than one
+  // independently mintable credential exists for this provider. A host must
+  // mint only this binding; OpenGeni never treats provider identity as enough
+  // to select among multiple accounts/installations.
+  credentialBindingId?: GitCredentialBindingId;
+  // Canonical lower-case host shared by this binding's repository refs when
+  // there is exactly one. Binding-aware providers echo it when present.
+  providerHost?: string;
   // Token requests are the existing behavior. Identity requests let lazy
   // sandbox provisioning resolve stable git author/committer identity before
   // the box exists while deferring the rotating token value to first provision.
@@ -1257,9 +1742,16 @@ export type GitCredentials = {
   // purpose="identity" so hosts can return only stable git identity before lazy
   // sandbox provision. The value never enters the manifest.
   token?: string;
-  // FORK-7 echo: the workspace the provider scoped this token to. The activity
+  // workspace-scope cross-check echo: the workspace the provider scoped this token to. The activity
   // asserts `workspaceId === request.workspaceId` before injecting.
   workspaceId: string;
+  // Strict request echoes for binding-aware requests. OpenGeni validates these
+  // before accepting a token, preventing a host routing bug from returning a
+  // sibling connection's credential. They remain optional for legacy single-
+  // binding/provider hosts.
+  credentialBindingId?: GitCredentialBindingId;
+  provider?: GitCredentialProvider;
+  providerHost?: string;
   // Optional provider expiry for host-managed proactive renewal. ISO-8601;
   // null/omitted means the host does not expose a deadline and OpenGeni uses
   // its conservative bounded refresh cadence instead.
@@ -1282,7 +1774,7 @@ export type SandboxSecrets = {
   // `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.
+  // workspace-scope cross-check echo: the workspace the provider scoped these secrets to.
   workspaceId: string;
   // Optional variableSet metadata; when omitted the activity uses the
   // variableSetId as both id and name (the local decrypt carries the row's
@@ -1292,24 +1784,266 @@ export type SandboxSecrets = {
   description?: string | null;
 };
 
+export type CredentialAuthNeededReason =
+  | "missing_connection"
+  | "expired"
+  | "insufficient_scope"
+  | "refresh_failed";
+
+/**
+ * Host-owned run credentials are materialized below one OpenGeni-owned sandbox
+ * directory. Paths are relative POSIX names; the runtime validates traversal,
+ * collisions, bounds, and modes before any content reaches a sandbox.
+ */
+export type RunCredentialFile = {
+  path: string;
+  content: string;
+  mode?: "0400" | "0600";
+};
+
+export type RunCredentialAuthNeeded = {
+  reason: CredentialAuthNeededReason;
+  providerDomain?: string;
+  connectionId?: string;
+  scopes?: string[];
+  resource?: string;
+  authorizationUrl?: string;
+  /** Bounded non-secret guidance. Never place credential material here. */
+  message?: string;
+};
+
+export type RunCredentialRedaction = {
+  /** Bounded diagnostic label used only in the replacement marker. */
+  name: string;
+  /** One atomic secret value that must be removed from streamed/audit output. */
+  value: string;
+};
+
+export type RunCredentialsRequest = {
+  accountId: string;
+  workspaceId: string;
+  sessionId: string;
+  parentSessionId: string | null;
+  rootSessionId: string;
+  /** All sessions sharing this sandbox group share one OS/filesystem trust boundary. */
+  sandboxGroupId: string;
+  turnId: string;
+  attemptId: string;
+  executionGeneration: number;
+  /** Immutable authority admitted with this turn. */
+  initiator: TurnInitiator;
+  initiatorContext: TurnInitiatorContext;
+  effectiveSandboxBackend: SandboxBackend;
+  sandboxOs: SandboxOs;
+  purpose: "provision" | "renewal";
+  forceRefresh: boolean;
+  /** Informational standalone variable-set identity; never gates host resolution. */
+  variableSet: { id: string; name: string } | null;
+};
+
+export type RunCredentialsResolution =
+  | {
+      /**
+       * The frozen target/attempt must not receive host material. Hosts use
+       * this for unsupported OSes/backends and policy-based opt-out; the
+       * decision must remain stable for the attempt.
+       */
+      status: "not_applicable";
+      accountId: string;
+      workspaceId: string;
+      sessionId: string;
+    }
+  | {
+      status: "ok";
+      /** Scope echoes are mandatory and checked before materialization. */
+      accountId: string;
+      workspaceId: string;
+      sessionId: string;
+      /** Secret environment values. Always delivered off-manifest. */
+      environment: Record<string, string>;
+      files?: RunCredentialFile[];
+      /** Environment name to one returned relative file path. */
+      fileEnvironment?: Record<string, string>;
+      /**
+       * Atomic sensitive values embedded inside credential files or derived
+       * material. Environment values are registered automatically; hosts list
+       * additional file-contained values here so chunked output is redacted.
+       */
+      redactions?: RunCredentialRedaction[];
+      /** Earliest material expiry. Null/omitted uses a bounded refresh cadence. */
+      expiresAt?: string | null;
+      /** Partial degradation: usable material may coexist with reconnect notices. */
+      authNeeded?: RunCredentialAuthNeeded[];
+    }
+  | {
+      status: "auth_needed";
+      accountId: string;
+      workspaceId: string;
+      sessionId: string;
+      authNeeded: RunCredentialAuthNeeded[];
+    };
+
+export const McpConnectionResourceScope = z
+  .object({
+    /** Provider-stable repository identity, serialized as a string on the wire. */
+    id: z.string().min(1).max(512),
+    kind: z.literal("repository"),
+  })
+  .strict();
+export type McpConnectionResourceScope = z.infer<typeof McpConnectionResourceScope>;
+
+const McpConnectionResourceScopes = z
+  .array(McpConnectionResourceScope)
+  .min(1)
+  .max(256)
+  .superRefine((resources, context) => {
+    const seen = new Set<string>();
+    for (const [index, resource] of resources.entries()) {
+      const key = `${resource.kind}\0${resource.id}`;
+      if (seen.has(key)) {
+        context.addIssue({
+          code: "custom",
+          message: "selectedResources must not contain duplicates",
+          path: [index],
+        });
+      }
+      seen.add(key);
+    }
+  });
+
+export const McpServerConnectionRef = z
+  .object({
+    /** Opaque host or standalone connection identifier. */
+    connectionId: z.string().min(1).optional(),
+    /** Stable provider family (for example github, gitlab, or azure_devops). */
+    provider: z.string().min(1).max(128).optional(),
+    /** Provider host or tenant domain. */
+    providerDomain: z.string().min(1),
+    kind: z.enum(["oauth2", "api_key", "app_install", "delegated"]).optional(),
+    scopes: z.array(z.string().min(1)).optional(),
+    /** OAuth resource indicator. This is distinct from selectedResources. */
+    resource: z.string().min(1).optional(),
+    /** Exact provider resources this MCP binding is allowed to operate on. */
+    selectedResources: McpConnectionResourceScopes.optional(),
+    subjectScope: z.enum(["workspace", "subject"]).optional(),
+  })
+  .strict()
+  .superRefine((reference, context) => {
+    if (!reference.selectedResources) return;
+    if (!reference.connectionId) {
+      context.addIssue({
+        code: "custom",
+        message: "selectedResources requires connectionId",
+        path: ["connectionId"],
+      });
+    }
+    if (!reference.provider) {
+      context.addIssue({
+        code: "custom",
+        message: "selectedResources requires provider",
+        path: ["provider"],
+      });
+    }
+  });
+export type McpServerConnectionRef = z.infer<typeof McpServerConnectionRef>;
+
+export type McpCredentialsRequest = {
+  accountId: string;
+  workspaceId: string;
+  /** Immediate session whose model or Toolspace call needs the credential. */
+  sessionId: string;
+  /** Workspace-scoped lineage root for host authorization and binding lookup. */
+  rootSessionId: string;
+  turnId: string;
+  /** Null only while a durable turn exists without a currently executing attempt. */
+  attemptId: string | null;
+  executionGeneration: number;
+  /** The immutable authority that admitted this turn. Never substitute the sandbox caller. */
+  initiator: TurnInitiator;
+  initiatorContext: TurnInitiatorContext;
+  /** Immediate technical caller, retained only as non-authoritative audit context. */
+  callerSubjectId?: string;
+  surface: "model" | "toolspace";
+  serverId: string;
+  toolName?: string;
+  connectionRef: McpServerConnectionRef;
+  forceRefresh: boolean;
+};
+
+export type McpCredentialAuthNeededReason =
+  | CredentialAuthNeededReason
+  | "unsupported_auth"
+  | "resource_scope_unavailable";
+
+export type McpCredentialResolution =
+  | {
+      status: "ok";
+      /** Scope echoes are mandatory and verified before any header is used. */
+      accountId: string;
+      workspaceId: string;
+      sessionId: string;
+      headers: Record<string, string>;
+      connectionId: string;
+      providerDomain: string;
+      provider?: string;
+      scopes?: string[];
+      resource?: string;
+      selectedResources?: McpConnectionResourceScope[];
+      expiresAt?: string | null;
+    }
+  | {
+      status: "auth_needed";
+      /** Scope echoes are mandatory even when the credential cannot be resolved. */
+      accountId: string;
+      workspaceId: string;
+      sessionId: string;
+      reason: McpCredentialAuthNeededReason;
+      providerDomain: string;
+      provider?: string;
+      connectionId?: string;
+      scopes?: string[];
+      resource?: string;
+      selectedResources?: McpConnectionResourceScope[];
+      authorizationUrl?: string;
+    };
+
 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.
+  // Every leg is optional: a host may drive only the credential classes it
+  // owns. An unset leg falls through to today's standalone implementation for
+  // that leg only.
   gitCredentials?(input: GitCredentialsRequest): Promise<GitCredentials>;
   sandboxSecrets?(input: SandboxSecretsRequest): Promise<SandboxSecrets>;
+  /**
+   * Resolve host-owned, session-aware sandbox credentials independently of an
+   * OpenGeni variable set. OpenGeni transports and renews the material; the host
+   * remains the sole owner of connection selection and credential policy.
+   */
+  runCredentials?(input: RunCredentialsRequest): Promise<RunCredentialsResolution>;
+  /**
+   * Resolve rotating MCP transport credentials at request time. Embedded hosts
+   * use this to keep their provider connection as the sole credential source;
+   * OpenGeni never requires a duplicate connection record. The same resolver is
+   * used by model-visible MCP tools and the additive Toolspace/Code Mode proxy.
+   */
+  mcpCredentials?(input: McpCredentialsRequest): Promise<McpCredentialResolution>;
 };
 
-// ============ P4a — GitHub App API port (BYO-App, §7.6 / SPIKE-2 remainder) ===
+// ============ connection-credential provider — GitHub App API port (BYO-App, §7.6 / GitHub credential prototype 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
+// The host-driven GitHub-API credential leg. GitHub credential prototype closed the establishment +
+// gate (storage) axis; this closes the credential leg by making the 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, …)`).
+//   - authorizeUser: OAuth code exchange + user-visible installation and
+//     repository permission discovery. Retained for provider ABI compatibility;
+//     visibility is not proof of installation authority and core does not use
+//     this method for new workspace binding.
+//   - verifyInstallationAccessForUser: OAuth code→token + installation lookup,
+//     also retained for provider ABI compatibility and not used for binding.
+//   - getInstallation: retained in the provider ABI for compatibility. Direct
+//     existing-installation selection is fail-closed and core does not call
+//     this method for binding.
 //   - listRepositories: the installation-scoped repo listing behind
 //     `GET /v1/workspaces/:id/github/repositories` (today
 //     `listGitHubAppRepositories(settings, …)`).
@@ -1324,11 +2058,31 @@ export type GitHubInstallationSummary = {
   suspended: boolean;
 };
 
+export type GitHubRepositoryPermissions = {
+  admin: boolean;
+  maintain: boolean;
+  push: boolean;
+  triage: boolean;
+  pull: boolean;
+};
+
+export type GitHubUserRepositoryAccess = GitHubRepository & {
+  permissions: GitHubRepositoryPermissions;
+};
+
+export type GitHubUserInstallationAccess = GitHubInstallationSummary & {
+  repositories: GitHubUserRepositoryAccess[];
+};
+
 export type GitHubAppApiPort = {
+  authorizeUser?: (input: { code: string }) => Promise<GitHubUserInstallationAccess[]>;
   verifyInstallationAccessForUser?: (input: {
     code: string;
     installationId: number;
   }) => Promise<GitHubInstallationSummary>;
+  getInstallation?: (input: {
+    installationId: number;
+  }) => Promise<GitHubInstallationSummary | null>;
   listRepositories?: (input: { installationIds?: number[] }) => Promise<GitHubRepository[]>;
 };
 
@@ -1368,6 +2122,8 @@ export const RepositoryResourceRef = z.object({
   mountPath: z.string().min(1).optional(),
   subpath: z.string().min(1).optional(),
   provider: GitCredentialProvider.optional(),
+  credentialBindingId: GitCredentialBindingId.optional(),
+  access: GitRepositoryAccess.optional(),
   repositoryId: GitProviderRepositoryId.optional(),
   installationId: GitProviderRepositoryId.optional(),
   projectId: GitProviderRepositoryId.optional(),
@@ -1377,6 +2133,53 @@ export const RepositoryResourceRef = z.object({
 });
 export type RepositoryResourceRef = z.infer<typeof RepositoryResourceRef>;
 
+function positiveGitProviderInteger(value: unknown): number | null {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
+  if (typeof value === "string" && /^\d+$/.test(value) && Number(value) > 0) {
+    return Number(value);
+  }
+  return null;
+}
+
+/**
+ * Resolve whether a repository participates in platform-brokered Git auth.
+ * Provider-less public repositories return null; legacy GitHub aliases infer
+ * GitHub only when both positive installation and repository ids are present.
+ */
+export function gitCredentialProviderForRepository(
+  resource: RepositoryResourceRef,
+): GitCredentialProvider | null {
+  if (resource.provider) return resource.provider;
+  if (
+    positiveGitProviderInteger(resource.githubInstallationId) &&
+    positiveGitProviderInteger(resource.githubRepositoryId)
+  ) {
+    return "github";
+  }
+  return null;
+}
+
+/**
+ * Derive the one canonical runtime/broker identity for a repository credential.
+ * Every consumer must use this helper so mint grouping, token filenames, and
+ * credential-helper routing cannot diverge on legacy provider ids.
+ */
+export function gitCredentialBindingIdForRepository(
+  resource: RepositoryResourceRef,
+  provider: GitCredentialProvider | null = gitCredentialProviderForRepository(resource),
+): GitCredentialBindingId | null {
+  if (!provider) return null;
+  const installationId =
+    provider === "github"
+      ? positiveGitProviderInteger(resource.githubInstallationId ?? resource.installationId)
+      : null;
+  return (
+    resource.credentialBindingId ??
+    resource.connectionId ??
+    (installationId ? `github-installation:${installationId}` : provider)
+  );
+}
+
 export const FileResourceRef = z.object({
   kind: z.literal("file"),
   fileId: z.string().uuid(),
@@ -1387,6 +2190,109 @@ export type FileResourceRef = z.infer<typeof FileResourceRef>;
 export const ResourceRef = z.discriminatedUnion("kind", [RepositoryResourceRef, FileResourceRef]);
 export type ResourceRef = z.infer<typeof ResourceRef>;
 
+export class ResourceMountPathError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ResourceMountPathError";
+  }
+}
+
+/**
+ * Normalize one workspace-relative resource mount path for every runtime.
+ *
+ * Backslashes are treated as separators so a path cannot be harmless on Linux
+ * but become traversal on a connected Windows machine. Empty, absolute,
+ * drive-qualified, dot-segment, NUL-containing, and repeated-separator paths
+ * fail closed instead of being silently reinterpreted.
+ */
+export function normalizeResourceMountPath(path: string): string {
+  const normalizedSeparators = path.trim().replace(/\\/g, "/");
+  if (
+    !normalizedSeparators ||
+    normalizedSeparators.startsWith("/") ||
+    /^[A-Za-z]:\//.test(normalizedSeparators) ||
+    normalizedSeparators.includes("\0")
+  ) {
+    throw new ResourceMountPathError(`invalid resource mount path: ${path}`);
+  }
+  const segments = normalizedSeparators.split("/");
+  if (
+    segments.some(
+      (segment) =>
+        !segment ||
+        segment === "." ||
+        segment === ".." ||
+        /[<>:"|?*\u0000-\u001f]/.test(segment) ||
+        /[ .]$/.test(segment) ||
+        /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(segment),
+    )
+  ) {
+    throw new ResourceMountPathError(`invalid resource mount path: ${path}`);
+  }
+  return segments.join("/");
+}
+
+/** Normalize a repository-internal subpath while preserving legacy `/path/` input. */
+export function normalizeRepositorySubpath(path: string): string {
+  const relative = path
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/^\/+|\/+$/g, "");
+  return normalizeResourceMountPath(relative);
+}
+
+/** A conservative collision identity that is portable to case-insensitive hosts. */
+export function resourceMountPathCollisionKey(path: string): string {
+  return normalizeResourceMountPath(path).normalize("NFKC").toLowerCase();
+}
+
+/**
+ * Default repository mount identity. The normalized remote host (including a
+ * non-default port) is part of the path, so equal owner/repo names on GitHub,
+ * GitLab, Azure DevOps, or a custom host do not collide. Encoding the host keeps
+ * IPv6/custom-port identities inside one portable path segment.
+ */
+export function defaultRepositoryMountPath(uri: string): string {
+  let url: URL;
+  try {
+    url = new URL(uri);
+  } catch {
+    throw new ResourceMountPathError(`invalid repository URI for mount path: ${uri}`);
+  }
+  if (url.protocol !== "https:" || !url.host) {
+    throw new ResourceMountPathError(`invalid repository URI for mount path: ${uri}`);
+  }
+  const repositoryPath = url.pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/, "");
+  const segments = repositoryPath.split("/").filter(Boolean);
+  if (segments.length < 2) {
+    throw new ResourceMountPathError(`repository URI must include owner and repo: ${uri}`);
+  }
+  return normalizeResourceMountPath(
+    `repos/${encodeURIComponent(url.host.toLowerCase())}/${segments.join("/")}`,
+  );
+}
+
+/** Resolve the exact mount used by API normalization, manifests, and clone hooks. */
+export function resourceMountPath(resource: ResourceRef): string {
+  if (resource.mountPath) return normalizeResourceMountPath(resource.mountPath);
+  return resource.kind === "file"
+    ? normalizeResourceMountPath(`files/${resource.fileId}`)
+    : defaultRepositoryMountPath(resource.uri);
+}
+
+/** Fail before sandbox execution when two resources share a portable path. */
+export function assertUniqueResourceMountPaths(resources: readonly ResourceRef[]): void {
+  const mounted = new Set<string>();
+  for (const resource of resources) {
+    const path = resourceMountPath(resource);
+    const key = resourceMountPathCollisionKey(path);
+    if (mounted.has(key)) {
+      throw new ResourceRefConflictError(`resource mount path is already attached: ${path}`);
+    }
+    mounted.add(key);
+  }
+}
+
 export const FileStatus = z.enum(["pending_upload", "ready", "failed", "expired", "deleted"]);
 export type FileStatus = z.infer<typeof FileStatus>;
 
@@ -1728,6 +2634,9 @@ export const SessionMcpServerInput = z.object({
   // Write-only credential headers. Values are encrypted at rest and never
   // returned in session responses or events; response metadata exposes names.
   headers: z.record(z.string(), z.string()).optional(),
+  // Non-secret opaque pointer resolved at request time by the standalone
+  // connection broker or an embedding host's mcpCredentials port.
+  connectionRef: McpServerConnectionRef.optional(),
 });
 export type SessionMcpServerInput = z.infer<typeof SessionMcpServerInput>;
 
@@ -1744,6 +2653,7 @@ export const SessionMcpServerMetadata = z
     url: httpsUrl,
     headerNames: z.array(z.string()).default([]),
     credentialVersion: z.number().int().positive(),
+    connectionRef: McpServerConnectionRef.nullable().default(null),
   })
   .strict();
 export type SessionMcpServerMetadata = z.infer<typeof SessionMcpServerMetadata>;
@@ -1783,10 +2693,14 @@ export function mergeResourceRefs(
   additions: ResourceRef[],
   options: { rejectConflicts?: boolean } = {},
 ): ResourceRef[] {
+  if (options.rejectConflicts) {
+    assertUniqueResourceMountPaths(existing);
+  }
   const out = [...existing];
   const mountPaths = new Map(
-    existing.flatMap((resource) =>
-      resource.mountPath ? [[resource.mountPath, stableJson(resource)] as const] : [],
+    existing.map(
+      (resource) =>
+        [resourceMountPathCollisionKey(resourceMountPath(resource)), stableJson(resource)] as const,
     ),
   );
   const identities = new Map(
@@ -1800,11 +2714,10 @@ export function mergeResourceRefs(
       continue;
     }
     if (options.rejectConflicts) {
-      const existingAtMount = resource.mountPath ? mountPaths.get(resource.mountPath) : undefined;
+      const mountPath = resourceMountPath(resource);
+      const existingAtMount = mountPaths.get(resourceMountPathCollisionKey(mountPath));
       if (existingAtMount && existingAtMount !== serialized) {
-        throw new ResourceRefConflictError(
-          `resource mount path is already attached: ${resource.mountPath}`,
-        );
+        throw new ResourceRefConflictError(`resource mount path is already attached: ${mountPath}`);
       }
       const identity = resourceIdentityKey(resource);
       const existingIdentity = identities.get(identity);
@@ -1817,9 +2730,7 @@ export function mergeResourceRefs(
     out.push(resource);
     exact.add(serialized);
     identities.set(resourceIdentityKey(resource), serialized);
-    if (resource.mountPath) {
-      mountPaths.set(resource.mountPath, serialized);
-    }
+    mountPaths.set(resourceMountPathCollisionKey(resourceMountPath(resource)), serialized);
   }
   return out;
 }
@@ -1874,6 +2785,7 @@ export const SessionTurnStatus = z.enum([
   "failed",
   "cancelled",
   "superseded",
+  "withdrawn_for_edit",
 ]);
 export type SessionTurnStatus = z.infer<typeof SessionTurnStatus>;
 
@@ -1987,7 +2899,9 @@ export type ClearSessionContextRequest = z.infer<typeof ClearSessionContextReque
 export const CLEARED_RUN_STATE_MARKER = "$opengeniCleared" as const;
 
 /** The canonical sentinel serializedRunState value a context clear stores. */
-export const CLEARED_RUN_STATE_BLOB = JSON.stringify({ [CLEARED_RUN_STATE_MARKER]: true });
+export const CLEARED_RUN_STATE_BLOB = JSON.stringify({
+  [CLEARED_RUN_STATE_MARKER]: true,
+});
 
 /**
  * True when a serialized run-state blob is the cleared sentinel rather than a
@@ -2027,6 +2941,168 @@ export const CompactSessionContextResult = z.object({
 });
 export type CompactSessionContextResult = z.infer<typeof CompactSessionContextResult>;
 
+/**
+ * The principal whose authority accepted a session or turn. `subjectId` is an
+ * opaque host/standalone identity and therefore must never encode `kind` by
+ * convention: embedding hosts own their subject namespace.
+ */
+export const TurnInitiator = z.object({
+  kind: z.enum(["subject", "service"]),
+  ...turnInitiatorIdentityFields,
+});
+export type TurnInitiator = z.infer<typeof TurnInitiator>;
+
+// ============ embedding host session authorization ============
+//
+// Workspace permissions answer whether a principal may use an OpenGeni
+// capability. An embedding host can additionally own per-session visibility
+// (ownership, sharing, nested workspaces, revocation). This port is the one
+// host-neutral boundary for that second decision. Inputs contain OpenGeni ids
+// and immutable, non-secret authority only; host records and policy details
+// never cross the boundary.
+
+export const SessionAuthorizationSurface = z.enum([
+  "http",
+  "core",
+  "stream",
+  "first_party_mcp",
+  "toolspace",
+]);
+export type SessionAuthorizationSurface = z.infer<typeof SessionAuthorizationSurface>;
+
+export const SessionAuthorizationOperation = z.enum([
+  "session.read",
+  "session.events.read",
+  "session.stream.read",
+  "session.stream.acknowledge",
+  "session.turns.read",
+  "session.append",
+  "session.steer",
+  "session.control",
+  "session.queue.read",
+  "session.queue.control",
+  "session.composer.read",
+  "session.composer.write",
+  "session.lineage.read",
+  "session.capture.read",
+  "session.files.read",
+  "session.files.write",
+  "session.git.read",
+  "session.terminal.read",
+  "session.terminal.control",
+  "session.viewer.read",
+  "session.viewer.control",
+  "session.first_party_mcp.call",
+  "session.toolspace.call",
+  "session.pin.write",
+  "session.codex_account.write",
+  "session.context.write",
+  "session.approval.write",
+  "session.human_input.read",
+  "session.human_input.write",
+  "session.title.write",
+  "session.goal.read",
+  "session.goal.write",
+  "session.child.create",
+]);
+export type SessionAuthorizationOperation = z.infer<typeof SessionAuthorizationOperation>;
+
+export const SessionAuthorizationActor = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("subject"),
+    subjectId: z.string().min(1),
+    subjectLabel: z.string().min(1).optional(),
+  }),
+  z.object({
+    kind: z.literal("agent_attempt"),
+    /** Technical, authenticated first-party caller (not the host authority). */
+    subjectId: z.string().min(1),
+    callerSessionId: z.string().uuid(),
+    callerRootSessionId: z.string().uuid(),
+    turnId: z.string().uuid(),
+    attemptId: z.string().uuid(),
+    executionGeneration: z.number().int().positive(),
+    /** Frozen authority that admitted the calling turn. */
+    initiator: TurnInitiator,
+    initiatorContext: TurnInitiatorContext,
+  }),
+]);
+export type SessionAuthorizationActor = z.infer<typeof SessionAuthorizationActor>;
+
+export const SessionAuthorizationTarget = z.object({
+  sessionId: z.string().uuid(),
+  /** Server-resolved workspace lineage root; never accepted from a caller. */
+  rootSessionId: z.string().uuid(),
+});
+export type SessionAuthorizationTarget = z.infer<typeof SessionAuthorizationTarget>;
+
+export type AuthorizeSessionInput = {
+  accountId: string;
+  workspaceId: string;
+  actor: SessionAuthorizationActor;
+  target: SessionAuthorizationTarget;
+  operation: SessionAuthorizationOperation;
+  surface: SessionAuthorizationSurface;
+};
+
+export const SessionAuthorizationDecision = z.discriminatedUnion("allowed", [
+  z.object({
+    allowed: z.literal(true),
+    /**
+     * Whether related-session metadata may be projected with the target.
+     * `target` is the fail-closed default for exact shares; `root` permits the
+     * target's full lineage tree. This does not authorize a separate operation
+     * against another session, which always requires its own decision.
+     */
+    relatedSessionAccess: z.enum(["target", "root"]).optional(),
+    /** A host may request a tighter stream reauthorization bound. */
+    reauthorizeAfterMs: z.number().int().min(1_000).max(60_000).optional(),
+  }),
+  z.object({
+    allowed: z.literal(false),
+    reason: z.enum(["not_found", "forbidden", "revoked"]),
+  }),
+]);
+export type SessionAuthorizationDecision = z.infer<typeof SessionAuthorizationDecision>;
+
+/**
+ * A database-applicable listing scope. `rootSessionIds` includes every
+ * descendant of those lineage anchors; `sessionIds` authorizes only the exact
+ * sessions. Supplying neither is an explicit empty scope. OpenGeni intersects
+ * every id with the requested workspace and never trusts a host scope as
+ * session existence evidence.
+ */
+export const SESSION_AUTHORIZATION_LIST_SCOPE_MAX_IDS = 10_000;
+
+export const SessionAuthorizationListScope = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("all") }),
+  z.object({
+    kind: z.literal("scoped"),
+    rootSessionIds: z.array(z.string().uuid()).max(SESSION_AUTHORIZATION_LIST_SCOPE_MAX_IDS),
+    sessionIds: z.array(z.string().uuid()).max(SESSION_AUTHORIZATION_LIST_SCOPE_MAX_IDS),
+  }),
+]);
+export type SessionAuthorizationListScope = z.infer<typeof SessionAuthorizationListScope>;
+
+export type ResolveSessionAuthorizationListScopeInput = {
+  accountId: string;
+  workspaceId: string;
+  actor: SessionAuthorizationActor;
+  surface: SessionAuthorizationSurface;
+};
+
+export type SessionAuthorizationPort = {
+  authorizeSession(input: AuthorizeSessionInput): Promise<SessionAuthorizationDecision>;
+  /**
+   * Return the complete current scope used inside OpenGeni's cursor query.
+   * This is deliberately not a post-filter callback: search, pinning, ordering,
+   * totals, and cursor advancement must all operate on authorized rows.
+   */
+  resolveListScope(
+    input: ResolveSessionAuthorizationListScopeInput,
+  ): Promise<SessionAuthorizationListScope>;
+};
+
 export const SessionTurn = z.object({
   id: z.string().uuid(),
   workspaceId: z.string().uuid(),
@@ -2049,6 +3125,8 @@ export const SessionTurn = z.object({
   executionGeneration: z.number().int().nonnegative(),
   activeAttemptId: z.string().uuid().nullable(),
   lineage: z.record(z.string(), z.unknown()),
+  initiator: TurnInitiator,
+  initiatorContext: TurnInitiatorContext,
   cancelledBy: z.string().nullable(),
   cancelReason: z.string().nullable(),
   startedAt: z.string().nullable(),
@@ -2058,70 +3136,409 @@ export const SessionTurn = z.object({
 });
 export type SessionTurn = z.infer<typeof SessionTurn>;
 
+export const EffectiveControlBlocker = z.object({
+  kind: z.enum(["session", "workspace"]),
+  sessionId: z.string().uuid().optional(),
+  displayName: z.string().min(1),
+  actor: z.string().nullable(),
+  reason: z.string().nullable(),
+  changedAt: z.string().nullable(),
+  revision: z.number().int().nonnegative(),
+});
+export type EffectiveControlBlocker = z.infer<typeof EffectiveControlBlocker>;
+
+export const EffectiveControlResumeOption = z.object({
+  scope: z.enum(["selected", "session", "workspace"]),
+  targetId: z.string().uuid().optional(),
+  selectedStateAfter: SessionControlState,
+  remainingPrimaryBlocker: EffectiveControlBlocker.optional(),
+  impactCopy: z.string().min(1),
+});
+export type EffectiveControlResumeOption = z.infer<typeof EffectiveControlResumeOption>;
+
+export const EffectiveSessionControl = z.object({
+  state: SessionControlState,
+  controlVersion: z.number().int().nonnegative(),
+  controlEtag: z.string().min(1),
+  directState: SessionControlState,
+  primaryBlocker: EffectiveControlBlocker.nullable(),
+  additionalBlockerCount: z.number().int().nonnegative(),
+  blockers: z.array(EffectiveControlBlocker),
+  resumeOptions: z.array(EffectiveControlResumeOption),
+  override: z
+    .object({
+      rootSessionId: z.string().uuid(),
+      revision: z.number().int().nonnegative(),
+    })
+    .nullable(),
+  settlement: z
+    .object({
+      state: z.literal("stopping"),
+      attemptCount: z.number().int().positive(),
+      interruptionPendingCount: z.number().int().nonnegative(),
+      quiescencePendingCount: z.number().int().nonnegative(),
+    })
+    .nullable(),
+});
+export type EffectiveSessionControl = z.infer<typeof EffectiveSessionControl>;
+
+export const SESSION_OPERATION_KEY_MAX_CHARS = 256;
+const SessionOperationKey = z.string().min(1).max(SESSION_OPERATION_KEY_MAX_CHARS);
+
+export const SessionCommandReceipt = z.object({
+  id: z.string().uuid(),
+  action: z.string().min(1),
+  operationKey: z.string().min(1).max(SESSION_OPERATION_KEY_MAX_CHARS),
+  targetSessionId: z.string().uuid().nullable(),
+  targetTurnId: z.string().uuid().nullable(),
+  appliedControlRevision: z.number().int().nonnegative().nullable(),
+  appliedQueueVersion: z.number().int().nonnegative().nullable(),
+  appliedTurnVersion: z.number().int().positive().nullable(),
+  appliedDraftRevision: z.number().int().positive().nullable(),
+  createdAt: z.string(),
+});
+export type SessionCommandReceipt = z.infer<typeof SessionCommandReceipt>;
+
+export const ComposerDraft = z.object({
+  revision: z.number().int().nonnegative(),
+  text: z.string(),
+  resources: z.array(ResourceRef),
+  tools: z.array(ToolRef),
+  model: z.string().min(1),
+  reasoningEffort: ReasoningEffort,
+  sourceTurnId: z.string().uuid().nullable(),
+  sourceTurnVersion: z.number().int().positive().nullable(),
+  updatedAt: z.string().nullable(),
+});
+export type ComposerDraft = z.infer<typeof ComposerDraft>;
+
 export const SessionQueueSnapshot = z.object({
   version: z.number().int().nonnegative(),
-  controlState: SessionControlState,
-  controlGeneration: z.number().int().nonnegative(),
-  workspaceInferenceState: WorkspaceInferenceState,
-  workspaceInferenceGeneration: z.number().int().nonnegative(),
-  workspaceRunExceptionGeneration: z.number().int().nonnegative().nullable(),
+  effectiveControl: EffectiveSessionControl,
+  /**
+   * True while the latest attempt is interrupted but has not durably proved
+   * quiescence: no more inference, user-visible output, or workspace-persistence
+   * authority. Temporal cancellation/terminalization is not that proof. This is
+   * distinct from ordinary capacity queueing, remains accurate with an empty
+   * visible queue, and is independent of Steer-row metadata or withdrawal.
+   */
+  stoppingPreviousAttempt: z.boolean(),
   items: z.array(SessionTurn),
 });
 export type SessionQueueSnapshot = z.infer<typeof SessionQueueSnapshot>;
 
-export const CancelSessionQueueItemRequest = z.object({
+export const MoveSessionQueueItemRequest = z.object({
+  clientEventId: SessionOperationKey,
   expectedQueueVersion: z.number().int().nonnegative(),
-  expectedItemVersion: z.number().int().positive(),
+  beforeTurnId: z.string().uuid().nullable(),
+});
+export type MoveSessionQueueItemRequest = z.infer<typeof MoveSessionQueueItemRequest>;
+
+export const EditSessionQueueItemRequest = z.object({
+  clientEventId: SessionOperationKey,
+  expectedTurnVersion: z.number().int().positive(),
+  expectedDraftRevision: z.number().int().nonnegative(),
+  replaceDraft: z.boolean(),
+});
+export type EditSessionQueueItemRequest = z.infer<typeof EditSessionQueueItemRequest>;
+
+export const SteerSessionQueueItemRequest = z.object({
+  clientEventId: SessionOperationKey,
+  expectedTurnVersion: z.number().int().positive(),
+  controlEtag: z.string().min(1).optional(),
+});
+export type SteerSessionQueueItemRequest = z.infer<typeof SteerSessionQueueItemRequest>;
+
+export const DeleteSessionQueueItemRequest = z.object({
+  clientEventId: SessionOperationKey,
+  expectedTurnVersion: z.number().int().positive(),
   reason: z.string().min(1).optional(),
 });
-export type CancelSessionQueueItemRequest = z.infer<typeof CancelSessionQueueItemRequest>;
+export type DeleteSessionQueueItemRequest = z.infer<typeof DeleteSessionQueueItemRequest>;
+
+export const SaveComposerDraftRequest = ComposerDraft.pick({
+  text: true,
+  resources: true,
+  tools: true,
+  model: true,
+  reasoningEffort: true,
+}).extend({ expectedRevision: z.number().int().nonnegative() });
+export type SaveComposerDraftRequest = z.infer<typeof SaveComposerDraftRequest>;
+
+export const WORKSPACE_CONTROL_REASON_MAX_BYTES = 8 * 1024;
+export const WORKSPACE_CONTROL_ACTOR_MAX_BYTES = 1024;
+export const WORKSPACE_CONTROL_EVENT_MAX_BYTES = 16 * 1024;
+
+const WorkspaceControlReason = z
+  .string()
+  .min(1)
+  .refine((value) => !value.includes("\u0000"), "reason must not contain NUL bytes")
+  .refine(
+    (value) => workspaceControlUtf8Bytes(value) <= WORKSPACE_CONTROL_REASON_MAX_BYTES,
+    `reason must not exceed ${WORKSPACE_CONTROL_REASON_MAX_BYTES} UTF-8 bytes`,
+  );
 
 export const SessionControlRequest = z.object({
-  mode: z.enum(["pause", "resume"]),
-  reason: z.string().min(1).optional(),
-  clientEventId: z.string().min(1).optional(),
-  expectedControlState: SessionControlState.optional(),
-  expectedControlGeneration: z.number().int().nonnegative().optional(),
-  expectedWorkspaceInferenceGeneration: z.number().int().nonnegative().optional(),
+  action: z.enum(["pause", "resume"]),
+  reason: WorkspaceControlReason.optional(),
+  clientEventId: SessionOperationKey,
+  expectedControlEtag: z.string().min(1).optional(),
 });
 export type SessionControlRequest = z.infer<typeof SessionControlRequest>;
 
 export const WorkspaceInferenceControlRequest = z.object({
-  state: WorkspaceInferenceState,
-  reason: z.string().min(1),
-  clientEventId: z.string().min(1),
-  expectedState: WorkspaceInferenceState,
-  expectedGeneration: z.number().int().nonnegative(),
-  exceptSessionIds: z.array(z.string().uuid()).default([]),
+  action: z.enum(["pause", "resume"]),
+  reason: WorkspaceControlReason.optional(),
+  clientEventId: SessionOperationKey,
+  expectedRevision: z.number().int().nonnegative().optional(),
 });
 export type WorkspaceInferenceControlRequest = z.infer<typeof WorkspaceInferenceControlRequest>;
 
 export const WorkspaceInferenceControlResponse = z.object({
-  operationId: z.string().uuid(),
-  state: WorkspaceInferenceState,
-  generation: z.number().int().nonnegative(),
-  affectedSessionIds: z.array(z.string().uuid()),
-  controlSessionIds: z.array(z.string().uuid()),
-  exceptionSessionIds: z.array(z.string().uuid()),
+  receipt: SessionCommandReceipt,
+  state: SessionControlState,
+  revision: z.number().int().nonnegative(),
+  interruptionCount: z.number().int().nonnegative(),
+  wakeCount: z.number().int().nonnegative(),
 });
 export type WorkspaceInferenceControlResponse = z.infer<typeof WorkspaceInferenceControlResponse>;
 
+/**
+ * One durable workspace-wide invalidation for one committed control revision.
+ * It is not conversation history and never becomes queue work; clients use it
+ * only to refetch authoritative workspace/session projections.
+ */
+export const WorkspaceControlEventTruncation = z.object({
+  truncated: z.literal(true),
+  surface: z.enum([
+    "durable_control",
+    "database_guard",
+    "http_projection",
+    "nats_legacy_guard",
+    "sse_legacy_guard",
+  ]),
+  deliveredBytes: z.number().int().nonnegative(),
+  fields: z.array(
+    z.object({
+      field: z.enum(["reason", "actor"]),
+      originalBytes: z.number().int().nonnegative(),
+      deliveredBytes: z.number().int().nonnegative(),
+      omittedBytes: z.number().int().nonnegative(),
+    }),
+  ),
+  fullEvidence: z.object({
+    available: z.literal(false),
+    reason: z.literal("not_retained"),
+  }),
+});
+export type WorkspaceControlEventTruncation = z.infer<typeof WorkspaceControlEventTruncation>;
+
+export const WorkspaceControlEvent = z.object({
+  id: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  sequence: z.number().int().positive(),
+  revision: z.number().int().positive(),
+  type: z.literal("workspace.control.changed"),
+  scope: z.enum(["workspace", "session"]),
+  rootSessionId: z.string().uuid().nullable(),
+  action: z.enum(["pause", "resume"]),
+  automatic: z.boolean(),
+  reason: z.string().nullable(),
+  actor: z.string().min(1),
+  occurredAt: z.string(),
+  truncation: WorkspaceControlEventTruncation.nullable().optional(),
+});
+export type WorkspaceControlEvent = z.infer<typeof WorkspaceControlEvent>;
+
+export type WorkspaceControlBoundarySurface = WorkspaceControlEventTruncation["surface"];
+
+export type BoundWorkspaceControlEventOptions = {
+  surface?: WorkspaceControlBoundarySurface;
+  reasonOriginalBytes?: number | null;
+  actorOriginalBytes?: number | null;
+};
+
+/** UTF-8 byte count used by workspace-control storage and transport guards. */
+export function workspaceControlUtf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+/**
+ * Canonical bounded invalidation event. The event is not a full evidence store:
+ * when a producer or legacy row exceeds a field cap, the retained head carries
+ * a visible marker and structured exact byte-loss facts.
+ */
+export function boundWorkspaceControlEvent(
+  event: WorkspaceControlEvent,
+  options: BoundWorkspaceControlEventOptions = {},
+): WorkspaceControlEvent {
+  const existingFields = new Map(
+    (event.truncation?.fields ?? []).map((field) => [field.field, field] as const),
+  );
+  const reason =
+    event.reason === null
+      ? null
+      : boundWorkspaceControlText(event.reason, WORKSPACE_CONTROL_REASON_MAX_BYTES);
+  const actor = boundWorkspaceControlText(event.actor, WORKSPACE_CONTROL_ACTOR_MAX_BYTES);
+  const reasonBytes = reason === null ? 0 : workspaceControlUtf8Bytes(reason);
+  const actorBytes = workspaceControlUtf8Bytes(actor);
+  const reasonOriginalBytes =
+    event.reason === null
+      ? null
+      : Math.max(
+          workspaceControlUtf8Bytes(event.reason),
+          normalizedWorkspaceControlOriginalBytes(options.reasonOriginalBytes),
+          existingFields.get("reason")?.originalBytes ?? 0,
+        );
+  const actorOriginalBytes = Math.max(
+    workspaceControlUtf8Bytes(event.actor),
+    normalizedWorkspaceControlOriginalBytes(options.actorOriginalBytes),
+    existingFields.get("actor")?.originalBytes ?? 0,
+  );
+  const fields: WorkspaceControlEventTruncation["fields"] = [];
+  if (reasonOriginalBytes !== null && reasonOriginalBytes > reasonBytes) {
+    fields.push({
+      field: "reason",
+      originalBytes: reasonOriginalBytes,
+      deliveredBytes: reasonBytes,
+      omittedBytes: reasonOriginalBytes - reasonBytes,
+    });
+  }
+  if (actorOriginalBytes > actorBytes) {
+    fields.push({
+      field: "actor",
+      originalBytes: actorOriginalBytes,
+      deliveredBytes: actorBytes,
+      omittedBytes: actorOriginalBytes - actorBytes,
+    });
+  }
+  if (fields.length === 0 && event.truncation == null) {
+    if (sessionEventJsonBytes(event) > WORKSPACE_CONTROL_EVENT_MAX_BYTES) {
+      throw new RangeError("Workspace control event exceeds its bounded envelope");
+    }
+    return event;
+  }
+
+  const truncation: WorkspaceControlEventTruncation = {
+    truncated: true,
+    surface: event.truncation?.surface ?? options.surface ?? "durable_control",
+    deliveredBytes: 0,
+    fields,
+    fullEvidence: { available: false, reason: "not_retained" },
+  };
+  const bounded: WorkspaceControlEvent = {
+    ...event,
+    reason,
+    actor,
+    truncation,
+  };
+  settleWorkspaceControlDeliveredBytes(bounded, truncation);
+  const deliveredBytes = sessionEventJsonBytes(bounded);
+  if (deliveredBytes > WORKSPACE_CONTROL_EVENT_MAX_BYTES) {
+    throw new RangeError(
+      `Bounded workspace control event exceeds its final envelope (${deliveredBytes} > ${WORKSPACE_CONTROL_EVENT_MAX_BYTES} bytes)`,
+    );
+  }
+  return bounded;
+}
+
+function boundWorkspaceControlText(value: string, maxBytes: number): string {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  const bytes = encoder.encode(value);
+  if (bytes.byteLength <= maxBytes) return value;
+  const marker = "…[truncated]";
+  const prefixBudget = Math.max(0, maxBytes - encoder.encode(marker).byteLength);
+  let prefixEnd = Math.min(prefixBudget, bytes.byteLength);
+  while (prefixEnd > 0 && prefixEnd < bytes.byteLength && (bytes[prefixEnd]! & 0xc0) === 0x80) {
+    prefixEnd -= 1;
+  }
+  return `${decoder.decode(bytes.subarray(0, prefixEnd))}${marker}`;
+}
+
+function normalizedWorkspaceControlOriginalBytes(value: number | null | undefined): number {
+  return value === null || value === undefined || !Number.isFinite(value)
+    ? 0
+    : Math.max(0, Math.floor(value));
+}
+
+function settleWorkspaceControlDeliveredBytes(
+  event: WorkspaceControlEvent,
+  truncation: WorkspaceControlEventTruncation,
+): void {
+  for (let attempt = 0; attempt < 16; attempt += 1) {
+    const deliveredBytes = sessionEventJsonBytes(event);
+    if (truncation.deliveredBytes === deliveredBytes) return;
+    truncation.deliveredBytes = deliveredBytes;
+  }
+  const deliveredBytes = sessionEventJsonBytes(event);
+  if (truncation.deliveredBytes !== deliveredBytes) {
+    throw new RangeError("Workspace control event byte accounting did not converge");
+  }
+}
+
 export const SystemUpdateClassification = z.enum(["success", "failure", "action_required", "info"]);
 export type SystemUpdateClassification = z.infer<typeof SystemUpdateClassification>;
 
 export const SessionSystemUpdateKind = z.enum([
-  "child_session_update",
-  "scheduled_wake",
-  "lifecycle_event",
-  "runtime_notice",
+  "scheduled_occurrence",
+  "goal_continuation",
+  "agent_message",
+  "agent_steer_instruction",
+  "child_terminal_result",
 ]);
 export type SessionSystemUpdateKind = z.infer<typeof SessionSystemUpdateKind>;
 
+export const SessionSystemUpdatePayload = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("scheduled_occurrence"),
+      text: z.string().min(1),
+      scheduledTaskId: z.string().uuid(),
+      scheduledTaskRunId: z.string().uuid(),
+      resources: z.array(ResourceRef).optional(),
+      tools: z.array(ToolRef).optional(),
+    })
+    .passthrough(),
+  z
+    .object({
+      type: z.literal("goal_continuation"),
+      goalId: z.string().uuid(),
+      goalVersion: z.number().int().positive(),
+      prompt: z.string().min(1),
+      reason: z.string().optional(),
+    })
+    .passthrough(),
+  z
+    .object({
+      type: z.literal("agent_message"),
+      text: z.string().min(1),
+      operationId: z.string().uuid(),
+    })
+    .passthrough(),
+  z
+    .object({
+      type: z.literal("agent_steer_instruction"),
+      instruction: z.string().min(1),
+      operationId: z.string().uuid(),
+    })
+    .passthrough(),
+  z
+    .object({
+      type: z.literal("child_terminal_result"),
+      childSessionId: z.string().uuid(),
+      status: z.enum(["idle", "failed"]),
+    })
+    .passthrough(),
+]);
+export type SessionSystemUpdatePayload = z.infer<typeof SessionSystemUpdatePayload>;
+
 export const SessionSystemUpdateState = z.enum([
   "pending",
   "deferred",
   "delivered",
   "cancelled",
+  "superseded",
   "failed",
 ]);
 export type SessionSystemUpdateState = z.infer<typeof SessionSystemUpdateState>;
@@ -2134,7 +3551,7 @@ export const SessionSystemUpdate = z.object({
   sourceId: z.string(),
   dedupeKey: z.string(),
   summary: z.string(),
-  payload: z.record(z.string(), z.unknown()),
+  payload: SessionSystemUpdatePayload,
   lineage: z.record(z.string(), z.unknown()),
   state: SessionSystemUpdateState,
   deliveredTurnId: z.string().uuid().nullable(),
@@ -2365,7 +3782,10 @@ export type RigDefinitionEditPayload = z.infer<typeof RigDefinitionEditPayload>;
 
 export const ProposeRigChangeRequest = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("setup_append"), payload: RigSetupAppendPayload }),
-  z.object({ kind: z.literal("definition_edit"), payload: RigDefinitionEditPayload }),
+  z.object({
+    kind: z.literal("definition_edit"),
+    payload: RigDefinitionEditPayload,
+  }),
 ]);
 export type ProposeRigChangeRequest = z.infer<typeof ProposeRigChangeRequest>;
 
@@ -2785,27 +4205,15 @@ export const CreateSocialPostRequest = z.object({
   text: z.string().min(1),
   publishedAt: z.string().datetime({ offset: true }),
   metrics: z.record(z.string(), z.number()).default({}),
-  raw: z.record(z.string(), z.unknown()).default({}),
-});
-export type CreateSocialPostRequest = z.infer<typeof CreateSocialPostRequest>;
-
-export const ConnectionKind = z.enum(["oauth2", "api_key", "app_install", "delegated"]);
-export type ConnectionKind = z.infer<typeof ConnectionKind>;
-
-export const ConnectionStatus = z.enum(["active", "needs_reauth", "revoked", "error"]);
-export type ConnectionStatus = z.infer<typeof ConnectionStatus>;
-
-export const McpServerConnectionRef = z
-  .object({
-    connectionId: z.string().uuid().optional(),
-    providerDomain: z.string().min(1),
-    kind: ConnectionKind.optional(),
-    scopes: z.array(z.string().min(1)).optional(),
-    resource: z.string().min(1).optional(),
-    subjectScope: z.enum(["workspace", "subject"]).optional(),
-  })
-  .strict();
-export type McpServerConnectionRef = z.infer<typeof McpServerConnectionRef>;
+  raw: z.record(z.string(), z.unknown()).default({}),
+});
+export type CreateSocialPostRequest = z.infer<typeof CreateSocialPostRequest>;
+
+export const ConnectionKind = z.enum(["oauth2", "api_key", "app_install", "delegated"]);
+export type ConnectionKind = z.infer<typeof ConnectionKind>;
+
+export const ConnectionStatus = z.enum(["active", "needs_reauth", "revoked", "error"]);
+export type ConnectionStatus = z.infer<typeof ConnectionStatus>;
 
 export const ConnectionMetadata = z.object({
   id: z.string().uuid(),
@@ -2925,6 +4333,7 @@ export type CapabilityKind = z.infer<typeof CapabilityKind>;
 
 export const CapabilitySource = z.enum([
   "built_in",
+  "library",
   "configured",
   "public_registry",
   "registry",
@@ -3077,6 +4486,9 @@ export const Session = z.object({
   resources: z.array(ResourceRef),
   tools: z.array(ToolRef),
   metadata: z.record(z.string(), z.unknown()),
+  /** Frozen creator fact used only for creation attribution/idempotent repair. */
+  createdBy: TurnInitiator,
+  createdByContext: TurnInitiatorContext,
   model: z.string(),
   sandboxBackend: SandboxBackend,
   // The OS the session's box runs. Defaults to 'linux' (today's only OS).
@@ -3126,12 +4538,7 @@ export const Session = z.object({
   queueVersion: z.number().int().nonnegative(),
   queueHeadPosition: z.number().int(),
   queueTailPosition: z.number().int(),
-  controlState: SessionControlState,
-  controlGeneration: z.number().int().nonnegative(),
-  controlReason: z.string().nullable(),
-  controlChangedBy: z.string().nullable(),
-  controlChangedAt: z.string().nullable(),
-  workspaceRunExceptionGeneration: z.number().int().nonnegative().nullable(),
+  effectiveControl: EffectiveSessionControl,
   lastSequence: z.number().int().nonnegative(),
   // Multi-account Codex (P1). codexPinnedCredentialId: the account this session is
   // manually PINNED to (null ⇒ follow the workspace active pointer).
@@ -3159,6 +4566,8 @@ export const Session = z.object({
       attentionDescendants: z.number().int().nonnegative(),
       pausedDescendants: z.number().int().nonnegative(),
       failedDescendants: z.number().int().nonnegative(),
+      /** Counts are lower bounds rather than exact totals when true. */
+      truncated: z.boolean().default(false),
     })
     .optional(),
   createdAt: z.string(),
@@ -3166,16 +4575,30 @@ export const Session = z.object({
 });
 export type Session = z.infer<typeof Session>;
 
+/**
+ * Additive receipt returned only by session creation. `activeTurnId` remains an
+ * execution pointer and is correctly null while the first turn is queued;
+ * embedders use this immutable identity to correlate their preallocated run.
+ */
+export const CreateSessionResponse = Session.extend({
+  initialTurnId: z.string().uuid().nullable(),
+});
+export type CreateSessionResponse = z.infer<typeof CreateSessionResponse>;
+
 export type SessionSummary = Session;
 
 /**
  * The canonical session-list page. Pinned rows are returned separately and are
  * excluded from `sessions`, so a cursor can page ordinary recency rows without
- * duplicating a pin. Pins are filtered by the same parent/search predicates as
- * ordinary rows and ordered by pinnedAt DESC, id DESC.
+ * duplicating a pin. The newest 100 matching pins are returned, ordered by
+ * pinnedAt DESC, id DESC; `pinnedTruncated` makes an older-pin omission
+ * explicit. Pins are filtered by the same parent/search predicates as ordinary
+ * rows.
  */
 export const SessionListResponse = z.object({
   pinned: z.array(Session),
+  /** True when older matching pins were omitted from this bounded page. */
+  pinnedTruncated: z.boolean().optional(),
   sessions: z.array(Session),
   nextCursor: z.string().nullable(),
 });
@@ -3204,8 +4627,14 @@ export type SessionLineageResponse = z.infer<typeof SessionLineageResponse>;
 
 export const SessionEventType = z.enum([
   "session.created",
+  // Defensive read/transport projection for a malformed or historically
+  // oversized retained event envelope. The original row stays durable; this
+  // explicit synthetic type prevents unbounded free-form envelope fields from
+  // crossing NATS, SSE, REST, or browser boundaries.
+  "session.event.envelope_omitted",
   "session.status.changed",
   "session.requiresAction",
+  "session.humanInput.requested",
   "session.context.compaction.requested",
   "session.context.compacted",
   "session.context.compaction.skipped",
@@ -3213,6 +4642,7 @@ export const SessionEventType = z.enum([
   "user.message",
   "user.pause",
   "user.approvalDecision",
+  "user.humanInputResponse",
   "turn.queued",
   "turn.started",
   "turn.completed",
@@ -3228,6 +4658,7 @@ export const SessionEventType = z.enum([
   "agent.toolCall.output",
   "agent.model.usage",
   "tool.auth_needed",
+  "credential.auth_needed",
   "agent.updated",
   "rig.setup.started",
   "rig.setup.completed",
@@ -3252,6 +4683,7 @@ export const SessionEventType = z.enum([
   "session.control.steer_requested",
   "workspace.inference.paused",
   "workspace.inference.resumed",
+  "session.queue.changed",
   "session.queue.prompt.cancelled",
   "session.queue.history",
   // A terminal/stale activity callback is retained as an audit wrapper rather
@@ -3266,15 +4698,15 @@ export const SessionEventType = z.enum([
   "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
+  // Desktop recording signals. The capture loop records the same display humans
+  // watch, then stores the finalized artifact for replay.
   // → 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
+  // Structured-service notifications. File, Git, and terminal reads 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
@@ -3291,10 +4723,10 @@ export const SessionEventType = z.enum([
   // (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",
-  // OPE-21 per-turn selection audit. Payload is metadata only: credential row
+  // credential allocator per-turn selection audit. Payload is metadata only: credential row
   // id, bounded strategy/reason, and pool counts — never token material.
   "codex.credential.selected",
-  // OPE-21 durable zero-capacity wait lifecycle. Runtime/system events only;
+  // credential allocator durable zero-capacity wait lifecycle. Runtime/system events only;
   // no synthetic user message is created when capacity returns.
   "codex.capacity.waiting",
   "codex.capacity.resumed",
@@ -3319,12 +4751,12 @@ export const SessionEventType = z.enum([
   // target id or command content. Announce-only; hits the timeline projection default
   // (no rendered item) like the other sandbox.* diagnostics.
   "session.route.reconciled",
-  // Workbench v2 turn-end workspace capture (dossier §10.1). ANNOUNCE-ONLY: a new
+  // Workbench v2 turn-end workspace capture. ANNOUNCE-ONLY: a new
   // capture revision was persisted at turn end; the client refetches the latest
   // capture. It carries metadata only (revision/turnId/capturedAt/leaseEpoch/stats),
   // never file content. Hits the timeline projection default case (ignored) — it
   // must NEVER gain a rendered timeline item without regenerating the golden
-  // snapshots (dossier §7.3 golden-grammar gate).
+  // snapshots (golden-grammar gate).
   "workspace.revision.captured",
   // Repository discovery could not prove a complete capture. The worker
   // persisted a failed/degraded revision marker and clients must fall back to
@@ -3366,19 +4798,197 @@ export const SessionEventType = z.enum([
 ]);
 export type SessionEventType = z.infer<typeof SessionEventType>;
 
+/**
+ * Stable semantic groups for bounded session monitoring. These are a read
+ * projection only: an event keeps its canonical durable `type`, and callers
+ * can always combine a class with explicit type include/exclude filters.
+ */
+export const SessionEventSemanticClass = z.enum([
+  "control",
+  "terminal",
+  "failure",
+  "checkpoint",
+  "tool_receipt",
+  "provider_account",
+]);
+export type SessionEventSemanticClass = z.infer<typeof SessionEventSemanticClass>;
+
+export const SessionEventPayloadMode = z.enum(["none", "summary", "full"]);
+export type SessionEventPayloadMode = z.infer<typeof SessionEventPayloadMode>;
+
+export const SessionEventReadMode = z.enum(["monitoring", "forensic"]);
+export type SessionEventReadMode = z.infer<typeof SessionEventReadMode>;
+
+export const SessionEventReadDirection = z.enum(["after", "before"]);
+export type SessionEventReadDirection = z.infer<typeof SessionEventReadDirection>;
+
+export const SESSION_EVENT_RAW_DELTA_TYPES = [
+  "agent.message.delta",
+  "agent.reasoning.delta",
+  "sandbox.command.output.delta",
+  "terminal.pty.output.delta",
+] as const satisfies readonly SessionEventType[];
+
+export const SESSION_EVENT_SEMANTIC_CLASS_TYPES = {
+  control: [
+    "session.status.changed",
+    "session.requiresAction",
+    "session.humanInput.requested",
+    "user.pause",
+    "user.approvalDecision",
+    "user.humanInputResponse",
+    "goal.set",
+    "goal.updated",
+    "goal.completed",
+    "goal.paused",
+    "goal.resumed",
+    "goal.cleared",
+    "goal.continuation",
+    "system.update.pending",
+    "system.update.delivered",
+    "session.control.paused",
+    "session.control.resumed",
+    "session.control.steer_requested",
+    "workspace.inference.paused",
+    "workspace.inference.resumed",
+    "session.queue.changed",
+    "session.queue.prompt.cancelled",
+  ],
+  terminal: [
+    "turn.completed",
+    "turn.failed",
+    "turn.cancelled",
+    "turn.superseded",
+    "goal.completed",
+    "goal.paused",
+    "rig.setup.completed",
+    "rig.setup.skipped",
+    "rig.setup.failed",
+    "sandbox.operation.completed",
+    "sandbox.operation.failed",
+    "recording.available",
+    "recording.failed",
+    "terminal.pty.exited",
+  ],
+  failure: [
+    "session.event.envelope_omitted",
+    "turn.failed",
+    "tool.auth_needed",
+    "credential.auth_needed",
+    "rig.setup.failed",
+    "sandbox.operation.failed",
+    "recording.failed",
+    "sandbox.box.lost",
+    "workspace.revision.degraded",
+    "machine.op.failed",
+    "machine.link.lost",
+  ],
+  checkpoint: [
+    "session.context.compaction.requested",
+    "session.context.compacted",
+    "session.context.compaction.skipped",
+    "session.context.cleared",
+    "turn.recovery.requested",
+    "session.queue.history",
+    "sandbox.box.snapshot",
+    "workspace.revision.captured",
+  ],
+  tool_receipt: [
+    "agent.toolCall.created",
+    "agent.toolCall.output",
+    "tool.auth_needed",
+    "artifact.created",
+  ],
+  provider_account: [
+    "agent.model.usage",
+    "codex.account.switched",
+    "codex.credential.selected",
+    "codex.capacity.waiting",
+    "codex.capacity.resumed",
+    "codex.capacity.superseded",
+    "sandbox.box.created",
+    "sandbox.box.lost",
+    "sandbox.box.terminated",
+    "sandbox.box.snapshot",
+    "sandbox.env.drift",
+    "session.route.reconciled",
+    "machine.op.failed",
+    "machine.op.recovered",
+    "machine.link.lost",
+    "machine.link.restored",
+    "machine.runner.restarted",
+  ],
+} as const satisfies Record<SessionEventSemanticClass, readonly SessionEventType[]>;
+
+export type ResolveSessionEventTypeFiltersInput = {
+  includeTypes?: readonly SessionEventType[] | undefined;
+  excludeTypes?: readonly SessionEventType[] | undefined;
+  includeClasses?: readonly SessionEventSemanticClass[] | undefined;
+  excludeClasses?: readonly SessionEventSemanticClass[] | undefined;
+  /** Applied unless the same type was explicitly included by type or class. */
+  defaultExcludeTypes?: readonly SessionEventType[] | undefined;
+};
+
+/** Resolve class/type filter algebra once so every read surface behaves alike. */
+export function resolveSessionEventTypeFilters(input: ResolveSessionEventTypeFiltersInput): {
+  includeTypes: SessionEventType[];
+  excludeTypes: SessionEventType[];
+} {
+  const included = new Set<SessionEventType>(input.includeTypes ?? []);
+  for (const semanticClass of input.includeClasses ?? []) {
+    for (const type of SESSION_EVENT_SEMANTIC_CLASS_TYPES[semanticClass]) included.add(type);
+  }
+
+  const excluded = new Set<SessionEventType>(input.excludeTypes ?? []);
+  for (const semanticClass of input.excludeClasses ?? []) {
+    for (const type of SESSION_EVENT_SEMANTIC_CLASS_TYPES[semanticClass]) excluded.add(type);
+  }
+  for (const type of input.defaultExcludeTypes ?? []) {
+    if (!included.has(type)) excluded.add(type);
+  }
+
+  // An explicit exclusion always wins over a positive selector.
+  for (const type of excluded) included.delete(type);
+  return { includeTypes: [...included], excludeTypes: [...excluded] };
+}
+
 export const ToolAuthNeededPayload = z.object({
   serverId: z.string().min(1),
   toolName: z.string().min(1).nullable().optional(),
   providerDomain: z.string().min(1),
-  connectionId: z.string().uuid().nullable().optional(),
-  reason: z.enum(["missing_connection", "expired", "insufficient_scope", "refresh_failed"]),
+  provider: z.string().min(1).max(128).optional(),
+  // Embedded hosts may use an opaque connection identity; never assume an
+  // OpenGeni UUID on the public event wire.
+  connectionId: z.string().min(1).nullable().optional(),
+  reason: z.enum([
+    "missing_connection",
+    "expired",
+    "insufficient_scope",
+    "refresh_failed",
+    "unsupported_auth",
+    "resource_scope_unavailable",
+  ]),
   scopes: z.array(z.string().min(1)).optional(),
   resource: z.string().min(1).optional(),
+  selectedResources: McpConnectionResourceScopes.optional(),
   authorizationUrl: z.string().url().optional(),
   subjectId: z.string().min(1).nullable().optional(),
 });
 export type ToolAuthNeededPayload = z.infer<typeof ToolAuthNeededPayload>;
 
+/** A host-owned non-tool credential needed by the active run. */
+export const CredentialAuthNeededPayload = z.object({
+  credentialClass: z.literal("run"),
+  providerDomain: z.string().min(1).optional(),
+  connectionId: z.string().min(1).optional(),
+  reason: z.enum(["missing_connection", "expired", "insufficient_scope", "refresh_failed"]),
+  scopes: z.array(z.string().min(1)).optional(),
+  resource: z.string().min(1).optional(),
+  authorizationUrl: z.string().url().optional(),
+  message: z.string().min(1).optional(),
+});
+export type CredentialAuthNeededPayload = z.infer<typeof CredentialAuthNeededPayload>;
+
 // 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/
@@ -3480,7 +5090,7 @@ export const RecordingFailedPayload = z.object({
 });
 export type RecordingFailedPayload = z.infer<typeof RecordingFailedPayload>;
 
-// ── Channel-A structured services (P4.4 / modules/08-channel-a.md) ───────────
+// ── Structured sandbox services ─────────────────────────────────────────────
 // 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
@@ -3647,7 +5257,9 @@ export const FsDeleteRequest = z.object({
   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 const FsDeleteResponse = z.object({
+  revision: z.number().int().nonnegative(),
+});
 export type FsDeleteResponse = z.infer<typeof FsDeleteResponse>;
 
 export const FsMoveRequest = z.object({
@@ -3748,6 +5360,9 @@ 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)
+  // Workspace review includes after-images that ordinary `git diff` omits.
+  // Explicit so commit/staged consumers keep native Git semantics by default.
+  includeUntracked: z.boolean().default(false),
   fromRef: z.string().optional(),
   toRef: z.string().optional(),
   pathspec: z.array(z.string()).default([]),
@@ -3766,7 +5381,7 @@ export const GitDiffResponse = z.object({
 });
 export type GitDiffResponse = z.infer<typeof GitDiffResponse>;
 
-// ─── Workbench v2 turn-end workspace capture (dossier §10.1/§10.2) ────────────
+// ─── Workbench v2 turn-end workspace capture ────────────
 // A capture is a point-in-time snapshot of the session workspace's CHANGES,
 // probed live off the box at turn end (detectRepos → gitStatus/gitDiff → fsRead
 // after-images → fsList tree index). It is the cold/offline read source that
@@ -3783,7 +5398,7 @@ export const WorkspaceCaptureFile = z.object({
   status: GitFileStatusCode,
   // sha256 of the captured after-image bytes; null when deleted / tooLarge.
   hash: z.string().nullable(),
-  // git blob sha of the HEAD version — the wake-on-edit flush guard (dossier
+  // git blob sha of the HEAD version — the wake-on-edit flush guard (design
   // §10.1). null when the path is new/untracked (no HEAD blob).
   baseHash: z.string().nullable(),
   // Content-addressed storage key of the after-image; null when deleted /
@@ -3821,7 +5436,7 @@ export const WorkspaceCaptureDegradedReason = z.enum([
 export type WorkspaceCaptureDegradedReason = z.infer<typeof WorkspaceCaptureDegradedReason>;
 
 // Rollup counters — carried on the row (jsonb) and the announce event so the UI
-// can reserve layout (dossier §12 no-layout-shift) before fetching the manifest.
+// can reserve layout (no layout shift) before fetching the manifest.
 export const WorkspaceCaptureStats = z.object({
   repoCount: z.number().int().nonnegative(),
   fileCount: z.number().int().nonnegative(),
@@ -3858,7 +5473,7 @@ export const WorkspaceCaptureManifest = z.object({
 });
 export type WorkspaceCaptureManifest = z.infer<typeof WorkspaceCaptureManifest>;
 
-// Announce-only event payload (dossier §10.1). Metadata only — never content.
+// Announce-only event payload. Metadata only — never content.
 export const WorkspaceRevisionCapturedPayload = z.object({
   revision: z.number().int().nonnegative(),
   turnId: z.string().nullable(),
@@ -3877,7 +5492,7 @@ export const WorkspaceRevisionDegradedPayload = z.object({
 });
 export type WorkspaceRevisionDegradedPayload = z.infer<typeof WorkspaceRevisionDegradedPayload>;
 
-// --- M2 capture READ API (dossier §10.3) -------------------------------------
+// --- M2 capture READ API -------------------------------------
 // A short-TTL signed GET URL minted PER REQUEST (never stored). The manifest is
 // served inline for the ≤2MB common case (the <200ms one-round-trip paint); a
 // >2MB manifest and a >256KB single-file after-image fall back to one of these.
@@ -3954,14 +5569,25 @@ 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() }),
+  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 const GitLogResponse = z.object({
+  commits: z.array(GitCommit),
+  hasMore: z.boolean(),
+});
 export type GitLogResponse = z.infer<typeof GitLogResponse>;
 
 export const GitShowRequest = z.object({
@@ -4033,7 +5659,10 @@ export const PtyOpenResponse = z.object({
   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 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(),
@@ -4048,7 +5677,11 @@ export type PtyCloseRequest = z.infer<typeof PtyCloseRequest>;
 // 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() }),
+  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
@@ -4066,39 +5699,644 @@ export const SessionEvent = z.object({
   type: SessionEventType,
   payload: z.unknown().default({}),
   occurredAt: z.string(),
-  clientEventId: z.string().min(1).nullable().optional(),
+  clientEventId: SessionOperationKey.nullable().optional(),
   turnId: z.string().uuid().nullable().optional(),
   turnGeneration: z.number().int().nonnegative().nullable().optional(),
   turnAttemptId: z.string().uuid().nullable().optional(),
   turnAssociation: z.enum(["current", "late_rejected", "duplicate"]).nullable().optional(),
   duplicateOfEventId: z.string().uuid().nullable().optional(),
-  duplicateReason: z.string().min(1).nullable().optional(),
+  duplicateReason: z.string().min(1).max(1024).nullable().optional(),
 });
 export type SessionEvent = z.infer<typeof SessionEvent>;
 
+// --- Durable host export ------------------------------------------------------
+
+/** Wire revision for the durable host event/usage export stream. */
+export const OPENGENI_HOST_EXPORT_SCHEMA_REVISION = "2026-07-host-export-v1" as const;
+
+/**
+ * Decimal string rather than a JavaScript number: export cursors are PostgreSQL
+ * bigint values and must remain exact beyond Number.MAX_SAFE_INTEGER.
+ */
+export const HostExportCursor = z.string().regex(/^(0|[1-9][0-9]*)$/);
+export type HostExportCursor = z.infer<typeof HostExportCursor>;
+
+export const HostExportConsumerId = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+export type HostExportConsumerId = z.infer<typeof HostExportConsumerId>;
+
+export const HostExportInitiator = TurnInitiator.extend({
+  subjectId: z.string().min(1).max(1024),
+  label: z.string().min(1).max(256).optional(),
+});
+export type HostExportInitiator = z.infer<typeof HostExportInitiator>;
+
+export const HostExportInitiatorContext = TurnInitiatorContext.refine(
+  (value) => {
+    try {
+      return new TextEncoder().encode(JSON.stringify(value)).byteLength <= 4096;
+    } catch {
+      return false;
+    }
+  },
+  { message: "Host export initiator context exceeds 4096 UTF-8 bytes" },
+);
+export type HostExportInitiatorContext = z.infer<typeof HostExportInitiatorContext>;
+
+const HostExportAttribution = {
+  initiator: HostExportInitiator.nullable(),
+  initiatorContext: HostExportInitiatorContext,
+  origin: SessionTurnSource.nullable(),
+} as const;
+
+/**
+ * Host streams are deliberately forward-tolerant across rolling upgrades.
+ * OpenGeni's application contract enumerates the event types known to this
+ * build, while the durable export may be read by an older host consumer after
+ * a newer writer has committed a bounded type. The database remains the
+ * authority for the byte bounds on these persisted strings.
+ */
+export const HostSessionEvent = SessionEvent.extend({
+  type: z.string().min(1).max(256),
+  clientEventId: z.string().max(1024).nullable().optional(),
+  turnAssociation: z.string().min(1).max(64).nullable().optional(),
+  duplicateReason: z.string().max(4096).nullable().optional(),
+});
+export type HostSessionEvent = z.infer<typeof HostSessionEvent>;
+
+/** Export-bounded usage fact; custom bounded metric names remain supported. */
+export const HostUsageEvent = UsageEvent.extend({
+  subjectId: z.string().max(1024).nullable(),
+  eventType: z.string().min(1).max(256),
+  unit: z.string().min(1).max(128),
+  sourceResourceType: z.string().max(256).nullable(),
+  sourceResourceId: z.string().max(2048).nullable(),
+  idempotencyKey: z.string().min(1).max(2048),
+  billingProviderEventId: z.string().max(2048).nullable(),
+});
+export type HostUsageEvent = z.infer<typeof HostUsageEvent>;
+
+/**
+ * One immutable, bounded session-event snapshot from the transactional host
+ * outbox. Cross-session cursor order is stable but deliberately non-causal;
+ * within a session, `event.sequence` remains authoritative and monotonic.
+ */
+export const HostEventExport = z.object({
+  schemaRevision: z.literal(OPENGENI_HOST_EXPORT_SCHEMA_REVISION),
+  cursor: HostExportCursor,
+  idempotencyKey: z.string().min(1).max(2048),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  /**
+   * Immutable root of event.sessionId's session lineage at capture time. Null
+   * only for an unresolved pre-lineage/legacy export row.
+   */
+  rootSessionId: z.string().uuid().nullable(),
+  ...HostExportAttribution,
+  event: HostSessionEvent,
+});
+export type HostEventExport = z.infer<typeof HostEventExport>;
+
+/** One exact, idempotency-keyed usage fact from the same ordered outbox. */
+export const HostUsageExport = z.object({
+  schemaRevision: z.literal(OPENGENI_HOST_EXPORT_SCHEMA_REVISION),
+  cursor: HostExportCursor,
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  sessionId: z.string().uuid().nullable(),
+  /** Null when sessionId is null or an unresolved pre-lineage legacy row. */
+  rootSessionId: z.string().uuid().nullable(),
+  turnId: z.string().uuid().nullable(),
+  turnAttemptId: z.string().uuid().nullable(),
+  ...HostExportAttribution,
+  usage: HostUsageEvent,
+});
+export type HostUsageExport = z.infer<typeof HostUsageExport>;
+
+export const HostEventExportBatch = z.object({
+  schemaRevision: z.literal(OPENGENI_HOST_EXPORT_SCHEMA_REVISION),
+  consumerId: HostExportConsumerId,
+  leaseToken: z.string().uuid(),
+  checkpoint: HostExportCursor,
+  throughCursor: HostExportCursor,
+  events: z.array(HostEventExport).min(1).max(256),
+});
+export type HostEventExportBatch = z.infer<typeof HostEventExportBatch>;
+
+export const HostUsageExportBatch = z.object({
+  schemaRevision: z.literal(OPENGENI_HOST_EXPORT_SCHEMA_REVISION),
+  consumerId: HostExportConsumerId,
+  leaseToken: z.string().uuid(),
+  checkpoint: HostExportCursor,
+  throughCursor: HostExportCursor,
+  events: z.array(HostUsageExport).min(1).max(256),
+});
+export type HostUsageExportBatch = z.infer<typeof HostUsageExportBatch>;
+
+/**
+ * Optional embedded-host sinks. Delivery is at least once: the same batch may
+ * be repeated after a process dies between sink success and checkpoint commit,
+ * so sinks must deduplicate by event/usage idempotency key.
+ */
+export type HostEventSink = {
+  consumerId: HostExportConsumerId;
+  deliverEvents: (batch: HostEventExportBatch) => Promise<void>;
+};
+
+export type HostUsageSink = {
+  consumerId: HostExportConsumerId;
+  deliverUsage: (batch: HostUsageExportBatch) => Promise<void>;
+};
+
+export const SESSION_EVENT_TYPE_MAX_BYTES = 256;
+export const SESSION_EVENT_CLIENT_EVENT_ID_MAX_BYTES = SESSION_OPERATION_KEY_MAX_CHARS * 4;
+export const SESSION_EVENT_TURN_ASSOCIATION_MAX_BYTES = 64;
+export const SESSION_EVENT_DUPLICATE_REASON_MAX_BYTES = 4 * 1024;
+export const SESSION_EVENT_ENVELOPE_MAX_BYTES = 80 * 1024;
+
+export type BoundSessionEventOptions = {
+  surface?: SessionEventBoundarySurface;
+  maxBytes?: number;
+};
+
+/**
+ * Canonical lossy projection for a complete session event. Payload bounds alone
+ * are insufficient: a malformed retained row can also carry an oversized type,
+ * client id, or duplicate diagnostic. Keep cursor/UUID identity intact, bound
+ * every free-form envelope string, and assert the exact final JSON envelope.
+ */
+export function boundSessionEvent(
+  event: SessionEvent,
+  options: BoundSessionEventOptions = {},
+): SessionEvent {
+  const surface = options.surface ?? "durable_audit";
+  const maxBytes = Math.max(8 * 1024, options.maxBytes ?? SESSION_EVENT_ENVELOPE_MAX_BYTES);
+  // Never stringify the untrusted complete event. Measurement has one global
+  // work budget and never invokes accessors/custom toJSON; serialization is
+  // permitted only after the compact projection below has been constructed.
+  const originalBytes = measureSessionEventJson(event).bytes;
+  const source = sessionEventOwnDataFields(event);
+  const id = canonicalSessionEventUuid(source.id, SESSION_EVENT_ZERO_UUID);
+  const workspaceId = canonicalSessionEventUuid(source.workspaceId, SESSION_EVENT_ZERO_UUID);
+  const sessionId = canonicalSessionEventUuid(source.sessionId, SESSION_EVENT_ZERO_UUID);
+  const sequence =
+    source.sequence.readable &&
+    typeof source.sequence.value === "number" &&
+    Number.isSafeInteger(source.sequence.value) &&
+    source.sequence.value > 0
+      ? source.sequence.value
+      : 1;
+  const occurredAt =
+    source.occurredAt.readable &&
+    typeof source.occurredAt.value === "string" &&
+    sessionEventUtf8Bytes(source.occurredAt.value) <= 256
+      ? source.occurredAt.value
+      : "1970-01-01T00:00:00.000Z";
+  const rawType = source.type.readable ? source.type.value : undefined;
+  const typeIsSafe =
+    typeof rawType === "string" &&
+    sessionEventUtf8Bytes(rawType) <= SESSION_EVENT_TYPE_MAX_BYTES &&
+    !rawType.includes("\n") &&
+    !rawType.includes("\r");
+  const rawClientEventId = source.clientEventId.readable ? source.clientEventId.value : undefined;
+  const clientEventId = boundOptionalSessionEventText(
+    typeof rawClientEventId === "string" || rawClientEventId === null
+      ? rawClientEventId
+      : undefined,
+    SESSION_EVENT_CLIENT_EVENT_ID_MAX_BYTES,
+  );
+  const rawTurnAssociation = source.turnAssociation.readable
+    ? source.turnAssociation.value
+    : undefined;
+  const turnAssociation =
+    rawTurnAssociation === null ||
+    rawTurnAssociation === undefined ||
+    rawTurnAssociation === "current" ||
+    rawTurnAssociation === "late_rejected" ||
+    rawTurnAssociation === "duplicate"
+      ? rawTurnAssociation
+      : null;
+  const rawDuplicateReason = source.duplicateReason.readable
+    ? source.duplicateReason.value
+    : undefined;
+  const duplicateReason = boundOptionalSessionEventText(
+    typeof rawDuplicateReason === "string" || rawDuplicateReason === null
+      ? rawDuplicateReason
+      : undefined,
+    SESSION_EVENT_DUPLICATE_REASON_MAX_BYTES,
+  );
+  const turnId = canonicalOptionalSessionEventUuid(source.turnId);
+  const turnGeneration = canonicalSessionEventGeneration(source.turnGeneration);
+  const turnAttemptId = canonicalOptionalSessionEventUuid(source.turnAttemptId);
+  const duplicateOfEventId = canonicalOptionalSessionEventUuid(source.duplicateOfEventId);
+  const envelopeFields = [
+    sessionEventCustomSerializerProjection(event),
+    sessionEventAdditionalTopLevelFieldProjection(event),
+    !typeIsSafe
+      ? sessionEventEnvelopeFieldProjection(
+          "type",
+          rawType,
+          "session.event.envelope_omitted",
+          source.type.readable,
+        )
+      : null,
+    !source.clientEventId.readable || rawClientEventId !== clientEventId
+      ? sessionEventEnvelopeFieldProjection(
+          "clientEventId",
+          rawClientEventId,
+          clientEventId,
+          source.clientEventId.readable,
+        )
+      : null,
+    !source.turnAssociation.readable || rawTurnAssociation !== turnAssociation
+      ? sessionEventEnvelopeFieldProjection(
+          "turnAssociation",
+          rawTurnAssociation,
+          turnAssociation,
+          source.turnAssociation.readable,
+        )
+      : null,
+    !source.duplicateReason.readable || rawDuplicateReason !== duplicateReason
+      ? sessionEventEnvelopeFieldProjection(
+          "duplicateReason",
+          rawDuplicateReason,
+          duplicateReason,
+          source.duplicateReason.readable,
+        )
+      : null,
+    ...sessionEventCanonicalFieldProjections(source, {
+      id,
+      workspaceId,
+      sessionId,
+      sequence,
+      occurredAt,
+    }),
+    ...sessionEventOptionalFieldProjections(source, {
+      turnId,
+      turnGeneration,
+      turnAttemptId,
+      duplicateOfEventId,
+    }),
+    !source.payload.readable
+      ? sessionEventEnvelopeFieldProjection("payload", undefined, null, false)
+      : null,
+  ].filter((field) => field !== null);
+  const rawPayload = source.payload.readable
+    ? source.payload.value
+    : "[event payload accessor omitted at bounded projection boundary]";
+  const payload =
+    envelopeFields.length === 0
+      ? boundSessionEventPayload(rawPayload, { surface })
+      : boundSessionEventPayload(
+          {
+            preview: "[legacy event envelope normalized at bounded projection boundary]",
+            originalEventBytes: originalBytes,
+            originalType: typeof rawType === "string" ? boundSessionEventText(rawType, 256) : null,
+            envelopeProjection: {
+              truncated: true,
+              surface,
+              fields: envelopeFields,
+            },
+            fullEvidence: { available: false, reason: "not_retained" },
+          },
+          { surface, maxBytes: 8 * 1024 },
+        );
+  const bounded: SessionEvent = {
+    id,
+    workspaceId,
+    sessionId,
+    sequence,
+    type: typeIsSafe ? (rawType as SessionEvent["type"]) : "session.event.envelope_omitted",
+    payload,
+    occurredAt,
+    ...(sessionEventShouldEmitOptionalField(source.clientEventId) ? { clientEventId } : {}),
+    ...(sessionEventShouldEmitOptionalField(source.turnId) ? { turnId } : {}),
+    ...(sessionEventShouldEmitOptionalField(source.turnGeneration) ? { turnGeneration } : {}),
+    ...(sessionEventShouldEmitOptionalField(source.turnAttemptId) ? { turnAttemptId } : {}),
+    ...(sessionEventShouldEmitOptionalField(source.turnAssociation) ? { turnAssociation } : {}),
+    ...(sessionEventShouldEmitOptionalField(source.duplicateOfEventId)
+      ? { duplicateOfEventId }
+      : {}),
+    ...(sessionEventShouldEmitOptionalField(source.duplicateReason) ? { duplicateReason } : {}),
+  };
+  if (sessionEventJsonBytes(bounded) <= maxBytes) return bounded;
+
+  const fallback: SessionEvent = {
+    id,
+    workspaceId,
+    sessionId,
+    sequence,
+    type: "session.event.envelope_omitted",
+    payload: boundSessionEventPayload(
+      {
+        preview: "[legacy event envelope omitted at bounded projection boundary]",
+        originalEventBytes: originalBytes,
+        originalType: typeof rawType === "string" ? boundSessionEventText(rawType, 256) : null,
+        fullEvidence: { available: false, reason: "not_retained" },
+      },
+      { surface, maxBytes: 4 * 1024 },
+    ),
+    occurredAt,
+    ...(sessionEventShouldEmitOptionalField(source.clientEventId) ? { clientEventId } : {}),
+    ...(sessionEventShouldEmitOptionalField(source.turnId) ? { turnId } : {}),
+    ...(sessionEventShouldEmitOptionalField(source.turnGeneration) ? { turnGeneration } : {}),
+    ...(sessionEventShouldEmitOptionalField(source.turnAttemptId) ? { turnAttemptId } : {}),
+    ...(sessionEventShouldEmitOptionalField(source.turnAssociation) ? { turnAssociation } : {}),
+    ...(sessionEventShouldEmitOptionalField(source.duplicateOfEventId)
+      ? { duplicateOfEventId }
+      : {}),
+    ...(sessionEventShouldEmitOptionalField(source.duplicateReason) ? { duplicateReason } : {}),
+  };
+  const deliveredBytes = sessionEventJsonBytes(fallback);
+  if (deliveredBytes > maxBytes) {
+    throw new RangeError(
+      `Bounded session event exceeds its final envelope (${deliveredBytes} > ${maxBytes} bytes)`,
+    );
+  }
+  return fallback;
+}
+
+function sessionEventEnvelopeFieldProjection(
+  field: string,
+  original: unknown,
+  delivered: unknown,
+  originalReadable = true,
+): { field: string; originalBytes: number | null; deliveredBytes: number } {
+  return {
+    field,
+    originalBytes: originalReadable
+      ? typeof original === "string"
+        ? sessionEventUtf8Bytes(original)
+        : typeof original === "number" || typeof original === "boolean"
+          ? sessionEventJsonBytes(original)
+          : original === null || original === undefined
+            ? 0
+            : null
+      : null,
+    deliveredBytes:
+      typeof delivered === "string"
+        ? sessionEventUtf8Bytes(delivered)
+        : typeof delivered === "number" || typeof delivered === "boolean"
+          ? sessionEventJsonBytes(delivered)
+          : 0,
+  };
+}
+
+function sessionEventCustomSerializerProjection(
+  event: SessionEvent,
+): { field: string; originalBytes: null; deliveredBytes: 0 } | null {
+  const projection = {
+    field: "toJSON",
+    originalBytes: null,
+    deliveredBytes: 0,
+  } as const;
+  let candidate: object | null = event;
+  try {
+    for (let depth = 0; depth <= SESSION_EVENT_PROTOTYPE_MAX_DEPTH; depth += 1) {
+      if (candidate === null) return null;
+      const descriptor = Object.getOwnPropertyDescriptor(candidate, "toJSON");
+      if (descriptor) {
+        // JSON.stringify performs an ordinary lookup, so an accessor is both
+        // executable behavior and an unknown possible serializer. A data
+        // property shadows the rest of the chain and is relevant only when it
+        // is callable.
+        return !("value" in descriptor) || typeof descriptor.value === "function"
+          ? projection
+          : null;
+      }
+      candidate = Object.getPrototypeOf(candidate);
+    }
+    // A hostile or malformed prototype chain that exceeds the fixed lookup
+    // budget cannot prove the absence of inherited serialization behavior.
+    return projection;
+  } catch {
+    return projection;
+  }
+}
+
+const SESSION_EVENT_PROTOTYPE_MAX_DEPTH = 32;
+const SESSION_EVENT_ZERO_UUID = "00000000-0000-4000-8000-000000000000";
+const SESSION_EVENT_UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+const SESSION_EVENT_OWN_DATA_FIELDS = [
+  "id",
+  "workspaceId",
+  "sessionId",
+  "sequence",
+  "type",
+  "payload",
+  "occurredAt",
+  "clientEventId",
+  "turnId",
+  "turnGeneration",
+  "turnAttemptId",
+  "turnAssociation",
+  "duplicateOfEventId",
+  "duplicateReason",
+] as const satisfies readonly (keyof SessionEvent)[];
+const SESSION_EVENT_KNOWN_ENUMERABLE_FIELDS = new Set<string>([
+  ...SESSION_EVENT_OWN_DATA_FIELDS,
+  "toJSON",
+]);
+
+/**
+ * Detect future/legacy own enumerable envelope fields without reading their
+ * values. There can be at most the fixed known-key cardinality before an
+ * additional key must be observed, so the source-level iterator is bounded.
+ * A proxy/enumeration failure is conservatively surfaced as unknown loss.
+ */
+function sessionEventAdditionalTopLevelFieldProjection(
+  event: SessionEvent,
+): { field: string; originalBytes: null; deliveredBytes: 0 } | null {
+  const projection = {
+    field: "additionalTopLevelFields",
+    originalBytes: null,
+    deliveredBytes: 0,
+  } as const;
+  let inspected = 0;
+  try {
+    for (const key in event as SessionEvent & Record<string, unknown>) {
+      inspected += 1;
+      if (inspected > SESSION_EVENT_KNOWN_ENUMERABLE_FIELDS.size + 1) return projection;
+      const descriptor = Object.getOwnPropertyDescriptor(event, key);
+      if (descriptor?.enumerable && !SESSION_EVENT_KNOWN_ENUMERABLE_FIELDS.has(key)) {
+        return projection;
+      }
+    }
+    return null;
+  } catch {
+    return projection;
+  }
+}
+
+type SessionEventOwnField = { readable: true; value: unknown } | { readable: false };
+type SessionEventOwnDataFields = Record<keyof SessionEvent, SessionEventOwnField>;
+
+function sessionEventOwnDataFields(event: SessionEvent): SessionEventOwnDataFields {
+  return Object.fromEntries(
+    SESSION_EVENT_OWN_DATA_FIELDS.map((key) => {
+      try {
+        const descriptor = Object.getOwnPropertyDescriptor(event, key);
+        if (!descriptor) return [key, { readable: true, value: undefined }];
+        return [
+          key,
+          "value" in descriptor ? { readable: true, value: descriptor.value } : { readable: false },
+        ];
+      } catch {
+        return [key, { readable: false }];
+      }
+    }),
+  ) as SessionEventOwnDataFields;
+}
+
+function canonicalSessionEventUuid(field: SessionEventOwnField, fallback: string): string {
+  return field.readable &&
+    typeof field.value === "string" &&
+    SESSION_EVENT_UUID_PATTERN.test(field.value)
+    ? field.value
+    : fallback;
+}
+
+function canonicalOptionalSessionEventUuid(field: SessionEventOwnField): string | null {
+  return field.readable &&
+    typeof field.value === "string" &&
+    SESSION_EVENT_UUID_PATTERN.test(field.value)
+    ? field.value
+    : null;
+}
+
+function canonicalSessionEventGeneration(field: SessionEventOwnField): number | null {
+  return field.readable &&
+    typeof field.value === "number" &&
+    Number.isSafeInteger(field.value) &&
+    field.value >= 0
+    ? field.value
+    : null;
+}
+
+function sessionEventShouldEmitOptionalField(field: SessionEventOwnField): boolean {
+  return !field.readable || field.value !== undefined;
+}
+
+function sessionEventCanonicalFieldProjections(
+  source: SessionEventOwnDataFields,
+  delivered: {
+    id: string;
+    workspaceId: string;
+    sessionId: string;
+    sequence: number;
+    occurredAt: string;
+  },
+): Array<{
+  field: string;
+  originalBytes: number | null;
+  deliveredBytes: number;
+}> {
+  return (["id", "workspaceId", "sessionId", "sequence", "occurredAt"] as const).flatMap(
+    (field) => {
+      const original = source[field].readable ? source[field].value : undefined;
+      return source[field].readable && original === delivered[field]
+        ? []
+        : [
+            sessionEventEnvelopeFieldProjection(
+              field,
+              original,
+              delivered[field],
+              source[field].readable,
+            ),
+          ];
+    },
+  );
+}
+
+function sessionEventOptionalFieldProjections(
+  source: SessionEventOwnDataFields,
+  delivered: {
+    turnId: string | null;
+    turnGeneration: number | null;
+    turnAttemptId: string | null;
+    duplicateOfEventId: string | null;
+  },
+): Array<{
+  field: string;
+  originalBytes: number | null;
+  deliveredBytes: number;
+}> {
+  return (["turnId", "turnGeneration", "turnAttemptId", "duplicateOfEventId"] as const).flatMap(
+    (field) => {
+      const original = source[field].readable ? source[field].value : undefined;
+      const canonicalOriginal = original ?? null;
+      return source[field].readable && canonicalOriginal === delivered[field]
+        ? []
+        : [
+            sessionEventEnvelopeFieldProjection(
+              field,
+              original,
+              delivered[field],
+              source[field].readable,
+            ),
+          ];
+    },
+  );
+}
+
+function boundOptionalSessionEventText<T extends string | null | undefined>(
+  value: T,
+  maxBytes: number,
+): T {
+  return (typeof value === "string" ? boundSessionEventText(value, maxBytes) : value) as T;
+}
+
+function boundSessionEventText(value: string, maxBytes: number): string {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  const bytes = encoder.encode(value);
+  if (bytes.byteLength <= maxBytes) return value;
+  const marker = "…[truncated]";
+  const markerBytes = encoder.encode(marker).byteLength;
+  const prefixBudget = Math.max(0, maxBytes - markerBytes);
+  let prefixEnd = Math.min(prefixBudget, bytes.byteLength);
+  while (prefixEnd > 0 && prefixEnd < bytes.byteLength && (bytes[prefixEnd]! & 0xc0) === 0x80) {
+    prefixEnd -= 1;
+  }
+  return `${decoder.decode(bytes.subarray(0, prefixEnd))}${marker}`;
+}
+
+function sessionEventUtf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
 export const SessionQueueMutationResponse = z.object({
+  receipt: SessionCommandReceipt,
   snapshot: SessionQueueSnapshot,
-  events: z.array(SessionEvent),
-  shouldWake: z.boolean(),
+  draft: ComposerDraft.optional(),
 });
 export type SessionQueueMutationResponse = z.infer<typeof SessionQueueMutationResponse>;
 
 export const SessionControlResponse = z.object({
-  operationId: z.string().uuid(),
-  event: SessionEvent,
-  controlState: SessionControlState,
-  controlGeneration: z.number().int().nonnegative(),
-  expectedActiveTurnId: z.string().uuid().nullable(),
-  expectedExecutionGeneration: z.number().int().nonnegative().nullable(),
-  expectedAttemptId: z.string().uuid().nullable(),
-  deliveryEventId: z.string().uuid().nullable(),
-  shouldSignalControl: z.boolean(),
-  shouldWake: z.boolean(),
+  receipt: SessionCommandReceipt,
+  effectiveControl: EffectiveSessionControl,
+  interruptionCount: z.number().int().nonnegative(),
+  wakeCount: z.number().int().nonnegative(),
 });
 export type SessionControlResponse = z.infer<typeof SessionControlResponse>;
 
 export const CreateSessionRequest = withVariableSetIdAlias({
+  /**
+   * Optional UUID preallocated by an embedding host. This lets the host durably
+   * link its own projection before OpenGeni admits the initial turn. Replays
+   * must pair it with the same idempotency key; OpenGeni never derives host
+   * identity or authorization from the UUID.
+   */
+  requestedSessionId: z.string().uuid().optional(),
   initialMessage: z.string().min(1),
+  // System-level host context for the initial turn only. Unlike `instructions`,
+  // this does not persist into later turns and is never emitted as a user event.
+  turnInstructions: z.string().trim().min(1).max(32768).optional(),
   // Per-session agent persona/system instructions (org-visible metadata, NOT a
   // secret). Rides the SAME system-level instructions channel the per-workspace
   // agentInstructions rides, composed AFTER the workspace persona so it refines
@@ -4108,7 +6346,14 @@ export const CreateSessionRequest = withVariableSetIdAlias({
   // matches the codebase's largest free-form string convention (workspace
   // variable set variable values). Absent ⇒ byte-identical to today.
   instructions: z.string().trim().min(1).max(32768).optional(),
+  // For an agent-created child, omission inherits the trusted immediate
+  // parent's repository/file context. An explicit array, including [], is
+  // authoritative. Top-level omission remains []. Presence is resolved from
+  // the raw request because this Zod default erases absent-vs-empty.
   resources: z.array(ResourceRef).default([]),
+  // The same child omission rule applies to selected MCP tool refs. Top-level
+  // omission still applies workspace-default capability MCP tools; explicit []
+  // suppresses those defaults (the first-party OpenGeni server remains added).
   tools: z.array(ToolRef).default([]),
   metadata: z.record(z.string(), z.unknown()).default({}),
   model: z.string().min(1).optional(),
@@ -4135,7 +6380,7 @@ export const CreateSessionRequest = withVariableSetIdAlias({
   // behavior). An id that does not name a rig in the workspace is a 422.
   rigId: z.string().uuid().optional(),
   goal: GoalSpec.optional(),
-  clientEventId: z.string().min(1).optional(),
+  clientEventId: SessionOperationKey.optional(),
   // Workspace-scoped CREATE idempotency key: collapses concurrent/retried
   // create calls carrying the same key to a single session (partial unique
   // index on (workspace_id, create_idempotency_key)). Distinct from
@@ -4143,13 +6388,19 @@ export const CreateSessionRequest = withVariableSetIdAlias({
   // creation of a brand-new session. Absent means no create-dedup (each call
   // is an independent create).
   idempotencyKey: z.string().min(1).max(200).optional(),
-  // Permissions the session's first-party MCP token should carry instead of
-  // the fixed worker default — how an operator hands a manager-style session
-  // the orchestration/variableSet/github tools. Capped at creation: every
-  // requested permission must be held by the creating grant (no escalation).
+  // Permissions the session's first-party MCP token should carry. A top-level
+  // omission uses the deployment's worker default; a child omission inherits
+  // the creating session's effective grant. An explicit set is capped at
+  // creation: every requested permission must be held by the creating grant.
+  // A goal-bearing session whose explicit/effective set omits goals:manage is
+  // rejected; creation never silently expands a child beyond that set.
   firstPartyMcpPermissions: z.array(Permission).optional(),
-  // Third-party MCP servers attached only to this session. Credential headers are
-  // write-only: create responses and events expose only SessionMcpServerMetadata.
+  // Third-party MCP servers attached only to this session. For an agent-created
+  // child, omission snapshots its trusted immediate parent's server definitions,
+  // policies, connection refs, and encrypted credentials. Explicit arrays,
+  // including [], are authoritative; non-empty explicit arrays require attach
+  // permission. Credential headers are write-only: create responses and events
+  // expose only SessionMcpServerMetadata.
   mcpServers: z.array(SessionMcpServerInput).default([]),
   // Shared-sandbox placement (addendum 05 §D.1). Three-way union; OMITTED ⇒
   // today's behavior (a context-dependent default resolved server-side: from
@@ -4174,16 +6425,198 @@ export const CreateSessionRequest = withVariableSetIdAlias({
 });
 export type CreateSessionRequest = z.infer<typeof CreateSessionRequest>;
 
+// Generic, host-neutral structured human input. One model tool call creates one
+// request containing one or more questions; the durable response resumes that
+// exact call. This is deliberately distinct from tool approval: an answer,
+// skip, or expiry is structured tool output, never an approve/reject decision.
+export const HumanInputQuestionKind = z.enum(["text", "single_select", "multi_select"]);
+export type HumanInputQuestionKind = z.infer<typeof HumanInputQuestionKind>;
+
+export const HumanInputOption = z.object({
+  id: z.string().min(1).max(64),
+  label: z.string().min(1).max(256),
+  description: z.string().max(2048).nullable().optional(),
+});
+export type HumanInputOption = z.infer<typeof HumanInputOption>;
+
+export const HumanInputQuestion = z
+  .object({
+    id: z.string().min(1).max(64),
+    kind: HumanInputQuestionKind,
+    prompt: z.string().min(1).max(4096),
+    label: z.string().min(1).max(128).nullable().optional(),
+    helpText: z.string().max(2048).nullable().optional(),
+    options: z.array(HumanInputOption).max(20).default([]),
+    required: z.boolean().default(true),
+    allowOther: z.boolean().default(false),
+    validation: z
+      .object({
+        minLength: z.number().int().nonnegative().max(8192).nullable().optional(),
+        maxLength: z.number().int().positive().max(8192).nullable().optional(),
+        minSelections: z.number().int().nonnegative().max(20).nullable().optional(),
+        maxSelections: z.number().int().positive().max(20).nullable().optional(),
+      })
+      .nullable()
+      .optional(),
+  })
+  .superRefine((question, ctx) => {
+    const optionIds = new Set(question.options.map((option) => option.id));
+    if (optionIds.size !== question.options.length) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["options"],
+        message: "option ids must be unique",
+      });
+    }
+    if (question.kind === "text") {
+      if (question.options.length > 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["options"],
+          message: "text questions cannot have options",
+        });
+      }
+      if (question.allowOther) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["allowOther"],
+          message: "text questions do not use Other",
+        });
+      }
+    } else if (question.options.length === 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["options"],
+        message: "select questions require options",
+      });
+    }
+    const validation = question.validation;
+    if (
+      validation?.minLength != null &&
+      validation?.maxLength != null &&
+      validation.minLength > validation.maxLength
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["validation"],
+        message: "minLength exceeds maxLength",
+      });
+    }
+    if (
+      validation?.minSelections != null &&
+      validation?.maxSelections != null &&
+      validation.minSelections > validation.maxSelections
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["validation"],
+        message: "minSelections exceeds maxSelections",
+      });
+    }
+  });
+export type HumanInputQuestion = z.infer<typeof HumanInputQuestion>;
+
+export const HumanInputRequestStatus = z.enum([
+  "pending",
+  "answered",
+  "skipped",
+  "expired",
+  "cancelled",
+]);
+export type HumanInputRequestStatus = z.infer<typeof HumanInputRequestStatus>;
+
+export const RequestHumanInputToolInput = z.object({
+  questions: z.array(HumanInputQuestion).min(1).max(20),
+  allowSkip: z.boolean().default(false),
+  expiresInSeconds: z
+    .number()
+    .int()
+    .positive()
+    .max(30 * 24 * 60 * 60)
+    .nullable()
+    .optional(),
+});
+export type RequestHumanInputToolInput = z.infer<typeof RequestHumanInputToolInput>;
+
+export const HumanInputAnswer = z.object({
+  questionId: z.string().min(1).max(64),
+  values: z.array(z.string().max(8192)).max(20),
+  other: z.string().max(8192).nullable().optional(),
+});
+export type HumanInputAnswer = z.infer<typeof HumanInputAnswer>;
+
+export const HumanInputResponse = z.discriminatedUnion("outcome", [
+  z.object({
+    outcome: z.literal("answered"),
+    answers: z.array(HumanInputAnswer).max(20),
+  }),
+  z.object({ outcome: z.literal("skipped") }),
+  z.object({ outcome: z.literal("expired") }),
+  z.object({ outcome: z.literal("cancelled") }),
+]);
+export type HumanInputResponse = z.infer<typeof HumanInputResponse>;
+
+export const SubmitHumanInputResponseRequest = z.discriminatedUnion("outcome", [
+  z.object({
+    outcome: z.literal("answered"),
+    answers: z.array(HumanInputAnswer).max(20),
+  }),
+  z.object({ outcome: z.literal("skipped") }),
+]);
+export type SubmitHumanInputResponseRequest = z.infer<typeof SubmitHumanInputResponseRequest>;
+
+export const SessionHumanInputRequest = z.object({
+  id: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  sessionId: z.string().uuid(),
+  turnId: z.string().uuid(),
+  turnGeneration: z.number().int().positive(),
+  creationAttemptId: z.string().uuid(),
+  toolCallId: z.string().min(1).max(1024),
+  status: HumanInputRequestStatus,
+  questions: z.array(HumanInputQuestion).min(1).max(20),
+  allowSkip: z.boolean(),
+  response: HumanInputResponse.nullable(),
+  respondedBy: z.string().max(1024).nullable(),
+  respondedAt: z.string().nullable(),
+  expiresAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type SessionHumanInputRequest = z.infer<typeof SessionHumanInputRequest>;
+
+/**
+ * Extract the stable approval identity used by both durable admission and
+ * runtime resume. Serialized SDK interruptions may place it on the wrapper or
+ * its raw item; malformed entries fail closed instead of inventing an id.
+ */
+export function approvalIdentifier(value: unknown): string | null {
+  if (!value || typeof value !== "object") return null;
+  const approval = value as Record<string, unknown>;
+  const rawItem =
+    approval.rawItem && typeof approval.rawItem === "object"
+      ? (approval.rawItem as Record<string, unknown>)
+      : null;
+  const candidate = rawItem?.callId ?? rawItem?.id ?? approval.id ?? approval.name;
+  if (typeof candidate !== "string" && typeof candidate !== "number") return null;
+  return String(candidate);
+}
+
 export const ClientSessionEvent = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("user.message"),
-    clientEventId: z.string().min(1).optional(),
+    clientEventId: SessionOperationKey.optional(),
     payload: z.object({
       text: z.string().min(1),
+      // System-level host context for this exact turn only. Persisted on the
+      // turn for retry/recovery, never copied into the visible user message.
+      turnInstructions: z.string().trim().min(1).max(32768).optional(),
       resources: z.array(ResourceRef).default([]),
       tools: z.array(ToolRef).default([]),
       model: z.string().min(1).optional(),
       reasoningEffort: ReasoningEffort.optional(),
+      controlEtag: z.string().min(1).optional(),
+      expectedDraftRevision: z.number().int().nonnegative().optional(),
       // Header-value rotation only. URL/name/tool settings are immutable after
       // session create; persisted events expose metadata, never header values.
       mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional(),
@@ -4191,25 +6624,35 @@ export const ClientSessionEvent = z.discriminatedUnion("type", [
   }),
   z.object({
     type: z.literal("user.approvalDecision"),
-    clientEventId: z.string().min(1).optional(),
+    clientEventId: SessionOperationKey.optional(),
     payload: z.object({
-      approvalId: z.string().min(1),
+      approvalId: z.string().min(1).max(SESSION_OPERATION_KEY_MAX_CHARS),
       decision: z.enum(["approve", "reject"]),
       message: z.string().optional(),
     }),
   }),
+  z.object({
+    type: z.literal("user.humanInputResponse"),
+    clientEventId: SessionOperationKey.optional(),
+    payload: z.object({
+      requestId: z.string().uuid(),
+      response: SubmitHumanInputResponseRequest,
+    }),
+  }),
 ]);
 export type ClientSessionEvent = z.infer<typeof ClientSessionEvent>;
 
 export const SteerSessionMessageRequest = z.object({
   text: z.string().min(1),
+  // Same per-turn system-level context as a queued user.message.
+  turnInstructions: z.string().trim().min(1).max(32768).optional(),
   resources: z.array(ResourceRef).default([]),
   tools: z.array(ToolRef).default([]),
   model: z.string().min(1).optional(),
   reasoningEffort: ReasoningEffort.optional(),
-  clientEventId: z.string().min(1).optional(),
-  expectedControlGeneration: z.number().int().nonnegative().optional(),
-  expectedWorkspaceInferenceGeneration: z.number().int().nonnegative().optional(),
+  clientEventId: SessionOperationKey.optional(),
+  controlEtag: z.string().min(1).optional(),
+  expectedDraftRevision: z.number().int().nonnegative().optional(),
   mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional(),
 });
 export type SteerSessionMessageRequest = z.infer<typeof SteerSessionMessageRequest>;
@@ -4249,6 +6692,37 @@ export const GitHubRepository = z.object({
 });
 export type GitHubRepository = z.infer<typeof GitHubRepository>;
 
+export const GitHubRepositoryScope = z.enum(["all", "selected"]);
+export type GitHubRepositoryScope = z.infer<typeof GitHubRepositoryScope>;
+
+export const GitHubInstallationBinding = z.object({
+  installationId: z.number().int().positive(),
+  accountLogin: z.string().nullable(),
+  accountType: z.string().nullable(),
+  repositoryScope: GitHubRepositoryScope,
+  repositoryCount: z.number().int().nonnegative(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type GitHubInstallationBinding = z.infer<typeof GitHubInstallationBinding>;
+
+export const GitHubAppInfo = z.object({
+  configured: z.boolean(),
+  appId: z.string().nullable(),
+  clientId: z.string().nullable(),
+  appSlug: z.string().nullable(),
+  installUrl: z.string().nullable(),
+  linkUrl: z.string().nullable(),
+  installations: z.array(GitHubInstallationBinding),
+  missing: z.array(z.string()),
+});
+export type GitHubAppInfo = z.infer<typeof GitHubAppInfo>;
+
+export const GitHubRepositoriesResponse = z.object({
+  repositories: z.array(GitHubRepository),
+});
+export type GitHubRepositoriesResponse = z.infer<typeof GitHubRepositoriesResponse>;
+
 export const ClientAuthConfig = z.discriminatedUnion("mode", [
   z.object({
     mode: z.literal("none"),
@@ -4269,7 +6743,7 @@ export const ClientAuthConfig = z.discriminatedUnion("mode", [
 ]);
 export type ClientAuthConfig = z.infer<typeof ClientAuthConfig>;
 
-// The negotiated capability handshake document (master-spine C.3). ONE shape;
+// The negotiated capability handshake document (sandbox contract 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.
@@ -4402,14 +6876,14 @@ export const ViewerHolder = z.object({
   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).
+  // a viewer grant is minted (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
+// acknowledgment of the un-redacted pixel plane. 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
@@ -4453,7 +6927,7 @@ export type ViewerHeartbeatResponse = z.infer<typeof ViewerHeartbeatResponse>;
 // (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
+// request bodies additionally carry the consent-relevant fields the design brief
 // mandates (the agent ed25519 pubkey + can-offer-display + requests-screen-control).
 // =============================================================================
 
@@ -4699,7 +7173,7 @@ export const EnrollTokenExchangeResponse = z.object({
 });
 export type EnrollTokenExchangeResponse = z.infer<typeof EnrollTokenExchangeResponse>;
 
-// ── Machines dashboard + per-machine metrics (M10, dossier §10.7) ────────────
+// ── Machines dashboard + per-machine metrics (M10) ────────────
 //
 // The SHARED data contract M10 (backend) implements + M9 (UI) renders. THE
 // orchestrator owns this shape; M9 imports these types so the dashboard never
@@ -4853,8 +7327,20 @@ export const ClientModel = z.object({
 });
 export type ClientModel = z.infer<typeof ClientModel>;
 
+/**
+ * Exact public HTTP protocol revision spoken by this release train.
+ *
+ * This is deliberately independent from a deployment SHA: API and web may roll
+ * at different instants, while incompatible request shapes must never cross
+ * that rollout boundary. Mutating clients send this value in
+ * `x-opengeni-api-contract`; the API rejects any other value before routing.
+ */
+export const OPENGENI_API_CONTRACT_REVISION = "2026-07-turn-instructions-v1" as const;
+export const OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract" as const;
+
 export const ClientConfig = z.object({
   deploymentRevision: z.string(),
+  apiContractRevision: z.literal(OPENGENI_API_CONTRACT_REVISION),
   // Release-train version of the server (absent on dev/source builds). The
   // compatibility policy lives in docs/architecture.md — clients within the
   // same major are supported; evolution is additive within a major.