@opengeni/contracts 0.9.0 → 0.10.0

package/src/index.ts

@@ -5,6 +5,9 @@ export const SessionStatus = z.enum([
   "running",
   "idle",
   "requires_action",
+  "recovering",
+  "waiting_capacity",
+  "paused",
   "failed",
   "cancelled",
 ]);
@@ -472,8 +475,12 @@ export const Permission = z.enum([
   "api_keys:manage",
   "connections:read",
   "connections:write",
+  /** @deprecated alias of variable-sets:manage */
   "environments:manage",
+  /** @deprecated alias of variable-sets:use */
   "environments:use",
+  "variable-sets:manage",
+  "variable-sets:use",
   // Attach or rotate per-session third-party MCP server credentials. Deliberately
   // not part of the worker's default first-party MCP permission set: a sandboxed
   // agent must not be able to hand itself new bearer credentials.
@@ -490,6 +497,13 @@ export const Permission = z.enum([
   // admin-shaped action. workspace:admin is the super-wildcard over both.
   "enrollments:read",
   "enrollments:manage",
+  // Rigs (workspace-scoped, versioned sandbox machine definitions). rigs:use is
+  // read + propose-change (the agent-native, additive path a sandboxed session
+  // is trusted with); rigs:manage is create/edit/activate/promote/delete (the
+  // admin-shaped path that mints or rolls versions). workspace:admin is the
+  // super-wildcard over both.
+  "rigs:use",
+  "rigs:manage",
 ]);
 export type Permission = z.infer<typeof Permission>;
 
@@ -532,14 +546,66 @@ export const Workspace = z.object({
   // Per-workspace agent persona template (white-label override). null means
   // the deployment default (OPENGENI_AGENT_INSTRUCTIONS_TEMPLATE /
   // DEFAULT_AGENT_INSTRUCTIONS) is used. The runtime always injects the
-  // non-bypassable CORE (goal-loop ownership + environment block), so an
+  // non-bypassable CORE (goal-loop ownership + variableSet block), so an
   // override restyles the persona without dropping that contract.
   agentInstructions: z.string().nullable(),
+  // Growth-ready per-workspace settings bag (migration 0045). Known keys are
+  // 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(),
+  // Workspace default rig used by session/scheduled-task create fallback.
+  defaultRigId: z.string().uuid().nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
 export type Workspace = z.infer<typeof Workspace>;
 
+// 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.
+export const WorkspaceSettingsSchema = z
+  .object({
+    memoryEnabled: z.boolean().optional(),
+  })
+  .passthrough();
+export type WorkspaceSettings = z.infer<typeof WorkspaceSettingsSchema>;
+
+// Resolve the effective memoryEnabled flag from a raw settings bag (default off).
+export function resolveWorkspaceMemoryEnabled(settings: unknown): boolean {
+  const parsed = WorkspaceSettingsSchema.safeParse(settings ?? {});
+  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.
+export const UpdateWorkspaceSettingsRequest = z
+  .object({
+    memoryEnabled: z.boolean().optional(),
+  })
+  .passthrough();
+export type UpdateWorkspaceSettingsRequest = z.infer<typeof UpdateWorkspaceSettingsRequest>;
+
+export const SetWorkspaceDefaultRigRequest = z.object({
+  rigId: z.string().uuid().nullable(),
+});
+export type SetWorkspaceDefaultRigRequest = z.infer<typeof SetWorkspaceDefaultRigRequest>;
+
+// PUT body for the workspace model policy (full replace, not a merge). null (or
+// omitted) = unrestricted for that dimension; an EMPTY array is a valid,
+// explicit total block. Entries are provider ids / exact model ids as the
+// router resolves them (see evaluateWorkspaceModelPolicy).
+export const UpdateWorkspaceModelPolicyRequest = z.object({
+  allowedProviders: z.array(z.string().min(1).max(128)).max(64).nullable().optional(),
+  allowedModels: z.array(z.string().min(1).max(256)).max(256).nullable().optional(),
+});
+export type UpdateWorkspaceModelPolicyRequest = z.infer<typeof UpdateWorkspaceModelPolicyRequest>;
+
 export const AccountGrant = z.object({
   accountId: z.string().uuid(),
   subjectId: z.string().min(1),
@@ -580,17 +646,32 @@ export const DelegatedAccessTokenPayload = z.object({
   // 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 type DelegatedAccessTokenPayload = z.infer<typeof DelegatedAccessTokenPayload>;
 
-export async function signDelegatedAccessToken(secret: string, payload: DelegatedAccessTokenPayload): Promise<string> {
-  const encodedPayload = base64UrlEncode(JSON.stringify(DelegatedAccessTokenPayload.parse(payload)));
+export async function signDelegatedAccessToken(
+  secret: string,
+  payload: DelegatedAccessTokenPayload,
+): Promise<string> {
+  const encodedPayload = base64UrlEncode(
+    JSON.stringify(DelegatedAccessTokenPayload.parse(payload)),
+  );
   const signature = await hmacSha256Base64Url(secret, encodedPayload);
   return `ogd_${encodedPayload}.${signature}`;
 }
 
-export async function verifyDelegatedAccessToken(secret: string, token: string, nowSeconds = Math.floor(Date.now() / 1000)): Promise<DelegatedAccessTokenPayload | null> {
+export async function verifyDelegatedAccessToken(
+  secret: string,
+  token: string,
+  nowSeconds = Math.floor(Date.now() / 1000),
+): Promise<DelegatedAccessTokenPayload | null> {
   if (!token.startsWith("ogd_")) {
     return null;
   }
@@ -605,7 +686,9 @@ export async function verifyDelegatedAccessToken(secret: string, token: string,
   if (!constantTimeEqual(signature, expected)) {
     return null;
   }
-  const payload = DelegatedAccessTokenPayload.safeParse(JSON.parse(base64UrlDecode(encodedPayload)));
+  const payload = DelegatedAccessTokenPayload.safeParse(
+    JSON.parse(base64UrlDecode(encodedPayload)),
+  );
   if (!payload.success || payload.data.exp < nowSeconds) {
     return null;
   }
@@ -633,13 +716,20 @@ export const EnrollmentBearerPayload = z.object({
 });
 export type EnrollmentBearerPayload = z.infer<typeof EnrollmentBearerPayload>;
 
-export async function signEnrollmentBearer(secret: string, payload: EnrollmentBearerPayload): Promise<string> {
+export async function signEnrollmentBearer(
+  secret: string,
+  payload: EnrollmentBearerPayload,
+): Promise<string> {
   const encodedPayload = base64UrlEncode(JSON.stringify(EnrollmentBearerPayload.parse(payload)));
   const signature = await hmacSha256Base64Url(secret, encodedPayload);
   return `oge_${encodedPayload}.${signature}`;
 }
 
-export async function verifyEnrollmentBearer(secret: string, token: string, nowSeconds = Math.floor(Date.now() / 1000)): Promise<EnrollmentBearerPayload | null> {
+export async function verifyEnrollmentBearer(
+  secret: string,
+  token: string,
+  nowSeconds = Math.floor(Date.now() / 1000),
+): Promise<EnrollmentBearerPayload | null> {
   if (!token.startsWith("oge_")) {
     return null;
   }
@@ -689,7 +779,10 @@ export const EnrollTokenPayload = z.object({
 });
 export type EnrollTokenPayload = z.infer<typeof EnrollTokenPayload>;
 
-export async function signEnrollToken(secret: string, payload: EnrollTokenPayload): Promise<string> {
+export async function signEnrollToken(
+  secret: string,
+  payload: EnrollTokenPayload,
+): Promise<string> {
   const encodedPayload = base64UrlEncode(JSON.stringify(EnrollTokenPayload.parse(payload)));
   const signature = await hmacSha256Base64Url(secret, encodedPayload);
   return `oget_${encodedPayload}.${signature}`;
@@ -703,7 +796,11 @@ export async function signEnrollToken(secret: string, payload: EnrollTokenPayloa
  * bearer fails the prefix gate; a same-secret token that lacks the typ claim fails
  * the schema gate — both halves of the domain separation are enforced here.
  */
-export async function verifyEnrollToken(secret: string, token: string, nowSeconds = Math.floor(Date.now() / 1000)): Promise<EnrollTokenPayload | null> {
+export async function verifyEnrollToken(
+  secret: string,
+  token: string,
+  nowSeconds = Math.floor(Date.now() / 1000),
+): Promise<EnrollTokenPayload | null> {
   if (!token.startsWith("oget_")) {
     return null;
   }
@@ -765,7 +862,10 @@ export const StreamTokenPayload = z.object({
 });
 export type StreamTokenPayload = z.infer<typeof StreamTokenPayload>;
 
-export async function signStreamToken(secret: string, payload: StreamTokenPayload): Promise<string> {
+export async function signStreamToken(
+  secret: string,
+  payload: StreamTokenPayload,
+): Promise<string> {
   const encodedPayload = base64UrlEncode(JSON.stringify(StreamTokenPayload.parse(payload)));
   const signature = await hmacSha256Base64Url(secret, encodedPayload);
   return `ogs_${encodedPayload}.${signature}`;
@@ -781,7 +881,11 @@ export async function signStreamToken(secret: string, payload: StreamTokenPayloa
  * lease + route params — verify proves the token is authentic + unexpired, the
  * caller proves it is for THIS box's current epoch and THIS workspace+session.
  */
-export async function verifyStreamToken(secret: string, token: string, nowSeconds = Math.floor(Date.now() / 1000)): Promise<StreamTokenPayload | null> {
+export async function verifyStreamToken(
+  secret: string,
+  token: string,
+  nowSeconds = Math.floor(Date.now() / 1000),
+): Promise<StreamTokenPayload | null> {
   if (!token.startsWith("ogs_")) {
     return null;
   }
@@ -858,7 +962,11 @@ export async function signRelayToken(secret: string, payload: RelayTokenPayload)
  * The channel-key scope (claim.workspaceId/agentId vs the StreamOpen channel key)
  * is enforced by the relay at USE — verify proves authenticity + freshness only.
  */
-export async function verifyRelayToken(secret: string, token: string, nowSeconds = Math.floor(Date.now() / 1000)): Promise<RelayTokenPayload | null> {
+export async function verifyRelayToken(
+  secret: string,
+  token: string,
+  nowSeconds = Math.floor(Date.now() / 1000),
+): Promise<RelayTokenPayload | null> {
   if (!token.startsWith("ogr_")) {
     return null;
   }
@@ -1064,7 +1172,12 @@ export type LimitDecision = z.infer<typeof LimitDecision>;
 // the admitted quantity so a PULL host can grant a partial allowance.
 export const EntitlementDecision = z.discriminatedUnion("allowed", [
   z.object({ allowed: z.literal(true), quantity: z.number().optional() }),
-  z.object({ allowed: z.literal(false), reason: z.string(), code: z.string().optional(), quantity: z.number().optional() }),
+  z.object({
+    allowed: z.literal(false),
+    reason: z.string(),
+    code: z.string().optional(),
+    quantity: z.number().optional(),
+  }),
 ]);
 export type EntitlementDecision = z.infer<typeof EntitlementDecision>;
 
@@ -1079,16 +1192,32 @@ export type EntitlementsPort = {
   admitRun(input: AdmitRunInput): Promise<EntitlementDecision>;
 };
 
+export const GitCredentialProvider = z.enum(["github", "gitlab", "azure_devops"]);
+export type GitCredentialProvider = z.infer<typeof GitCredentialProvider>;
+
+const GitProviderRepositoryId = z.union([z.number().int().positive(), z.string().min(1)]);
+
+export const GitCredentialRepositoryRef = z.object({
+  provider: GitCredentialProvider.optional(),
+  uri: z.string().min(1),
+  ref: z.string().min(1),
+  repositoryId: GitProviderRepositoryId.optional(),
+  installationId: GitProviderRepositoryId.optional(),
+  projectId: GitProviderRepositoryId.optional(),
+  connectionId: z.string().min(1).optional(),
+});
+export type GitCredentialRepositoryRef = z.infer<typeof GitCredentialRepositoryRef>;
+
 // ============ P4a — Connection-credential provider (§7.6) ============
 //
 // The host-providable per-run credential-mint seam over OpenGeni's TWO
 // run-scoped credential sites in the worker:
-//   - GIT credentials: the GitHub App installation token minted in
-//     `sandboxEnvironmentForRun` (today `createGitHubAppInstallationToken`
-//     from `settings`) and injected as `GH_TOKEN`/`GITHUB_TOKEN`/the git
-//     extraheader.
-//   - SANDBOX secrets: the decrypted workspace environment values loaded in
-//     `loadWorkspaceEnvironmentForRun` (today decrypted with
+//   - 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)
+//     and seeded off-manifest into sandbox token files for git + provider CLIs.
+//   - SANDBOX secrets: the decrypted variable set values loaded in
+//     `loadVariableSetForRun` (today decrypted with
 //     `environmentsEncryptionKeyBytes(settings)`).
 //
 // In embedded/separate topologies the HOST owns these external connections
@@ -1100,28 +1229,41 @@ export type EntitlementsPort = {
 // FORK-7 CROSS-CHECK (the host-mapping safety guardrail): a credential
 // provider returns the `workspaceId` it scoped the credential to, and the
 // activity ASSERTS it agrees with the run's workspace BEFORE injecting
-// `GH_TOKEN` (or applying the decrypted values). A host mapping bug that
+// any git provider token seed (or applying decrypted environment values). A host mapping bug that
 // returns tenant B's creds while the run is tenant A is thereby caught at the
 // seam, never silently injected into tenant A's sandbox.
 
 export type GitCredentialsRequest = {
   accountId: string;
   workspaceId: string;
-  // The GitHub App installation the run's repository resources resolved to,
-  // and the specific repositories the token must be scoped to. Mirrors the
-  // shape `createGitHubAppInstallationToken` consumes today.
+  // 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;
+  // 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.
+  purpose?: "token" | "identity";
+  // Provider-neutral repository refs for hosts that broker non-GitHub tokens.
+  // For GitHub requests these are additive to the legacy fields below.
+  repositoryRefs?: GitCredentialRepositoryRef[];
+  // Legacy GitHub App installation shape retained for 0.x compatibility.
   installationId: number;
   repositoryIds: number[];
 };
 
 export type GitCredentials = {
-  // The minted installation token the activity injects as GH_TOKEN/GITHUB_TOKEN
-  // and into the git http extraheader (identical downstream handling to the
-  // self-mint path).
-  token: string;
+  // The minted provider token. Required for purpose="token"; optional for
+  // 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
   // asserts `workspaceId === request.workspaceId` before injecting.
   workspaceId: 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.
+  expiresAt?: string | null;
   // Optional git identity override. When omitted the activity falls back to
   // today's `githubAppBotIdentity(settings)`.
   identity?: { name: string; email: string } | null;
@@ -1130,20 +1272,20 @@ export type GitCredentials = {
 export type SandboxSecretsRequest = {
   accountId: string;
   workspaceId: string;
-  // The workspace environment the run's session declares (null = unattached;
+  // The variable set the run's session declares (null = unattached;
   // the provider, like the self-mint path, returns null values for it).
-  environmentId: string;
+  variableSetId: string;
 };
 
 export type SandboxSecrets = {
-  // The decrypted environment values the run injects, replacing the local
+  // The decrypted variableSet values the run injects, replacing the local
   // `environmentsEncryptionKeyBytes` decrypt. Same shape the self-mint path
   // produces (plaintext name→value).
   values: Record<string, string>;
   // FORK-7 echo: the workspace the provider scoped these secrets to.
   workspaceId: string;
-  // Optional environment metadata; when omitted the activity uses the
-  // environmentId as both id and name (the local decrypt carries the row's
+  // Optional variableSet metadata; when omitted the activity uses the
+  // variableSetId as both id and name (the local decrypt carries the row's
   // id/name/description, but only `id` is load-bearing downstream).
   id?: string;
   name?: string;
@@ -1154,8 +1296,8 @@ export type ConnectionCredentialsPort = {
   // Both legs are optional: a host may drive ONLY git creds (BYO-GitHub-App)
   // and leave sandbox secrets to OpenGeni's local decrypt, or vice-versa. An
   // unset leg falls through to today's self-mint for THAT leg only.
-  gitCredentials?: (input: GitCredentialsRequest) => Promise<GitCredentials>;
-  sandboxSecrets?: (input: SandboxSecretsRequest) => Promise<SandboxSecrets>;
+  gitCredentials?(input: GitCredentialsRequest): Promise<GitCredentials>;
+  sandboxSecrets?(input: SandboxSecretsRequest): Promise<SandboxSecrets>;
 };
 
 // ============ P4a — GitHub App API port (BYO-App, §7.6 / SPIKE-2 remainder) ===
@@ -1187,9 +1329,7 @@ export type GitHubAppApiPort = {
     code: string;
     installationId: number;
   }) => Promise<GitHubInstallationSummary>;
-  listRepositories?: (input: {
-    installationIds?: number[];
-  }) => Promise<GitHubRepository[]>;
+  listRepositories?: (input: { installationIds?: number[] }) => Promise<GitHubRepository[]>;
 };
 
 export const BillingBalance = z.object({
@@ -1202,10 +1342,14 @@ export type BillingBalance = z.infer<typeof BillingBalance>;
 
 export const CreateCheckoutRequest = z.object({
   accountId: z.string().uuid().optional(),
-  amountUsd: z.number().min(5).max(10_000).refine(
-    (value) => Number.isFinite(value) && Math.abs(value - Math.round(value * 100) / 100) < 1e-9,
-    { message: "amountUsd must use cent precision" },
-  ),
+  amountUsd: z
+    .number()
+    .min(5)
+    .max(10_000)
+    .refine(
+      (value) => Number.isFinite(value) && Math.abs(value - Math.round(value * 100) / 100) < 1e-9,
+      { message: "amountUsd must use cent precision" },
+    ),
   successUrl: z.string().url().optional(),
   cancelUrl: z.string().url().optional(),
 });
@@ -1223,6 +1367,11 @@ export const RepositoryResourceRef = z.object({
   ref: z.string().min(1),
   mountPath: z.string().min(1).optional(),
   subpath: z.string().min(1).optional(),
+  provider: GitCredentialProvider.optional(),
+  repositoryId: GitProviderRepositoryId.optional(),
+  installationId: GitProviderRepositoryId.optional(),
+  projectId: GitProviderRepositoryId.optional(),
+  connectionId: z.string().min(1).optional(),
   githubInstallationId: z.number().int().positive().optional(),
   githubRepositoryId: z.number().int().positive().optional(),
 });
@@ -1241,7 +1390,13 @@ export type ResourceRef = z.infer<typeof ResourceRef>;
 export const FileStatus = z.enum(["pending_upload", "ready", "failed", "expired", "deleted"]);
 export type FileStatus = z.infer<typeof FileStatus>;
 
-export const FileUploadStatus = z.enum(["pending", "completed", "expired", "failed"]);
+export const FileUploadStatus = z.enum([
+  "pending",
+  "cleanup_pending",
+  "completed",
+  "expired",
+  "failed",
+]);
 export type FileUploadStatus = z.infer<typeof FileUploadStatus>;
 
 export const FileAsset = z.object({
@@ -1292,7 +1447,16 @@ export type FileDownloadUrlResponse = z.infer<typeof FileDownloadUrlResponse>;
 export const DocumentStatus = z.enum(["queued", "indexing", "ready", "failed"]);
 export type DocumentStatus = z.infer<typeof DocumentStatus>;
 
-export const KnowledgeSourceKind = z.enum(["manual_upload", "meeting_transcript", "repository", "email", "chat", "document", "web", "other"]);
+export const KnowledgeSourceKind = z.enum([
+  "manual_upload",
+  "meeting_transcript",
+  "repository",
+  "email",
+  "chat",
+  "document",
+  "web",
+  "other",
+]);
 export type KnowledgeSourceKind = z.infer<typeof KnowledgeSourceKind>;
 
 export const DocumentSearchMode = z.enum(["hybrid", "vector", "keyword"]);
@@ -1389,10 +1553,28 @@ export const DocumentSearchRequest = z.object({
 });
 export type DocumentSearchRequest = z.infer<typeof DocumentSearchRequest>;
 
-export const KnowledgeMemoryStatus = z.enum(["proposed", "approved", "rejected"]);
+// proposed/approved/rejected are the legacy curated-knowledge review states
+// (docs-MCP memory_propose lane). active/superseded/archived are Workspace
+// Memory V1: agent-written memories land `active` (usable immediately — human is
+// auditor, not gatekeeper), get `superseded` when replaced, `archived` when
+// retired. Agent-visible set = active ∪ approved.
+export const KnowledgeMemoryStatus = z.enum([
+  "proposed",
+  "approved",
+  "rejected",
+  "active",
+  "superseded",
+  "archived",
+]);
 export type KnowledgeMemoryStatus = z.infer<typeof KnowledgeMemoryStatus>;
 
-export const KnowledgeMemoryKind = z.enum(["semantic", "episodic", "procedural", "decision", "preference"]);
+export const KnowledgeMemoryKind = z.enum([
+  "semantic",
+  "episodic",
+  "procedural",
+  "decision",
+  "preference",
+]);
 export type KnowledgeMemoryKind = z.infer<typeof KnowledgeMemoryKind>;
 
 export const KnowledgeSourceRef = z.object({
@@ -1417,13 +1599,29 @@ export const KnowledgeMemory = z.object({
   createdBySessionId: z.string().uuid().nullable(),
   reviewedBy: z.string().nullable(),
   reviewedAt: z.string().nullable(),
+  // Workspace Memory V1 fields. usageCount/lastUsedAt feed end-state ranking and
+  // decay; supersedesId/supersededById link correction chains; validFrom/validUntil
+  // are the point-in-time window. embedding/embeddingModel/textHash are internal
+  // and never exposed on the wire.
+  pinned: z.boolean(),
+  usageCount: z.number().int(),
+  lastUsedAt: z.string().nullable(),
+  supersedesId: z.string().uuid().nullable(),
+  supersededById: z.string().uuid().nullable(),
+  validFrom: z.string(),
+  validUntil: z.string().nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
 export type KnowledgeMemory = z.infer<typeof KnowledgeMemory>;
 
+// Default status is `active`: a create through this request lands an
+// agent-visible memory via the one write gate (saveWorkspaceMemory). Passing an
+// explicit `proposed`/`approved`/`rejected` status routes to the legacy curated
+// create instead (the docs-MCP memory_propose lane). pinned/replacesId apply to
+// the active (memory) path.
 export const CreateKnowledgeMemoryRequest = z.object({
-  status: KnowledgeMemoryStatus.default("proposed"),
+  status: KnowledgeMemoryStatus.default("active"),
   kind: KnowledgeMemoryKind.default("semantic"),
   scope: z.string().min(1).default("workspace"),
   text: z.string().min(1),
@@ -1431,6 +1629,8 @@ export const CreateKnowledgeMemoryRequest = z.object({
   confidence: z.number().min(0).max(1).default(0.5),
   metadata: z.record(z.string(), z.unknown()).default({}),
   createdBySessionId: z.string().uuid().optional(),
+  pinned: z.boolean().optional(),
+  replacesId: z.string().min(1).optional(),
 });
 export type CreateKnowledgeMemoryRequest = z.infer<typeof CreateKnowledgeMemoryRequest>;
 
@@ -1443,9 +1643,12 @@ export const UpdateKnowledgeMemoryRequest = z.object({
   confidence: z.number().min(0).max(1).optional(),
   metadata: z.record(z.string(), z.unknown()).optional(),
   reviewedBy: z.string().min(1).optional(),
+  // Human audit action: pin (never decays) / unpin.
+  pinned: z.boolean().optional(),
 });
 export type UpdateKnowledgeMemoryRequest = z.infer<typeof UpdateKnowledgeMemoryRequest>;
 
+// GET list/filter over knowledge memories (curated + memory).
 export const KnowledgeMemorySearchRequest = z.object({
   query: z.string().min(1).optional(),
   status: KnowledgeMemoryStatus.optional(),
@@ -1455,6 +1658,32 @@ export const KnowledgeMemorySearchRequest = z.object({
 });
 export type KnowledgeMemorySearchRequest = z.infer<typeof KnowledgeMemorySearchRequest>;
 
+export const WorkspaceMemorySearchMode = z.enum(["hybrid", "vector", "keyword"]);
+export type WorkspaceMemorySearchMode = z.infer<typeof WorkspaceMemorySearchMode>;
+
+// POST hybrid search over the workspace's agent-visible memory (active ∪ approved).
+export const WorkspaceMemorySearchRequest = z.object({
+  query: z.string().min(1),
+  kind: KnowledgeMemoryKind.optional(),
+  limit: z.number().int().positive().max(20).optional(),
+  mode: WorkspaceMemorySearchMode.optional(),
+});
+export type WorkspaceMemorySearchRequest = z.infer<typeof WorkspaceMemorySearchRequest>;
+
+export const WorkspaceMemorySearchResult = z.object({
+  memory: KnowledgeMemory,
+  score: z.number(),
+  matchType: WorkspaceMemorySearchMode,
+  vectorScore: z.number().nullable(),
+  keywordScore: z.number().nullable(),
+});
+export type WorkspaceMemorySearchResult = z.infer<typeof WorkspaceMemorySearchResult>;
+
+export const WorkspaceMemorySearchResponse = z.object({
+  results: z.array(WorkspaceMemorySearchResult),
+});
+export type WorkspaceMemorySearchResponse = z.infer<typeof WorkspaceMemorySearchResponse>;
+
 export const ToolRef = z.object({
   kind: z.literal("mcp"),
   id: z.string().min(1),
@@ -1469,13 +1698,19 @@ export const ToolRef = z.object({
 export type ToolRef = z.infer<typeof ToolRef>;
 
 const registryId = /^[A-Za-z0-9_-]+$/;
-const httpsUrl = z.string().url().refine((value) => {
-  try {
-    return new URL(value).protocol === "https:";
-  } catch {
-    return false;
-  }
-}, { message: "URL must use https" });
+const httpsUrl = z
+  .string()
+  .url()
+  .refine(
+    (value) => {
+      try {
+        return new URL(value).protocol === "https:";
+      } catch {
+        return false;
+      }
+    },
+    { message: "URL must use https" },
+  );
 
 export const SessionMcpServerInput = z.object({
   id: z.string().min(1).regex(registryId),
@@ -1502,13 +1737,15 @@ export const SessionMcpCredentialUpdateInput = z.object({
 });
 export type SessionMcpCredentialUpdateInput = z.infer<typeof SessionMcpCredentialUpdateInput>;
 
-export const SessionMcpServerMetadata = z.object({
-  id: z.string().min(1).regex(registryId),
-  name: z.string().min(1).nullable(),
-  url: httpsUrl,
-  headerNames: z.array(z.string()).default([]),
-  credentialVersion: z.number().int().positive(),
-}).strict();
+export const SessionMcpServerMetadata = z
+  .object({
+    id: z.string().min(1).regex(registryId),
+    name: z.string().min(1).nullable(),
+    url: httpsUrl,
+    headerNames: z.array(z.string()).default([]),
+    credentialVersion: z.number().int().positive(),
+  })
+  .strict();
 export type SessionMcpServerMetadata = z.infer<typeof SessionMcpServerMetadata>;
 
 export class ResourceRefConflictError extends Error {
@@ -1547,8 +1784,14 @@ export function mergeResourceRefs(
   options: { rejectConflicts?: boolean } = {},
 ): ResourceRef[] {
   const out = [...existing];
-  const mountPaths = new Map(existing.flatMap((resource) => resource.mountPath ? [[resource.mountPath, stableJson(resource)] as const] : []));
-  const identities = new Map(existing.map((resource) => [resourceIdentityKey(resource), stableJson(resource)] as const));
+  const mountPaths = new Map(
+    existing.flatMap((resource) =>
+      resource.mountPath ? [[resource.mountPath, stableJson(resource)] as const] : [],
+    ),
+  );
+  const identities = new Map(
+    existing.map((resource) => [resourceIdentityKey(resource), stableJson(resource)] as const),
+  );
   const exact = new Set(existing.map(stableJson));
 
   for (const resource of additions) {
@@ -1559,12 +1802,16 @@ export function mergeResourceRefs(
     if (options.rejectConflicts) {
       const existingAtMount = resource.mountPath ? mountPaths.get(resource.mountPath) : undefined;
       if (existingAtMount && existingAtMount !== serialized) {
-        throw new ResourceRefConflictError(`resource mount path is already attached: ${resource.mountPath}`);
+        throw new ResourceRefConflictError(
+          `resource mount path is already attached: ${resource.mountPath}`,
+        );
       }
       const identity = resourceIdentityKey(resource);
       const existingIdentity = identities.get(identity);
       if (existingIdentity && existingIdentity !== serialized) {
-        throw new ResourceRefConflictError(`resource is already attached with different settings: ${identity}`);
+        throw new ResourceRefConflictError(
+          `resource is already attached with different settings: ${identity}`,
+        );
       }
     }
     out.push(resource);
@@ -1577,9 +1824,17 @@ export function mergeResourceRefs(
   return out;
 }
 
-export function reasoningEffortForMetadata(metadata: Record<string, unknown>, fallback: ReasoningEffort): ReasoningEffort {
+export function reasoningEffortForMetadata(
+  metadata: Record<string, unknown>,
+  fallback: ReasoningEffort,
+): ReasoningEffort {
   const value = metadata.reasoningEffort;
-  return value === "none" || value === "minimal" || value === "low" || value === "medium" || value === "high" || value === "xhigh"
+  return value === "none" ||
+    value === "minimal" ||
+    value === "low" ||
+    value === "medium" ||
+    value === "high" ||
+    value === "xhigh"
     ? value
     : fallback;
 }
@@ -1600,17 +1855,44 @@ function sortJson(value: unknown): unknown {
     return value.map(sortJson);
   }
   if (value && typeof value === "object") {
-    return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, nested]) => [key, sortJson(nested)]));
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, nested]) => [key, sortJson(nested)]),
+    );
   }
   return value;
 }
 
-export const SessionTurnStatus = z.enum(["queued", "running", "requires_action", "completed", "failed", "cancelled"]);
+export const SessionTurnStatus = z.enum([
+  "queued",
+  "running",
+  "requires_action",
+  "recovering",
+  "waiting_capacity",
+  "completed",
+  "failed",
+  "cancelled",
+  "superseded",
+]);
 export type SessionTurnStatus = z.infer<typeof SessionTurnStatus>;
 
-export const SessionTurnSource = z.enum(["user", "scheduled_task", "api", "goal"]);
+export const SessionTurnSource = z.enum([
+  "user",
+  "scheduled_task",
+  "api",
+  "goal",
+  "system",
+  "compaction",
+]);
 export type SessionTurnSource = z.infer<typeof SessionTurnSource>;
 
+export const SessionControlState = z.enum(["active", "paused"]);
+export type SessionControlState = z.infer<typeof SessionControlState>;
+
+export const WorkspaceInferenceState = z.enum(["active", "paused"]);
+export type WorkspaceInferenceState = z.infer<typeof WorkspaceInferenceState>;
+
 export const SessionGoalStatus = z.enum(["active", "paused", "completed"]);
 export type SessionGoalStatus = z.infer<typeof SessionGoalStatus>;
 
@@ -1619,7 +1901,7 @@ export type SessionGoalCreatedBy = z.infer<typeof SessionGoalCreatedBy>;
 
 export const SessionGoalPausedReason = z.enum([
   "agent",
-  "user_interrupt",
+  "user_pause",
   "api",
   "no_progress",
   "max_auto_continuations",
@@ -1667,6 +1949,18 @@ export const UpdateSessionRequest = z.object({
 });
 export type UpdateSessionRequest = z.infer<typeof UpdateSessionRequest>;
 
+/**
+ * A member's personal pin preference for a session. `expectedVersion` is
+ * optional: ordinary pin/unpin actions are idempotent last-write-wins, while a
+ * client that has a known version can fail closed rather than overwrite a newer
+ * action from another browser.
+ */
+export const UpdateSessionPinRequest = z.object({
+  pinned: z.boolean(),
+  expectedVersion: z.number().int().nonnegative().optional(),
+});
+export type UpdateSessionPinRequest = z.infer<typeof UpdateSessionPinRequest>;
+
 // Operator context controls (slash-command palette: /clear, /compact). These
 // are session/operator actions, NOT a structured way to talk to the agent —
 // the human↔agent channel stays plain chat. Both require `sessions:control`.
@@ -1709,9 +2003,11 @@ export function isClearedRunStateBlob(serialized: string | null | undefined): bo
   }
   try {
     const parsed = JSON.parse(serialized) as unknown;
-    return typeof parsed === "object"
-      && parsed !== null
-      && (parsed as Record<string, unknown>)[CLEARED_RUN_STATE_MARKER] === true;
+    return (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      (parsed as Record<string, unknown>)[CLEARED_RUN_STATE_MARKER] === true
+    );
   } catch {
     return false;
   }
@@ -1723,9 +2019,10 @@ export type CompactSessionContextRequest = z.infer<typeof CompactSessionContextR
 
 /** Outcome of a manual /compact trigger. */
 export const CompactSessionContextResult = z.object({
-  // queued: a client-side (Azure) compaction will run before the next turn.
-  // noop:   nothing to do (server-managed provider, mode off, or no history).
-  status: z.enum(["queued", "noop"]),
+  // pending: an active/paused session will compact at its next safe boundary.
+  // completed: an idle compaction-only activity completed synchronously.
+  // noop: there is no active history to compact.
+  status: z.enum(["pending", "completed", "noop"]),
   message: z.string(),
 });
 export type CompactSessionContextResult = z.infer<typeof CompactSessionContextResult>;
@@ -1738,7 +2035,7 @@ export const SessionTurn = z.object({
   temporalWorkflowId: z.string(),
   status: SessionTurnStatus,
   source: SessionTurnSource,
-  position: z.number().int().positive(),
+  position: z.number().int(),
   prompt: z.string().min(1),
   resources: z.array(ResourceRef),
   tools: z.array(ToolRef),
@@ -1748,6 +2045,12 @@ export const SessionTurn = z.object({
   // Per-turn OS override. NULL = inherit the session's sandboxOs.
   sandboxOs: SandboxOs.nullable(),
   metadata: z.record(z.string(), z.unknown()),
+  version: z.number().int().positive(),
+  executionGeneration: z.number().int().nonnegative(),
+  activeAttemptId: z.string().uuid().nullable(),
+  lineage: z.record(z.string(), z.unknown()),
+  cancelledBy: z.string().nullable(),
+  cancelReason: z.string().nullable(),
   startedAt: z.string().nullable(),
   finishedAt: z.string().nullable(),
   createdAt: z.string(),
@@ -1755,68 +2058,316 @@ export const SessionTurn = z.object({
 });
 export type SessionTurn = z.infer<typeof SessionTurn>;
 
-export const UpdateSessionTurnRequest = z.object({
-  prompt: z.string().min(1).optional(),
-  resources: z.array(ResourceRef).optional(),
-  tools: z.array(ToolRef).optional(),
-  model: z.string().min(1).optional(),
-  reasoningEffort: ReasoningEffort.optional(),
-  sandboxBackend: SandboxBackend.optional(),
-  metadata: z.record(z.string(), z.unknown()).optional(),
+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(),
+  items: z.array(SessionTurn),
+});
+export type SessionQueueSnapshot = z.infer<typeof SessionQueueSnapshot>;
+
+export const CancelSessionQueueItemRequest = z.object({
+  expectedQueueVersion: z.number().int().nonnegative(),
+  expectedItemVersion: z.number().int().positive(),
+  reason: z.string().min(1).optional(),
 });
-export type UpdateSessionTurnRequest = z.infer<typeof UpdateSessionTurnRequest>;
+export type CancelSessionQueueItemRequest = z.infer<typeof CancelSessionQueueItemRequest>;
+
+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(),
+});
+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([]),
+});
+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()),
+});
+export type WorkspaceInferenceControlResponse = z.infer<typeof WorkspaceInferenceControlResponse>;
+
+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",
+]);
+export type SessionSystemUpdateKind = z.infer<typeof SessionSystemUpdateKind>;
 
-export const ReorderSessionTurnsRequest = z.object({
-  turnIds: z.array(z.string().uuid()).min(1),
+export const SessionSystemUpdateState = z.enum([
+  "pending",
+  "deferred",
+  "delivered",
+  "cancelled",
+  "failed",
+]);
+export type SessionSystemUpdateState = z.infer<typeof SessionSystemUpdateState>;
+
+export const SessionSystemUpdate = z.object({
+  id: z.string().uuid(),
+  sessionId: z.string().uuid(),
+  kind: SessionSystemUpdateKind,
+  classification: SystemUpdateClassification,
+  sourceId: z.string(),
+  dedupeKey: z.string(),
+  summary: z.string(),
+  payload: z.record(z.string(), z.unknown()),
+  lineage: z.record(z.string(), z.unknown()),
+  state: SessionSystemUpdateState,
+  deliveredTurnId: z.string().uuid().nullable(),
+  deliveredAt: z.string().nullable(),
+  createdAt: z.string(),
 });
-export type ReorderSessionTurnsRequest = z.infer<typeof ReorderSessionTurnsRequest>;
+export type SessionSystemUpdate = z.infer<typeof SessionSystemUpdate>;
+
+export const VariableSetVariableName = z
+  .string()
+  .regex(/^[A-Z][A-Z0-9_]*$/)
+  .max(128);
+export type VariableSetVariableName = z.infer<typeof VariableSetVariableName>;
 
-export const WorkspaceEnvironmentVariableName = z.string().regex(/^[A-Z][A-Z0-9_]*$/).max(128);
-export type WorkspaceEnvironmentVariableName = z.infer<typeof WorkspaceEnvironmentVariableName>;
+function withVariableSetIdAlias<T extends z.ZodRawShape>(shape: T) {
+  return z.preprocess((input) => {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      return input;
+    }
+    const record = input as Record<string, unknown>;
+    if (record.variableSetId !== undefined || record.environmentId === undefined) {
+      return record;
+    }
+    return { ...record, variableSetId: record.environmentId };
+  }, z.object(shape));
+}
 
 // Metadata only by design: no schema in this file ever carries a variable value
 // back to a client. Values are write-only and decrypted exclusively inside the
 // worker at sandbox materialization time.
-export const WorkspaceEnvironmentVariableMetadata = z.object({
-  name: WorkspaceEnvironmentVariableName,
+export const VariableSetVariableMetadata = z.object({
+  name: VariableSetVariableName,
   version: z.number().int().positive(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
-export type WorkspaceEnvironmentVariableMetadata = z.infer<typeof WorkspaceEnvironmentVariableMetadata>;
+export type VariableSetVariableMetadata = z.infer<typeof VariableSetVariableMetadata>;
+/** @deprecated use VariableSetVariableMetadata */
+export const WorkspaceEnvironmentVariableMetadata = VariableSetVariableMetadata;
+/** @deprecated use VariableSetVariableMetadata */
+export type WorkspaceEnvironmentVariableMetadata = VariableSetVariableMetadata;
 
-export const WorkspaceEnvironment = z.object({
+export const VariableSet = z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
   workspaceId: z.string().uuid(),
   name: z.string(),
   description: z.string().nullable(),
-  variables: z.array(WorkspaceEnvironmentVariableMetadata),
+  variables: z.array(VariableSetVariableMetadata),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
-export type WorkspaceEnvironment = z.infer<typeof WorkspaceEnvironment>;
+export type VariableSet = z.infer<typeof VariableSet>;
+/** @deprecated use VariableSet */
+export const WorkspaceEnvironment = VariableSet;
+/** @deprecated use VariableSet */
+export type WorkspaceEnvironment = VariableSet;
 
-export const CreateWorkspaceEnvironmentRequest = z.object({
+export const CreateVariableSetRequest = z.object({
   name: z.string().min(1).max(120),
   description: z.string().max(2000).optional(),
-  variables: z.array(z.object({
-    name: WorkspaceEnvironmentVariableName,
-    value: z.string().min(1).max(32768),
-  })).default([]),
+  variables: z
+    .array(
+      z.object({
+        name: VariableSetVariableName,
+        value: z.string().min(1).max(32768),
+      }),
+    )
+    .default([]),
+});
+export type CreateVariableSetRequest = z.infer<typeof CreateVariableSetRequest>;
+/** @deprecated use CreateVariableSetRequest */
+export const CreateWorkspaceEnvironmentRequest = CreateVariableSetRequest;
+/** @deprecated use CreateVariableSetRequest */
+export type CreateWorkspaceEnvironmentRequest = CreateVariableSetRequest;
+
+export const UpdateVariableSetRequest = z.object({
+  name: z.string().min(1).max(120).optional(),
+  description: z.string().max(2000).nullable().optional(),
+});
+export type UpdateVariableSetRequest = z.infer<typeof UpdateVariableSetRequest>;
+/** @deprecated use UpdateVariableSetRequest */
+export const UpdateWorkspaceEnvironmentRequest = UpdateVariableSetRequest;
+/** @deprecated use UpdateVariableSetRequest */
+export type UpdateWorkspaceEnvironmentRequest = UpdateVariableSetRequest;
+
+export const SetVariableSetVariableRequest = z.object({
+  value: z.string().min(1).max(32768),
 });
-export type CreateWorkspaceEnvironmentRequest = z.infer<typeof CreateWorkspaceEnvironmentRequest>;
+export type SetVariableSetVariableRequest = z.infer<typeof SetVariableSetVariableRequest>;
+/** @deprecated use SetVariableSetVariableRequest */
+export const SetWorkspaceEnvironmentVariableRequest = SetVariableSetVariableRequest;
+/** @deprecated use SetVariableSetVariableRequest */
+export type SetWorkspaceEnvironmentVariableRequest = SetVariableSetVariableRequest;
 
-export const UpdateWorkspaceEnvironmentRequest = z.object({
+// --- Rigs ---------------------------------------------------------------------
+// Workspace-scoped, versioned sandbox machine definitions. A rig is the named
+// truth; each sandbox is a disposable fork of a rig version. Versions are
+// append-only and content-immutable; exactly one is active per rig.
+
+// A self-declared health check: a name + the shell command that must exit 0.
+export const RigCheck = z.object({
+  name: z.string().min(1).max(120),
+  command: z.string().min(1).max(8192),
+});
+export type RigCheck = z.infer<typeof RigCheck>;
+
+export const RigVersion = z.object({
+  id: z.string().uuid(),
+  rigId: z.string().uuid(),
+  version: z.number().int().positive(),
+  image: z.string().nullable(),
+  setupScript: z.string().nullable(),
+  checks: z.array(RigCheck),
+  credentialHooks: z.array(z.string()),
+  defaultVariableSetIds: z.array(z.string().uuid()),
+  changelog: z.string().nullable(),
+  // Attribution: 'user:<subject>' | 'session:<id>' | 'system'.
+  createdBy: z.string().nullable(),
+  active: z.boolean(),
+  createdAt: z.string(),
+});
+export type RigVersion = z.infer<typeof RigVersion>;
+
+export const RigVerificationHealth = z.object({
+  checkHealth: z.enum(["passing", "failing", "unknown"]),
+  lastVerifiedAt: z.string().nullable(),
+});
+export type RigVerificationHealth = z.infer<typeof RigVerificationHealth>;
+
+export const Rig = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  name: z.string(),
+  description: z.string().nullable(),
+  createdBy: z.string().nullable(),
+  // The rig's currently-active version (present after create; nullable so a
+  // partial/list read can omit it without a schema change).
+  activeVersion: RigVersion.nullable(),
+  // Summary for the currently active version. null only when there is no active
+  // version; otherwise "unknown" means the active version has no verification.
+  activeVersionHealth: RigVerificationHealth.nullable(),
+  versionCount: z.number().int().nonnegative(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type Rig = z.infer<typeof Rig>;
+
+export const RigChangeKind = z.enum(["setup_append", "definition_edit"]);
+export type RigChangeKind = z.infer<typeof RigChangeKind>;
+
+export const RigChangeStatus = z.enum(["proposed", "verifying", "merged", "rejected", "failed"]);
+export type RigChangeStatus = z.infer<typeof RigChangeStatus>;
+
+// A single check's outcome inside a verification run (populated in M4).
+export const RigCheckResult = z.object({
+  name: z.string(),
+  command: z.string(),
+  exitCode: z.number().int().nullable(),
+  output: z.string().optional(),
+});
+export type RigCheckResult = z.infer<typeof RigCheckResult>;
+
+// The verification record a rig-CI run writes onto a change (M4). Open-ended
+// (passthrough) so M4 can enrich it without a contracts break.
+export const RigChangeVerification = z
+  .object({
+    startedAt: z.string().optional(),
+    finishedAt: z.string().optional(),
+    log: z.string().optional(),
+    checkResults: z.array(RigCheckResult).optional(),
+  })
+  .passthrough();
+export type RigChangeVerification = z.infer<typeof RigChangeVerification>;
+
+export const RigChange = z.object({
+  id: z.string().uuid(),
+  rigId: z.string().uuid(),
+  baseVersionId: z.string().uuid().nullable(),
+  kind: RigChangeKind,
+  payload: z.record(z.string(), z.unknown()),
+  status: RigChangeStatus,
+  proposedBy: z.string().nullable(),
+  verification: RigChangeVerification.nullable(),
+  resultVersionId: z.string().uuid().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type RigChange = z.infer<typeof RigChange>;
+
+export const CreateRigRequest = z.object({
+  name: z.string().min(1).max(120),
+  description: z.string().max(2000).optional(),
+  // Initial (version 1) content, inline.
+  image: z.string().max(1024).optional(),
+  setupScript: z.string().max(131072).optional(),
+  checks: z.array(RigCheck).max(100).default([]),
+  credentialHooks: z.array(z.string().min(1).max(200)).max(50).default([]),
+  defaultVariableSetIds: z.array(z.string().uuid()).max(25).default([]),
+});
+export type CreateRigRequest = z.infer<typeof CreateRigRequest>;
+
+export const UpdateRigRequest = z.object({
   name: z.string().min(1).max(120).optional(),
   description: z.string().max(2000).nullable().optional(),
 });
-export type UpdateWorkspaceEnvironmentRequest = z.infer<typeof UpdateWorkspaceEnvironmentRequest>;
+export type UpdateRigRequest = z.infer<typeof UpdateRigRequest>;
 
-export const SetWorkspaceEnvironmentVariableRequest = z.object({
-  value: z.string().min(1).max(32768),
+// setup_append: the exact command that already worked (+ an optional note).
+export const RigSetupAppendPayload = z.object({
+  command: z.string().min(1).max(8192),
+  note: z.string().max(2000).optional(),
 });
-export type SetWorkspaceEnvironmentVariableRequest = z.infer<typeof SetWorkspaceEnvironmentVariableRequest>;
+export type RigSetupAppendPayload = z.infer<typeof RigSetupAppendPayload>;
+
+// definition_edit: the full next-version content (all fields optional; unset
+// fields inherit from the base version at promote time).
+export const RigDefinitionEditPayload = z.object({
+  image: z.string().max(1024).nullish(),
+  setupScript: z.string().max(131072).nullish(),
+  checks: z.array(RigCheck).max(100).optional(),
+  credentialHooks: z.array(z.string().min(1).max(200)).max(50).optional(),
+  defaultVariableSetIds: z.array(z.string().uuid()).max(25).optional(),
+  changelog: z.string().max(4096).nullish(),
+});
+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 }),
+]);
+export type ProposeRigChangeRequest = z.infer<typeof ProposeRigChangeRequest>;
 
 export const ScheduledTaskStatus = z.enum(["active", "paused"]);
 export type ScheduledTaskStatus = z.infer<typeof ScheduledTaskStatus>;
@@ -1850,7 +2401,10 @@ export const ScheduledTaskScheduleSpec = z.discriminatedUnion("type", [
     timeZone: z.string().min(1).default("UTC"),
     hour: z.number().int().min(0).max(23),
     minute: z.number().int().min(0).max(59),
-    daysOfWeek: z.array(z.enum(["SUNDAY", "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY"])).min(1).optional(),
+    daysOfWeek: z
+      .array(z.enum(["SUNDAY", "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY"]))
+      .min(1)
+      .optional(),
   }),
 ]);
 export type ScheduledTaskScheduleSpec = z.infer<typeof ScheduledTaskScheduleSpec>;
@@ -1879,7 +2433,13 @@ export const ScheduledTask = z.object({
   overlapPolicy: ScheduledTaskOverlapPolicy,
   agentConfig: ScheduledTaskAgentConfig,
   reusableSessionId: z.string().uuid().nullable(),
-  environmentId: z.string().uuid().nullable(),
+  variableSetId: z.string().uuid().nullable().default(null),
+  /** @deprecated use variableSetId */
+  environmentId: z.string().uuid().nullable().default(null),
+  // The rig each run binds to (M3). Stored on the task; the ACTIVE version is
+  // resolved PER FIRE (at dispatch), so a task always runs the rig's current
+  // version rather than one frozen at task-create time. Null ⇒ rig-less runs.
+  rigId: z.string().uuid().nullable().default(null),
   metadata: z.record(z.string(), z.unknown()),
   createdAt: z.string(),
   updatedAt: z.string(),
@@ -1903,26 +2463,33 @@ export const ScheduledTaskRun = z.object({
 });
 export type ScheduledTaskRun = z.infer<typeof ScheduledTaskRun>;
 
-export const CreateScheduledTaskRequest = z.object({
+export const CreateScheduledTaskRequest = withVariableSetIdAlias({
   name: z.string().min(1),
   schedule: ScheduledTaskScheduleSpec,
   runMode: ScheduledTaskRunMode.default("new_session_per_run"),
   overlapPolicy: ScheduledTaskOverlapPolicy.default("allow_concurrent"),
   agentConfig: ScheduledTaskAgentConfig,
   status: ScheduledTaskStatus.default("active"),
+  variableSetId: z.string().uuid().nullable().optional(),
   environmentId: z.string().uuid().nullable().optional(),
+  // The rig each run binds to (M3); its active version is resolved per fire.
+  rigId: z.string().uuid().nullable().optional(),
   metadata: z.record(z.string(), z.unknown()).default({}),
 });
 export type CreateScheduledTaskRequest = z.infer<typeof CreateScheduledTaskRequest>;
 
-export const UpdateScheduledTaskRequest = z.object({
+export const UpdateScheduledTaskRequest = withVariableSetIdAlias({
   name: z.string().min(1).optional(),
   schedule: ScheduledTaskScheduleSpec.optional(),
   runMode: ScheduledTaskRunMode.optional(),
   overlapPolicy: ScheduledTaskOverlapPolicy.optional(),
   agentConfig: ScheduledTaskAgentConfig.optional(),
   status: ScheduledTaskStatus.optional(),
+  variableSetId: z.string().uuid().nullable().optional(),
   environmentId: z.string().uuid().nullable().optional(),
+  // The rig each run binds to (M3); null clears it. Its active version is
+  // resolved per fire, so an update takes effect on the next dispatch.
+  rigId: z.string().uuid().nullable().optional(),
   metadata: z.record(z.string(), z.unknown()).optional(),
 });
 export type UpdateScheduledTaskRequest = z.infer<typeof UpdateScheduledTaskRequest>;
@@ -1977,7 +2544,9 @@ export const CapabilityPackScheduledTaskTemplate = z.object({
   // instantiable templates; built-in packs may instead build prompts in code.
   prompt: z.string().min(1).optional(),
 });
-export type CapabilityPackScheduledTaskTemplate = z.infer<typeof CapabilityPackScheduledTaskTemplate>;
+export type CapabilityPackScheduledTaskTemplate = z.infer<
+  typeof CapabilityPackScheduledTaskTemplate
+>;
 
 // One file inside a pack skill directory. Paths are workspace-relative POSIX
 // paths inside the skill directory (for example "SKILL.md" or
@@ -1995,66 +2564,119 @@ export type CapabilityPackSkillFile = z.infer<typeof CapabilityPackSkillFile>;
 // A skill delivered by a capability pack. The name doubles as the skill
 // directory under the sandbox skill index (skills/<name>), so it must be a
 // single safe path segment. Every skill must ship a top-level SKILL.md.
-export const CapabilityPackSkill = z.object({
-  name: z.string().min(1).max(64).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, {
-    message: "skill name must be a single path segment of letters, digits, '.', '_' or '-'",
-  }),
-  description: z.string().min(1).max(2048).optional(),
-  files: z.array(CapabilityPackSkillFile).min(1).max(64),
-}).superRefine((skill, ctx) => {
-  const seen = new Set<string>();
-  skill.files.forEach((file, index) => {
-    if (seen.has(file.path)) {
-      ctx.addIssue({ code: "custom", message: `duplicate skill file path: ${file.path}`, path: ["files", index, "path"] });
+export const CapabilityPackSkill = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .max(64)
+      .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, {
+        message: "skill name must be a single path segment of letters, digits, '.', '_' or '-'",
+      }),
+    description: z.string().min(1).max(2048).optional(),
+    files: z.array(CapabilityPackSkillFile).min(1).max(64),
+  })
+  .superRefine((skill, ctx) => {
+    const seen = new Set<string>();
+    skill.files.forEach((file, index) => {
+      if (seen.has(file.path)) {
+        ctx.addIssue({
+          code: "custom",
+          message: `duplicate skill file path: ${file.path}`,
+          path: ["files", index, "path"],
+        });
+      }
+      seen.add(file.path);
+    });
+    if (!skill.files.some((file) => file.path === "SKILL.md")) {
+      ctx.addIssue({
+        code: "custom",
+        message: "skill must include a top-level SKILL.md file",
+        path: ["files"],
+      });
     }
-    seen.add(file.path);
   });
-  if (!skill.files.some((file) => file.path === "SKILL.md")) {
-    ctx.addIssue({ code: "custom", message: "skill must include a top-level SKILL.md file", path: ["files"] });
-  }
-});
 export type CapabilityPackSkill = z.infer<typeof CapabilityPackSkill>;
 
 function isSafePackSkillRelativePath(path: string): boolean {
   if (path.startsWith("/") || path.includes("\\")) {
     return false;
   }
-  return path.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+  return path
+    .split("/")
+    .every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
 }
 
-export const CapabilityPack = z.object({
-  id: z.string().min(1),
-  name: z.string().min(1),
+const CapabilityPackVariableSet = z.object({
   description: z.string().min(1),
-  role: z.string().min(1),
-  category: z.string().min(1),
-  version: z.string().min(1),
-  // Container image ref (digest-pinned recommended) the pack's sessions run
-  // in. At most one enabled pack per workspace may declare one; with none,
-  // sessions use the deployment-wide image settings.
-  sandboxImage: z.string().trim().min(1).max(512).optional(),
-  // Skills delivered into the sandbox skill index when the pack is enabled.
-  skills: z.array(CapabilityPackSkill).max(32).superRefine((skills, ctx) => {
-    const seen = new Set<string>();
-    skills.forEach((skill, index) => {
-      const key = skill.name.toLowerCase();
-      if (seen.has(key)) {
-        ctx.addIssue({ code: "custom", message: `duplicate pack skill name: ${skill.name}`, path: [index, "name"] });
-      }
-      seen.add(key);
-    });
-  }).default([]),
-  tools: z.array(ToolRef).default([]),
-  connectors: z.array(CapabilityPackConnector).default([]),
-  knowledge: z.array(CapabilityPackKnowledge).default([]),
-  scheduledTaskTemplates: z.array(CapabilityPackScheduledTaskTemplate).default([]),
-  environment: z.object({
-    description: z.string().min(1),
-    requiredVariables: z.array(WorkspaceEnvironmentVariableName).default([]),
-    required: z.boolean().default(false),
-  }).optional(),
-  metadata: z.record(z.string(), z.unknown()).default({}),
+  requiredVariables: z.array(VariableSetVariableName).default([]),
+  required: z.boolean().default(false),
 });
+
+export const CapabilityPack = z.preprocess(
+  (input) => {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      return input;
+    }
+    const record = input as Record<string, unknown>;
+    if (record.variableSet !== undefined) {
+      return record;
+    }
+    if (record.environment !== undefined) {
+      const { environment: _environment, ...rest } = record;
+      return { ...rest, variableSet: record.environment };
+    }
+    if (record.requiredVariables !== undefined) {
+      const { requiredVariables: _requiredVariables, ...rest } = record;
+      return {
+        ...rest,
+        variableSet: {
+          description: "Required variables",
+          requiredVariables: record.requiredVariables,
+          required: Array.isArray(record.requiredVariables) && record.requiredVariables.length > 0,
+        },
+      };
+    }
+    return record;
+  },
+  z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string().min(1),
+    role: z.string().min(1),
+    category: z.string().min(1),
+    version: z.string().min(1),
+    // Container image ref (digest-pinned recommended) the pack's sessions run
+    // in. At most one enabled pack per workspace may declare one; with none,
+    // sessions use the deployment-wide image settings.
+    sandboxImage: z.string().trim().min(1).max(512).optional(),
+    // Skills delivered into the sandbox skill index when the pack is enabled.
+    skills: z
+      .array(CapabilityPackSkill)
+      .max(32)
+      .superRefine((skills, ctx) => {
+        const seen = new Set<string>();
+        skills.forEach((skill, index) => {
+          const key = skill.name.toLowerCase();
+          if (seen.has(key)) {
+            ctx.addIssue({
+              code: "custom",
+              message: `duplicate pack skill name: ${skill.name}`,
+              path: [index, "name"],
+            });
+          }
+          seen.add(key);
+        });
+      })
+      .default([]),
+    tools: z.array(ToolRef).default([]),
+    connectors: z.array(CapabilityPackConnector).default([]),
+    knowledge: z.array(CapabilityPackKnowledge).default([]),
+    scheduledTaskTemplates: z.array(CapabilityPackScheduledTaskTemplate).default([]),
+    variableSet: CapabilityPackVariableSet.optional(),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+  }),
+);
 export type CapabilityPack = z.infer<typeof CapabilityPack>;
 
 // Registering a pack stores the manifest itself; the request body is a full
@@ -2086,7 +2708,8 @@ export const PackInstallation = z.object({
 });
 export type PackInstallation = z.infer<typeof PackInstallation>;
 
-export const EnablePackRequest = z.object({
+export const EnablePackRequest = withVariableSetIdAlias({
+  variableSetId: z.string().uuid().optional(),
   environmentId: z.string().uuid().optional(),
   metadata: z.record(z.string(), z.unknown()).default({}),
 });
@@ -2172,14 +2795,16 @@ 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 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>;
 
 export const ConnectionMetadata = z.object({
@@ -2240,17 +2865,28 @@ export const ListConnectionsResponse = z.object({
 });
 export type ListConnectionsResponse = z.infer<typeof ListConnectionsResponse>;
 
-export const OAuthStartRequest = z.object({
-  providerDomain: z.string().min(1).optional(),
-  mcpUrl: z.string().url().optional(),
-  resource: z.string().url().optional(),
-  requestedScopes: z.array(z.string().min(1)).default([]),
-  returnPath: z.string().min(1).optional(),
-  connectionId: z.string().uuid().optional(),
-}).refine((value) => Boolean(value.mcpUrl ?? value.resource), {
-  message: "mcpUrl is required",
-  path: ["mcpUrl"],
-});
+export const OAuthStartRequest = z
+  .object({
+    providerDomain: z.string().min(1).optional(),
+    mcpUrl: z.string().url().optional(),
+    resource: z.string().url().optional(),
+    requestedScopes: z.array(z.string().min(1)).default([]),
+    returnPath: z.string().min(1).optional(),
+    connectionId: z.string().uuid().optional(),
+    oauthClient: z
+      .object({
+        clientId: z.string().min(1),
+        clientSecret: z.string().min(1).optional(),
+        tokenEndpointAuthMethod: z
+          .enum(["none", "client_secret_post", "client_secret_basic"])
+          .optional(),
+      })
+      .optional(),
+  })
+  .refine((value) => Boolean(value.mcpUrl ?? value.resource), {
+    message: "mcpUrl is required",
+    path: ["mcpUrl"],
+  });
 export type OAuthStartRequest = z.infer<typeof OAuthStartRequest>;
 
 export const OAuthStartResponse = z.object({
@@ -2287,7 +2923,13 @@ export type MarketingDailyAnalysisTaskRequest = z.infer<typeof MarketingDailyAna
 export const CapabilityKind = z.enum(["pack", "mcp", "api", "skill", "plugin"]);
 export type CapabilityKind = z.infer<typeof CapabilityKind>;
 
-export const CapabilitySource = z.enum(["built_in", "configured", "public_registry", "registry", "manual"]);
+export const CapabilitySource = z.enum([
+  "built_in",
+  "configured",
+  "public_registry",
+  "registry",
+  "manual",
+]);
 export type CapabilitySource = z.infer<typeof CapabilitySource>;
 
 export const CapabilityInstallationStatus = z.enum(["active", "disabled"]);
@@ -2337,6 +2979,18 @@ export const CapabilityCatalogItem = z.object({
   runtime: CapabilityRuntime.default({ available: false, notes: null }),
   enabled: z.boolean().default(false),
   enabledReason: z.string().nullable().default(null),
+  // The connection backing this enabled installation, when the enable-time
+  // connectionRef resolved to one (null for header/credential-free items —
+  // that means "no connection involved", not "broken"). Lets the UI match
+  // connection health by id instead of guessing from providerDomain alone.
+  connectionRef: z
+    .object({
+      connectionId: z.string().min(1),
+      providerDomain: z.string().min(1),
+      kind: z.string().min(1),
+    })
+    .nullable()
+    .default(null),
   metadata: z.record(z.string(), z.unknown()).default({}),
   createdAt: z.string().optional(),
   updatedAt: z.string().optional(),
@@ -2373,23 +3027,24 @@ export const CreateCapabilityCatalogItemRequest = z.object({
 });
 export type CreateCapabilityCatalogItemRequest = z.infer<typeof CreateCapabilityCatalogItemRequest>;
 
-export const EnableCapabilityRequest = z.object({
+export const EnableCapabilityRequest = withVariableSetIdAlias({
   config: z.record(z.string(), z.unknown()).default({}),
   metadata: z.record(z.string(), z.unknown()).default({}),
   connectionRef: McpServerConnectionRef.optional(),
   /**
    * Credential headers for remote MCP capabilities (for example an
    * Authorization bearer token). Values are encrypted at rest with the
-   * workspace-environments key, injected only into the runtime MCP client,
+   * workspace-variable-sets key, injected only into the runtime MCP client,
    * and never returned by the API — responses expose header names only.
    */
   headers: z.record(z.string(), z.string()).default({}),
   /**
-   * Initial environment attachment for kind=pack capabilities. Mirrors the
+   * Initial variableSet attachment for kind=pack capabilities. Mirrors the
    * dedicated POST /packs/:id/enable body: required to enable an
-   * environment.required pack through the unified capability-enable path,
+   * variableSet.required pack through the unified capability-enable path,
    * optional otherwise. Ignored by non-pack capabilities.
    */
+  variableSetId: z.string().uuid().optional(),
   environmentId: z.string().uuid().optional(),
 });
 export type EnableCapabilityRequest = z.infer<typeof EnableCapabilityRequest>;
@@ -2437,7 +3092,16 @@ export const Session = z.object({
   // stale in-flight op and retry against the new active sandbox.
   activeSandboxId: z.string().uuid().nullable(),
   activeEpoch: z.number().int().nonnegative(),
-  environmentId: z.string().uuid().nullable(),
+  variableSetId: z.string().uuid().nullable().default(null),
+  /** @deprecated use variableSetId */
+  environmentId: z.string().uuid().nullable().default(null),
+  // The rig this session rides (M3 runtime binding). Both are resolved and
+  // FROZEN at session create: rigId names the rig, rigVersionId pins the exact
+  // active version the session's box/env/setup/doctrine are built from for the
+  // session's whole life (a later promote does NOT move an existing session).
+  // Both null ⇒ a rig-less session (byte-for-byte today's behavior).
+  rigId: z.string().uuid().nullable().default(null),
+  rigVersionId: z.string().uuid().nullable().default(null),
   // Non-default first-party MCP token permissions (manager-style sessions);
   // null means the fixed worker default set.
   firstPartyMcpPermissions: z.array(Permission).nullable(),
@@ -2456,9 +3120,18 @@ export const Session = z.object({
   temporalWorkflowId: z.string().nullable(),
   activeTurnId: z.string().uuid().nullable(),
   // Actual input tokens of the last model call of the most recent turn; the
-  // pre-turn client-side context-compaction trigger reads it as its budget
+  // pre-turn portable context-compaction trigger reads it as its budget
   // signal. Null until a turn with usage has completed.
   lastInputTokens: z.number().int().nonnegative().nullable(),
+  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(),
   lastSequence: z.number().int().nonnegative(),
   // Multi-account Codex (P1). codexPinnedCredentialId: the account this session is
   // manually PINNED to (null ⇒ follow the workspace active pointer).
@@ -2466,34 +3139,100 @@ export const Session = z.object({
   // "Running on:" indicator's source). Both are credential-row ids, null until set.
   codexPinnedCredentialId: z.string().uuid().nullable(),
   codexLastCredentialId: z.string().uuid().nullable(),
+  /** Personal (authenticated subject) workspace pin state, never workspace-global. */
+  pinned: z.boolean().default(false),
+  /** Stable pin ordering key; null when this subject has not pinned the session. */
+  pinnedAt: z.string().nullable().default(null),
+  /** Optimistic pin-state revision; zero represents an absent pin relation. */
+  pinVersion: z.number().int().nonnegative().default(0),
+  /**
+   * Server-authoritative hierarchy summary populated on session-list reads.
+   * Detail reads may omit it. The rail uses this instead of guessing a tree
+   * from whichever global recency page happened to be loaded.
+   */
+  treeStats: z
+    .object({
+      directChildren: z.number().int().nonnegative(),
+      totalDescendants: z.number().int().nonnegative(),
+      runningDescendants: z.number().int().nonnegative(),
+      queuedDescendants: z.number().int().nonnegative(),
+      attentionDescendants: z.number().int().nonnegative(),
+      pausedDescendants: z.number().int().nonnegative(),
+      failedDescendants: z.number().int().nonnegative(),
+    })
+    .optional(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
 export type Session = z.infer<typeof Session>;
 
+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.
+ */
+export const SessionListResponse = z.object({
+  pinned: z.array(Session),
+  sessions: z.array(Session),
+  nextCursor: z.string().nullable(),
+});
+export type SessionListResponse = z.infer<typeof SessionListResponse>;
+
+// Recursive: the TS type is declared first so the schema annotation can carry
+// the FULL recursive shape (a shallow annotation loses type information for
+// contracts consumers after one level of nesting).
+export type LineageNode = {
+  session: SessionSummary;
+  children: LineageNode[];
+};
+export const LineageNode: z.ZodType<LineageNode> = z.lazy(() =>
+  z.object({
+    session: Session,
+    children: z.array(LineageNode),
+  }),
+);
+
+export const SessionLineageResponse = z.object({
+  ancestors: z.array(Session),
+  children: z.array(LineageNode),
+  truncated: z.boolean().default(false),
+});
+export type SessionLineageResponse = z.infer<typeof SessionLineageResponse>;
+
 export const SessionEventType = z.enum([
   "session.created",
   "session.status.changed",
   "session.requiresAction",
+  "session.context.compaction.requested",
   "session.context.compacted",
+  "session.context.compaction.skipped",
   "session.context.cleared",
   "user.message",
-  "user.interrupt",
+  "user.pause",
   "user.approvalDecision",
   "turn.queued",
-  "turn.updated",
   "turn.started",
   "turn.completed",
   "turn.failed",
   "turn.cancelled",
-  "turn.preempted",
+  "turn.superseded",
+  "turn.recovery.requested",
+  "turn.capacity_waiting",
   "agent.message.delta",
   "agent.message.completed",
   "agent.reasoning.delta",
   "agent.toolCall.created",
   "agent.toolCall.output",
+  "agent.model.usage",
   "tool.auth_needed",
   "agent.updated",
+  "rig.setup.started",
+  "rig.setup.completed",
+  "rig.setup.skipped",
+  "rig.setup.failed",
   "sandbox.operation.started",
   "sandbox.operation.completed",
   "sandbox.operation.failed",
@@ -2504,7 +3243,22 @@ export const SessionEventType = z.enum([
   "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.prompt.cancelled",
+  "session.queue.history",
+  // A terminal/stale activity callback is retained as an audit wrapper rather
+  // than being dropped or emitted as though it belonged to the current turn.
+  "turn.event.rejected_late",
+  "memory.saved",
+  "memory.corrected",
   // Channel-B desktop pixel-plane signals (07-channel-b §1.2). The pixel socket
   // carries opaque RFB and cannot carry a control message the client can act on,
   // so these ride the durable, sequenced, gap-filled Channel-A SSE spine.
@@ -2537,6 +3291,78 @@ 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
+  // id, bounded strategy/reason, and pool counts — never token material.
+  "codex.credential.selected",
+  // OPE-21 durable zero-capacity wait lifecycle. Runtime/system events only;
+  // no synthetic user message is created when capacity returns.
+  "codex.capacity.waiting",
+  "codex.capacity.resumed",
+  "codex.capacity.superseded",
+  // Sandbox durability observability (sandbox-file-persistence). The 2026-07
+  // incidents (mid-session box death with /workspace loss; a fatal manifest-env
+  // delta on a live box) were near-unattributable because box lifecycle left no
+  // durable trace — only worker logs, which rotate within hours. These events
+  // make every box transition and env recomputation drift readable from the DB
+  // alone. Payloads carry ids/flags/key NAMES only — never env values (secrets).
+  "sandbox.box.created", // box cold-created/cold-restored ({hydrated: "archive"|"none"})
+  "sandbox.box.lost", // resume-by-id found the box gone (provider NotFound)
+  "sandbox.box.terminated", // reaper drain terminated the box ({actor, persisted})
+  "sandbox.box.snapshot", // mid-session /workspace snapshot persisted ({trigger})
+  "sandbox.env.drift", // recomputed manifest env != live box env (key names only)
+  // Active-sandbox pointer reconcile (issue #341 invariant B). Turn start found the
+  // persisted (active_sandbox_id, active_epoch) pointing at a target the turn cannot
+  // establish — a deleted/absent sandbox, a Modal sibling with no establisher, or a
+  // selfhosted sandbox with no enrollment — and reset it to the session HOME under
+  // the epoch fence instead of routing every op into the dead target. A VISIBLE,
+  // never-silent downgrade: payload carries the typed reason + from/to epoch, never a
+  // 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
+  // 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).
+  "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
+  // the live box rather than trust a zero-repository snapshot.
+  "workspace.revision.degraded",
+  // Connected Machine (selfhosted) op-outcome observability (failure-visibility
+  // doctrine, out-of-band plane). SESSION-scoped facts only: these fire for the
+  // session whose turn ran the op (the two-planes rule — machine-plane facts like
+  // pressure live in the M10 metrics DB, never as session events). Payloads carry
+  // the op kind + a typed fault class + attempt count — NEVER command content.
+  //
+  // `machine.op.failed` fires ONLY for INFRASTRUCTURE fault classes (offline,
+  // draining-exhausted, payload-too-large, reconnecting-timeout, OS/stream/protocol)
+  // — a semantic miss the model asked about (a missing path, a consent gate, a
+  // nonzero exit) is an OUTCOME, not an infra fault, and never fires this.
+  // `machine.op.recovered` is the healed-fault leading indicator (a blip/backpressure
+  // the transport absorbed): announce-only, quiet. Both hit the timeline projection's
+  // quiet status-tick tier (the severity split's "degraded"); adding a rendered item
+  // requires regenerating the golden snapshots (the golden-grammar gate).
+  "machine.op.failed",
+  "machine.op.recovered",
+  // Connected Machine (selfhosted) LINK-plane observability (failure-visibility
+  // doctrine). SESSION-scoped, ANNOUNCE-ONLY facts fanned out to the sessions that
+  // had an active op running on the machine when its control link changed — never
+  // to idle/historical sessions. Payloads carry ids / a typed reason / key-names
+  // only, NEVER command content.
+  //
+  // `machine.link.lost` — the machine announced a clean GoingOffline (its control
+  // link is going away) while a session had a running turn on it. `machine.link.
+  // restored` — a reconnect Hello re-established the link that was previously lost.
+  // `machine.runner.restarted` — the additional signal that the going-offline was
+  // a self-update restart specifically (link.lost also fires for it; this
+  // distinguishes a restart from a plain stop / host shutdown). All three hit the
+  // timeline projection's quiet default tier (no rendered item); adding a rendered
+  // item requires regenerating the golden snapshots (the golden-grammar gate).
+  "machine.link.lost",
+  "machine.link.restored",
+  "machine.runner.restarted",
 ]);
 export type SessionEventType = z.infer<typeof SessionEventType>;
 
@@ -2676,13 +3502,17 @@ export type SandboxCommandOutputDeltaPayload = z.infer<typeof SandboxCommandOutp
 export const FsChangeKind = z.enum(["created", "modified", "deleted", "renamed"]);
 export type FsChangeKind = z.infer<typeof FsChangeKind>;
 export const FsChangedPayload = z.object({
-  changes: z.array(z.object({
-    path: z.string(), // workspace-relative POSIX path
-    kind: FsChangeKind,
-    isDir: z.boolean().default(false),
-    sizeBytes: z.number().int().nonnegative().nullable().default(null),
-    oldPath: z.string().optional(), // for "renamed"
-  })).min(1),
+  changes: z
+    .array(
+      z.object({
+        path: z.string(), // workspace-relative POSIX path
+        kind: FsChangeKind,
+        isDir: z.boolean().default(false),
+        sizeBytes: z.number().int().nonnegative().nullable().default(null),
+        oldPath: z.string().optional(), // for "renamed"
+      }),
+    )
+    .min(1),
   source: z.enum(["write", "watch", "agent"]).default("write"),
   // Monotonic FS revision (per-lease, paired with leaseEpoch for staleness).
   revision: z.number().int().nonnegative(),
@@ -2699,7 +3529,9 @@ export const GitChangedPayload = z.object({
   ahead: z.number().int().nonnegative().default(0),
   behind: z.number().int().nonnegative().default(0),
   changedFileCount: z.number().int().nonnegative(),
-  reason: z.enum(["commit", "checkout", "stage", "worktree", "fetch", "unknown"]).default("unknown"),
+  reason: z
+    .enum(["commit", "checkout", "stage", "worktree", "fetch", "unknown"])
+    .default("unknown"),
   revision: z.number().int().nonnegative().default(0),
   leaseEpoch: z.number().int().nonnegative().default(0),
 });
@@ -2744,16 +3576,18 @@ export interface FsTreeNode {
   children?: FsTreeNode[] | undefined;
   truncated: boolean; // dir had more entries than the cap
 }
-export const FsTreeNode: z.ZodType<FsTreeNode> = z.lazy(() => z.object({
-  name: z.string(),
-  path: z.string(),
-  type: FsNodeType,
-  sizeBytes: z.number().int().nonnegative().nullable(),
-  mtimeMs: z.number().int().nonnegative().nullable(),
-  mode: z.number().int().nullable(),
-  children: z.array(FsTreeNode).optional(),
-  truncated: z.boolean().default(false),
-})) as z.ZodType<FsTreeNode>;
+export const FsTreeNode: z.ZodType<FsTreeNode> = z.lazy(() =>
+  z.object({
+    name: z.string(),
+    path: z.string(),
+    type: FsNodeType,
+    sizeBytes: z.number().int().nonnegative().nullable(),
+    mtimeMs: z.number().int().nonnegative().nullable(),
+    mode: z.number().int().nullable(),
+    children: z.array(FsTreeNode).optional(),
+    truncated: z.boolean().default(false),
+  }),
+) as z.ZodType<FsTreeNode>;
 
 export const FsListRequest = z.object({
   path: z.string().default(""), // "" = workspace root
@@ -2774,7 +3608,12 @@ export type FsEncoding = z.infer<typeof FsEncoding>;
 export const FsReadRequest = z.object({
   path: z.string(),
   encoding: FsEncoding.default("utf8"),
-  maxBytes: z.number().int().positive().max(25 * 1024 * 1024).default(5 * 1024 * 1024),
+  maxBytes: z
+    .number()
+    .int()
+    .positive()
+    .max(25 * 1024 * 1024)
+    .default(5 * 1024 * 1024),
 });
 export type FsReadRequest = z.infer<typeof FsReadRequest>;
 export const FsReadResponse = z.object({
@@ -2838,7 +3677,15 @@ export type FsMkdirResponse = z.infer<typeof FsMkdirResponse>;
 
 // --- A2 Git request/response (read-only; feeds Pierre diff/tree) -------------
 export const GitFileStatusCode = z.enum([
-  "added", "modified", "deleted", "renamed", "copied", "untracked", "ignored", "conflicted", "typechange",
+  "added",
+  "modified",
+  "deleted",
+  "renamed",
+  "copied",
+  "untracked",
+  "ignored",
+  "conflicted",
+  "typechange",
 ]);
 export type GitFileStatusCode = z.infer<typeof GitFileStatusCode>;
 export const GitFileStatus = z.object({
@@ -2905,7 +3752,12 @@ export const GitDiffRequest = z.object({
   toRef: z.string().optional(),
   pathspec: z.array(z.string()).default([]),
   contextLines: z.number().int().min(0).max(10).default(3),
-  maxBytesPerFile: z.number().int().positive().max(2 * 1024 * 1024).default(512 * 1024),
+  maxBytesPerFile: z
+    .number()
+    .int()
+    .positive()
+    .max(2 * 1024 * 1024)
+    .default(512 * 1024),
 });
 export type GitDiffRequest = z.infer<typeof GitDiffRequest>;
 export const GitDiffResponse = z.object({
@@ -2914,6 +3766,182 @@ export const GitDiffResponse = z.object({
 });
 export type GitDiffResponse = z.infer<typeof GitDiffResponse>;
 
+// ─── Workbench v2 turn-end workspace capture (dossier §10.1/§10.2) ────────────
+// 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
+// lets the workbench paint instantly with zero machine round-trips. Live always
+// wins when the box is warm; a capture is a labelled cache, never a replacement.
+// This is the shape the M1 worker writes and the M2 API serves inline.
+
+// One touched file in the capture. `contentRef` is the content-addressed storage
+// key of its after-image blob (shared across revisions → the GC set-difference
+// key). Deleted / binary / >5MB (tooLarge) files carry no contentRef; the UI
+// renders "too large — open live" for tooLarge, and the diff hunks for the rest.
+export const WorkspaceCaptureFile = z.object({
+  path: z.string(),
+  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
+  // §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 /
+  // tooLarge / binary (no inline content captured).
+  contentRef: z.string().nullable(),
+  sizeBytes: z.number().int().nonnegative(),
+  isBinary: z.boolean().default(false),
+  // >5MB per-file content guard tripped: content NOT captured, render "open live".
+  tooLarge: z.boolean().default(false),
+  deleted: z.boolean().default(false),
+});
+export type WorkspaceCaptureFile = z.infer<typeof WorkspaceCaptureFile>;
+
+// One repo discovered in the workspace. `diff` is `git diff HEAD` (combined
+// staged+unstaged tracked changes vs HEAD — the review diff); `status` is the
+// full porcelain file list (drives the rail glyphs incl. untracked, which the
+// HEAD diff omits). root "" = the workspace root repo.
+export const WorkspaceCaptureRepo = z.object({
+  root: z.string(),
+  head: z.string().nullable(),
+  detached: z.boolean().default(false),
+  upstream: z.string().nullable(),
+  ahead: z.number().int().nonnegative().default(0),
+  behind: z.number().int().nonnegative().default(0),
+  status: z.array(GitFileStatus),
+  diff: z.array(GitFileDiff),
+});
+export type WorkspaceCaptureRepo = z.infer<typeof WorkspaceCaptureRepo>;
+
+export const WorkspaceCaptureDegradedReason = z.enum([
+  "repository_discovery_command_failed",
+  "repository_discovery_timed_out",
+  "repository_discovery_result_limit_exceeded",
+]);
+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.
+export const WorkspaceCaptureStats = z.object({
+  repoCount: z.number().int().nonnegative(),
+  fileCount: z.number().int().nonnegative(),
+  additions: z.number().int().nonnegative(),
+  deletions: z.number().int().nonnegative(),
+  totalBytes: z.number().int().nonnegative(),
+  tooLargeCount: z.number().int().nonnegative(),
+  binaryCount: z.number().int().nonnegative(),
+  treeEntryCount: z.number().int().nonnegative(),
+  treeTruncated: z.boolean().default(false),
+  durationMs: z.number().int().nonnegative(),
+  // sha256 over the change surface (per-file path/hash/status + per-repo diff
+  // summary, tree/mtime excluded). The empty-turn gate skips a capture whose
+  // fingerprint equals the previous revision's — "no new revision when nothing
+  // changed" holds even when the tree stays dirty across read-only turns.
+  fingerprint: z.string().optional(),
+});
+export type WorkspaceCaptureStats = z.infer<typeof WorkspaceCaptureStats>;
+
+// The single manifest blob (one per revision). Holds everything the workbench
+// needs for a cold paint: the tree index, per-repo status+diff, and the file
+// index (after-image refs). The M2 API serves this inline when small (≤2MB).
+export const WorkspaceCaptureManifest = z.object({
+  version: z.literal(1),
+  revision: z.number().int().nonnegative(),
+  capturedAt: z.string(),
+  turnId: z.string().nullable(),
+  leaseEpoch: z.number().int().nonnegative(),
+  treeIndex: FsTreeNode,
+  treeTruncated: z.boolean().default(false),
+  repos: z.array(WorkspaceCaptureRepo),
+  files: z.array(WorkspaceCaptureFile),
+  stats: WorkspaceCaptureStats,
+});
+export type WorkspaceCaptureManifest = z.infer<typeof WorkspaceCaptureManifest>;
+
+// Announce-only event payload (dossier §10.1). Metadata only — never content.
+export const WorkspaceRevisionCapturedPayload = z.object({
+  revision: z.number().int().nonnegative(),
+  turnId: z.string().nullable(),
+  capturedAt: z.string(),
+  leaseEpoch: z.number().int().nonnegative(),
+  stats: WorkspaceCaptureStats,
+});
+export type WorkspaceRevisionCapturedPayload = z.infer<typeof WorkspaceRevisionCapturedPayload>;
+
+export const WorkspaceRevisionDegradedPayload = z.object({
+  revision: z.number().int().nonnegative(),
+  turnId: z.string().nullable(),
+  capturedAt: z.string(),
+  leaseEpoch: z.number().int().nonnegative(),
+  reason: WorkspaceCaptureDegradedReason,
+});
+export type WorkspaceRevisionDegradedPayload = z.infer<typeof WorkspaceRevisionDegradedPayload>;
+
+// --- M2 capture READ API (dossier §10.3) -------------------------------------
+// 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.
+export const WorkspaceCaptureSignedUrl = z.object({
+  url: z.string().url(),
+  expiresAt: z.string(),
+});
+export type WorkspaceCaptureSignedUrl = z.infer<typeof WorkspaceCaptureSignedUrl>;
+
+// GET …/sessions/:sid/workspace/capture. `{available:false}` when no capture row
+// exists yet (or its manifest blob was GC'd) — the client falls back to the
+// live/wake path (status-quo behavior, NEVER an error → served 200). When
+// available: the row metadata (revision/turn/epoch/stats/size) is always inline;
+// the manifest is inline (`manifest`) for the ≤2MB common case and a signed GET
+// URL (`manifestUrl`) above that. Exactly one of manifest/manifestUrl is non-null.
+export const GetWorkspaceCaptureResponse = z.discriminatedUnion("available", [
+  z.object({
+    available: z.literal(false),
+    // Optional for additive compatibility with older servers. New servers set
+    // these fields when the newest durable revision is an explicit degraded
+    // marker rather than "no capture exists yet".
+    degradedReason: WorkspaceCaptureDegradedReason.nullable().optional(),
+    revision: z.number().int().nonnegative().nullable().optional(),
+    capturedAt: z.string().nullable().optional(),
+    turnId: z.string().nullable().optional(),
+    leaseEpoch: z.number().int().nonnegative().nullable().optional(),
+  }),
+  z.object({
+    available: z.literal(true),
+    revision: z.number().int().nonnegative(),
+    capturedAt: z.string(),
+    turnId: z.string().nullable(),
+    leaseEpoch: z.number().int().nonnegative(),
+    sizeBytes: z.number().int().nonnegative(),
+    stats: WorkspaceCaptureStats,
+    manifest: WorkspaceCaptureManifest.nullable().default(null),
+    manifestUrl: WorkspaceCaptureSignedUrl.nullable().default(null),
+  }),
+]);
+export type GetWorkspaceCaptureResponse = z.infer<typeof GetWorkspaceCaptureResponse>;
+
+// GET …/sessions/:sid/workspace/capture/file?path=…&revision=…. A single
+// after-image resolved from the (revision|latest) manifest. The file metadata
+// (from the manifest entry) is always present; `content` is inline for ≤256KB
+// (base64 for binary, utf8 otherwise), else a signed GET URL (`contentUrl`) to
+// the raw content-addressed blob. A tooLarge marker (or a captured file with no
+// content blob — e.g. the after-image was GC'd) returns metadata only, no
+// content and no URL. Path-not-in-manifest / deleted → 404 at the route (not
+// represented here).
+export const GetWorkspaceCaptureFileResponse = z.object({
+  path: z.string(),
+  revision: z.number().int().nonnegative(),
+  status: GitFileStatusCode,
+  hash: z.string().nullable(),
+  baseHash: z.string().nullable(),
+  sizeBytes: z.number().int().nonnegative(),
+  isBinary: z.boolean(),
+  tooLarge: z.boolean(),
+  encoding: FsEncoding.nullable().default(null), // set iff content is inline
+  content: z.string().nullable().default(null), // inline ≤256KB (per encoding)
+  contentUrl: WorkspaceCaptureSignedUrl.nullable().default(null), // signed >256KB
+});
+export type GetWorkspaceCaptureFileResponse = z.infer<typeof GetWorkspaceCaptureFileResponse>;
+
 export const GitLogRequest = z.object({
   path: z.string().default(""),
   ref: z.string().default("HEAD"),
@@ -2941,13 +3969,25 @@ export const GitShowRequest = z.object({
   ref: z.string(), // a commit/tag/tree-ish
   filePath: z.string().optional(), // ref + filePath => raw blob ("open file at commit")
   encoding: FsEncoding.default("utf8"),
-  maxBytesPerFile: z.number().int().positive().max(2 * 1024 * 1024).default(512 * 1024),
+  maxBytesPerFile: z
+    .number()
+    .int()
+    .positive()
+    .max(2 * 1024 * 1024)
+    .default(512 * 1024),
 });
 export type GitShowRequest = z.infer<typeof GitShowRequest>;
 export const GitShowResponse = z.object({
   commit: GitCommit.nullable(), // null when fetching a raw blob
   files: z.array(GitFileDiff), // commit diff vs first parent
-  blob: z.object({ content: z.string(), encoding: FsEncoding, sizeBytes: z.number().int(), truncated: z.boolean() }).nullable(),
+  blob: z
+    .object({
+      content: z.string(),
+      encoding: FsEncoding,
+      sizeBytes: z.number().int(),
+      truncated: z.boolean(),
+    })
+    .nullable(),
   revision: z.number().int().nonnegative(),
 });
 export type GitShowResponse = z.infer<typeof GitShowResponse>;
@@ -2995,7 +4035,11 @@ export const PtyOpenResponse = z.object({
 export type PtyOpenResponse = z.infer<typeof PtyOpenResponse>;
 export const PtyWriteRequest = z.object({ ptyId: z.string().uuid(), data: z.string() }); // utf-8 stdin
 export type PtyWriteRequest = z.infer<typeof PtyWriteRequest>;
-export const PtyResizeRequest = z.object({ ptyId: z.string().uuid(), cols: z.number().int().positive(), rows: z.number().int().positive() });
+export const PtyResizeRequest = z.object({
+  ptyId: z.string().uuid(),
+  cols: z.number().int().positive(),
+  rows: z.number().int().positive(),
+});
 export type PtyResizeRequest = z.infer<typeof PtyResizeRequest>;
 export const PtyCloseRequest = z.object({ ptyId: z.string().uuid() });
 export type PtyCloseRequest = z.infer<typeof PtyCloseRequest>;
@@ -3024,10 +4068,36 @@ export const SessionEvent = z.object({
   occurredAt: z.string(),
   clientEventId: z.string().min(1).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(),
 });
 export type SessionEvent = z.infer<typeof SessionEvent>;
 
-export const CreateSessionRequest = z.object({
+export const SessionQueueMutationResponse = z.object({
+  snapshot: SessionQueueSnapshot,
+  events: z.array(SessionEvent),
+  shouldWake: z.boolean(),
+});
+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(),
+});
+export type SessionControlResponse = z.infer<typeof SessionControlResponse>;
+
+export const CreateSessionRequest = withVariableSetIdAlias({
   initialMessage: z.string().min(1),
   // Per-session agent persona/system instructions (org-visible metadata, NOT a
   // secret). Rides the SAME system-level instructions channel the per-workspace
@@ -3036,7 +4106,7 @@ export const CreateSessionRequest = z.object({
   // leaking them into the user-visible timeline (it is NEVER emitted as an
   // event, unlike goal/initialMessage). Trimmed, non-empty. The 32768-char cap
   // matches the codebase's largest free-form string convention (workspace
-  // environment variable values). Absent ⇒ byte-identical to today.
+  // variable set variable values). Absent ⇒ byte-identical to today.
   instructions: z.string().trim().min(1).max(32768).optional(),
   resources: z.array(ResourceRef).default([]),
   tools: z.array(ToolRef).default([]),
@@ -3055,9 +4125,15 @@ export const CreateSessionRequest = z.object({
   // (the agent's resolve_cwd handles both). Only valid WITH targetSandboxId
   // (workingDir alone is a 422); omitted ⇒ the machine's default workspace_root.
   workingDir: z.string().min(1).optional(),
-  // Workspace environment attachment is fixed at session creation; follow-up
+  // Variable set attachment is fixed at session creation; follow-up
   // user.message events cannot switch or add one.
+  variableSetId: z.string().uuid().optional(),
   environmentId: z.string().uuid().optional(),
+  // The rig to bind this session to (M3). Its ACTIVE version is resolved and
+  // FROZEN onto the session at create. Omitted ⇒ the workspace's default rig
+  // (workspaces.default_rig_id) when set, else a rig-less session (today's
+  // 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(),
   // Workspace-scoped CREATE idempotency key: collapses concurrent/retried
@@ -3069,7 +4145,7 @@ export const CreateSessionRequest = z.object({
   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/environment/github tools. Capped at creation: every
+  // the orchestration/variableSet/github tools. Capped at creation: every
   // requested permission must be held by the creating grant (no escalation).
   firstPartyMcpPermissions: z.array(Permission).optional(),
   // Third-party MCP servers attached only to this session. Credential headers are
@@ -3087,16 +4163,14 @@ export const CreateSessionRequest = z.object({
   // A shared spawn inherits the box's (backend, os) — it is literally the same
   // box; the child cannot pick its own backend. Cross-workspace sharing is
   // forbidden by construction (the parent/group reads are RLS-workspace-scoped).
-  // ENV-AWARE: the box's environment is fixed at creation, so a share requires
-  // the SAME environmentId as the creator's box. On a mismatch the inherited
+  // ENV-AWARE: the box's variable set is fixed at creation, so a share requires
+  // the SAME variableSetId as the creator's box. On a mismatch the inherited
   // default silently falls back to an own box; an explicit "shared"/{groupId}
   // request 422s at create (instead of the first turn dying on the SDK's
   // manifest-env guard).
-  sandbox: z.union([
-    z.literal("shared"),
-    z.literal("new"),
-    z.object({ groupId: z.string().uuid() }),
-  ]).optional(),
+  sandbox: z
+    .union([z.literal("shared"), z.literal("new"), z.object({ groupId: z.string().uuid() })])
+    .optional(),
 });
 export type CreateSessionRequest = z.infer<typeof CreateSessionRequest>;
 
@@ -3115,11 +4189,6 @@ export const ClientSessionEvent = z.discriminatedUnion("type", [
       mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional(),
     }),
   }),
-  z.object({
-    type: z.literal("user.interrupt"),
-    clientEventId: z.string().min(1).optional(),
-    payload: z.object({ reason: z.string().optional() }).default({}),
-  }),
   z.object({
     type: z.literal("user.approvalDecision"),
     clientEventId: z.string().min(1).optional(),
@@ -3132,6 +4201,25 @@ export const ClientSessionEvent = z.discriminatedUnion("type", [
 ]);
 export type ClientSessionEvent = z.infer<typeof ClientSessionEvent>;
 
+export const SteerSessionMessageRequest = z.object({
+  text: z.string().min(1),
+  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(),
+  mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional(),
+});
+export type SteerSessionMessageRequest = z.infer<typeof SteerSessionMessageRequest>;
+
+export const SteerSessionMessageResponse = z.object({
+  accepted: SessionEvent,
+  turn: SessionTurn,
+});
+export type SteerSessionMessageResponse = z.infer<typeof SteerSessionMessageResponse>;
+
 export const SessionBusMessage = z.object({
   workspaceId: z.string().uuid(),
   sessionId: z.string().uuid(),
@@ -3435,7 +4523,13 @@ export const DeviceEnrollmentPollRequest = z.object({
 });
 export type DeviceEnrollmentPollRequest = z.infer<typeof DeviceEnrollmentPollRequest>;
 
-export const DeviceEnrollmentState = z.enum(["pending", "authorized", "denied", "expired", "disabled"]);
+export const DeviceEnrollmentState = z.enum([
+  "pending",
+  "authorized",
+  "denied",
+  "expired",
+  "disabled",
+]);
 export type DeviceEnrollmentState = z.infer<typeof DeviceEnrollmentState>;
 
 // The EnrollmentCredentials (field names match the proto's JSON). natsAccountCreds
@@ -3717,6 +4811,19 @@ export const SwapActiveSandboxResponse = z.object({
   activeSandboxId: z.string().nullable(),
   activeEpoch: z.number().int(),
   reason: z.string().optional(),
+  // Typed rejection discriminant (issue #341). Present only when swapped is false,
+  // so a client distinguishes a deleted/absent target from an unaddressable
+  // enrollment from a backend the turn cannot establish from a lost epoch race —
+  // without parsing the human reason string.
+  code: z
+    .enum([
+      "stale_pointer",
+      "offline_enrollment",
+      "unsupported_backend_context",
+      "transient_establishment",
+      "concurrent_swap",
+    ])
+    .optional(),
 });
 export type SwapActiveSandboxResponse = z.infer<typeof SwapActiveSandboxResponse>;
 
@@ -3739,7 +4846,7 @@ export type MachineMetricsSeriesResponse = z.infer<typeof MachineMetricsSeriesRe
 export const ClientModel = z.object({
   id: z.string(),
   label: z.string(),
-  provider: z.string(),        // provider id
+  provider: z.string(), // provider id
   providerLabel: z.string(),
   api: z.enum(["responses", "chat"]),
   contextWindowTokens: z.number().int().positive().optional(),
@@ -3759,10 +4866,14 @@ export const ClientConfig = z.object({
   models: z.array(ClientModel).default([]),
   defaultReasoningEffort: ReasoningEffort,
   allowedReasoningEfforts: z.array(ReasoningEffort).min(1),
-  mcpServers: z.array(z.object({
-    id: z.string(),
-    name: z.string(),
-  })).default([]),
+  mcpServers: z
+    .array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+      }),
+    )
+    .default([]),
   fileUploads: z.object({
     enabled: z.boolean(),
     maxSizeBytes: z.number().int().positive(),
@@ -3773,11 +4884,13 @@ export const ClientConfig = z.object({
   // at all (P4.4). Per-session availability is negotiated on /stream-capabilities
   // (it depends on the session's pinned backend); this is the coarse on/off the
   // client uses to decide whether to even attempt the fs/git/terminal panels.
-  structuredServices: z.object({
-    fileSystem: z.boolean(),
-    git: z.boolean(),
-    terminalEvents: z.boolean(),
-  }).default({ fileSystem: false, git: false, terminalEvents: false }),
+  structuredServices: z
+    .object({
+      fileSystem: z.boolean(),
+      git: z.boolean(),
+      terminalEvents: z.boolean(),
+    })
+    .default({ fileSystem: false, git: false, terminalEvents: false }),
 });
 export type ClientConfig = z.infer<typeof ClientConfig>;
 
@@ -3816,6 +4929,42 @@ function constantTimeEqual(actual: string, expected: string): boolean {
 
 export type HealthResponse = {
   service: string;
-  environment: string;
+  variableSet: string;
   ok: boolean;
 };
+
+/**
+ * Per-workspace model/provider availability policy (see @opengeni/db
+ * workspace_model_policies). NULL fields = unrestricted; a non-null
+ * allowedProviders is a strict allowlist over RESOLVED provider identities
+ * (the built-in OpenAI/Azure client's id — "openai"/"azure" — including the
+ * legacy null-resolution fallback; "codex-subscription" for the ChatGPT/Codex
+ * overlay; registry providers by their declared ids); a non-null allowedModels
+ * is an additional exact-model-id allowlist. Pure and shared so the API edge
+ * (422) and the worker's authoritative post-resolution gate (fail-loud
+ * turn.failed, never a silent remap) can never disagree on semantics.
+ */
+export type WorkspaceModelPolicyContract = {
+  allowedProviders: string[] | null;
+  allowedModels: string[] | null;
+};
+
+export type WorkspaceModelPolicyVerdict =
+  | { allowed: true }
+  | { allowed: false; reason: "provider" | "model" };
+
+export function evaluateWorkspaceModelPolicy(
+  policy: WorkspaceModelPolicyContract | null | undefined,
+  candidate: { providerId: string; modelId: string },
+): WorkspaceModelPolicyVerdict {
+  if (!policy) {
+    return { allowed: true };
+  }
+  if (policy.allowedProviders !== null && !policy.allowedProviders.includes(candidate.providerId)) {
+    return { allowed: false, reason: "provider" };
+  }
+  if (policy.allowedModels !== null && !policy.allowedModels.includes(candidate.modelId)) {
+    return { allowed: false, reason: "model" };
+  }
+  return { allowed: true };
+}